ChromiumFish는 단일하고 일관된 브라우저 신원을 제시하는 지문(fingerprint) 강화형 Chromium 포크입니다. 스푸핑이 주입된 JavaScript가 아닌 C++ 엔진 레벨에서 발생하기 때문에,

from chromiumfish import launch_agent   # JS: import { launchAgent } from "chromiumfish"

with launch_agent() as agent:           # OPENAI_API_* read from a nearby .env
...

AI 에이전트 가이드와 실행 가능한 예제를 확인하세요.

🪤 제작 동기

저는 대규모로 웹 스크래핑 (Web Scraping)을 수행하는데, 일부 사이트들은 매우 강력하게 대응합니다. 저는 대부분의 오픈 소스 은폐 브라우저 (Stealth Browsers)와 몇몇 유료 브라우저들을 사용해 보았지만, 모두 동일한 방식으로 실패했습니다. 이들은 리눅스 (Linux) 서버에서 실행되면서 리눅스가 아닌 것처럼 보이려고 시도하지만, 이를 JavaScript 패치 (JS patches)를 통해 수행합니다. 이는 숨기에 매우 좋지 않은 방식입니다. JS 패치는 "이것이 조작되었는가?"를 확인하는 체크 로직이 위치한 바로 그 지점에 조작 흔적을 남기며, 제가 중요하게 생각하는 탐지기 (Detectors)들은 매번 이를 잡아냈습니다. 그래서 저는 스푸핑 (Spoofing) 기능을 조작 탐지 프로브 (Tampering probe)가 찾아낼 수 없는 C++ 엔진 레벨로 내려보냈고, 이를 사용하여 제 스크래퍼 (Scrapers)들의 차단을 해제하기 시작했습니다. 그 이후로 이 방식은 제가 시도했던 다른 모든 방법이 차단되었던 몇몇 사이트들을 통과할 수 있게 해주었습니다.

✨ 제공 기능

• 🧬 스크립트가 아닌 엔진 수준에서의 스푸핑 (Spoofing). UA (User Agent), Client Hints, 폰트, 오디오, 화면, 그리고 WebRTC가 Chromium 내부에서 직접 스푸핑됩니다. CDP (Chrome DevTools Protocol) 환경에서도 navigator.webdriver는 false 상태를 유지하며, cdc_와 같은 자동화 흔적(artifacts)도 남지 않습니다.
• 🎭 하나의 시드, 하나의 페르소나. 단일 persona_seed (임의의 안정적인 문자열 ID)를 통해 내부적으로 일관된 안정적인 정체성을 부여받습니다. 새로운, 연결 불가능한(unlinkable) 정체성이 필요하면 시드를 변경하고, 세션 간 연속성을 유지하려면 동일한 시드를 재사용하세요.
• 🎨 선택적 브릿지를 통한 Canvas & WebGL. SwiftShader로 인해 정체가 탄로 나기 쉬운 헤드리스(headless) Linux 환경에서 가장 속이기 어려운 신호들입니다. ChromiumFish를 Windows에서 실행되는 작은 렌더 브릿지(render bridge)로 지정하면, Canvas/WebGL 읽기 값이 실제 머신으로부터 전달됩니다. 이는 바이너리에 포함되지 않은 별도의 선택적 서비스입니다.
• 🤝 그저 Playwright일 뿐입니다. Chromium 그 자체이기 때문에, Playwright에서 이미 수행하던 모든 작업이 변경 없이 작동합니다. SDK는 chromium.launch(executablePath=…)를 감싸는 얇은 래퍼(wrapper)입니다.
• 🤖 네이티브 AI 에이전트 (Native AI agent). Playwright 퍼펫티어(puppeteer) 스크립트가 아닌, 브라우저 프로세스 내에 구축된 '인지(perceive) → 사고(think) → 행동(act)' 에이전트입니다. 일상 언어로 된 작업을 전달하고 OpenAI 호환 LLM(Large Language Model)을 지정하기만 하면 됩니다. AI 에이전트 가이드를 참조하세요.
• 📦 한 줄로 설치. pip install chromiumfish 또는 npm i chromiumfish를 사용하세요. 처음 실행할 때 바이너리가 자동으로 다운로드되어 캐시됩니다.
• 🖥️ 쾌적한 헤드리스 환경. SwiftShader를 통해 GPU가 없는 Linux에서도 실행됩니다.

📦 설치 (Installation)

Python

pip install chromiumfish
chromiumfish fetch        # 브라우저 빌드 다운로드 및 캐시

Node

npm install chromiumfish
npx chromiumfish fetch

두 SDK 모두 Playwright가 필요합니다 (peer dependency). 처음 사용할 때 이 리포지토리의 Releases에서 브라우저 바이너리를 가져와 ~/.cache/chromiumfish/<version>/에 캐시하므로, 다운로드는 한 번만 수행하면 됩니다.

