Security Harness

Um harness de revisão de segurança de aplicações multiagente para o Claude Code (e, posteriormente, outros agentes de IA). Uma skill de roteamento despacha para um pipeline completo de segurança ofensiva que mapeia uma base de código, caça vulnerabilidades com uma base de conhecimento por classe, encadeia descobertas em escalonamentos, verifica o impacto real e reporta para README / JSON / SARIF / doc / PDF.

Escopo: este harness realiza análise estática (revisão de código-fonte, rastreamento de fluxo de dados, construção de PoC/payload) em código que você possui ou está autorizado a testar. Ele não ataca sistemas terceiros em produção.

O que está incluído```

security-harness/ # a plugin marketplace └── plugins/security-harness/ ├── skills/ │ ├── sh-router # single entry point - routes any appsec request │ ├── sh-security-review # the pipeline orchestrator (Stages 0-5) │ └── sh-kb-* (15) # per-vuln-class knowledge bases ├── agents/ │ ├── sh-recon # map: Graft graph + stack/SBOM/CVE + attack surface │ ├── sh-hunter # find: source→sink hunting, one per class (parallel) │ ├── sh-chainer # escalate: combine findings into attack chains │ ├── sh-verifier # confirm: offensive + seceng + dev verification + PoC │ └── sh-reporter # deliver: README/JSON/SARIF/HTML/PDF/doc └── references/ # shared contracts (finding schema, SARIF map, state files, rubrics)

### Classes de vulnerabilidade cobertas (as skills `sh-kb-*`)

access-control (IDOR/BOLA/priv-esc) · sqli · xss · ssrf · injection (cmd/code/SSTI/LDAP) · auth (session/JWT)
· deserialization · path-traversal (LFI/RFI) · secrets · csrf · xxe · open-redirect · crypto · race-conditions
· file-upload. CVEs de dependências/SBOM são tratados pelo estágio de recon.

## Instalação

O harness é distribuído para vários agentes. Detalhes completos de empacotamento e a checklist
de release estão em [`docs/DISTRIBUTION.md`](https://github.com/dmdhrumilmistry/security-harness/blob/main/docs/DISTRIBUTION.md).

**Claude Code** - adicione este repositório como um marketplace de plugins e instale o plugin:```
/plugin marketplace add dmdhrumilmistry/security-harness
/plugin install security-harness

/plugin marketplace add aceita qualquer um dos seguintes: um owner/repo do GitHub (como acima), uma URL git completa (https://github.com/dmdhrumilmistry/security-harness.git), ou um caminho local para um clone (por exemplo, /plugin marketplace add ./security-harness a partir do diretório que contém o seu checkout). Em seguida, execute /plugin install security-harness e recarregue quando solicitado.

Gemini CLI - uma extensão nativa, com manifesto na raiz do repositório:```bash gemini extensions install https://github.com/dmdhrumilmistry/security-harness

**opencode, Codex, ou qualquer agente [agentskills.io](https://agentskills.io)** - copie as
skills para um diretório de descoberta. O Codex adicionalmente captura `AGENTS.md` por conta própria:```bash
git clone https://github.com/dmdhrumilmistry/security-harness
cd security-harness
python3 scripts/sync-agent-skills.py --install agents     # ~/.agents/skills
python3 scripts/sync-agent-skills.py --install opencode   # ~/.config/opencode/skills

O Graft é instalado e configurado automaticamente pelo pipeline. O Estágio 0 executa npm install -g @nanonets/graft se estiver em falta (requer Node/npm), depois graft init <target> --no-agents --no-global para registar o servidor MCP do Graft e os hooks de frescura para o repositório alvo. O grafo em si (<target>/graft/, auto-gitignored) é construído durante o recon. Para pré-instalar manualmente: npm install -g @nanonets/graft. A construção estrutural do Graft é gratuita e não precisa de chave de API; a passagem LLM opcional --deep usa GRAFT_API_KEY / GRAFT_PROVIDER / GRAFT_MODEL quando definidos.

As outras ferramentas também são auto-instaladas pelo Estágio 0 quando em falta (através do gestor de pacotes que estiver na máquina - winget/choco/scoop, brew, apt, npm/pip/go - ver references/tooling-setup.md). As instalações são anunciadas, preferem métodos sem elevação e nunca bloqueiam a execução: tudo o que não puder ser instalado é simplesmente marcado como indisponível e o pipeline recorre a alternativas. O Estágio 0 instala apenas o que preenche um grupo de capacidades em falta:

• SBOM: syft · CVEs: um de grype (preferido), trivy, ou osv-scanner
• Relatórios: wkhtmltopdf ou pandoc (para PDF/DOCX); caso contrário obtém report.html (ou um PDF headless-Chrome).

Todos eles são opcionais - o pipeline degrada graciosamente para pesquisa nativa + análise de manifestos se nenhum for instalado.

Utilização

Invoque o router com um pedido em linguagem natural:``` /sh-router full security review of ./api /sh-router find SQLi and IDOR in src/ /sh-router just map this codebase # recon only

Ou chame o pipeline diretamente:```
/sh-security-review . classes:sqli,access-control,ssrf depth:deep
/sh-security-review . stage:report       # regenerate reports for the latest run

Controle de modelo e custo

Cada estágio é executado em um modelo adequado à sua carga cognitiva, de modo que os tokens são gastos onde a qualidade da descoberta realmente depende deles e economizados em trabalho mecânico. Este é o padrão - nenhum argumento necessário.

Estágio	Modelo padrão
recon	sonnet
hunt (por classe)	haiku para classes de padrão (secrets, crypto, open-redirect, csrf) · sonnet para rastreamento source→sink (sqli, xss, ssrf, injection, path-traversal, xxe, file-upload, auth) · opus para classes de lógica profunda (access-control, race-conditions, deserialization)
chain	opus
verify	opus (o portão de precisão - mantido forte)
report	haiku

Substitua com o argumento models: (também passado pelo router):``` /sh-security-review . # default tiered map above /sh-security-review . models:max # every stage + hunter on opus (max quality, max cost) /sh-security-review . models:cheap # aggressive downshift (trades some verify precision) /sh-security-review . models:verify=opus,hunt=sonnet # per-stage overrides /sh-security-review . models:report=sonnet,hunt.pattern=sonnet # per-hunter-tier override

Estágios: `setup, recon, hunt, chain, verify, report`. Modelos: `opus, sonnet, haiku, inherit`. Para `hunt`,
um modelo simples nivela todos os hunters para ele; `hunt.pattern` / `hunt.trace` / `hunt.logic` visam um nível.
Outros economizadores de tokens são incorporados: o recon só gera hunters para classes com superfície de ataque real, os hunters
consultam o grafo Graft em vez de ler arquivos inteiros, e `findings.json`/SARIF são gerados por um
script determinístico em vez do modelo.

### Saída

Tudo fica em `<target>/.security-harness/<run-id>/`:

- `recon.md`, `codebase-map.json` - o mapa (stack, SBOM, CVEs, superfície de ataque).
- `findings.jsonl` → `chains.md` → `verified.jsonl` - o estado de trabalho (veja `references/state-files.md`).
- `reports/` - `README.md`, `findings.json`, `results.sarif`, `report.html`, `report.pdf` (+ `report.docx`).

Cada achado publicado carrega um payload, um PoC, o veredito de verificação, ids CWE/OWASP, CVSS e uma
mitigação em nível de código.

## Revisão de pull request

`sh-pr-review` revisa um único pull request em vez de todo um codebase, publica o
resultado como comentários inline **no próprio PR**, e define um status de commit `security/pr-review`
que a proteção de branch pode impor.