# @pentester — Revisão adversarial de segurança opt-in

> **Para quem é:** quem quer uma auditoria de segurança delimitada e autorizada.

## Para que serve

Pentester mapeia superfícies de ataque, executa checks autorizados e produz findings com severidade, evidência e recomendação. Quando o hardening é determinístico e preserva os contratos aprovados, ele também pode implementar uma correção limitada.

Ele começa desligado em todas as classificações. MEDIUM não o torna inline nem automático.

## Quando invocar

- O usuário pede uma auditoria.
- O plano aprovado exige revisão para uma superfície sensível.
- QA encontra evidência concreta que justifica investigação de segurança especializada.
- Uma release precisa de cobertura adicional antes da decisão humana.

## Escopo e relatório

Duas escolhas definem o custo da execução e são resolvidas antes de qualquer probe:

- **Escopo** (`--scope-mode=`): `feature` (uma feature registrada), `simple-plan` (um plano simples e seus paths), `paths` (pastas/arquivos explícitos em `--paths=`), `routes` (rotas/URL local em `--routes=`) ou `project` (todas as superfícies alcançáveis do projeto, em profundidade `comprehensive`).
- **Relatório** (`--report=full|none`, ou `--no-report`): `full` gera o pacote HTML localizado de quatro páginas; `none` é o modo econômico — só o JSON autoritativo mais um resumo curto na resposta, gastando menos tokens.

O comando completo é o do agente. Exemplos:

```text
/aioson:agent:pentester --scope-mode=feature
/aioson:agent:pentester --scope-mode=paths --paths=src/auth,src/routes --report=none
/aioson:agent:pentester --scope-mode=project --report=full
```

Quando as flags, o handoff ou o próprio pedido já respondem, o agente não pergunta. Caso contrário ele faz uma única pergunta com o alvo concreto e o custo relativo de cada opção.

**Slug nunca é adivinhado.** Com `--scope-mode=feature` sem slug, o agente lista as features reais do projeto (`aioson feature:list . --json`) e pede para você escolher; com `--scope-mode=simple-plan`, lista os planos em `.aioson/context/simple-plans/`. Se a lista estiver vazia, ele diz isso e oferece `paths`, `routes` ou `project`.

O relatório nunca é obrigatório e nunca é perdido:

```bash
aioson pentester:report .                              # lista as execuções salvas e quais já têm HTML
aioson pentester:report . --feature=<slug> --json      # monta o pacote de uma delas
```

O segundo comando monta o mesmo pacote depois, a partir do JSON persistido, sem repetir os probes. O modo econômico não afeta cobertura, evidência, severidade nem correção — só a projeção HTML.

## Execução

Uma chamada direta do usuário já habilita aquela execução do Pentester. Para QA/Autopilot invocá-lo automaticamente, a entrada `pentester` precisa estar habilitada em `agent-execution-{slug}.json` e ter um gatilho aplicável. A chamada direta não liga execuções futuras. O escopo deve ser autorizado; sistemas externos fora do escopo são recusados.

Antes de editar, Pentester persiste o finding e `allowed_fix_paths`. Uma execução direta com Pentester desabilitado adiciona `--manual` ao avanço sem alterar o manifesto. O CLI valida os paths, captura o baseline Git e bloqueia o retorno ao QA quando o diff sai do escopo. A correção local deve ser reproduzível, caber em até 3 arquivos de comportamento / 5 paths totais, não mudar API pública, modelo de permissão, dados, arquitetura, migração ou dependência, e possuir teste/probe direcionado. Ela roda em ciclo finito e volta ao QA como `needs_validation`.

Findings transversais ou decisões de risco/permissão voltam uma única vez ao DEV/owner. QA sempre faz a aceitação independente e continua sendo o único dono do Gate D.

## Handoff típico

- **Vem de:** usuário, plano ou finding concreto de QA.
- **Vai para:** DEV para correção transversal e QA para validar findings ou hardening limitado.

## Veja também

- [Receita de auditoria de segurança](../3-receitas/auditoria-seguranca.md)
- [Ficha do @qa](./qa.md)
- [Secure by Default](../5-referencia/secure-by-default.md)