Profilo di pentest agentico per Hermes: 31 playbook per ricognizione autorizzata, attacchi web/controllo accessi, validazione sicura degli exploit e reportistica basata su evidenze con guard gate.
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/50022/55f1c11f1fa53cb32838b487d5b5b6f1745b609c7123ce0a2b28ff21108c765b.png" alt="Violin" width="256"/>
</p>
<h1 align="center">Violin ☤ — Profilo di pentest agentico supervisionato per Hermes</h1>
<p align="center">
<a href="https://github.com/Strategic-Automation/violin"><img src="https://img.shields.io/badge/Status-Release%20Ready-2ea44f?style=for-the-badge" alt="Release Ready"></a>
<a href="https://github.com/Strategic-Automation/violin/blob/master/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue?style=for-the-badge" alt="License: MIT"></a>
<a href="https://hermes-agent.nousresearch.com/"><img src="https://img.shields.io/badge/Hermes-%3E=0.21.5-FFD700?style=for-the-badge" alt="Hermes >=0.21.5"></a>
<a href="https://www.kali.org/"><img src="https://img.shields.io/badge/Kali%20Linux-557C94?style=for-the-badge&logo=kali-linux&logoColor=white" alt="Kali Linux"></a>
<a href="https://www.parrotsec.org/"><img src="https://img.shields.io/badge/Parrot%20OS-2E8B57?style=for-the-badge" alt="Parrot OS"></a>
<a href="https://strategic-automation.github.io/violin/"><img src="https://img.shields.io/badge/Site-Landing%20page-FF3B4A?style=for-the-badge" alt="Landing page"></a>
<a href="https://github.com/Strategic-Automation/violin/stargazers"><img src="https://img.shields.io/github/stars/Strategic-Automation/violin?style=for-the-badge&color=FFD166" alt="GitHub stars"></a>
</p>
<p align="center">
<b>35 playbook · 19 reference · 14 template · guard di esecuzione obbligatorio · nativo per Hermes</b>
</p>
Violin è un **profilo di pentest agentico nativo per Hermes** per penetration test supervisionati e autorizzati — dalla ricognizione alla validazione sicura degli exploit fino al reporting. Utilizza i toolset integrati di Hermes, sette skill instradate e il plugin obbligatorio `violin_guard` al confine dell'esecuzione sul target. La CLI standalone supporta controlli di rilascio, diagnostica e ripristino amministrativo; i comandi sul target vengono eseguiti tramite il plugin. Violin non aggiunge credenziali specifiche del profilo ed eredita i backend di provider e strumenti già configurati in Hermes.
<p align="center">
<a href="#quick-start">Avvio rapido</a> ·
<a href="#engagement-lifecycle">Flusso di lavoro</a> ·
<a href="#guard-tools">Strumenti di guardia</a> ·
<a href="#benchmarks">Benchmark</a> ·
<a href="https://strategic-automation.github.io/violin/">Landing page</a> ·
<a href="https://github.com/Strategic-Automation/violin/discussions">Discussioni</a> ·
<a href="#development">Sviluppo</a>
</p>
<p align="center">
<strong>Segui Violin?</strong>
<a href="https://github.com/Strategic-Automation/violin/stargazers">Metti una stella al repository</a>
per mantenerlo facilmente reperibile e aiutare altri ingegneri della sicurezza a scoprire il pentesting agentico supervisionato.
</p>
### Scoperta nella community
Violin è elencato in raccolte curate dalla community tra cui
[awesome-ai-security](https://github.com/gmh5225/awesome-ai-security),
[awesome-hermes-skills](https://github.com/ZeroPointRepo/awesome-hermes-skills),
[awesome-hermes-agent](https://github.com/Anil-matcha/awesome-hermes-agent) e
[awesome-infosec](https://github.com/onlurking/awesome-infosec).
Copertura di terze parti:
[analisi tecnica di Starlog](https://starlog.is/articles/cybersecurity/strategic-automation-violin) e
[“Violin: Supervised Agentic Penetration Testing Profile for Hermes Agent”](https://hamradio.my/violin-supervised-agentic-pentest-profile-hermes/).
Per una valutazione indipendente, utilizza il
[kit per i revisori](https://strategic-automation.github.io/violin/review.html), che
raccoglie il percorso dei benchmark, i limiti noti, il contesto di revisione e un confronto
fattuale con i design dei pentest-agent autonomi.
---
<table>
<tr><td width="240"><strong>Esecuzione controllata del target</strong></td><td>I controlli di scope, fase, PTT, skill, ipotesi, cronologia e sincronizzazione vengono eseguiti prima dell'avvio di un comando sul target.</td></tr>
<tr><td><strong>Stato di engagement persistente</strong></td><td>Attività PTT, ipotesi, cronologia dei comandi, checkpoint, evidenze e report sopravvivono alla compressione del contesto.</td></tr>
<tr><td><strong>Risultati supportati da evidenze</strong></td><td>Una sottomissione tipizzata collega ogni risultato validato a ricevute di esecuzione autenticate.</td></tr>
<tr><td><strong>Metodologia instradata</strong></td><td>Un orchestratore di pentest seleziona playbook mirati per web, identità, API, business-logic, sicurezza LLM e misconfigurazioni.</td></tr>
<tr><td><strong>Esecuzione limitata</strong></td><td>Comandi singoli, raffiche di comandi, processi in background, revisione batch, controlli heartbeat e cancellazione condividono un unico modello di stato.</td></tr>
<tr><td><strong>Release verificabili</strong></td><td>Registrazione dei plugin, schemi, snapshot delle skill, contratti della documentazione, lint, formattazione e l'intera suite di test sono vincolati al rilascio.</td></tr>
</table>
## Avvio rapido
### Installare il profilo
```bash
hermes profile install https://github.com/Strategic-Automation/violin
hermes -p violin plugins disable violin_guard
hermes -p violin plugins enable violin_guard --no-allow-tool-override
hermes -p violin
```
Le dipendenze di Guard sono dichiarate in `plugins/violin_guard/plugin.yaml`. Il nome del plugin, la directory e la configurazione di abilitazione usano tutti `violin_guard`, così Hermes può risolvere le sue dipendenze senza un workaround sulla directory. Installare le dipendenze nella `.venv` di sviluppo non le installa in Hermes. Il ciclo di disabilitazione/abilitazione sopra forza l'ammissione delle dipendenze anche quando la configurazione del profilo abilita già il plugin. Verificare la registrazione dopo l'installazione:
```bash
hermes -p violin plugins doctor ~/.hermes/profiles/violin/plugins/violin_guard --ci
hermes -p violin tools list
```
Plugin Doctor dovrebbe riportare 12 strumenti e 5 hook, e `violin_guard` dovrebbe apparire
come toolset abilitato. Riavvia Hermes dopo l'installazione prima di iniziare un
engagement. Reinstalla il profilo per migrare un'installazione precedente di `violin-guard`.
Poi inizia con un target autorizzato e lascia che Violin raccolga lo scope prima
di qualsiasi interazione con il target:
```text
Run an authorized penetration test against example.com.
```
### Requisiti
- [Hermes Agent](https://hermes-agent.nousresearch.com/) 0.21.5 o superiore (il container fissa il commit di rilascio `v2026.9.24`)
- Python 3.11 e `uv` per lo sviluppo locale
- Kali Linux o Parrot OS per l'ambiente previsto con gli strumenti di sicurezza
- Autorizzazione scritta e un perimetro approvato
Violin non seleziona un modello o un provider. Configurali in Hermes. Per un
default adeguato, usa **Qwen3.8 27B** in locale oppure **DeepSeek V4 Flash** tramite un
provider ospitato.
## Ciclo di vita dell'engagement
```mermaid
flowchart LR
S[Scope] --> R[Recon]
R --> V[Vulnerability research]
V --> E[Exploit validation]
E --> P[Reporting]
P --> X[Retrospective]
G[Violin Guard] -. validates .-> R
G -. validates .-> V
G -. validates .-> E
```
1. Inizializza l'engagement e approva `scope/scope.yaml`.
2. Seleziona un'attività PTT attiva e la relativa skill instradata con
`violin_record_ptt`.
3. Esegui i comandi sul target con `violin_exec` o `violin_exec_burst`.
4. Aggiorna le ipotesi man mano che le evidenze ne modificano lo stato.
5. Rivedi ogni batch di comandi delimitato con `violin_review_batch`.
6. Invia i risultati validati e genera il report finale.
7. Completa la retrospettiva.
Il modello completo delle fasi è:
```text
SCOPING → RECON → VULN_RESEARCH → EXPLOITATION
→ POST_EXPLOITATION / PRIVESC / FLAGS
→ REPORTING → RETROSPECTIVE
```
L'inizio del lavoro in una nuova fase richiede un'attività PTT sotto quella fase. Le attività esistenti non vengono spostate tra le sezioni delle fasi.
## Strumenti di protezione
Il plugin registra dodici strumenti Hermes da un unico registro tipizzato:
| Strumento | Scopo |
|---|---|
| `violin_record_ptt` | Crea, avvia, aggiorna, chiude o annulla un'attività PTT |
| `violin_record_hypothesis` | Crea o aggiorna un'ipotesi con ambito definito |
| `violin_submit_finding` | Invia un risultato validato vincolato alle sue ricevute di esecuzione firmate |
| `violin_exec` | Esegue un singolo comando protetto |
| `violin_exec_burst` | Esegue un file di comandi con limiti definiti |
| `violin_exec_status` | Legge lo stato di esecuzione in background |
| `violin_exec_cancel` | Annulla l'esecuzione in background tracciata |
| `violin_review_batch` | Esamina un batch completato e stabilizza lo stato |
| `violin_rebind_pending_batch` | Ricollega un batch in sospeso dopo conferma |
| `violin_heartbeat_done` | Cancella una revisione heartbeat completata |
| `violin_target` | Risolve il target di valutazione approvato |
| `violin_status` | Spiega le attività, le competenze e i blocchi correnti |
`violin_exec` è il confine generico per i comandi sul target. Non esistono
adattatori di esecuzione specifici per strumento né allowlist di binari. Gli strumenti
non interattivi installati possono essere eseguiti solo dopo il superamento dei gate di engagement.
L'hook del terminale grezzo è una rete di sicurezza best-effort, non un contenimento di rete.
Usare `terminal` solo per la preparazione e l'amministrazione locale all'host.
## Modello di sicurezza
```mermaid
flowchart LR
A[Written authorization] --> B[Approved scope]
B --> C[Active phase task]
C --> D[Skill and hypothesis gates]
D --> E[Guarded execution]
E --> F[Evidence receipt]
F --> G[Batch review]
```
- Nessuna interazione con il target prima dell'approvazione dello scope e della validazione del bootstrap.
- Nessuna esecuzione diretta di shell per i comandi sul target.
- Nessuna azione distruttiva, di disturbo, relativa a credenziali, di persistenza, stealth o verso terzi senza esplicita autorizzazione scritta.
- Le evidenze grezze restano sotto `$ENG_DIR/evidence/<phase>/`.
- Segreti, dump e output di proof restano fuori da `$ENG_DIR/state/`.
- La compressione del contesto riprende dai file di engagement nella conversazione Hermes corrente.
La policy dettagliata è
[`skills/pentest/references/standards.md`](https://github.com/strategic-automation/violin/blob/master/skills/pentest/references/standards.md).
## Stato dell'engagement
`init-engagement` crea la struttura di lavoro canonica:
```text
$ENG_DIR/
├── scope/
│ └── scope.yaml
├── state/
│ ├── ptt.md
│ ├── history.md
│ └── checkpoint.json
├── hypotheses.md
├── evidence/
├── reporting/
└── retrospective/
```
### Aggiornamento da Violin 3.3
Violin 4.0 memorizza lo stato dell'esecutore in `state/runtime.json` e non migra
i file `sync.json`, `counts.json` o `heartbeat.json` della versione 3.3. Avvia un nuovo
engagement in una nuova directory; conserva la directory 3.3 come registro storico.
Riusare la sua directory lascia in posizione i file di stato legacy, quindi Violin 4.0
la rifiuterà.
### Consegna delle skill
Le skill vengono caricate su richiesta. La prima chiamata a `violin_record_ptt` per una skill
instradata può restituire `skill_prepared` senza modificare il PTT. Dopo che Hermes
ha consegnato il contenuto della skill, ripeti la transizione per associare la ricevuta e applicare
la modifica del task. `violin_status` riporta l'azione di recupero esatta.
I file marker come `.skill-loaded-*` non dimostrano la consegna della skill.
## Skill instradate
| Skill | Copertura |
|---|---|
| `pentest` | Scope, ciclo di vita, ricognizione, sfruttamento, reporting, chiusura |
| `web-app` | Injection, SSRF, traversal, deserializzazione, vulnerabilità lato client |
| `identity-auth` | Autenticazione, autorizzazione, IDOR, JWT, CSRF, crittografia |
| `api-testing` | REST, SOAP, GraphQL, WebSocket |
| `business-logic` | Workflow, prezzi, coupon, quota, referral, race condition |
| `llm-security` | Prompt injection, MCP, JSON-RPC |
| `misconfig` | Deployment, gestione degli errori, osservabilità, oscurità |
L'orchestratore carica solo il materiale della fase e il playbook specialistico necessari
per il task corrente.
## CLI amministrativa
La CLI non sostituisce l'esecuzione protetta del target.
```bash
python scripts/violin_guard.py --help
python scripts/violin_guard.py init-engagement engagements/example --host example.com
python scripts/violin_guard.py check-bootstrap --eng-dir engagements/example
python scripts/violin_guard.py status --eng-dir engagements/example
python scripts/violin_guard.py generate-closeout --eng-dir engagements/example
python scripts/violin_guard.py check-release
```
`check-command` espone controlli di ammissione per la diagnostica e non esegue
il comando fornito.
## Architettura
```text
plugins/violin_guard/
├── core/
│ ├── commands/ shell parsing, targets, HTTP proof
│ ├── engagement/ state, PTT, phases, hypotheses, bootstrap
│ ├── evidence/ findings, history, receipts, redaction
│ └── skills/ skill policy and receipts
├── gates/ command, scope, hypothesis, terminal policies
├── engine/ execution, runtime backend, code audit, release checks
├── handlers/ public Hermes tool handlers
├── hooks.py Hermes lifecycle hooks
└── registry.py registered tool definitions
skills/ orchestrator, routed skills, playbooks, references
benchmark/ runner, scorer, proof checks, calibration fixtures
scripts/ administrative CLI and platform smoke tests
tests/ runtime, integration, documentation, release tests
```
## Benchmark
Il repository include la definizione di Escape Duck Store insieme a fixture dello scorer note come valide e note come non valide. La calibrazione dimostra che lo scorer gestisce tali fixture; non stabilisce il recall degli agenti live, il completamento dei workflow o la qualità dei report.
```bash
uv run python -m benchmark.score --calibrate known-good
uv run python -m benchmark.score --calibrate known-bad
uv run python -m benchmark.run \
--target http://localhost:<published-port> \
--provider <provider> \
--api-base <openai-compatible-base-url> \
--model <model-id> \
--target-isolation-id escape-duck-store-2026-04:<image-digest-or-reset-id>
```
Leggi la [metodologia di benchmark](https://github.com/strategic-automation/violin/blob/master/docs/BENCHMARKS.md) prima di pubblicare un punteggio.
Definisce i requisiti di prova, riproducibilità, valutazione privata e divulgazione
per un risultato credibile.
## Sviluppo
```bash
uv sync --dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run python scripts/violin_guard.py check-release
```
Il gate di rilascio verifica le superfici di versione, l'import isolato dei plugin, i tool registrati, gli schemi generati, gli snapshot delle skill, i contratti della documentazione, Ruff e l'intera suite di test.
Smoke test multipiattaforma:
- `scripts/smoke-test.sh` — smoke test di rilascio per Linux e Kali/Parrot
- `scripts/smoke-test.ps1` — smoke test per bootstrap, scope e risoluzione dei target su Windows; la consegna delle skill e l'esecuzione dei target richiedono Hermes
Consulta [CONTRIBUTING.md](https://github.com/strategic-automation/violin/blob/master/CONTRIBUTING.md) per le regole di contribuzione e
[SECURITY.md](https://github.com/strategic-automation/violin/blob/master/SECURITY.md) per la segnalazione privata delle vulnerabilità.
## Uso responsabile
Violin è destinato alle valutazioni di sicurezza autorizzate. Gli operatori sono responsabili di
scope, approvazioni, proprietà dei target, gestione dei dati e legge locale.
## Supporta Violin
Violin è un progetto open-source mantenuto da Strategic Automation Ltd.
Se Violin è utile a te o alla tua organizzazione, puoi
[sponsorizzarne lo sviluppo continuo](https://github.com/sponsors/Strategic-Automation).
La sponsorizzazione sostiene lo sviluppo continuo, i test, la documentazione,
il lavoro di compatibilità e le release.
Violin rimane disponibile con licenza MIT. La sponsorizzazione non include
supporto garantito, priorità sulle funzionalità o influenza sulla politica di sicurezza.
## Licenza
MIT — vedi [LICENSE](https://github.com/strategic-automation/violin/blob/master/LICENSE).