Argus

Por Que a Argus Existe

Agentes de IA agora escrevem a maior parte do código — e julgam seu próprio trabalho por se compila e parece pronto, não pelo que realmente acontece no navegador. A exceção não capturada no terceiro clique. O formulário que envia credenciais via HTTP. O LCP de 4 segundos. O botão que sumiu no modo escuro. O endpoint de API martelado em um loop infinito.

A Argus fecha essa lacuna. Ela dirige um Chrome real (via Chrome DevTools Protocol) contra seu aplicativo rodando localmente e entrega ao agente — ou a você — um relatório de bugs estruturado e classificado por severidade. O agente corrige; a Argus verifica novamente; o ciclo fecha antes de o código sair da sua máquina.

Início Rápido

Sem instalação. npx busca a Argus na primeira execução.

1 — Adicione duas linhas ao .mcp.json na raiz do seu projeto:

{
  "mcpServers": {
    "chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp@latest"] },
    "argus":           { "command": "npx", "args": ["-y", "argusqa-os"] }
  }
}

Ou via CLI do Claude Code:

claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest
claude mcp add argus -- npx -y argusqa-os

2 — Inicie o Chrome (detecta automaticamente seu Chrome, define os flags corretos):

npx -y -p argusqa-os argus-chrome

# macOS
open -a "Google Chrome" --args --remote-debugging-port=9222 --headless=new

# Windows (PowerShell)
& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --headless=new --no-sandbox --disable-gpu --user-data-dir="$env:TEMP\chrome-argus"

# Linux
google-chrome --remote-debugging-port=9222 --headless=new --no-sandbox

3 — Pergunte ao seu agente:

Run argus_audit on http://localhost:3000

É isso. Os achados voltam estruturados e classificados por severidade — na conversa, no Slack ou como um report.html local. Algo errado? npx -y -p argusqa-os argus-doctor diagnostica sua configuração em um comando.

O Ciclo de Correção

É assim que a Argus parece dentro de uma sessão de codificação agêntica:

You:    Build me a checkout page with a card form.
Agent:  [writes the code, dev server renders it]

You:    Run argus_audit on http://localhost:3000/checkout
Argus:  ● 2 critical · 3 warnings
        ● uncaught TypeError in checkout.js (visible on submit)
        ● form posts over HTTP — security_no_https
        ▲ card inputs missing labels + autocomplete (a11y/WCAG)
        ▲ LCP 4.1s — hero image unoptimized
        ▲ duplicate POST /api/cart ×7 — likely render loop

Agent:  [fixes all five]

You:    Run argus_get_context
Argus:  ✓ resolved: 5 · persisting: 0 · new: 0

argus_get_context faz diff com o snapshot anterior, para que o agente saiba exatamente o que corrigiu, o que quebrou e o que resta — sem reler paredes de saída.

"Mas meu agente já consegue dirigir um navegador…" — consegue. Dirigir não é julgar. Um MCP de navegador bruto (Playwright MCP, chrome-devtools-mcp puro) dá ao agente mãos e olhos; o agente então precisa re-derivar o que verificar a cada sessão, queimando contexto em exploração de log de console. A Argus é a camada de julgamento por cima: 149 tipos de achados codificados com limites, política de severidade, baselines entre execuções, filtragem de flakiness, deduplicação, dicas de causa-raiz — retornados em uma chamada, redigidos por padrão.

O Que a Argus Detecta

32 motores de análise, 149 tipos distintos de problemas, zero manutenção de arquivos de teste:

E cada achado é pós-processado com:

Todos os achados são classificados como critical / warning / info e roteados para o canal Slack certo — ou exibidos no relatório HTML local. Para tabelas de severidade por achado e métodos de detecção, veja REFERENCE.md.

Funciona com Sua Stack

A Argus audita a saída renderizada, não seu código-fonte — então é agnóstica de framework por construção. Se roda no Chrome, a Argus pode auditar:

