howmp/dsh-pentest

What it is

dsh‑pentest is a plugin bundle for DeepSeek Harness (DSH) – an open‑source AI‑agent framework. The bundle adds a penetration‑testing mode that lets a DSH session record, organise and visualise security‑assessment data (goals, intents, facts, findings, assets and their relationships) inside the DSH UI.

Who it’s for

• Security professionals who already use DSH and have explicit permission to test a target.
• Developers building custom DSH agents who need a structured way to capture and display pentest artefacts.
• Anyone who wants a ready‑made UI for tracking a security engagement inside an LLM‑driven workflow.

Core pieces (as described in the README)

Component	Role
Host plugin (pentest.js)	Exposes nine pentest_* tools (e.g., pentest_add_goal, pentest_add_finding, pentest_submit) that agents call to store data.
SQLite backend (storage-sqlite.js)	Persists the pentest graph in $DSH_HOME/storages/pentest‑sessions.db using Node’s built‑in node:sqlite.
Web UI (ui‑pentest.client.js)	Adds a new tab in the DSH web client with four sub‑views: exploration graph, vulnerability list, asset view, and a markdown report.
Domain model (spec.ts)	Defines six tables – goals, intents, facts, findings, assets, edges – and the edge vocabularies (spawns, yields, derived_from, proves, parent).
Projection layer (projection.ts)	Projects the stored graph into a windowed view (latest 200 nodes/assets) for fast UI rendering while keeping full history in the DB.
Protocol (instructions.ts)	Supplies a system prompt (pentest:protocol) that guides the LLM to follow the pentest workflow and write data via the tools.

How you use it

1. Install – via the DSH CLI, either from npm (dsh plugin add @howmp/dsh-pentest) or by downloading the released tarball.
2. Restart DSH – the plugin registers automatically; a new “渗透模式” (pentest mode) appears in the session selector.
3. Run a pentest – use the provided tools (or have a sub‑agent call pentest_submit) to add goals, intents, facts, findings, and assets. All calls are stored in the SQLite DB, not in the main DSH session log.
4. Explore – the UI shows a directed graph of the engagement, a list of vulnerabilities (with severity, reproducible steps, impacted assets), an asset hierarchy, and a generated markdown report.
5. Export / Repair – the bundle ships a dsh-pentest-repair script to fix corrupted session logs caused by older DSH versions.

Limits & safety notes

• Authorization only – the plugin is intended for legally‑authorized testing; it does not enforce any access control.
• Session‑scoped data – each pentest run lives in a single DSH session; there is no cross‑session persistence.
• Windowed UI – the UI only shows the most recent 200 nodes/assets; older items are still in the DB and can be accessed via pentest_state or pentest_report.
• No log pollution – the plugin deliberately avoids writing its own events to the main DSH session log to prevent breaking older DSH versions.
• Compatibility – requires DSH ≥ 0.1.6 and Node ≥ 22.5; older DSH versions need a specific pre‑release of the bundle.

Why it matters

Security assessments often involve many moving parts (targets, findings, evidence, remediation steps). By embedding this workflow directly into an LLM‑driven agent platform, dsh‑pentest lets analysts keep the entire engagement structured, reproducible, and visualised without leaving the AI assistant environment.

---

All details above are taken directly from the repository’s README; no additional features have been inferred.