# DSH VulnClaw Penetration Mode

**Bridges the [VulnClaw](https://github.com/Netw0rkNoob/VulnClaw) penetration-testing toolchain into the
[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), adding a "Penetration Test" agent
mode to the Harness mode list.**

With that mode selected, 37 VulnClaw tools (`nmap_scan`, `http_probe_batch`, `dir_enum`, `js_recon`,
`crypto_decode`, `source_extract`, `evidence_*`, `traffic_*`, `cve_lookup`, `attack_map`, …) appear as
**native Harness tools**, driven by the Harness's own model and agent loop.

[中文](README.md) · [Install](#install) · [Design](docs/DESIGN.md) · [Findings](docs/FINDINGS.md) · [Troubleshooting](#troubleshooting)

---

## What this is / is not

**Is**: a DSH plugin bundle. It adds one mode to the Harness and wires VulnClaw's capabilities into it.

**Is not**: a fork, wrapper script, or replacement for VulnClaw. This repository contains **no
VulnClaw source** — VulnClaw is installed into a private environment on first use
(see [Python environment](#3-python-environment)).

> ⚠️ **Authorized testing only.** This project is for authorized penetration tests, CTF competitions,
> security education, and red-team exercises. Confirm you have explicit written authorization for the
> target and comply with local law. Unauthorized penetration testing is illegal.

> ℹ️ **Requires the DeepSeek Harness.** This is not a standalone program. Without the Harness it has
> nowhere to run.

---

## Features

| Feature | Detail |
|---|---|
| **One model** | The Harness owns the model; VulnClaw only supplies capability. VulnClaw's own agent loop is **never started** — no second API key to configure, and no two agents competing for the same tool calls. |
| **No VulnClaw source changes** | Everything goes through public modules: `AgentCore` to build, `build_openai_tools()` for schemas, `execute_mcp_tool()` to execute — the same dispatch VulnClaw's own loop uses. |
| **Intact evidence chain** | Every tool result is written to VulnClaw evidence and returned with its `[evidence:eNNN]` id, so `evidence_view` / `evidence_search` / `traffic_*` / report generation all see the full history. |
| **Scope-registered tools** | Tools exist only inside this mode. The standard / ptc / minimal / cordis modes gain nothing; removing the bundle removes the mode and its tools together. |
| **Model seam closed by default** | VulnClaw is prevented from opening its own model connection, so a leftover credential cannot quietly start a second agent. Opt in with an environment variable. |
| **Self-provisioning** | The Python environment and VulnClaw are detected or created on first tool use, including the execution libraries VulnClaw's own tool descriptions promise. |

---

## Requirements

| Dependency | Notes |
|---|---|
| [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) | The host. This plugin is a bundle for it. |
| Python 3.10+ | An interpreter that can `import vulnclaw`. If you have none, the install step provisions one with `uv`. |
| [`uv`](https://docs.astral.sh/uv/) (recommended) | Used to create that environment. Not needed if you already have a usable interpreter. |
| `nmap` (optional) | Only `nmap_scan` needs it. Without it that one tool reports a clear error; nothing else is affected. |

---

## Install

### 1. Get the code

```bash
git clone https://github.com/R1145141919810/dsh-vulnclaw-pentest.git
cd dsh-vulnclaw-pentest
```

> **Prefer an ASCII-only path.** The installer hands the package directory to pnpm, and a non-ASCII
> path (a CJK directory name, for example) can be mangled by the encoding round-trip, leaving a
> `link:` entry in the profile that points nowhere. Something like `D:\dsh-vulnclaw-pentest` is safest.

### 2. Install the bundle, then link dependencies (order matters)

```
plugin_manager(action: "install_bundle", target: "<absolute path to this repository>")
```

Then link the Harness's own packages:

```bash
npm run link-deps
```

**Why this step exists**: `install_bundle` links a local package into the profile with pnpm as a
**symlink**. Node follows that link to the package's real directory and walks *its* ancestors looking
for `node_modules` — a walk that never reaches the Harness's own packages, so activation fails with
`ERR_MODULE_NOT_FOUND: @deepseek-ai/dsh-tools`. `link-deps.mjs` resolves those two packages from the
profile and creates directory links (a junction on Windows, no elevation needed). It downloads
nothing, copies nothing, and hardcodes no machine path. Re-run it after a Harness upgrade.

If the Harness is installed elsewhere:

```bash
DSH_HOME=/path/to/.dsh DSH_PROFILE=desktop npm run link-deps
```

### 3. Python environment

**Usually nothing to do.** On **first tool use** (not at activation, so Harness startup is never
slowed) the plugin resolves an interpreter in this order:

1. `VULNCLAW_PYTHON` — an interpreter you named explicitly. Used as-is; if it fails, that is an error
   rather than a silent fallback to a different interpreter.
2. `$DSH_HOME/vulnclaw-bridge/venv` — an already-provisioned managed environment.
3. Create one with `uv` and `uv pip install "vulnclaw[web]"`.

It then verifies that the execution libraries VulnClaw's tool descriptions promise (`requests` and
friends) are actually importable, and installs any that are missing — see
[Findings](docs/FINDINGS.md#2-python_execute-is-missing-a-library-it-advertises).

To name an interpreter yourself:

```bash
export VULNCLAW_PYTHON=/usr/bin/python3   # must already be able to import vulnclaw
```

### 4. Restart the Harness

New JavaScript modules need a new process. After restarting, start a **new session** and pick
"渗透测试" (Penetration Test) from the mode list.

### 5. Verify the install

```bash
export TEST_PYTHON="<an interpreter with vulnclaw installed>"

node dev-verify-activation.mjs   # 31 checks: export form / registration / pruning / first-call
node dev-regression.mjs          #  9 checks: defects a real engagement exposed
node dev-verify-schema.mjs       # 37 schemas through the Harness's real compiler
node dev-test.mjs                # 25 checks: bridge client and tool surface
```

All four green means the install is correct. `dev-regression.mjs` and `dev-verify-schema.mjs` call the
Harness's **real** schema compiler; point `DSH_APP_NODE_MODULES` at it if installed elsewhere.

---

## Configuration

Set these in the relevant row's `config` in the bundle patch:

| Key | Default | Meaning |
|---|---|---|
| `pythonPath` | empty | Interpreter that can `import vulnclaw`; empty auto-resolves or provisions. |
| `sourcePath` | empty | Local VulnClaw checkout to install editable on first provision; empty installs the published package. |
| `exposeTools` | `true` | Register tools in this plugin's scope. Host row sets `false`, preset row `true`. |
| `toolPrefix` | empty | Prefix for every registered tool name, to avoid collisions. |
| `callTimeoutMs` | `600000` | Per-tool-call timeout. |
| `permissionMode` | `full_access` | VulnClaw's internal `safety.permission_mode`. |
| `keepDefaultDeny` | `true` | Hide the desktop-automation tool family irrelevant to an engagement. |
| `denyTools` | `[]` | Additional tool names to hide. |

### Environment variables

| Variable | Meaning |
|---|---|
| `VULNCLAW_PYTHON` | Name an interpreter; skips provisioning. |
| `VULNCLAW_BRIDGE_PERMISSION_MODE` | Override `permissionMode`. |
| `VULNCLAW_BRIDGE_MAX_RESULT_CHARS` | Per-result cap, default `120000`. |
| `VULNCLAW_BRIDGE_LLM_BASE_URL` / `_API_KEY` | Open the model seam (see [Design](docs/DESIGN.md#the-model-seam-is-closed-by-default)). |
| `DSH_HOME` / `DSH_PROFILE` | How `link-deps.mjs` finds the Harness. |
| `DSH_APP_NODE_MODULES` | How the verification scripts find the Harness schema compiler. |

### Permissions and approval

VulnClaw's dangerous tools (`shell_command`, `python_execute`, PoC) prompt
`Approve this execution? [y/N]` by default. The bridge is a headless child process with no channel
for that prompt, so `permissionMode` defaults to `full_access` — otherwise those tools are refused
outright with `no_channel`.

**Approval has not disappeared; it moved up.** In the Harness, `shell_command` and `python_execute`
amount to running commands on this host, so they fall under the Harness's permission system. Control
them with the Harness permission presets — do not treat this as an unapproved arbitrary-code-execution
entry point.

---

## Optional: VulnClaw CLI changes

`python/vulnclaw_dsh_mode.py` and `python/dsh-vulnclaw.py` apply two **runtime** customizations that do
not touch the installed package: a "Penetration Test" entry in the TUI check-mode list, and hiding the
AI-management commands (`config` / `login` / `logout` / `doctor` / `init`). Details in
[Design](docs/DESIGN.md#vulnclaw-cli-changes).

```bash
python python/dsh-vulnclaw.py --help
python python/dsh-vulnclaw.py tui --target https://target.example
```

Running bare `vulnclaw` is completely unaffected — the customization lives only in that process.

> Skip this section entirely if your Harness session already provides a model and tools.

---

## Layout

```
.
├── package.json                  Plugin manifest (dsh.bundle.patch + display metadata + icon)
├── cordis.patch.yml              Two rows: host row + preset-pentest (persona and environment contract)
├── index.js                      Host plugin: dynamic tools, session tools, catalog pruning, schema translation
├── bridge.js                     JSON-RPC client for the Python bridge (one long-lived process)
├── tools.js                      The three session-level tool definitions
├── python-runtime.js             Interpreter resolution, provisioning, execution-library repair
├── llm-offline.js                Model-sovereignty constraint and diagnostics
├── link-deps.mjs                 Resolve and link Harness dependencies from the profile
├── icon.svg                      Plugin icon
├── locale/{en,zh}.json           Display strings
├── docs/DESIGN.md                Architecture and design tradeoffs
├── docs/FINDINGS.md              Defects a real engagement exposed, and their fixes
├── python/
│   ├── vulnclaw_bridge.py        stdio JSON-RPC bridge exposing the VulnClaw tool surface
│   ├── vulnclaw_dsh_mode.py      CLI customization: pentest mode + hidden AI-management commands
│   └── dsh-vulnclaw.py           VulnClaw CLI launcher with those customizations
└── dev-*.mjs                     Verification and regression tests (not published to npm)
```

---

## Troubleshooting

| Symptom | Cause and fix |
|---|---|
| `failed to import` / `ERR_MODULE_NOT_FOUND: @deepseek-ai/dsh-tools` | You skipped `npm run link-deps`; after running it you **must restart the Harness**. |
| `nmap_scan` and friends are missing | The Penetration Test mode is not selected; tools are scope-registered. |
| `VulnClaw tools unavailable: ... uv is not available` | Install `uv`, or set `VULNCLAW_PYTHON` to an interpreter that already has `vulnclaw`. |
| Tools refused with `no_channel` | `permissionMode` was changed to `ask` / `auto_review`; a headless process has no approval channel. |
| `nmap_scan` reports nmap not installed | VulnClaw needs the external `nmap` binary on PATH. |
| `python_execute` reports `ModuleNotFoundError: requests` | It is repaired automatically; if it persists, `uv` is unavailable — run `uv pip install --python <venv> requests`. |
| `python_execute` reports `lab mode blocked operation` | The code uses `__import__()` / `importlib` / `exec()`; use plain `import` statements. |
| Desktop-automation tools are not listed | Hidden by default (56 of them are irrelevant to an engagement); `keepDefaultDeny: false` restores them. |
| A broken `link:` path in the profile after installing from a non-ASCII path | Move the repository to an ASCII-only path and install again. |
| Want to check the Python side | Ask the bridge: `initialize` returns the version, tool count, `model_seam`, and `llm_refusals`. |

---

## Contributing

Issues and pull requests are welcome. When changing plugin behavior, run all four verification suites
from step 5 — they call the Harness's real schema compiler and catch most changes that look right but
fail at activation.

---

## Credits and license

Built on **[VulnClaw](https://github.com/Netw0rkNoob/VulnClaw)** by
[UncleC](https://github.com/Netw0rkNoob) (MIT licensed,
[unclecheng-li.github.io/vulnclaw.com](https://unclecheng-li.github.io/vulnclaw.com/)).

VulnClaw supplies every penetration-testing capability here — the tool implementations, evidence and
traffic storage, report and PoC generation, and the skill knowledge base. This plugin does one thing:
it presents those capabilities as native Harness tools and lets the Harness's model drive them.
**Without VulnClaw this plugin is pointless.**

This repository contains no VulnClaw source; the plugin's provisioner installs VulnClaw into a private
environment. VulnClaw's copyright notice and full MIT license text are in
[THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).

It also depends on the DeepSeek Harness packages `@deepseek-ai/dsh-tools` and
`@deepseek-ai/schemastery`, resolved at runtime from the Harness installation and not redistributed
here.

This plugin is released under the **MIT license**; see [LICENSE](LICENSE).