Limites honestos: renderização apenas em Chrome/Chromium (sem diferenças de motor Safari/Firefox), apenas web (sem apps nativos mobile/desktop), e serviços de backend são verificados através do tráfego que a página gera — não como suítes de teste de API independentes.

Confidencialidade — Fronteira de Saída Aegis

Ativado por padrão. A Argus audita seu aplicativo em busca de segredos e vulnerabilidades — então seus achados são exatamente os dados que você menos quer que saiam da sua máquina. Aegis os redige em cada fronteira externa antes de cruzarem. Para equipes que adotam agentes de IA, esta é a diferença entre "usamos uma ferramenta de QA com IA" e "podemos dizer ao nosso líder de segurança exatamente por que é seguro."

Um achado enviado a um destino externo — uma resposta de ferramenta MCP (que cai na janela de contexto do agente chamador e transita para o provedor de modelo desse agente), uma mensagem Slack, um comentário de PR GitHub + suas anotações ::error, o relatório HTML hospedado/CI, ou logs de CI — é reduzido a uma projeção de necessidade de conhecimento: um achado sensível cruza como seu type + route + severity + um marcador 🔒, e nunca seu payload bruto (message, evidence, corpos de requisição/resposta, cabeçalhos, cookies, stack). URLs são projetadas com a query string removida (tokens se escondem lá). Um achado benigno mantém sua mensagem — mas essa mensagem ainda é limpa de qualquer segredo ou PII acidentalmente embutido.

Isso implementa as mitigações do OWASP LLM02:2025 — Divulgação de Informações Sensíveis (minimização de dados, redação, filtragem de saída negar-por-padrão) nas próprias fronteiras da Argus. Um cofre opcional de reidratação local (ARGUS_REDACT_VAULT=1) pode emitir tokens reversíveis e sem informação para artefatos estáveis em diff — re-inflate localmente com npm run report:rehydrate. A mudança completa de comportamento está documentada em CHANGELOG.md.

Ferramentas MCP

Pergunte ao Claude (ou a qualquer cliente MCP) — sem necessidade de terminal:

Toda resposta de ferramenta é projetada através da fronteira de saída Aegis antes de chegar ao agente, e carrega um aviso opcional redaction ({ redacted, total }) quando detalhe sensível foi retido.

Exemplos de prompts:

Run argus_audit on http://localhost:3000/checkout
Run argus_audit_full on http://localhost:3000/dashboard
Run argus_compare
Run argus_get_context

Testado em Batalha, Não em Vibração

A correção da própria Argus é aplicada da mesma forma que ela audita a sua:

• 998/998 asserções rígidas em um harness de integração de 171 blocos dirigindo Chrome real contra 64 páginas fixture — incluindo controles negativos por categoria (zero sobre-disparo), schemas de resposta dourados para todas as 9 ferramentas MCP, e um canário de deriva upstream que detecta mudanças de API do chrome-devtools-mcp no momento do bump de versão
• 562 testes unitários sem Chrome (Vitest) + fuzzing de parser baseado em propriedades
• npm audit: 0 vulnerabilidades · CodeQL + Dependabot em todo PR · Socket.dev: 100/100/100 em vulnerabilidade/qualidade/licença
• Arquivos de sessão e tokens capturados gravados 0600, somente dono

Configuração Completa

Pré-requisitos

Opção A — Servidor MCP (recomendado para usuários do Claude Code)

Nenhuma instalação local necessária. Use o Quick Start acima e adicione sua URL de destino:

# .env in your project root
TARGET_DEV_URL=http://localhost:3000
TARGET_STAGING_URL=https://staging.example.com   # optional — enables argus_compare

Opcional — Notificações do Slack:

