dsh-pentest-bugtrace

Readme

# dsh-pentest-bugtrace

[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Validate](https://github.com/elliseang0000-lang/dsh-pentest-bugtrace/actions/workflows/validate.yml/badge.svg)](https://github.com/elliseang0000-lang/dsh-pentest-bugtrace/actions/workflows/validate.yml)

🌐 [繁體中文](README_zh.md) · [简体中文](README_zh_CN.md) · [日本語](README_ja.md)

A penetration-testing mode plugin for [deepseek-harness](https://github.com/deepseek-ai/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](https://github.com/BugTraceAI/BugTraceAI-CLI) checkout with a Python venv:

```bash
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):

```bash
dsh plugin --profile pentest add git+https://github.com/elliseang0000-lang/dsh-pentest-bugtrace.git
```

## Quick start

```bash
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

```bash
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](LICENSE).

🌐 [繁體中文](README_zh.md) · [简体中文](README_zh_CN.md) · [日本語](README_ja.md)