플랫폼 (Platforms): 현재 macOS 및 Linux용 사전 빌드(prebuilt)가 제공됩니다. Windows 빌드도 곧 출시될 예정입니다.

🧠 작동 원리 (How it works)

브라우저는 이 저장소에 함께 존재하는 Chromium 포크(fork)입니다. 업스트림(upstream) 체크아웃 버전에 patches/와 assets/를 적용한 후, 빌드하여 릴리스(Release)로 게시합니다. SDK가 수행하는 작업은 매우 적습니다. 사용자의 버전 및 플랫폼과 일치하는 에셋(asset)을 찾아내고, SHA-256을 확인하고, 압축을 해제한 뒤 Playwright에 경로를 전달합니다. 자세한 내용은 Quickstart에서 확인할 수 있습니다.

이는 각각 한 가지 역할을 수행하는 세 가지 요소로 요약됩니다:

📚 문서 (Docs)

전체 문서는 **chromiumfish.com**에 있으며 (docs/에서 Just the Docs로 구축됨), 다음 내용을 포함합니다:

• 소개 (Introduction)
• 설치 (Installation) · 빠른 시작 (Quickstart) · 페르소나 (Personas)
• AI 에이전트 (AI Agent) — 브라우저 네이티브 에이전트
• 레시피 (Recipes) · Canvas & WebGL 브릿지 (Canvas & WebGL bridge) · 문제 해결 (Troubleshooting)
• Python API · JavaScript API

🗂️ 구성 요소 (What's in here)

이것은 모노레포 (monorepo)입니다. 브라우저 포크 (upstream 대비 소스 델타 (source delta)만 포함)와 이를 배포하는 요소들 — SDK 및 문서 — 이 나란히 위치합니다.

chromiumfish/
├── patches/          # upstream Chromium 대비 포크의 소스 델타 (source delta)
├── assets/           # src/로 rsync되는 바이너리 빌드 오버레이 (아이콘, 폰트)
...

Chromium 체크아웃 (src/) 및 빌드 출력물 (out/, dist/)은 추적되지 않습니다 — .gitignore를 참조하세요. 일치하는 upstream 체크아웃에 patches/ + assets/를 적용함으로써 포크를 다시 빌드할 수 있습니다.

🐛 이름의 유래

물고기와는 관련이 없습니다. 이 이름은 4억 년 된 곤충인 **좀벌레 (silverfish)**에서 따왔습니다. 이 곤충은 갑옷도, 속도도, 추적할 만한 흔적도 남기지 않고 그저 눈에 띄지 않음으로써 네 번의 대멸종을 버텨냈습니다. 이것이 바로 핑거프린팅 (fingerprinting)을 당하지 않기를 원하는 브라우저의 핵심 아이디어입니다. 더 자세한 이야기는 여기에서 확인하세요.

⚠️ 면책 조항 (Disclaimer)

ChromiumFish는 **교육 및 허가된 연구 목적 (for educational and authorized research purposes only)**으로만 제공됩니다. 즉, 브라우저 핑거프린팅 (browser fingerprinting)이 작동하는 방식을 학습하고, 본인이 소유하거나 테스트가 명시적으로 허용된 시스템의 탄력성을 테스트하며, 개인정보 보호 연구를 수행하기 위한 용도입니다.

사용 방식에 대한 책임은 전적으로 사용자에게 있습니다. 모든 관련 법률 및 상호작용하는 모든 사이트나 서비스의 서비스 약관을 준수하여 사용하십시오. 사기, 무단 액세스, 보안 제어 회피 또는 기타 불법적이거나 남용적인 활동에 사용하지 마십시오.

본 소프트웨어는 명시적이든 묵시적이든 어떠한 종류의 보증 없이 "있는 그대로" (as is) 제공됩니다. 법이 허용하는 최대 범위 내에서, 저자와 기여자들은 본 소프트웨어의 사용 또는 오용으로 인해 발생하는 어떠한 청구, 손해 또는 기타 손실에 대해서도 책임을 지지 않습니다. ChromiumFish를 사용함으로써 귀하는 귀하의 행동에 대한 모든 책임을 수용하게 됩니다.

⚖️ 라이선스 (License)

MIT © Arman Hossain. ChromiumFish는 Chromium 프로젝트 (BSD-3-Clause)를 기반으로 구축되었습니다. 브라우저 배포판에는 Chromium의 라이선스와 크레딧이 포함되어 있습니다. "Chromium" 및 "Google Chrome"은 Google LLC의 상표입니다. ChromiumFish는 독립적인 포크 (fork)이며 Google과 제휴하거나 Google의 승인을 받지 않았습니다.