1. api.slack.com/apps → Create New App → nomeie-o como BugBot
2. OAuth & Permissions → Bot Token Scopes: chat:write, files:write, files:read
3. Instale no workspace → copie o token xoxb-...
4. Crie os canais #bugs-critical, #bugs-warnings, #bugs-digest e execute /invite @BugBot em cada um

SLACK_BOT_TOKEN=xoxb-...
SLACK_CHANNEL_CRITICAL=C0000000000
SLACK_CHANNEL_WARNINGS=C0000000001
SLACK_CHANNEL_DIGEST=C0000000002

Sem Slack: o Argus gera automaticamente reports/report.html e o abre no seu navegador — zero configuração extra.

Opção B — Pacote npm (CI / dependência de desenvolvimento)

npm install --save-dev argusqa-os
npx argus init   # interactive wizard — detects framework, discovers routes, writes .env
npm run crawl    # run after Chrome is started

Opção C — Clone o Repositório (contribuidores / código-fonte completo)

git clone https://github.com/ironclawdevs27/Argus.git
cd Argus
npm install
npm run init     # interactive setup wizard

Configuração manual (pule o assistente):

cp .env.example .env
# Fill in TARGET_DEV_URL and optional Slack tokens

Em seguida, configure suas rotas em src/config/targets.js:

export const routes = [
  { path: '/',          name: 'Home',      critical: true,  waitFor: 'main' },
  { path: '/login',     name: 'Login',     critical: true,  waitFor: 'form' },
  { path: '/dashboard', name: 'Dashboard', critical: true,  waitFor: '[data-testid="dashboard"]' },
  { path: '/settings',  name: 'Settings',  critical: false, waitFor: null },
];

• critical: true — erros nesta rota vão para #bugs-critical
• waitFor — seletor CSS que o Argus aguarda antes de capturar (sinaliza página pronta)

Comandos CLI

npm run chrome         # Launch Chrome with --remote-debugging-port=9222 (auto-detects binary)
npm run doctor         # Pre-flight check: Chrome reachable, .mcp.json valid, .env has TARGET_DEV_URL
npm run crawl          # Batch audit of all configured routes
npm run compare        # Dev vs staging diff (CSS-only if no staging URL)
npm run watch          # Passive monitor — polls open Chrome tab every 1s
npm run report:html    # Generate reports/report.html from last JSON audit
npm run report:pdf     # Export HTML report to A4 PDF (requires: npm install puppeteer)
npm run server         # Start Slack slash-command server (port 3001)
npm run init           # Interactive setup wizard
npm run test:unit          # 562 unit tests — no Chrome required
npm run test:harness       # 171-block correctness harness — requires Chrome
npm run test:harness:log   # same, but tees full output to harness-results.txt
npm run test:coverage      # merged unit + harness coverage gate (requires Chrome)

Modo de observação — monitoramento ao vivo enquanto você (ou seu agente) desenvolve:

# Terminal 1: start your app
npm run dev

# Terminal 2: start Argus watcher
npm run watch
# Ctrl+C → stops monitor and writes reports/report.html

Comando de barra do Slack (sob demanda, de qualquer canal):

/argus-retest https://staging.example.com/checkout

Para expor o servidor via túnel: cloudflared tunnel --url http://localhost:3001 (gratuito, sem necessidade de conta). Defina a URL resultante como Request URL no Slack App → Slash Commands.

GitHub Actions CI — Portão de PR

O Argus é fornecido como uma GitHub Action composta: em cada PR, ele mapeia o diff para as rotas afetadas, audita-as e bloqueia o merge apenas em descobertas que o PR introduz (ciente da linha de base) — com um comentário de PR idempotente e um Check Run.

Adicione aos segredos do seu repositório (Settings → Secrets → Actions):

O workflow incluído é executado no push para main, diariamente às 6h UTC e em acionamento manual. Se problemas críticos forem encontrados, o pipeline falha.

Variáveis de Ambiente

Solução de Problemas

