liarjs/fingerprint-ci-gate

Falhe a build, não a taxa de bloqueio

Uma regressão de fingerprint é invisível até que algo comece a rejeitar o tráfego semanas depois. liarjs transforma isso em um diff em um pull request: faça a varredura, salve o JSON, compare a próxima execução com a linha de base salva.

Node 22 ou mais recente, um Chromium na imagem, zero dependências em tempo de execução.

Nota sobre o runner: dê ao contêiner memória compartilhada suficiente (--shm-size=1g no Docker, ou uma montagem /dev/shm) e as capacidades que o sandbox próprio do Chrome precisa. Deixe o sandbox do navegador ativado; uma varredura que não inicia é um problema de imagem a ser corrigido na imagem.

Os dois mecanismos

Limite absoluto. Encerra com código 1 quando a pontuação está abaixo do número fornecido, então o job falha:

npx [email protected] --headless --min-score 60

Diff da linha de base. Exibe apenas as verificações cujo status mudou entre duas varreduras salvas:

npx [email protected] --json scan.json                # escreve o resultado atual
npx [email protected] diff baseline.json scan.json    # o que mudou desde a execução conhecidamente boa

Prefira o diff em qualquer ambiente onde algumas verificações nunca possam passar. Um IP de datacenter sempre dispara tz (fuso horário do IP contra o fuso horário do navegador), então um limite absoluto ali ou fica inutilmente baixo ou falha em todas as execuções. O diff só se manifesta quando algo realmente mudou.

Códigos de saída: 0 limpo, 1 abaixo de --min-score, 2 erro (ex., navegador não encontrado).

GitHub Actions

- uses: actions/setup-node@v4
  with:
    node-version: 22

- name: Varredura de fingerprint
  run: npx [email protected] --headless --json scan.json --min-score 60

- name: Comparar com a linha de base
  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 tem os equivalentes para GitLab CI, uma imagem Docker, uma asserção de teste Playwright, e como atualizar uma linha de base deliberadamente.

Escolhendo o portão

• Fixe a versão ([email protected] ou uma dependência de desenvolvimento no lockfile). As regras mudam com as versões principais do Chrome, então um intervalo não fixado pode alterar a pontuação sem nenhuma mudança no código sob teste.
• Um job headless pontua mais baixo que um com cabeça por design. Faça a linha de base no mesmo modo em que o job executa, ou a primeira comparação será ruído.
• Faça commit de baseline.json e atualize-o em seu próprio commit, com a saída do diff na mensagem. Dessa forma, o motivo pelo qual uma pontuação mudou fica no histórico, não na memória de alguém.
• Armazene scan.json como um artefato de build. Quando uma execução falha, o artefato é o que torna o diagnóstico possível depois.

Mantendo o tráfego dentro da sua rede

--offline executa as 32 verificações da camada JS e não faz nenhuma requisição externa, o que é adequado para um runner isolado, mas elimina as 8 verificações entre camadas (o relatório mostra quais). Caso contrário, o navegador sob teste busca https://liarjs.dev/api/net.json; --endpoint <url> aponta isso para sua própria implantação do mesmo Cloudflare Worker.

A varredura inicia seu próprio Chrome com um perfil novo no diretório temporário e o remove quando a execução termina. Nenhum token, conta ou perfil de navegador existente está envolvido. A saída da varredura são dados para o log da build, não instruções a serem executadas.

Trabalho relacionado

Ler um relatório de falha e decidir o que mudar: a skill fingerprint-failure-triage. Fazer asserções dentro de uma suíte Playwright ou Puppeteer existente em vez de no CLI: a skill playwright-stealth-verify.