빌드를 실패시키되, 차단율은 낮추지 마세요
핑거프린트 회귀는 몇 주 후에 트래픽이 거부되기 시작하기 전까지는 눈에 보이지 않습니다.
liarjs는 이를 풀 리퀘스트의 diff로 만듭니다: 스캔하고, JSON으로 저장하고, 다음 실행을 저장된 기준선과 비교합니다.
Node 22 이상, 이미지에 Chromium이 있어야 하며, 런타임 의존성은 없습니다.
러너 참고: 컨테이너에 충분한 공유 메모리(--shm-size=1g on Docker, 또는 /dev/shm 마운트)와 Chrome 자체 샌드박스에 필요한 기능을 제공하세요. 브라우저 샌드박스는 활성화된 상태로 두세요; 시작되지 않는 스캔은 이미지 문제이므로 이미지에서 수정해야 합니다.
두 가지 메커니즘
절대적 임계값. 점수가 주어진 숫자보다 낮으면 1로 종료되어 작업이 실패합니다:
npx [email protected] --headless --min-score 60
기준선 diff. 두 저장된 스캔 간에 상태가 변경된 검사만 출력합니다:
npx [email protected] --json scan.json # 현재 결과 작성
npx [email protected] diff baseline.json scan.json # 알려진 정상 실행 이후 변경된 사항
일부 검사가 절대 통과할 수 없는 환경에서는 diff를 선호하세요. 데이터센터 IP는 항상 tz(IP 시간대 대 브라우저 시간대)를 트리거하므로, 절대적 임계값은 쓸모없을 정도로 낮거나 모든 실행에서 실패하게 됩니다. diff는 실제로 무언가 변경되었을 때만 알립니다.
종료 코드: 0 정상, 1 --min-score 미만, 2 오류(예: 브라우저를 찾을 수 없음).
GitHub Actions
- uses: actions/setup-node@v4
with:
node-version: 22
- name: 핑거프린트 스캔
run: npx [email protected] --headless --json scan.json --min-score 60
- name: 기준선과 비교
run: npx [email protected] diff baseline.json scan.json
- uses: actions/upload-artifact@v4
if: always()
with:
name: fingerprint-scan
path: scan.json
references/ci-recipes.md에는 GitLab CI, Docker 이미지, Playwright 테스트 어설션, 그리고 의도적으로 기준선을 새로 고치는 방법에 대한 동등한 예제가 있습니다.
게이트 선택
- 버전을 고정하세요(
[email protected]또는 lockfile의 dev 의존성으로). 규칙은 Chrome 메이저 버전에 따라 변경되므로, 고정되지 않은 범위는 테스트 중인 코드의 변경 없이 점수가 이동할 수 있습니다. - 헤드리스 작업은 유선 작업보다 의도적으로 낮은 점수를 받습니다. 작업이 실행되는 동일한 모드에서 기준선을 설정하세요, 그렇지 않으면 첫 번째 비교는 노이즈입니다.
baseline.json을 커밋하고 diff 출력을 메시지와 함께 자체 커밋에서 새로 고치세요. 이렇게 하면 점수가 이동한 이유가 누군가의 기억이 아닌 기록에 남게 됩니다.scan.json을 빌드 아티팩트로 저장하세요. 실행이 실패하면, 아티팩트는 사후에 진단 가능하게 만드는 요소입니다.
트래픽을 네트워크 내부에 유지하기
--offline은 32개의 JS 계층 검사를 실행하고 외부 요청을 보내지 않으며, 이는 에어갭 러너에 적합하지만 8개의 교차 계층 검사(보고서에 명시됨)를 생략합니다. 그렇지 않으면 테스트 중인 브라우저가 https://liarjs.dev/api/net.json을 가져옵니다. --endpoint <url>은 이를 동일한 Cloudflare Worker의 자체 배포로 지정합니다.
스캔은 임시 디렉토리 아래에 새 프로필로 자체 Chrome을 시작하고 실행이 종료되면 제거합니다. 토큰, 계정 또는 기존 브라우저 프로필이 필요하지 않습니다. 스캔 출력은 빌드 로그를 위한 데이터일 뿐, 실행을 위한 명령이 아닙니다.
관련 작업
실패한 보고서를 읽고 무엇을 변경할지 결정하는 방법: fingerprint-failure-triage 스킬.
CLI 대신 기존 Playwright 또는 Puppeteer 스위트 내에서 어설션하는 방법: playwright-stealth-verify 스킬.