Primeiro recurso para qualquer problema: npx -y -p argusqa-os argus-doctor — verifica a acessibilidade do Chrome, a validade da configuração MCP e as chaves de ambiente necessárias, e imprime a correção exata para cada falha.

Chrome DevTools MCP não conectando

claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
# Restart Claude Code after adding

Mensagens do Slack não sendo postadas

• O token deve começar com xoxb- (não xoxp-, xoxe- ou xapp-)
• Execute /invite @BugBot em cada canal
• Escopos necessários: chat:write, files:write, files:read

Capturas de tela em branco

• A página não estabilizou — aumente pageSettleMs em src/config/targets.js ou adicione um seletor waitFor para a rota

/argus-retest retorna "dispatch_failed"

• A URL do túnel mudou — atualize a Request URL no Slack App → Slash Commands e reinstale

A análise de CSS retorna resultados vazios

• A página pode estar atrás de autenticação — certifique-se de estar logado na instância do Chrome que o Argus está controlando

O pipeline de CI falha imediatamente

• O Chrome pode não iniciar rápido o suficiente — aumente sleep 3 para sleep 5 em .github/workflows/argus.yml

Como o Argus Difere do Playwright / Cypress

O Argus é uma camada complementar, não um substituto para testes unitários ou E2E:

Limitações Conhecidas

Todas as 998 asserções do harness passam (998/998) — atualmente não há restrições conhecidas de camada MCP ou Chrome. O Lighthouse executa em headless (após a correção do argumento lighthouse_audit); as asserções suaves restantes (traços de performance, crescimento de heap dependente de GC) são promovidas a asserções duras contadas apenas na faixa semanal estrita-suave (harness-strict.yml) via ARGUS_HARNESS_STRICT_SOFT. Limites de escopo: apenas Chrome/Chromium, apenas aplicativos web — veja Works With Your Stack.

Argus Hospedado — Membros Fundadores

Quer auditorias sem executar Chrome ou npm — com histórico, tendências, agendamentos e um painel de equipe? Argus Cloud está em acesso antecipado para membros fundadores: US$ 19/mês, bloqueado para sempre (regular US$ 29).

Torne-se um membro fundador → argus-qa.com

O mecanismo de código aberto nesta página permanece MIT e totalmente funcional, sempre — o nível hospedado vende conveniência e memória, nunca detecções.

Estrutura do Projeto

src/
  argus.js              — single-page audit entry point
  mcp-server.js         — 9 MCP tools exposed to Claude / any MCP client
  orchestration/        — crawl loop, Slack/GitHub dispatch, env comparison, watch mode
  utils/                — 32 analysis engines (accessibility, security, performance, PDF, recording, etc.)
  adapters/browser.js   — CdpBrowserAdapter — wraps all chrome-devtools-mcp calls
  config/targets.js     — routes, thresholds, auth steps
  cli/
    init.js             — argus init interactive setup wizard
    chrome-launcher.js  — npm run chrome / argus-chrome — launches Chrome with correct flags
    doctor.js           — npm run doctor / argus-doctor — pre-flight checks
    pr-validate.js      — headless CI entry point for GitHub Actions
test-harness/           — 171-block correctness harness, 998 hard assertions, 64 fixture pages
test/unit/              — 562 Vitest unit tests (no Chrome required)
landing/                — Product landing page (React 19 + Vite + Tailwind)

Mapa completo do código-fonte → CLAUDE.md · Referência MCP/DSL → SKILL.md

Contribuindo

Contribuições são bem-vindas — páginas de fixture, novas categorias de detecção, descoberta de rotas de framework, documentação. Comece com CONTRIBUTING.md.

1. Faça um fork do repositório e crie uma branch
2. npm run test:unit — verifique sem Chrome (562 testes)
3. npm run test:harness — cobertura completa de integração (requer Chrome na porta 9222)
4. Abra um PR — o Argus audita a si mesmo via o workflow de CI

Licença

MIT © ironclawdevs27