Security Harness

Un harness multi-agente per la revisione della sicurezza applicativa per Claude Code (e, in seguito, altri agenti AI). Una skill router smista verso una pipeline completa di sicurezza offensiva che mappa una codebase, caccia vulnerabilità con una knowledge base per classe, concatena i risultati in escalation, verifica l'impatto reale e riporta su README / JSON / SARIF / doc / PDF.

Ambito: questo harness esegue analisi statica (revisione del codice, tracciamento del flusso di dati, costruzione di PoC/payload) su codice di tua proprietà o che sei autorizzato a testare. Non attacca sistemi terzi live.

Cosa contiene```

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)

### Classi di vulnerabilità coperte (le skill `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. Le CVE delle dipendenze/SBOM sono gestite dalla fase di recon.

## Installazione

L'harness è distribuito per diversi agenti. I dettagli completi sul packaging e la checklist
di rilascio sono in [`docs/DISTRIBUTION.md`](https://github.com/dmdhrumilmistry/security-harness/blob/main/docs/DISTRIBUTION.md).

**Claude Code** - aggiungi questo repo come plugin marketplace e installa il plugin:```
/plugin marketplace add dmdhrumilmistry/security-harness
/plugin install security-harness

/plugin marketplace add accetta uno qualsiasi tra: un owner/repo di GitHub (come sopra), un URL git completo (https://github.com/dmdhrumilmistry/security-harness.git), o un percorso locale a un clone (ad es. /plugin marketplace add ./security-harness dalla directory che contiene il tuo checkout). Poi esegui /plugin install security-harness e ricarica quando richiesto.

Gemini CLI - un'estensione nativa, con manifest alla radice del repo:```bash gemini extensions install https://github.com/dmdhrumilmistry/security-harness

**opencode, Codex o qualsiasi agente [agentskills.io](https://agentskills.io)** - copia le
skill in una directory di discovery. Codex rileva inoltre `AGENTS.md` autonomamente:```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

Graft viene installato e configurato automaticamente dalla pipeline. Lo Stage 0 esegue npm install -g @nanonets/graft se manca (richiede Node/npm), poi graft init <target> --no-agents --no-global per registrare il server MCP di Graft e gli hook di freshness per il repository target. Il grafo stesso (<target>/graft/, auto-gitignored) viene costruito durante la fase di recon. Per pre-installarlo manualmente: npm install -g @nanonets/graft. La build strutturale di Graft è gratuita e non richiede API key; il passaggio LLM opzionale --deep usa GRAFT_API_KEY / GRAFT_PROVIDER / GRAFT_MODEL quando impostati.

Anche gli altri tool vengono installati automaticamente dallo Stage 0 quando mancano (tramite qualunque package manager sia presente sulla macchina - winget/choco/scoop, brew, apt, npm/pip/go - vedi references/tooling-setup.md). Le installazioni vengono annunciate, preferiscono metodi senza elevazione e non bloccano mai l'esecuzione: tutto ciò che non può essere installato viene semplicemente marcato come non disponibile e la pipeline esegue il fallback. Lo Stage 0 installa solo ciò che colma un gruppo di capacità mancante:

• SBOM: syft · CVE: uno tra grype (preferito), trivy, o osv-scanner
• Report: wkhtmltopdf o pandoc (per PDF/DOCX); altrimenti ottieni report.html (o un PDF generato con headless-Chrome).

Tutti sono opzionali - la pipeline degrada in modo controllato verso ricerca nativa + parsing dei manifest se nessuno viene installato.

Utilizzo

Invoca il router con una richiesta in linguaggio naturale:``` /sh-router full security review of ./api /sh-router find SQLi and IDOR in src/ /sh-router just map this codebase # recon only

Oppure chiama direttamente la pipeline:```
/sh-security-review . classes:sqli,access-control,ssrf depth:deep
/sh-security-review . stage:report       # regenerate reports for the latest run

Controllo del modello e dei costi

Ogni fase viene eseguita su un modello adeguato al suo carico cognitivo, così i token vengono spesi dove la qualità della scoperta dipende effettivamente da essi e risparmiati sul lavoro meccanico. Questa è l'impostazione predefinita - non sono necessari argomenti.

Fase	Modello predefinito
recon	sonnet
hunt (per classe)	haiku per le classi di pattern (secrets, crypto, open-redirect, csrf) · sonnet per il tracciamento source→sink (sqli, xss, ssrf, injection, path-traversal, xxe, file-upload, auth) · opus per le classi di logica profonda (access-control, race-conditions, deserialization)
chain	opus
verify	opus (il gate di precisione - mantenuto forte)
report	haiku

Sovrascrivi con l'argomento models: (passato anche attraverso il 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

Stages: `setup, recon, hunt, chain, verify, report`. Models: `opus, sonnet, haiku, inherit`. Per `hunt`,
un modello nudo appiattisce tutti gli hunter su di esso; `hunt.pattern` / `hunt.trace` / `hunt.logic` puntano a un singolo tier.
Altri risparmiatori di token sono integrati: recon genera hunter solo per le classi con una reale superficie d'attacco, gli hunter
interrogano il grafo Graft invece di leggere interi file, e `findings.json`/SARIF sono generati da uno
script deterministico anziché dal modello.

### Output

Tutto finisce sotto `<target>/.security-harness/<run-id>/`:

- `recon.md`, `codebase-map.json` - la mappa (stack, SBOM, CVE, superficie d'attacco).
- `findings.jsonl` → `chains.md` → `verified.jsonl` - lo stato di lavoro (vedi `references/state-files.md`).
- `reports/` - `README.md`, `findings.json`, `results.sarif`, `report.html`, `report.pdf` (+ `report.docx`).

Ogni finding pubblicato porta con sé un payload, un PoC, il verdetto di verifica, gli id CWE/OWASP, il CVSS e una
mitigazione a livello di codice.

## Revisione delle pull request

`sh-pr-review` revisiona una singola pull request anziché un intero codebase, pubblica il
risultato come commenti inline **sulla PR stessa**, e imposta uno stato di commit `security/pr-review`
che la branch protection può far rispettare.