dsh-pentest-bugtrace
🌐 繁體中文 · 简体中文 · 日本語
A penetration-testing mode plugin for deepseek-harness (dsh). One command turns any dsh profile into a BugTraceAI pentest agent.
- Pentester persona — authorization-first operating rules; no scan without explicit user authorization, every finding verified before it is reported
- Bundled runbook skill — the
bugtrace-pentest skill ships inside the package: scan workflow, focused modes, auth config (TOTP), WAF bypass, model shifting, report formats
- BugTraceAI MCP bridge — 7 native tools (
mcp__bugtrace__*) drive the engine directly
- Headless runner — a one-shot task executor is included, so a profile built on
dsh-base alone boots a complete agent
Install
Prerequisites: the dsh CLI (built from deepseek-harness), plus a BugTraceAI-CLI checkout with a Python venv:
cd ~/projects/BugTraceAI-CLI
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
pip install -e . # makes `python -m bugtrace` importable from any directory
One command installs the plugin (creates the pentest profile if missing):
dsh plugin --profile pentest add git+https://github.com/elliseang0000-lang/dsh-pentest-bugtrace.git
Quick start
export DEEPSEEK_API_KEY=sk-... # dsh model key
export BUGTRACE_PYTHON=~/projects/BugTraceAI-CLI/.venv/bin/python
export BUGTRACEAI_HOME=~/projects/BugTraceAI-CLI # optional once pip install -e . is done
dsh --profile pentest "authorize and scan https://bugstore.bugtraceai.com, verify findings before reporting"
The agent states the authorization, starts the scan with mcp__bugtrace__start_scan, polls get_scan_status, then confirms with query_findings and export_report.
MCP tools
| Tool | Purpose |
|---|
mcp__bugtrace__start_scan | start a scan (target / full / focused modes / auth config) |
mcp__bugtrace__get_scan_status | poll scan progress |
mcp__bugtrace__query_findings | list findings (by severity / status) |
mcp__bugtrace__stop_scan | abort a scan |
mcp__bugtrace__export_report | export JSON / MD / HTML report |
mcp__bugtrace__explain_vulnerability | technical breakdown of a finding |
mcp__bugtrace__suggest_remediation | fix recommendations |
When the backend is down the bridge fails open (failOnStartupError: false) and the agent falls back to the REST API (http://127.0.0.1:8000) or the bugtraceai-cli shell command.
How it works
The package declares "dsh": { "bundle": { "patch": "pentest.patch.yml" } }. dsh plugin installs the dependency and reconciles it into the profile's dsh.profile.bundles layer stack automatically. The patch composes:
- a
system-prompt persona override (pentester, authorization-first),
skill-filesystem customSkillDirs pointing at this package's skills/,insert entries: dsh-code-runtime-worker-thread, the headless startup + runner, and the BugTraceAI MCP stdio client.
The MCP server is spawned as python3 -m bugtrace mcp (stdio). It must be importable from the interpreter named by BUGTRACE_PYTHON; long scan polls and report exports get a raised per-call tool timeout.
Uninstall
dsh plugin --profile pentest remove dsh-pentest-bugtrace
Troubleshooting
| Symptom | Fix |
|---|
mcp__bugtrace__* tools missing | check BUGTRACE_PYTHON points at a venv with pip install -e . done; verify python -m bugtrace mcp starts clean on a pipe (the upstream stdout-pollution fixes are in BugTraceAI-CLI commit a3d8de8) |
Provider preset not found on scan start | BugTraceAI's own bugtraceaicli.conf needs a provider section; the deepseek preset ships in BugTraceAI-CLI data/providers/deepseek.json (commit a3d8de8) |
git-hosted install blocked by pnpm allowBuilds | this package has no build scripts, so nothing to allow; if pnpm still complains, add the printed key under allowBuilds in the profile's pnpm-workspace.yaml |
Authorization
Use only against targets you are explicitly authorized to test. The persona refuses un-authorized scans, states authorization before starting, and verifies every finding before reporting.
License
MIT — see LICENSE.
🌐 繁體中文 · 简体中文 · 日本語
