31 playbooks · 10 references · 11 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, three 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.
hermes profile install https://github.com/Strategic-Automation/violin
hermes -p violin
| 🔬 31 Methodology Playbooks | 7 operational playbooks (five execution phases, optional post-exploitation, and the tools catalog) + 24 vulnerability-class playbooks, routed across the `pentest`, `web-attacks`, and `access-control` skills. |
| 🛡️ Multi-Layer Safety | Interactive scoping (9 questions) → scope validation → guard check → approval gates — every target-touching command validated before execution. |
| 🧠 Pentesting Task Tree | Structured artifact tracking every task via `[x]/[ ]/[~]` markers across phases, with executor-owned history, hypothesis linking, and guard-bound batch reviews. |
| 🌐 Browser + Web Research | Browser toolset for approved in-scope website enumeration; v3.0.0 gates the engagement workflow but does not provide a network-level browser allowlist. Web toolset for CVE lookup, exploit search, and OSINT. |
| 📋 Evidence-Driven Reporting | Reproducible evidence with screenshots, tool output, and request/response pairs. CVSS 3.1 + 4.0 crosswalks and optional remediation patches. |
| 🔗 Hermes-Native | Inherits your existing Hermes provider, model, and tool backends. Violin introduces no separate credential store or broker. |
# 1. Install the profile
hermes profile install https://github.com/Strategic-Automation/violin
# 2. Start a session
hermes -p violin
# 3. Let Violin ask scoping questions, then run your test
> Run a pentest against example.comPrerequisites
- Hermes Agent >= 0.18.0 — installed and on your PATH
- Hermes provider configured — Violin inherits your normal Hermes provider/model
- Kali Linux or Parrot OS — the primary execution environments; Docker Kali is the supported fallback when the host lacks pentest tools
- Optional web/browser backend — required only for Hermes web or browser capabilities; Violin does not add separate API credentials
Set as default profile
hermes profile use violinflowchart LR
A["1. Scoping"] --> B["2. Recon"]
B --> C["3. Vuln Research"]
C --> D["4. Exploitation"]
D --> E["5. Reporting"]
E --> F["6. Retrospective"]
A -.->|"clarify"| G("Approval Gate")
B -.->|"guard check"| G
C -.->|"guard check"| G
D -.->|"clarify + guard"| G
style A fill:#1a1a2e,stroke:#e94560,stroke-width:2px
style B fill:#16213e,stroke:#0f3460,stroke-width:2px
style C fill:#1a1a2e,stroke:#e94560,stroke-width:2px
style D fill:#16213e,stroke:#0f3460,stroke-width:2px
style E fill:#1a1a2e,stroke:#e94560,stroke-width:2px
style F fill:#16213e,stroke:#0f3460,stroke-width:2px
style G fill:#2d2d2d,stroke:#ffd700,stroke-width:2px
| Phase | Action | Safety Gate |
|---|---|---|
| 1. Scoping | 9 questions via clarify |
User approval |
| 2. Reconnaissance | Passive OSINT → tech detection → active scanning | Guard + approval |
| 3. Vuln Research | CVE lookup, exploit search, attack surface analysis | Guard check |
| 4. Exploitation | Safe PoC validation per vulnerability class | Guard + user approval |
| 5. Reporting | Evidence compilation, CVSS scoring, remediation | — |
| 6. Retrospective | Gap analysis, playbook coverage update | Mandatory |
graph TB
subgraph "Your Machine"
HE["Hermes Agent"]
VI["Violin Profile"]
GUARD["violin_guard execution + evidence"]
end
subgraph "Violin Skills"
SK["pentest orchestrator"]
WEB["web-attacks skill"]
AC["access-control skill"]
PB["31 Playbooks"]
REF["10 References"]
TEMP["11 Templates"]
end
subgraph "Configured Toolsets"
T["terminal"]
W["web"]
B["browser"]
F["file"]
CE["code_execution"]
S["skills"]
CL["clarify"]
D["delegation"]
V["vision"]
TD["todo"]
VG["violin_guard"]
end
LLM["Your LLM Provider"]
HE -->|"hermes -p violin"| VI
VI -->|"loads"| SK
VI -->|"requires"| GUARD
SK -->|"routes to"| WEB & AC & PB
WEB --> PB
AC --> PB
SK --> REF & TEMP
HE -->|"calls"| T & W & B & F & CE & S & CL & D & V & TD & VG
HE -->|"inherits"| LLM
style HE fill:#2d2d2d,stroke:#ffd700,stroke-width:2px
style VI fill:#1a1a2e,stroke:#e94560,stroke-width:2px
style GUARD fill:#16213e,stroke:#0f3460,stroke-width:2px
11 toolsets configured in config.yaml (platform_toolsets.cli): 10 built-in — terminal, web, browser, file, code_execution, skills, todo, clarify, delegation, vision — plus the violin_guard guard-plugin toolset.
memory.memory_enabled: false— no global memory recall/writememory.user_profile_enabled: false— no global user profile access- Engagement continuity lives in project files (scope docs, evidence, reports)
- Keep one Hermes conversation per engagement; after compression, resume in that conversation from
$ENG_DIR/state/
flowchart LR
subgraph "Layer 1"
A["9 Scoping Questions"]
B["Written Authorisation"]
end
subgraph "Layer 2"
C["violin_guard.py validate-scope"]
end
subgraph "Layer 3"
D["violin_guard.py check-command"]
end
subgraph "Layer 4"
E["clarify approval gate"]
end
subgraph "Layer 5"
F["Standards & Blocked Actions"]
end
A --> B --> C --> D --> E --> F
- Authorised testing only — no probing before scoping is complete
- Approval gates — scope, active recon, and exploitation each require explicit user approval
- Guard check — every target-touching command validated through
violin_execor another typed guard tool.violin_exechas no binary allowlist, so any installed non-interactive Kali/Parrot CLI tool can target the explicit in-scope host while the same scope, phase, PTT, hypothesis, history, evidence, timeout, and sync gates remain active. Violin'spre_tool_callplugin hook generically blocks target literals in rawterminalcommands instead of maintaining a partial tool-name list. The CLI exposes the same check for diagnostics (exit 0=allowed, 1=blocked, 2=review) - Non-destructive by default — exploitation limited to safe, reproducible PoC
- Evidence-first — every finding backed by reproducible tool output, screenshots, request/response pairs
- Exploit-first validation — no hypothesis advances to Validated without a verification command
- Stateful recovery — phase summaries and checkpoints restore the current engagement after context compression without starting a new conversation
- Self-explaining guard —
violin_status(orpython scripts/violin_guard.py status --eng-dir "$ENG_DIR") shows the active task and phase, pending commands and their required phases, phase requirements, skill state, blockers, and exact next actions without running a command - Phase-aware work windows — RECON/VULN_RESEARCH allow 10 guarded commands per reviewed batch; EXPLOITATION/POST_EXPLOITATION/PRIVESC/FLAGS allow 20, and the Hermes profile budget is 350 tool iterations
- One-call reconciliation —
violin_review_batchvalidates the completed batch, optionally writes its receipt-backed finding, updates the active PTT row once, and clears the batch lock last
Full safety policy: skills/pentest/references/standards.md. Forbidden actions: .hermes.md §Forbidden Behaviour.
violin/
├── .hermes.md # Project-level agent context
├── SOUL.md # Agent identity — senior pentester persona
├── config.yaml # Profile config (toolsets, safety, memory)
├── distribution.yaml # Hermes distribution manifest
├── plugins/violin_guard/ # Required Hermes guard plugin and execution boundary
│ ├── bash_ast.py # bashlex AST command tokenization and parsing
│ ├── terminal_policy.py # AST-based best-effort blocks for target-touching raw terminal calls
│ ├── targets.py # Scope enforcement using netaddr and yarl URL parsing
│ ├── schemas.py # Pydantic v2 tool schemas and validation
│ └── code_execution_audit.py # Engagement audit contract for execute_code
├── scripts/ # CLI and release smoke helpers
│ ├── violin_guard.py # Diagnostic/admin CLI over the plugin modules
│ ├── smoke-test.sh # Linux/macOS release smoke
│ ├── smoke-test.ps1 # Windows supplemental smoke
│ └── kali.sh # Docker Kali helper
└── skills/
├── pentest/ # Engagement orchestrator (23 playbooks, 10 refs, 11 templates)
│ ├── SKILL.md
│ ├── playbooks/ # 7 operational + 16 vulnerability-class playbooks
│ ├── references/ # 10 reference files
│ └── templates/ # 11 templates (reports, evidence, methodology, contracts)
├── web-attacks/ # Routed skill — 5 injection/web playbooks (SQLi, XSS, SSRF, cmdi, traversal)
└── access-control/ # Routed skill — 3 auth/authorisation playbooks (auth-bypass, IDOR, JWT)
python scripts/violin_guard.py check-releaseValidates the plugin manifest and registered tools, isolated Hermes-style plugin import, stale skill references, Ruff, and the full pytest suite.
Hermes skills are loaded on demand and enforced by Violin receipts. Start with pentest, then use violin_record_ptt to select the route-required skill. The first call prepares its real skill_view content without mutating the PTT; repeat the same transition after that tool result returns to the model to bind it. violin_status reports the route, binding, context generation, recovery action, and any obsolete legacy marker. Target and browser activity are blocked only in the same model call as delivery or binding, then open automatically on the next tool-loop continuation.
One-time setup for a full Kali toolchain on any OS
See scripts/kali.sh for the container exec helper.
docker pull kalilinux/kali-rolling
docker create -it --name kali-pentest \
-v /path/to/violin/engagements:/engagements \
kalilinux/kali-rolling bash
docker start kali-pentest
docker exec kali-pentest apt update
docker exec kali-pentest apt install -y kali-linux-headlessSee CONTRIBUTING.md for development setup, PR process, and code style.
See SECURITY.md for reporting vulnerabilities.
MIT — see LICENSE.