Get started

Install Violin, approve a scope, and work through your first supervised engagement.

Install the profile

You need Hermes Agent 0.18.0+ configured with a model provider. Kali or Parrot supplies the expected security tools.

hermes profile install https://github.com/Strategic-Automation/violin

Then launch the profile:

hermes -p violin

Before testing: obtain written authorization and approve the target scope. Violin does not provide network containment.

Local development, Docker & release checks

Local development requires Python 3.11 and uv. Docker builds from the repository’s Dockerfile.

$ hermes profile install https://github.com/Strategic-Automation/violin

Your first engagement

Start with an authorized target. Violin collects scope before any target interaction.

Run an authorized penetration test against example.com.

Open a step for the commands and evidence it needs.

01Scope 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.

02Activate 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.

03Run 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

04Keep 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.

05Review the Batch

Bounded command bursts are reviewed and settled so engagement state reflects what actually ran, including partial stdout and failures.

06Submit Findings that Cite Receipts

Severity, summary, and decisive evidence. violin_submit_finding enforces that every vulnerability is bound to the signed receipts authenticating the request and response.

07Close 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.

Common questions

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.

NextUnderstand the guard →