사용자가 설정하지 않은 구성 데이터는 [BrowserForge](https://github.com/daijro/browserforge) 지문을 사용하여 자동으로 채워집니다. 이 지문은 실제 트래픽에서 나타나는 기기 특성의 통계적 분포를 모방합니다.

[[구현된 속성 보기](https://camoufox.com/fingerprint/)]

---

## Python 사용법

Camoufox는 기존 Playwright 코드와 호환됩니다. 브라우저 초기화만 변경하면 됩니다.

**Sync API**```python
from camoufox.sync_api import Camoufox

with Camoufox() as browser:
    page = browser.new_page()
    page.goto("https://example.com")

[[설치 및 사용법](https://camoufox.com/python/)]

### 하드웨어 스푸핑을 최대한 활용하기

안정적인 릴리즈를 위해서는 항상 메인 [`camoufox`](https://pypi.org/project/camoufox/) pip 패키지를 사용해야 합니다. 하지만 컨텍스트별 지문과 하드웨어 스푸핑을 활용하려면 [`cloverlabs-camoufox`](https://pypi.org/project/cloverlabs-camoufox/) 패키지를 사용하세요. 이 패키지는 각 릴리즈마다 업데이트되는 반면, 공식 패키지는 지연 출시됩니다.

두 패키지 간의 충돌을 방지하기 위해 가상 환경을 사용하고 있는지 확인하세요.

**설치**```bash
pip install cloverlabs-camoufox

**사용법** — API는 상위 패키지와 동일합니다.```python
from camoufox.sync_api import Camoufox

with Camoufox() as browser:
    page = browser.new_page()
    page.goto("https://example.com")

라이브러리는 바이너리 버전에 따라 자동 라우팅됩니다: Firefox ≥ 149는 `fingerprint-presets-v150.json`을 로드합니다(312개의 프리셋, v149–v152 포함, macOS 67개 / Windows 180개 / Linux 65개). 이전 바이너리는 원래 번들로 폴백됩니다. UA 문자열은 활성 바이너리에 맞게 다시 작성되므로, 옵트인(opt in)은 버전 간에 안전합니다. 특정 핑거프린트를 고정하려면 `True` 대신 프리셋 딕셔너리를 전달하세요.

---

## Capabilities

Below is a list of patches and features implemented in Camoufox.

### 핑거프린트 스푸핑

- Navigator 속성 스푸핑 (장치, 브라우저, 로케일 등)
- 화면 크기, 해상도 등 에뮬레이션 지원
- WebGL 매개변수, 지원 확장, 컨텍스트 속성 및 셰이더 정밀도 형식 스푸핑
- 내부 및 외부 창 뷰포트 크기 스푸핑
- AudioContext 샘플레이트, 출력 지연 시간 및 최대 채널 수 스푸핑
- 장치 음성 및 재생 속도 스푸핑
- 사용 가능한 마이크, 웹캠 및 스피커 개수 스푸핑
- 네트워크 헤더(Accept-Languages 및 User-Agent)가 navigator 속성과 일치하도록 스푸핑됩니다
- 프로토콜 수준에서의 WebRTC IP 스푸핑
- 지리적 위치, 시간대 및 로케일 스푸핑
- 배터리 API 스푸핑
- 기타

### 스텔스 패치

- 메인 월드 실행 누출을 방지합니다. 모든 페이지 에이전트 자바스크립트는 샌드박스 처리됩니다.
- 프레임 실행 컨텍스트 누출 방지
- `navigator.webdriver` 감지 수정
- 포인터 유형을 통한 Firefox 헤드리스 감지 수정 ([#26](https://github.com/daijro/camoufox/issues/26))
- 잠재적으로 누출될 수 있는 안티 줌/메타 뷰포트 처리 패치 제거
- 기본이 아닌 화면 및 창 크기 사용
- 피전 콘텐츠 격리 재활성화
- PDF.js 재활성화
- 기타 누출 구성 속성 변경
- 사람과 유사한 커서 이동

### 폰트 핑거프린팅 방지

- 사용자 에이전트에 맞는 올바른 시스템 폰트를 자동으로 사용
- Windows, Mac 및 Linux 시스템 폰트 번들 제공
- 문자 간격을 무작위로 오프셋하여 폰트 메트릭 핑거프린팅 방지

### Playwright 지원

- 최신 Firefox를 위한 Playwright의 커스텀 구현
- 봇 탐지를 회피하기 위한 다양한 구성 패치

### 디블로트/최적화

- _매우 많은_ Mozilla 서비스를 제거/비활성화했습니다. 원본 Mozilla Firefox보다 빠르게 실행되며 메모리 사용량이 더 적습니다(200MB).
- LibreWolf 및 Ghostery의 패치로 텔레메트리 및 블로트 제거 지원
- PeskyFox, LibreWolf 등의 디블로트 구성
- FastFox의 속도 및 네트워크 최적화
- 모든 CSS 애니메이션 제거
- 미니멀리스트 테마
- 기타

### 애드온

- `addons` 속성에 경로 목록을 전달하여 디버그 서버 없이 Firefox 애드온 로드
- 커스텀 개인정보 보호 필터가 포함된 uBlock Origin 추가
- 애드온은 탭을 열 수 없음
- 애드온이 시크릿 모드에서 자동으로 활성화됨
- 애드온이 자동으로 툴바에 고정됨
- uBO 프리페칭으로 DNS 누출 수정

### Python 인터페이스

- 실제 분포를 기반으로 고유한 장치 특성을 자동으로 생성하여 Camoufox에 주입
- WebGL 핑거프린트 주입 및 순환
- 대상 OS에 따라 올바른 시스템 폰트와 서브픽셀 안티앨리어싱 및 힌팅 사용
- 프록시의 대상 지역에서 목표 지리적 위치, 시간대 및 로케일을 계산하여 프록시 탐지 방지
- 프록시 대상 지역의 언어 사용자 분포를 기반으로 브라우저 언어 계산 및 스푸핑
- Playwright를 지원하는 다른 언어에서 Camoufox를 사용할 수 있도록 원격 서버 호스팅
- 헤드리스 서버에서 Camoufox를 헤드풀(Headful) 방식으로 실행하기 위한 내장 가상 디스플레이 버퍼
- 이미지 로딩, WebRTC 및 WebGL 전환
- 기타

> [!NOTE]
> Camoufox는 Chromium 핑거프린트 주입을 완전히 지원하지 **않습니다**. 일부 WAF(예: [Interstitial](https://nopecha.com/demo/cloudflare))는 Spidermonkey 엔진 동작을 테스트하므로 스푸핑이 불가능합니다.

---

# Stealth Overview

## How Camoufox hides its automation library

> [!WARNING]
> **2026년 기준 현재 상태**:
> 개인 사정으로 인해 1년간 유지보수가 중단되었습니다. 기본 Firefox 버전 및 새로 발견된 핑거프린트 불일치로 인해 Camoufox의 성능이 저하되었습니다. **Camoufox는 현재 활발히 개발 중입니다.**

Camoufox에서는 Playwright의 내부 Page Agent 코드가 모두 샌드박스 처리 및 격리됩니다. 이로 인해 페이지가 JavaScript 검사를 통해 Playwright의 존재를 감지하는 것이 불가능해집니다.

일반적으로 Playwright는 `window.__playwright__binding__`과 같은 JavaScript를 페이지에 주입하여 요소 쿼리, JavaScript 평가, 초기화 스크립트 실행 등의 작업을 수행하며, 이는 웹사이트에서 감지될 수 있습니다. Camoufox에서는 이러한 작업이 페이지 외부의 격리된 범위에서 처리됩니다. 즉, 웹사이트는 Playwright가 일반적으로 주입하는 JavaScript를 더 이상 '볼' 수 없습니다. 이로 인해 Playwright의 흔적이 완전히 제거됩니다.

하지만 자동화 라이브러리를 숨기더라도 Camoufox는 핑거프린트 순환의 불일치에 면역이 아닙니다. 이를 발견하고 수정하기 위한 유지보수가 여전히 필요합니다.

### 페이지 상호작용

안티봇 시스템은 또한 클라이언트 측 스크립트를 실행하여 사용자 행동을 모니터링합니다. 예를 들어, 마우스 움직임, 클릭, 스크롤, 그리고 작업 간의 타이밍 패턴을 찾습니다.

<video controls src="https://github.com/user-attachments/assets/6d33d6af-3537-4603-bf24-6bd3f4f8f455" width="200px" loop muted></video>

Camoufox는 인간과 유사한 마우스 움직임 알고리즘으로 최선을 다합니다. 자연스러운 움직임 알고리즘은 원래 [riflosnake의 HumanCursor](https://github.com/riflosnake/HumanCursor)에서 가져와 C++로 다시 작성되었으며, 더 거리 인식적인 궤적을 위해 수정되었습니다.

하지만 이는 완벽하지 않습니다. 충분히 정교한 분석을 통해 여전히 감지될 수 있습니다. (향후 작업 중)

---

## How Camoufox rotates identities

AI 에이전트는 플래그가 지정되거나 속도 제한 없이 여러 세션에서 작동해야 합니다. IP 주소를 순환하는 것만으로는 충분하지 않습니다. 모든 브라우저 세션은 수천 개의 신호를 전달하여 고유한 **핑거프린트**를 생성합니다. 웹사이트는 OS, GPU, 화면 해상도, 폰트, 시간대 등을 볼 수 있습니다. 이러한 신호가 일관되지 않거나 비정상적이면 차단됩니다.

### 시장 점유율 분포

각 실행 중인 봇 인스턴스에 대해 IP를 순환하더라도 웹 접근 방화벽은 여전히 머신 러닝을 사용하여 들어오는 웹 트래픽을 분석하여 비정상 여부를 감지할 수 있습니다. Linux 시장 점유율이 5%였다면 갑자기 20%가 되는 것은 위험 신호입니다. 그러면 모든 Linux 사용자에게 조건 없이 캡차를 요구합니다.

Camoufox는 [BrowserForge](https://github.com/daijro/browserforge)의 핑거프린트 생성기를 사용하여 실제 트래픽에서 장치 데이터의 통계적 분포를 모방합니다. 예를 들어, Camoufox는 5%의 확률로 브라우저가 Linux 사용자처럼 보이게 만듭니다. 그 5% 중에서 2560x1440 화면 해상도를 9.5%, Intel HD GPU를 27.5%의 확률로 스푸핑합니다.

### How can Camoufox be detected?

Camoufox는 올바른 시장 점유율로 핑거프린트를 스푸핑할 수 있습니다. 하지만 **핑거프린트는 내부적으로도 일관되어야 합니다.** Apple M1 GPU가 있는 Windows 사용자 에이전트, Windows DirectX 렌더러가 있는 macOS 사용자 에이전트, 데스크탑 화면 해상도를 가진 모바일 장치는 모두 불가능하며 의심스러운 것으로 플래그가 지정됩니다.

설득력 있는 스푸핑된 핑거프린트를 만들기 위해 변경해야 하는 수천 가지 데이터 포인트 중 각 변경 사항이 서로 일관되어야 하는데, Camoufox는 항상 성공하지는 않습니다. 안티봇 제공업체는 단 하나의 독특한 불일치라도 찾기 위해 Camoufox를 반복적으로 테스트한 다음 즉시 백그라운드 스크립트를 업데이트하여 이를 테스트합니다.

---

## How does Camoufox compare to other solutions?

### JavaScript 기반 솔루션

과거에는 개발자들이 JavaScript를 주입하여 이러한 값을 스푸핑하려고 했지만, JavaScript가 모든 것을 스푸핑할 수 없기 때문에 안정적으로 작동하지 않습니다. 불완전한 커버리지는 일관되지 않은 핑거프린트를 초래합니다. 예를 들어, 네트워크 요청의 User Agent가 navigator의 User Agent와 일치하지 않으면 안티봇 시스템이 플래그를 지정합니다.

또한 주입된 모든 JavaScript는 어떤 방식으로든 감지 가능합니다. 안티봇 시스템은 `Object.getOwnPropertyDescriptor`가 덮어쓰여진 속성을 드러내는지, 함수의 `toString()`이 더 이상 `[native code]`를 반환하지 않는지(하이재킹되었음을 드러냄), 또는 window 컨텍스트의 데이터가 worker 스레드 컨텍스트와 일치하지 않는지 확인할 수 있습니다. 우회 방법도 한계가 있으며, 충분히 깊이 파고들면 JS 주입을 감지할 방법은 항상 존재합니다.

#### Camoufox의 접근 방식

Camoufox는 브라우저의 C++ 구현 수준에서 호출을 가로채기 때문에 하이재킹된 모든 객체와 속성이 네이티브로 보입니다. 감지할 JavaScript 하이재킹이 없습니다.

Camoufox는 또한 Browserforge를 사용하여 일관되고 설득력 있는 핑거프린트를 생성하려고 시도합니다. 하지만 이는 앞서 설명한 데이터 불일치와 같은 복잡한 핑거프린트 감지 방법에 의해 여전히 감지될 수 있습니다.

<hr width=50>

### CDP 기반 라이브러리

CDP(Chrome DevTools Protocol)는 Chromium과 Firefox에 내장된 자동화 프로토콜입니다. 그러나 CDP는 자동화 프로토콜이라는 사실을 숨기려는 노력을 전혀 하지 않으며, 그 기능의 많은 부분을 페이지 범위에 노출합니다. 일반적인 방법으로는 `navigator.webdriver`가 true인지 확인하거나, 스택 디버거를 읽는 것을 잡아내거나, ChromeDriver가 내부 통신을 위해 document 객체에 주입하는 변수를 확인하는 등이 있습니다.

#### Camoufox의 접근 방식

Playwright는 Chromium을 제어하기 위해 CDP를 사용하지만, Firefox에는 _Juggler_를 사용합니다. Juggler는 Firefox가 CDP를 지원하기 전에 개발된 커스텀 프로토콜입니다([원본 저장소](https://github.com/puppeteer/juggler)). 이는 Firefox 내의 별도 모듈이며 핵심 브라우저의 일부가 아닙니다. 따라서 페이지에 무엇을 노출할지 편집하고 제어하기가 더 쉽습니다.

Camoufox는 Juggler에 패치를 적용하여 작업할 수 있는 격리된 페이지 '복사본'을 제공합니다. Playwright는 자체 버전의 페이지를 자유롭게 읽고 편집할 수 있습니다. 모든 것이 정상적으로 작동하는 것처럼 보이지만 실제 페이지는 이러한 변경 사항에 전혀 영향을 받지 않습니다. 또한 페이지는 getter 하이재킹과 같은 트릭을 통해 무언가를 읽거나 요소를 감시하기 위해 리스너가 추가되는 것을 감지할 수 없습니다.

또한 Juggler는 Firefox의 원래 사용자 입력 핸들러를 통해 직접 입력을 전송하므로, 일반 브라우저를 사용할 때와 정확히 동일한 방식으로 처리됩니다. Camoufox는 또한 Firefox의 헤드리스 모드에 패치를 적용하여 일반 창에서 실행되는 것처럼 보이게 만듭니다. 그러나 대비책으로, 헤드리스 모드가 누출될 경우 Python 라이브러리는 [가상 디스플레이](https://camoufox.com/python/virtual-display/)에서 Camoufox를 실행할 수 있습니다.

---

<h1 align="center">Build System</h1>

> [!WARNING]
> 아래 내용은 Camoufox를 빌드하고 디버깅하는 데 관심이 있는 사람들을 위한 것입니다. Playwright 사용 방법은 [여기](https://github.com/daijro/camoufox/tree/main/pythonlib#camoufox-python-interface)를 참조하세요.

### 개요

다음은 빌드 시스템과 관련 make 명령어의 다이어그램입니다:```mermaid
graph TD
    FFSRC[Firefox Source] -->|make fetch| REPO

    subgraph REPO[Camoufox Repository]
        PATCHES[Fingerprint masking patches]
        ADDONS[uBlock & B.P.C.]
        DEBLOAT[Debloat/optimizations]
        SYSTEM_FONTS[Win, Mac, Linux fonts]
        JUGGLER[Patched Juggler]
    end

    subgraph Local
    REPO -->|make dir| PATCH[Patched Source]
    PATCH -->|make build| BUILD[Built]
    BUILD -->|make package-linux| LINUX[Linux Portable]
    BUILD -->|make package-windows| WIN[Windows Portable]
    BUILD -->|make package-macos| MAC[macOS Portable]
    end

다음으로, 다음 명령어를 사용하여 Camoufox 소스 코드를 빌드하십시오:```bash
make dir

> [!NOTE]
> 의존성 설치 프로그램은 현재까지 macOS에서만 테스트되었습니다.

그런 다음 Camoufox를 빌드할 수 있도록 시스템을 부트스트랩해야 합니다. 이 작업은 한 번만 수행하면 됩니다. 다음 명령을 실행하여 수행합니다:```bash
make bootstrap

새로운 빌드의 경우, `i686`은 Windows에서만 지원됩니다. 지원되지 않는 대상/아키텍처 조합은 건너뜁니다.

<details>
<summary>
CLI 매개변수
</summary>```bash
Options:
  -h, --help            show this help message and exit
  --target {linux,windows,macos} [{linux,windows,macos} ...]
                        Target platforms to build
  --arch {x86_64,arm64,i686} [{x86_64,arm64,i686} ...]
                        Target architectures to build for each platform
  --bootstrap           Bootstrap the build system
  --clean               Clean the build directory before starting

Example:
$ python3 multibuild.py --target linux windows macos --arch x86_64 arm64

2. Camoufox 패치를 대상 플랫폼 및 아키텍처로 빌드:```bash
docker run -v "$(pwd)/dist:/app/dist" camoufox-builder --target <os> --arch <arch>

패치는 여기서 편집, 생성, 제거 및 관리할 수 있습니다.

<img src="https://assets.kitploit.com/production/public/readmes/41473/19bffc384c42fb6eb69b3ee59622daed4770cf0f11ffe39401eca57a7d2457f4.png">

### 패치 만드는 방법

1. 개발자 UI에서 **Reset workspace**를 클릭합니다.
2. 필요에 따라 `camoufox-*/` 폴더에서 변경합니다. `make build`와 `make run`으로 변경 사항을 테스트할 수 있습니다.
3. 변경이 완료되면 **Write workspace to patch**를 클릭하고 패치 파일을 저장합니다.

### 기존 패치 작업 방법

1. 개발자 UI에서 **Edit a patch**를 클릭합니다.
2. 편집할 패치를 선택합니다. 작업 공간이 선택한 패치의 상태로 재설정됩니다.
3. 변경이 완료되면 **Write workspace to patch**를 누르고 기존 패치 파일을 덮어씁니다.

---

## Leak 디버깅

이것은 WAF 자바스크립트를 디난독화하지 않고 누수를 판단하는 제 프로세스를 보여주는 순서도입니다. 이 방법은 테스트 사이트가 플래그를 표시할 때까지 Camoufox의 기능을 Firefox 소스 코드에 점진적으로 다시 도입합니다.

이 프로세스는 Linux 시스템이 필요하며 Firefox 빌드 도구가 설치되어 있다고 가정합니다([여기](https://github.com/daijro/camoufox?tab=readme-ov-file#build-cli) 참조).

<details>
<summary>
순서도 보기...
</summary>```mermaid
flowchart TD
    A[Start] --> B[Does website flag in the official Firefox?]
    B -->|Yes| C[Likely bad IP/rate-limiting. If the website fails on both headless and headful mode on the official Firefox distribution, the issue is not with the browser.]
    B -->|No| D["Run make ff-dbg(1) and build(2) a clean distribution of Firefox. Does the website flag in Firefox **headless** mode(4)?"]
    D -->|Yes| E["Does the website flag in headful mode(3) AND headless mode(4)?"]
    D -->|No| F["Open the developer UI(5), apply config.patch, then rebuild(2). Does the website still flag(3)?"]
    E -->|No| G["Enable privacy.resistFingerprinting in the config(6). Does the website still flag(3)?"]
    E -->|Yes| C
    G -->|No| H["In the config(6), enable FPP and start omitting overrides until you find the one that fixed the leak."]
    G -->|Yes| I[If you get to this point, you may need to deobfuscate the Javascript behind the website to identify what it's testing.]
    F -->|Yes| K["Open the developer UI, apply the playwright bootstrap patch, then rebuild. Does it still flag?"]
    F -->|No| J["Omit options from camoufox.cfg(6) and rerun(3) until you find the one causing the leak."]
    K -->|No| M[Juggler needs to be debugged to locate the leak.]
    K -->|Yes| L[The issue has nothing to do with Playwright. Apply the rest of the Camoufox patches one by one until the one causing the leak is found.]
    M --> I