Violin
Supervised agentic pentesting that produces proof, not prose.
Violin runs authorization-scoped penetration tests where every target-touching command passes a required execution guard, gets a signed receipt, and feeds evidence-backed findings. You keep the engagement state, the coverage disposition, and the final call.
hermes profile install https://github.com/Strategic-Automation/violin
Built for the way engagements actually run
Not a toy agent that pops one flag in an artificial CTF box. A disciplined harness for scoped, multi-day client work where every finding must survive client and audit scrutiny.
Scope Checked Per Command
Every target command is AST-resolved against the approved scope before execution starts. Out-of-scope hosts and excluded URL paths are denied fail-closed, not logged-and-run.
Your Tools, Your Image
No tool-specific execution adapters and no fragile binary allowlists: installed non-interactive tooling (nmap, nuclei, ffuf, sqlmap, curl) drives through one boundary.
Coverage You Can Defend
A coverage matrix generated from scope obligations plus methodology disposition gates means every in-scope route and required testing category ends with a disposition — not with silence.
Evidence for the Report
Findings carry severity, summary, and the signed receipts that authenticate decisive request and response bytes — the verifiable artifact needed during client readouts.
Survives Context Compression
PTT tasks, hypotheses, checkpoints, command history, and evidence live in structured state on disk. Long assessments do not reset when prompt context gets summarized.
Human-in-the-Loop by Design
Bounded command bursts are reviewed and settled after execution, pending batches can be rebound, and phase transitions require explicit task activation.
✓ Use it for
- Scoped web, API, identity, business-logic, and LLM-security testing
- Consultants who need per-finding evidence and a defensible coverage story
- Teams that want agent leverage without losing the chain of custody
- Authorized lab, CTF-style, and internal assessment work
✗ Do not use it for
- Anything without written authorization and an approved scope
- Unattended mass scanning of hosts you do not own
- Replacing human judgment on severity, impact, or business context
- Network containment — that is your environment's job, not the profile's
How the approaches differ
Agentic security tools differ less in what they can find and more in what they can answer afterwards. This compares design centres, not named products.
| Architecture Dimension | Autonomous Black-Box Agent | General Agent + Shell Access | Violin Profile |
|---|---|---|---|
| Scope Enforcement | Configured per run; the run is the boundary | Whatever the prompt instructed | Every command validated against an approved scope file, fail-closed |
| Evidence Model | Internal proprietary report output | Markdown prose generated by the model | Signed execution receipts; findings must cite receipts that prove them |
| Coverage Accounting | Whatever built-in checks were executed | Usually unrecorded or forgotten | Coverage matrix with disposition gates closed out at reporting |
| Specialist Methodology | Fixed proprietary check set | Generic reasoning per prompt | 35 routed playbooks across 7 skills, chosen per active PTT task |
| State Across Sessions | Server-side run record | Prompt context window | Persistent engagement state on disk: PTT, hypotheses, checkpoints |
| Tool Execution | Proprietary internal tools | Anything the shell can reach | Guard-gated use of non-interactive tools in your Kali/Parrot image |
| Deployment Model | Hosted SaaS service | Local machine | Local environment, your model config, zero hosted dependencies |
What an engagement looks like
One active task, one routed skill, one guarded command boundary, and signed receipts as you go.
-
1. Scope First
Bootstrap the engagement and approve
scope/scope.yaml. Nothing touches a target before this exists, and the coverage matrix is generated from its obligations. -
2. Activate Exactly One Task
Create and start a PTT task under the current phase, naming the routed specialist skill and concrete technique. Work cannot jump ahead without a registered task.
-
3. Run Guarded Commands
Recon through the exact same boundary as exploitation. A typical command invocation through the registered tool:
// Single guarded command invocation, AST-resolved against scope violin_exec( eng_dir = "engagements/acme-web", phase = "RECON", target = "app.example.com", command = "nmap -sV -sC -T4 app.example.com -oA quick_app", label = "service-discovery" ) // Gates validated → status: ok, signed execution receipt written to disk
-
4. Keep Hypotheses Honest
Hypotheses carry status, confidence, a cheapest test, and kill criteria. Evidence updates status; a hypothesis that survives without proof never becomes a finding.
-
5. Review the Batch
Bounded command bursts are reviewed and settled so engagement state reflects what actually ran, including partial stdout and failures.
-
6. Submit Findings that Cite Receipts
Severity, summary, and decisive evidence.
violin_submit_findingenforces that every vulnerability is bound to the signed receipts authenticating the request and response. -
7. Close Out Coverage, then Report
In-scope routes and required testing categories receive an explicit disposition: tested, negative evidence, or justified exclusion. Then the closeout report.
Coverage: 35 Routed Playbooks
An orchestrator selects the focused playbook for the capability under test across 7 specialist skills instead of loading one giant, unfocused checklist.
Twelve Registered Tools
One typed Hermes registry. No tool-specific execution adapters, no target allowlists. The violin_exec boundary is identical for every non-interactive binary.
| Tool Name | Primary Purpose | Phase / Context |
|---|---|---|
violin_exec |
Execute one guarded command against approved scope | All Phases |
violin_submit_finding |
Submit validated vulnerability bound to signed execution receipts | Validation / Reporting |
violin_record_ptt |
Create, start, refresh, close, or cancel an engagement task | Workflow State |
violin_record_hypothesis |
Create or update scoped hypothesis with cheapest test and kill criteria | Planning |
violin_review_batch |
Review completed command burst and settle engagement state | Synchronization |
violin_exec_burst |
Execute bounded batch of commands with batch review requirements | Execution |
violin_rebind_pending_batch |
Rebind pending batch after operator confirmation | Review Flow |
violin_target |
Resolve approved target and scope authorization parameters | Discovery |
violin_status |
Inspect active tasks, routed skills, and current blockers | Diagnostics |
violin_heartbeat_done |
Clear completed operator review heartbeat | Safety |
violin_exec_status |
Query background process execution and stream logs | Monitoring |
violin_exec_cancel |
Cancel tracked background execution process | Safety |
Engineering Whitepapers
Deep-dive architectural essays exploring why prompt guardrails fail, how evidence is disciplined, and how to rigorously evaluate agentic security systems.
Guardrails for Agentic Pentesting
Why prompt-level guardrails consistently fail at the tool boundary, the required-guard architecture, AST-based command parsing, and how findings bind to signed receipts.
Read Full Whitepaper ↗Coverage Discipline for Agent-Assisted Pentests
How to turn an ad-hoc LLM testing session into a systematic assessment with auditable coverage dispositions, negative evidence tracking, and closeout gates.
Read Full Whitepaper ↗How to Evaluate an Agentic Pentest Tool
A practitioner checklist for cutting through agentic marketing hype: non-determinism distributions, proof rules, and why report prose must receive zero credit without receipts.
Read Full Whitepaper ↗Honest Limits
Most tool pages skip this. The project's own documentation does not, so neither does this page.
A Single Run is a Noisy Sample
Agentic runs vary run to run. Violin reports a distribution — mean pass@1, pass@k, pass^k — and prefers the mean to the best run. A repo test pass is not a live benchmark score.
The Guard is Not Containment
The guard constrains what the agent is allowed to run against an approved scope. It does not isolate your physical network for you; run in an isolated environment.
No Model Choices Baked In
Violin adds no credentials and selects no model provider; it uses your Hermes configuration. Use a capable frontier model — weaker models produce weaker hypotheses, not safer ones.
Receipts Are Not Judgment
Receipts authenticate what was sent and received. Severity, impact, exploitability, and whether a finding belongs in the report remain human calls.
Questions Testers Actually Ask
Direct answers to the most common architectural and operational inquiries.
Does this replace Burp, nmap, or nuclei?
No. It gates and drives the non-interactive tooling already installed in your Kali/Parrot environment, while maintaining the evidence trail and coverage matrix. Interactive proxies and your own manual verification remain essential.
Can it wander out of scope?
The guard denies commands whose resolved target is not in the approved scope. AST parsing handles compound commands, pipelines, and subshells, and path-scoped URL exclusions are strictly honored. The raw-terminal hook is a safety net; run in an isolated lab environment.
Which model should I use?
Whatever your Hermes Agent configuration provides. Violin selects no provider and ships no hardcoded API keys. A capable frontier model is recommended for complex hypothesis formulation.
Can I run it on a live client engagement?
Only with explicit written authorization and an approved scope file. You remain solely responsible for target authorization, legal compliance, and operational safety. Violin is for authorized assessment only.
How does a finding get accepted?
violin_submit_finding validates that the finding is bound to signed execution receipts authenticating the decisive request and response bytes. A claim without receipts is a hypothesis, not a finding.
Where are the benchmark numbers?
In the methodology documentation (docs/BENCHMARKS.md), not in marketing headlines. The project explicitly rejects single-run score claims.
Quick Start
Requirements: Hermes Agent 0.18.0+, Kali Linux or Parrot OS environment, Python 3.11 + uv for development, and written authorization with an approved scope.
$ hermes profile install https://github.com/Strategic-Automation/violin
$ hermes -p violin
# In the Hermes interactive session:
Run an authorized penetration test against example.com.