Violin ☤ — Supervised Agentic Hermes Pentest Profile

35 playbooks · 19 references · 14 templates · required execution guard · Hermes-native

Violin is a Hermes-native agentic pentest profile for supervised, authorised penetration tests — from reconnaissance through safe exploit validation to reporting. It uses Hermes' built-in toolsets, seven routed skills, and the required violin-guard plugin at the target-execution boundary. The standalone CLI supports release checks, diagnostics, and administrative recovery; target commands run through the plugin. Violin adds no profile-specific credentials and inherits the provider and tool backends already configured in Hermes.

Quick start · Workflow · Guard tools · Benchmarks · Landing page · Discussions · Development

Guarded target execution	Scope, phase, PTT, skill, hypothesis, history, and synchronization checks run before a target command starts.
Persistent engagement state	PTT tasks, hypotheses, command history, checkpoints, evidence, and reports survive context compression.
Evidence-backed findings	A typed submission binds each validated finding to authenticated execution receipts.
Routed methodology	A pentest orchestrator selects focused web, identity, API, business-logic, LLM-security, and misconfiguration playbooks.
Bounded execution	Single commands, command bursts, background processes, batch review, heartbeat checks, and cancellation share one state model.
Verifiable releases	Plugin registration, schemas, skill snapshots, documentation contracts, lint, formatting, and the full test suite are release-gated.

Quick start

Install the profile

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

Then start with an authorized target and let Violin collect the scope before any target interaction:

Run an authorized penetration test against example.com.

Requirements

Hermes Agent 0.18.0 or newer
Python 3.11 and uv for local development
Kali Linux or Parrot OS for the expected security-tool environment
Written authorization and an approved scope

Violin does not select a model or provider. Configure those in Hermes. For a capable default, use Qwen3.8 27B locally or DeepSeek V4 Flash through a hosted provider.

Engagement lifecycle

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

Initialize the engagement and approve scope/scope.yaml.
Select one active PTT task and its routed skill with violin_record_ptt.
Run target commands with violin_exec or violin_exec_burst.
Update hypotheses as evidence changes their status.
Review each bounded command batch with violin_review_batch.
Submit validated findings and generate the final report.
Complete the retrospective.

The complete phase model is:

SCOPING → RECON → VULN_RESEARCH → EXPLOITATION
         → POST_EXPLOITATION / PRIVESC / FLAGS
         → REPORTING → RETROSPECTIVE

Starting work in a new phase requires a PTT task under that phase. Existing tasks are not moved between phase sections.

Guard tools

The plugin registers twelve Hermes tools from one typed registry:

Tool	Purpose
`violin_record_ptt`	Create, start, refresh, close, or cancel a PTT task
`violin_record_hypothesis`	Create or update a scoped hypothesis
`violin_submit_finding`	Submit a validated finding bound to its signed execution receipts
`violin_exec`	Execute one guarded command
`violin_exec_burst`	Execute a bounded command file
`violin_exec_status`	Read background execution status
`violin_exec_cancel`	Cancel tracked background execution
`violin_review_batch`	Review a completed batch and settle state
`violin_rebind_pending_batch`	Rebind a pending batch after confirmation
`violin_heartbeat_done`	Clear a completed heartbeat review
`violin_target`	Resolve the approved assessment target
`violin_status`	Explain current tasks, skills, and blockers

violin_exec is the generic target-command boundary. There are no tool-specific execution adapters or binary allowlists. Installed non-interactive tools may run only after the engagement gates pass.

The raw-terminal hook is a best-effort safety net, not network containment. Use terminal only for host-local preparation and administration.

Safety model

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]

No target interaction before scope approval and bootstrap validation.
No raw shell execution for target commands.
No destructive, disruptive, credential, persistence, stealth, or third-party action without explicit written authorization.
Raw evidence stays under $ENG_DIR/evidence/<phase>/.
Secrets, dumps, and proof output stay out of $ENG_DIR/state/.
Context compression resumes from engagement files in the current Hermes conversation.

The detailed policy is skills/pentest/references/standards.md.

Engagement state

init-engagement creates the canonical working structure:

$ENG_DIR/
├── scope/
│   └── scope.yaml
├── state/
│   ├── ptt.md
│   ├── history.md
│   └── checkpoint.json
├── hypotheses.md
├── evidence/
├── reporting/
└── retrospective/

Skill delivery

Skills are loaded on demand. The first violin_record_ptt call for a routed skill may return skill_prepared without changing the PTT. After Hermes delivers the skill content, repeat the transition to bind the receipt and apply the task change. violin_status reports the exact recovery action.

Marker files such as .skill-loaded-* do not prove skill delivery.

Routed skills

Skill	Coverage
`pentest`	Scope, lifecycle, recon, exploitation, reporting, closeout
`web-app`	Injection, SSRF, traversal, deserialization, client-side flaws
`identity-auth`	Authentication, authorization, IDOR, JWT, CSRF, cryptography
`api-testing`	REST, SOAP, GraphQL, WebSocket
`business-logic`	Workflow, pricing, coupon, quota, referral, race conditions
`llm-security`	Prompt injection, MCP, JSON-RPC
`misconfig`	Deployment, error handling, observability, obscurity

The orchestrator loads only the phase material and specialist playbook needed for the current task.

Administrative CLI

The CLI does not replace guarded target execution.

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 exposes admission checks for diagnostics and does not execute the supplied command.

Architecture

plugins/violin_guard/
├── core/           state, schemas, parsing, phases, targets
├── gates/          command, scope, hypothesis, terminal policies
├── engine/         execution and release verification
├── 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

Benchmarks

The repository includes the Escape Duck Store definition plus known-good and known-bad scorer fixtures. Calibration proves that the scorer handles those fixtures; it does not establish live-agent recall, workflow completion, or report quality.

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>

Read the benchmark methodology before publishing a score. It defines the proof, reproducibility, private evaluation, and disclosure requirements for a credible result.

Development

uv sync --dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run python scripts/violin_guard.py check-release

The release gate checks version surfaces, isolated plugin import, registered tools, generated schemas, skill snapshots, documentation contracts, Ruff, and the full test suite.

Platform smoke tests:

scripts/smoke-test.sh — Linux and Kali/Parrot release smoke
scripts/smoke-test.ps1 — Windows bootstrap, scope, and target-resolution smoke; skill delivery and target execution require Hermes

See CONTRIBUTING.md for contribution rules and SECURITY.md for private vulnerability reporting.

Responsible use

Violin is for authorized security assessment. Operators are responsible for scope, approvals, target ownership, data handling, and local law.

Support Violin

Violin is an open-source project maintained by Strategic Automation Ltd. If Violin is useful to you or your organisation, you can sponsor its continued development.

Sponsorship supports continued development, testing, documentation, compatibility work, and releases.

Violin remains available under the MIT licence. Sponsorship does not include guaranteed support, feature priority, or influence over security policy.

License

MIT — see LICENSE.