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.

🌐 繁體中文 · 简体中文 · 日本語