redf0x1/camofox-browser

CamoFox Browser Server

무엇인가요 – C++ 수준의 지문 위조 기능을 갖춘 Firefox의 파생 버전인 Camoufox 스텔스 Firefox 엔진을 래핑하는 TypeScript 기반 서버입니다. 언어에 관계없이 사용 가능한 REST API와 강력한 CLI를 제공하여, AI 에이전트나 어떤 프로그램도 일반적인 자동화 도구(Puppeteer, Playwright 등)보다 훨씬 더 감지하기 어려운 브라우저를 제어할 수 있게 해줍니다.

AI 에이전트에게 중요한 이유 – 현대의 봇 탐지 서비스는 헤드리스 크롬 브라우저가 남기는 특징적인 지문을 탐지합니다. CamoFox는 지문 위조를 브라우저 엔진 자체 수준까지 내려가 수행하기 때문에, 결과적으로 일반 사용자의 Firefox처럼 보이는 세션을 생성합니다. 서버는 원시 HTML이나 스크린샷이 아닌 구조화된 접근성 스냅샷(안정적인 eN 요소 참조를 가진 작은 JSON 트리)을 반환하므로, LLM 기반 에이전트가 이를 파싱하고 행동하는 데 비용이 적게 듭니다.

주요 기능

• 엔진 수준의 앤티 탐지 – C++ 수준의 지문 위조(로케일, 타임존, 캔버스, WebGL 등)
• REST API – 페이지 열기, 클릭, 입력, 스크린샷 캡처, 구조화된 데이터 추출 등에 사용 가능한 HTTP 엔드포인트; 어떤 언어에서도 사용 가능.
• CLI – 50개 이상의 명령어(camofox open, snapshot, click e5, type e3 "text", trace start 등)로, 필요 시 자동으로 서버를 시작합니다.
• 다중 세션 및 프로필 – 최대 50개의 동시 사용자 세션을 지원하며, 각 세션은 고유한 지속적 Firefox 프로필을 갖습니다(쿠키, localStorage, IndexedDB는 재시작 후에도 유지됨).
• 지역 및 프록시 프리셋 – 8개의 내장 지역 프리셋과 세션별 프록시 설정, 하이브리드 "명시적 우선" 또는 "프록시 잠금" 모드 지원.
• 검색 매크로 – Google, YouTube, Amazon, Reddit, 위키백과, 트위터 등에서 한 줄로 검색 가능.
• 인증 보관소 – AES-256-GCM 암호화된 자격 정보 저장소(ARGon2id 기반 키)로, 호출된 LLM에 자격 정보를 노출하지 않고 브라우저에 직접 주입 가능.
• Playwright 트레이싱 – 복잡한 상호작용 디버깅을 위해 트레이스를 기록하고 내보낼 수 있음.
• 구조화된 추출 – 사용자가 제공한 스키마 기반의 결정론적 JSON 출력으로, 임의의 JavaScript 실행을 피함.
• Docker 및 포터블 Windows 빌드 – 공식 Docker 이미지(ghcr.io/redf0x1/camofox-browser)와 Node.js 및 Camoufox 바이너리가 포함된 헤드리스 우선 Windows-x64 ZIP 제공.

LLM 기반 에이전트의 일반적인 워크플로우

1. 서버 시작 (camofox 또는 Docker를 통해).
2. 페이지 열기 – camofox open https://example.com.
3. 스냅샷 – camofox snapshot --format json → 안정적인 eN 참조를 가진 JSON 트리.
4. 상호작용 – camofox click e5, camofox type e3 "hello".
5. 데이터 추출 – camofox extract-structured @schema.json 또는 /extract API 엔드포인트 사용.
6. 상태 유지 – camofox session save login-flow로 나중에 재사용 가능하게 저장.
7. 안전한 로그인 – 자격 정보를 보관소에 저장(camofox auth save gmail)하고, 직접 주입(camofox auth load gmail --inject --username-ref e5 --password-ref e12).

성숙도 – 현재 프리뷰(단계 1). API는 작동하지만, 마이너 릴리스 간에 엔드포인트 서명이 변경될 수 있으며, 호환되지 않는 업그레이드 시 로컬 상태 마이그레이션은 수동 리셋이 필요합니다.

시작하기

# 소스에서
git clone https://github.com/redf0x1/camofox-browser.git
cd camofox-browser
npm install && npm run build && npm start

# 또는 CLI를 전역으로 설치
npm install -g camofox-browser
camofox open https://example.com
camofox snapshot --format json

적합한 위치 – 일반적인 헤드리스 브라우저의 탐지 문제를 피하면서 신뢰성 있고 낮은 프로파일의 웹 상호작용(웹 검색, 폼 채우기, 데이터 추출, 테스트 등)이 필요한 AI 에이전트를 위한 프론트엔드입니다.