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

> **Para quem é:** quem vai publicar uma feature e quer garantir que não abriu brechas de segurança.
> **Tempo de leitura:** 5 min.
> **O que você vai sair sabendo:**
> - O que `@pentester` cobre (e o que está fora de escopo)
> - As superfícies de ataque que ele mapeia sistematicamente

---

## Para que serve

Segurança não é um checklist de última hora. Mas também não precisa ser uma consultoria de dois meses. `@pentester` ocupa o meio-termo: ele é estruturado, com escopo definido, e produz findings rastreáveis — não uma impressão subjetiva de "parece seguro".

Ele mapeia **superfícies de ataque** da feature (não apenas "checou XSS?"), gera um contrato de revisão antes de começar, e produz findings com ID, severidade, evidência e recomendação. Assim o `@dev` e o `@qa` podem agir sem ambiguidade.

Coberturas recentes adicionadas: **LLM Top 10** (vulnerabilidades específicas de sistemas com IA), **supply chain** (dependências com CVEs conhecidos), **tooling** (ferramentas de build e CI).

**Limite duro de escopo:** ele só atua no workspace local. Qualquer pedido de testar URLs externas, sistemas de terceiros, ou produção real é recusado e registrado como "out of scope".

---

## Dois modos de operação

`@pentester` opera em **dois modos** com catálogos de ataque distintos. O modo é escolhido pelo target da auditoria — não pelo usuário.

| Modo | Quando ativa | O que audita | Catálogo de ataque |
|---|---|---|---|
| **`framework_target`** (padrão) | Você está dentro de um repositório AIOSON (raiz tem `.aioson/`) e a auditoria é sobre o próprio framework | Prompts dos agentes, handoffs entre agentes, `last-handoff.json`, escalada via injeção de contexto, manipulação de `dev-state.md`, leak via `project-pulse.md` | Prompt injection inter-agente, context smuggling, agent impersonation, handoff tampering |
| **`app_target`** | Auditoria explicitamente sobre a aplicação que você está construindo *com* AIOSON (pedido com `--mode=app_target` ou handoff explícito) | Código de aplicação: rotas, autenticação, upload, queries SQL, dependências | OWASP Top 10, LLM Top 10, supply chain CVE, secrets em código |

Os dois modos produzem `security-findings-{slug}.json` com a mesma estrutura, mas o campo `target_mode` distingue. Se a sua feature mexe **tanto** no framework quanto na app (raro), rode os dois separadamente — não misture.

---

## Quando invocar

- Antes de publicar uma feature para produção.
- Quando a feature toca autenticação, pagamentos, upload de arquivos, ou dados sensíveis.
- Quando você quer um audit point de segurança antes de uma release.
- Quando o `@tester` encontrou indícios de problemas de segurança.

---

## Quando NÃO invocar

- Você quer testar segurança de um sistema externo (API de terceiro, site alheio) → recusado por design.
- Você quer validação de comportamento funcional → use `@qa`.
- Você quer cobertura de testes → use `@tester`.

---

## Diálogo típico

```
Você > @pentester

@pentester > Qual feature está sob revisão? (slug)
Você > checkout-stripe

@pentester > Carregando prd-checkout-stripe.md e spec-checkout-stripe.md...
             security-findings-checkout-stripe.json não existe — criando novo.
             
             Gerando review contract...
             
             Superfícies de ataque mapeadas para checkout-stripe:
             TS-checkout-stripe-01: memory_context     → injeção via context files
             TS-checkout-stripe-02: tool_invocation    → path traversal em Bash
             TS-checkout-stripe-03: secret_handling    → API key Stripe em logs
             TS-checkout-stripe-04: supply_chain       → dependência stripe@npm vulnerável?
             
             Revisando...
             
             Findings:
             HIGH  SEC-CS-01: stripe secret key aparece em dev-state.md linha 12
             MEDIUM SEC-CS-02: sem rate-limit no POST /checkout
             LOW   SEC-CS-03: dependência stripe@11.x — verificar CVE
             
             security-findings-checkout-stripe.json gravado.
             Recomendações prontas para @dev resolver HIGH/MEDIUM antes da release.
```

---

## Saídas em disco

| Arquivo | Conteúdo |
|---|---|
| `.aioson/context/security-findings-{slug}.json` | Findings com ID, severidade, evidência, recomendação |
| `.aioson/context/security-findings-project.json` | Findings de nível projeto (quando relevante) |

---

## Como ele lê seu projeto

- `.aioson/context/project.context.md` — confirma workspace e layout
- `.aioson/context/prd-{slug}.md` e `spec-{slug}.md` — mapa de superfície de ataque
- `.aioson/context/security-findings-{slug}.json` — findings anteriores (para não duplicar)
- `.aioson/rules/security-baseline.md` — controles `SEC-SBD-01..08` obrigatórios

---

## Superfícies cobertas

**Obrigatórias para qualquer feature:**

| ID | Tipo | O que verifica |
|---|---|---|
| TS-{slug}-01 | `memory_context` | Injeção de prompt, contaminação de context files |
| TS-{slug}-02 | `tool_invocation` | Chamadas shell inseguras, path traversal |
| TS-{slug}-03 | `delegation_handoff` | Escalada de trust em `last-handoff.json` |
| TS-{slug}-04 | `protocol_contract` | Violações de schema, bypass de workflow |
| TS-{slug}-05 | `secret_handling` | Credenciais em context files, logs, prompts |
| TS-{slug}-06 | `runtime_permissions` | Bypass de política de autonomia |

**Condicionais (quando aplicável):** OWASP Top 10 Web (input injection, broken auth, etc.), LLM Top 10 (prompt injection, training data leakage, etc.), supply chain (CVEs em dependências).

---

## Handoff típico

- **Vem de:** você diretamente, ou `@tester` (que encontrou indício)
- **Vai para:** `@dev` (para corrigir findings HIGH/MEDIUM) → `@qa` (re-validação)

---

## Próximo passo

- [Ficha do @qa](./qa.md) — re-valida após correções
- [Ficha do @dev](./dev.md) — corrige os findings
- [Glossário: Zero Trust, Security Baseline](../1-entender/glossario.md#zero-trust)
