| name | pentest |
| description | Supervised agentic penetration testing orchestrator — approved recon, vulnerability research, safe exploit validation, and reporting. Routes to per-vulnerability-class playbooks based on scoping and discovery. |
| version | 1.1.0 |
| author | Violin |
| license | MIT |
| tags | ["pentest","security","recon","exploitation","reporting","owasp","ptes"] |
Pentest Orchestrator Skill
The pentest skill is the authoritative orchestrator for penetration testing engagements. It routes specialised web-injection and access-control work to the sibling skills instead of loading every playbook eagerly.
1. Operating Model
📁 Project Structure
Every engagement creates a dedicated project directory at the repo root — never store evidence inside the skills directory.
violin/
├── skills/
│ ├── pentest/
│ ├── web-attacks/
│ └── access-control/
├── engagements/
│ └── <target>-<YYYY-MM-DD>/
│ ├── scope/
│ │ └── scope.yaml
│ └── evidence/
│ ├── recon/
│ │ ├── passive/
│ │ ├── tech/
│ │ └── active/
│ ├── vuln-research/
│ ├── exploitation/
│ ├── reporting/
│ └── retrospective/
Setup command (run during Phase 1 — Scoping): see playbooks/scoping.md §1 (0. Bootstrap: Create the Engagement Project) for the authoritative bootstrap — it creates the directory structure, PTT, hypothesis board, and command history. All subsequent commands and evidence paths use $ENG_DIR.
The agent operates as the Pentest Lead with supervised autonomy only after scope approval, phase approval, and guard checks.
Artifact-path rule: local scripts, payload files, and downloaded PoCs belong under $ENG_DIR/exploits/; local tool output belongs under $ENG_DIR/evidence/<phase>/. Never create local artifacts in /tmp. /tmp is permitted only when a payload explicitly creates a temporary file on the remote target; label that distinction in the command note.
Available capabilities:
terminal — host-local preparation and administration only; best-effort policy blocks obvious target traffic, while target-touching commands use the Violin guard tools belowweb (web_search, web_extract) — research: CVE lookup, exploit search, OSINT, documentation, PoC searchbrowser (browser_navigate, browser_click, browser_type, browser_vision, browser_snapshot) — website enumeration and interaction: navigate target web apps, interact with login forms and dashboards, capture screenshots, inspect DOM, crawl visible links, enumerate client-side routesfile (write_file, read_file, search_files) — evidence collection, report writing, config manipulationcode_execution — host-local Python automation only with a first-line audit header: # violin: {"eng_dir":"...","phase":"...","target":"...","session_id":"..."}. The source and completion record are saved to the named engagement; use typed Violin tools for target execution.clarify — ask the user structured questions during scoping and when decisions are neededtodo — track engagement phase progress and task breakdowndelegate_task — spawn sub-agents for parallel recon, exploit development, or report writingvision — analyse screenshots, diagrams, and visual outputs from tools
Tool discovery: The agent does NOT assume any tool is pre-installed. Before using a tool for the first time, it verifies availability (see Section 4).
Platform Awareness
Violin is intended for Kali Linux or Parrot OS first. The terminal tool may
still be bash/zsh, PowerShell, Git Bash, WSL, Docker exec, or a remote shell,
depending on where Hermes is running.
- Kali/Parrot fast path: run tools directly and prefer standard paths such
as
/usr/share/seclists/, /usr/share/wordlists/,
/usr/share/nmap/scripts/, and /usr/share/exploitdb/.
- Docker Kali fallback: run tools through
docker exec kali-pentest ... or
the scripts/kali.sh helper when the host lacks native tools.
- Windows/PowerShell/Git Bash fallback: detect the shell before assuming
path syntax. When chaining file writes into terminal execution, use paths that
the active shell can actually resolve.
- Remote environment fallback: if the user provides an SSH jump box or
remote test host, use the provided command prefix and keep evidence copied
back into
$ENG_DIR.
- Tool availability:
web_search or browser tooling may vary by host. When
unavailable, report the missing tool and use the next approved fallback.
- SPA routing: Raw HTTP
GET /#/route usually returns the SPA shell because
the client handles hash/history routes. Use the browser for DOM/client-side
state and call server-side API paths directly (for example /api/...,
/rest/..., /graphql, /b2b/...).
- Auth-context split: do not assume bearer tokens, cookies, and browser
sessions are interchangeable. Test the same endpoint with the actual auth
context the UI uses before dismissing a finding.
2. Workflow Drift Guard
Canonical bootstrap artifact set (do not invent extras): scope/scope.yaml, state/ptt.md, hypotheses.md, and state/history.md. check-bootstrap is authoritative for bootstrap readiness. state/checkpoint.json and state/phase-summary.md are continuity artifacts, not bootstrap blockers.
The phase workflow is mandatory for the entire session, including long, compressed, or resumed conversations. Do not treat it as startup-only guidance.
Required loop before every new phase or tool batch:
Violin guard tool map (prefer plugin tools when available):
violin_target resolves the current in-scope target from scope.yaml; use it instead of hardcoding reset-prone IPs.violin_exec is the single-command authorize, execute, and evidence boundary for target interaction. It has no binary allowlist: use it for any installed non-interactive Kali/Parrot CLI tool. Installation, root, hardware, service, GUI, and interactive-TTY requirements remain runtime constraints, never reasons to bypass the guard.violin_exec_status reads a tracked execution receipt; violin_exec_cancel cancels only its tracked process group.violin_exec_burst is the batch gate for exploit/race iterations. Keep one EXPLOITATION PTT task active while adapting up to 20 pre-approved commands; it records every completed command and requires one explicit PTT review/update only when the bounded burst ends.violin_status is the cheap first diagnostic: it shows the active task/phase, each pending command's required phase, phase requirements, blockers, and exact next actions without mutating engagement state.violin_httpx, violin_nuclei, and violin_ffuf build typed commands and delegate to violin_exec. Run nmap directly through violin_exec or violin_exec_burst.violin_search_exploit searches the local ExploitDB index only; it never downloads or executes a candidate.violin_exec / violin_exec_burst append exact command history themselves. Do not spend model calls recreating command history, and do not treat automatic history as proof that the PTT progressed.violin_record_ptt changes task lifecycle state; violin_record_hypothesis records semantic hypothesis changes.violin_review_batch is the only post-batch operation: it validates the completed batch, optionally creates one receipt-backed finding, applies the explicit PTT review/update once, and unlocks the batch last.violin_heartbeat_done clears the periodic review lock after re-reading this skill and reviewing engagement files.
- Bootstrap gate — at session start, after
/goal set, or after context compression that loses track of state, verify the engagement is bootstrapped: python $HOME/.hermes/profiles/violin/scripts/violin_guard.py check-bootstrap --eng-dir "$ENG_DIR". Exit 0 = proceed. Exit 1 = STOP and run playbooks/scoping.md §0 (creates $ENG_DIR/, scope/scope.yaml, state/ptt.md, hypotheses.md, state/history.md). Exit 2 = fix the warning, then proceed. This gate is non-negotiable: no curl, nmap, browser_navigate, or other target-touching tool call is allowed until exit 0.
0.1. Skill-load gate — launch with hermes chat --skills pentest when possible; otherwise load this skill immediately. After reading it, create state/.skill-loaded-<session-id> containing skill-loaded: <timestamp or label>, then verify it with status --eng-dir "$ENG_DIR" --section skill. Missing marker = BLOCK. If the marker exists but belongs to another session, create the canonical marker for the current session and re-run the check; do not silently rely on a stale marker. CTF bootstrap creates it when --session-id is supplied.
- Check/update
todo with a single active phase-gate item named for the current phase.
- Confirm an approved
$ENG_DIR/scope/scope.yaml exists before touching any target. If it does not, remain in SCOPING and ask via clarify. Verify with python $HOME/.hermes/profiles/violin/scripts/violin_guard.py validate-scope --scope $ENG_DIR/scope/scope.yaml (exit 0 required).
For an authorized HTB/CTF lab, init-engagement --ctf --host <ip> --session-id <id> "$ENG_DIR" creates a ready-to-test scope, active RECON PTT row, and skill marker.
- Read and activate the PTT task —
read_file path="$ENG_DIR/state/ptt.md" — and select the next open [ ] task for the current phase. Before any target command, mark exactly one task [~]:
python $HOME/.hermes/profiles/violin/scripts/violin_guard.py record-ptt --eng-dir "$ENG_DIR" --id PT-XXX --status "[~]" --note "starting task"
With no pending batch, this is the one permitted PTT start transition. The guard hard-blocks target execution when there is no unambiguous active task or the task sits under another phase heading. The executor never changes this row or its *Last updated* timestamp. After each bounded batch, review the results and call violin_review_batch with [~], [x], [!], or [-] plus a truthful result summary.
- Command history is executor-owned —
violin_exec appends every completed target command automatically. There is no public history-writing command; inspect recent history before a new batch to avoid repeats.
- Re-read this skill or the active playbook after context compression,
/resume, or any uncertainty about the workflow. Also read back evidence and hypotheses: read_file path="$ENG_DIR/hypotheses.md" and search_files path="$ENG_DIR/evidence" pattern="<target>" target="files" to restore investigation state.
- Validate target-touching commands before execution:
- Load/read the phase playbook before acting:
- SCOPING →
playbooks/scoping.md
- RECON →
playbooks/recon.md
- VULN RESEARCH →
playbooks/vuln-research.md
- EXPLOITATION →
playbooks/exploitation.md plus relevant vuln-class playbook
- REPORTING →
playbooks/reporting.md
- RETROSPECTIVE →
references/retrospective.md
- Before exploit validation, re-check the vuln playbook's
## Stop Conditions and ## Blocked Actions.
- If the requested action conflicts with the current phase, pause and reconcile phase/scope first.
- In-place context recovery per objective — When transitioning between major phases (RECON→VULN RESEARCH→EXPLOITATION→REPORTING), write a structured summary: PTT status, resolved hypotheses, evidence inventory, and any open unknowns into
$ENG_DIR/state/phase-summary.md. For every resolved test, preserve the exact command syntax, decisive response, and whether source/parser syntax was confirmed; do not compact an unverified conclusion into a fact. On each phase change, also update $ENG_DIR/state/checkpoint.json with the current phase, timestamp, and open items. Never ask the user to start /new for compression. If context is at risk of compression, tell the user: "Context is getting long. Continue in the current session; I will resume from $ENG_DIR/state/ files." Re-read $ENG_DIR/state/ptt.md, $ENG_DIR/state/phase-summary.md, and $ENG_DIR/state/checkpoint.json in the current session before the next target-touching action.
- Tell before do — Before executing a tool batch, changing phase, or running a major operation, announce to the user what you are about to do, why, with which tool, and what evidence you expect. Wait for acknowledgment before proceeding. Use a plain message or
clarify — never skip straight to running commands.
- Summarise after each batch — After each logical tool batch, give a 3-5 line summary: what ran, key results, evidence saved. Never dump raw command output into the chat — use
write_file for the full output and summarise.
12.1. Closeout requirements — Before declaring completion, ensure these shipped artifacts exist and are non-empty: evidence/reporting/report.md, evidence/retrospective/retrospective.md, state/phase-summary.md, and state/checkpoint.json. Do not claim a nonexistent close CLI gate was run.
- Ask what's next — After each sub-phase or completed batch, ask the user what they want to do next with concrete options.
Output Budget (mandatory)
- Keep chat summaries to 3-5 bullets per logical batch; save raw output under
$ENG_DIR/evidence/ or $ENG_DIR/state/ instead of pasting it into the chat.
- For scanners, fuzzers, crawlers, and long logs: do not paste full scanner output. Write the full output to an artifact path, then quote only decisive lines that support the next decision.
- Never summarize away evidence needed for validation: preserve full output, command, timestamp, and artifact path in the saved file/receipt.
- If the user asks for detail, provide a concise excerpt plus the artifact path first; only expand further on request.
Anti-Stuck Protocol (mandatory)
The classic failure mode is re-running the same command without recording what it learned. Treat a duplicate-command block as a signal to review evidence and change the next action.
- Check the history before retrying. Run
read_file path="$ENG_DIR/state/history.md" offset=<tail-20> and grep it for the command/endpoint. If it was already run, do not re-run it unchanged — change the variable (different host, param, wordlist, technique) or move to a new task.
- A block (
exit 1) is a signal to diversify, not to retry. When check-command blocks, you must pivot — and pivot to online research first, before reaching for another local command. Fire web_search/web_extract against the failing service/version/error, read back evidence (read_file $ENG_DIR/hypotheses.md, search_files $ENG_DIR/evidence), open a different PTT task, or switch information source (NVD → ExploitDB → GitHub advisories → CIRCL → OSV → vendor docs). Re-issuing the same command after a block violates the drift guard.
- When stuck, research online before re-running. The cheapest unstuck move is almost always new information, not another scan. If a command stalls, errors, or yields nothing new:
web_search the exact error string + tool name, pull the upstream docs / PoC / CVE advisory via web_extract, and only then change the variable (different host, param, wordlist, technique) or move to a new task. Treat the web capability as a primary recovery lever, not a last resort.
- Five-attempt research trigger. After five failed attempts against the same feature or exploit class, stop. Re-read captured source first; then research the exact parser, protocol, or primitive; then test one documented variant. If the source is unavailable or the next safe variant is unclear, ask the user for a hint rather than continuing a circular loop.
- False-negative checkpoint. Before declaring a feature unavailable, stubbed, or not implemented, match the exact test command and argument order against the captured source/parser. Record the command, decisive response, and
verification_status in the hypothesis. syntax_uncertain is not a rejection: it requires a corrected re-test.
- Context boundary. Prefix controller output with
[VICTIM]; prefix assessment-host commands and notes with [ATTACKER]. /proc, /run, UNIX sockets, and local service state belong to the machine on which the command runs. Host-local preparation (for example, starting an approved HTTP server or hashing a local artifact) may use the terminal directly; commands sent to a target still use violin_exec or one pre-approved violin_exec_burst.
- Mandatory research-loop (VULN RESEARCH / EXPLOITATION): for each detected version/service, record the actual NVD/ExploitDB/GitHub research and update the hypothesis when its semantic state changes (Candidate/Likely/Validated/Rejected). Do not fabricate a hypothesis update merely because another payload ran.
- Research-attempt gate: before any EXPLOITATION, POST_EXPLOITATION, PRIVESC, or FLAGS target command, the matching hypothesis must contain non-empty
CVE Research and Exploit Research fields. Each field records the online query, source, and outcome. A truthful no results, not applicable, or source unavailable outcome satisfies the attempt requirement; an omitted field blocks execution. Local SearchSploit alone does not satisfy the online attempt.
- Split continuity contract. Every approved target command is automatically mirrored to
state/history.md; PTT progress is never automatic. When the bounded window ends and violin_exec returns sync_required, stop, review the batch evidence, call violin_review_batch, then continue.
Drift signal: If the agent starts improvising tasks that are not tied to a phase, playbook, evidence path, and scope item, it must stop, reload this skill, and resume from the correct phase gate. Specifically: if the agent is about to run a target-touching command but cannot point to a [ ] PTT entry that justifies it and an existing hypothesis, stop.
3. Engagement Workflow
REPORTING and RETROSPECTIVE artifacts are mandatory before completion.
Every engagement follows this phase sequence:
1. SCOPING ──► 2. RECON ──► 3. VULN RESEARCH ──► 4. EXPLOITATION ──► 5. REPORTING ──► 6. RETROSPECTIVE
| Phase | Description |
|---|
| SCOPING | Gather requirements, define rules of engagement, select playbooks |
| RECON | Passive and active information gathering, asset discovery |
| VULN RESEARCH | Identify vulnerabilities, search for CVEs, analyse attack surface |
| EXPLOITATION | Validate findings with proof-of-concept exploits |
| REPORTING | Document findings, evidence, risk ratings, remediation |
| RETROSPECTIVE | Post-engagement gap analysis and playbook improvement (references/retrospective.md) |
⚠️ Phase 6 (Retrospective) is mandatory. After every engagement, run a gap analysis against the full target attack surface and patch the playbooks for anything missed. See references/retrospective.md for the full process.
4. Interactive Scoping
Before any technical work begins, the agent asks 9 questions via clarify:
- Application type — What kind of target? (web app, API, mobile, network infrastructure, cloud, thick client)
- Assessment mode — Passive recon, active recon, standard pentest, or specific exploit validation?
- Technical focus areas — OWASP Top 10, PTES, custom threat model, or specific vulnerability classes?
- Access depth — Black-box, grey-box, or white-box? What access, credentials, or source are available?
- Risk tolerance / forbidden actions — Which disruptive or sensitive actions are prohibited? The safe defaults remain in force unless explicitly changed in the RoE.
- Time window — What dates, hours, rate limits, or hard deadlines apply?
- Target environment — Production, staging, development, or isolated lab? What URLs, IPs, ranges, exclusions, and callback hosts apply?
- Tooling environment — Native Kali/Parrot, Docker Kali, WSL, remote jump box, or another approved environment?
- Authorisation — Who approved the written scope and Rules of Engagement? What emergency contact should be used?
Based on answers, select playbooks:
- Web app + OWASP priority → load
skills/web-attacks/playbooks/{sqli,xss,command-injection,ssrf,path-traversal}.md, skills/access-control/playbooks/{idor-access-control,auth-bypass}.md, and playbooks/api-security.md as findings warrant.
- API-heavy → load
playbooks/api-security.md, skills/access-control/playbooks/jwt-attacks.md, skills/web-attacks/playbooks/ssrf.md, and playbooks/business-logic.md as findings warrant.
- Cloud/infrastructure or mobile → select only applicable shipped playbooks and record any missing dedicated coverage in the retrospective; do not imply an unshipped skill exists.
5. Autonomous Tool Discovery
Before using any tool for the first time, verify availability:
command -v <tool> — on PATHls /usr/bin/ | grep <tool> — standard binary dirsapt list --installed 2>/dev/null | grep <tool> — package manager- Kali/Parrot: check
/usr/share/<tool>, /opt/<tool>, /usr/bin/<tool>
If not installed, see .hermes.md "When a Tool Is Missing" for the full fallback flow (search alternatives → ask user → find instructions → never silently skip).
6. Per-Vulnerability-Class Playbooks
When a vulnerability class is identified or scoped, the agent loads the corresponding playbook:
| Vulnerability Class | Playbook Path |
|---|
| SQL Injection (SQLi) | skills/web-attacks/playbooks/sqli.md |
| Cross-Site Scripting (XSS) | skills/web-attacks/playbooks/xss.md |
| Command Injection | skills/web-attacks/playbooks/command-injection.md |
| Server-Side Request Forgery (SSRF) | skills/web-attacks/playbooks/ssrf.md |
| Path Traversal | skills/web-attacks/playbooks/path-traversal.md |
| Insecure Direct Object References / Access Control (IDOR) | skills/access-control/playbooks/idor-access-control.md |
| Authentication Bypass | skills/access-control/playbooks/auth-bypass.md |
| JWT Attacks | skills/access-control/playbooks/jwt-attacks.md |
| (In)secure Deserialization | playbooks/deserialization.md |
| XML External Entities (XXE) | playbooks/xxe.md |
| Business Logic Flaws | playbooks/business-logic.md |
| API Security | playbooks/api-security.md |
| Server-Side Template Injection (SSTI) | playbooks/ssti.md |
| NoSQL Injection | playbooks/nosql-injection.md |
| LLM / AI Prompt Injection | playbooks/llm-prompt-injection.md |
| Broken Anti-Automation | playbooks/anti-automation.md |
| Cross-Site Request Forgery (CSRF) | playbooks/csrf.md |
| Cryptographic Issues | playbooks/cryptographic-issues.md |
| Improper Input Validation | playbooks/input-validation.md |
| Observability Failures | playbooks/observability-failures.md |
| Unvalidated Redirects | playbooks/redirects-unvalidated.md |
| Security Misconfiguration | playbooks/security-misconfiguration.md |
| Security Through Obscurity | playbooks/security-through-obscurity.md |
| Supply Chain / Vulnerable Components | playbooks/supply-chain.md |
Each playbook contains detection methods, guarded command guidance, safe validation techniques, evidence requirements, stop conditions, and blocked actions.
7. Confidence Tracking
Every finding is tracked with a confidence level:
| Level | Definition | Action Required |
|---|
| Candidate | Plausible finding, unproven | Needs verification — run additional checks |
| Likely | Evidence suggests the vulnerability exists | Gather more evidence, attempt exploitation |
| Validated | Proven with a working Proof-of-Concept | Document and report with evidence |
| Rejected | Tested — not vulnerable | Log the negative result for reporting |
Confidence is escalated stepwise: Candidate → Likely → Validated. A finding can be directly moved to Rejected if tests are negative.
8. Hypothesis Tracking & Investigation State
Pentesting is hypothesis-driven. Violin tracks theories as first-class entities,
separate from confirmed findings, in a hypothesis board.
File: $ENG_DIR/hypotheses.md (created during scoping bootstrap)
Template: skills/pentest/templates/hypothesis-board.md — contains lifecycle, usage rules, and format.
The board has five sections: Active Theories, Observations, Investigation Chains, Research Log, Resolved Theories.
Evidence Read-Back
The drift guard (SOUL.md, .hermes.md, §2) requires re-reading evidence and
hypotheses after context compression — not just the playbook:
search_files path="$ENG_DIR/evidence" pattern="<target>" target="files"
read_file path="$ENG_DIR/hypotheses.md"
This prevents re-running scans, missing cross-phase patterns, and losing the
investigation chain after compression.
9. Phase Descriptions
Each phase has its own detailed playbook:
| Phase | Playbook |
|---|
| Scoping | playbooks/scoping.md — scope definition, RoE, target validation |
| Reconnaissance | playbooks/recon.md — passive recon, active recon, asset enumeration |
| Vulnerability Research | playbooks/vuln-research.md — CVE lookup, manual analysis, tool-based scanning |
| Exploitation | playbooks/exploitation.md — PoC development, exploitation, evidence capture |
| Reporting | playbooks/reporting.md — finding documentation, risk rating, remediation, executive summary |
| Retrospective | references/retrospective.md — gap analysis, coverage matrix, playbook updates |
10. Tool Management
- Playbook:
playbooks/tools.md — tool selection matrix, recommended tools per vulnerability class
- Reference:
references/tool-discovery.md — installation instructions for common pentest tools (apt, pip, go, gh releases, docker)
11. CVE Research
For CVE and vulnerability research, consult these sources:
| Source | URL / Description |
|---|
| NVD (National Vulnerability Database) | https://nvd.nist.gov/ — Official CVE repository with CVSS scores |
| Exploit-DB | https://www.exploit-db.com/ — Public exploit archive maintained by Offensive Security |
| CVE Details | https://www.cvedetails.com/ — CVE search engine with vendor/product drill-down |
| GitHub Advisory Database | https://github.com/advisories — GHSA-format advisories with affected packages |
| OSV (Open Source Vulnerabilities) | https://osv.dev/ — Open-source vulnerability database with API |
| Nuclei Templates | https://github.com/projectdiscovery/nuclei-templates — Community-contributed vulnerability detection templates |
Reference: references/cve-apis.md — API endpoints and query patterns for each source.
12. Evidence & Severity Standards
- Reference:
references/standards.md — detailed guardrails (cloud metadata, rate limiting, bypass exhaustion), evidence handling policy (chat redaction vs file storage vs secrets vault), L1–L4 severity levels, and the CVSS 3.1 / 4.0 crosswalk
- Evidence is saved under
$ENG_DIR/evidence/<phase>/ as described in the engagement setup
- All L3 (Confirmed) and L4 (Critical) findings require a CVSS 3.1 vector and score; add CVSS 4.0 when feasible and use it as the preferred current scoring record
13. Safety & Blocked Behaviour
See .hermes.md (auto-loaded as project context) for the full safety boundary,
forbidden behaviour list, and conversation/memory isolation rules. See also
references/standards.md for detailed guardrails, evidence handling policy,
and CVSS scoring rules.
