# 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)

🌐 [English](README.md) · [繁體中文](README_zh.md) · [日本語](README_ja.md)

[deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）的渗透测试模式插件：一条命令把任何 dsh profile 变成 BugTraceAI 渗透测试 agent。

- **渗透测试者 persona** — 授权优先：没有明确授权不扫、每个 finding 先验证再上报
- **自带 runbook skill** — `bugtrace-pentest` 操作手册随包携带：扫描工作流、聚焦模式、auth 配置（TOTP）、WAF 绕过、模型调度、报告格式
- **BugTraceAI MCP bridge** — 7 个原生工具（`mcp__bugtrace__*`）直接操控引擎
- **内置 headless runner** — 只装 `dsh-base` 的 profile 也能开出完整 agent

## 安装

前置：`dsh` CLI（由 deepseek-harness 构建）+ [BugTraceAI-CLI](https://github.com/BugTraceAI/BugTraceAI-CLI) checkout 与 Python venv：

```bash
cd ~/projects/BugTraceAI-CLI
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
pip install -e .        # 让 `python -m bugtrace` 从任何目录可 import
```

一行安装（profile 不存在会自动创建）：

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

## 快速开始

```bash
export DEEPSEEK_API_KEY=sk-...                # dsh 的模型 key
export BUGTRACE_PYTHON=~/projects/BugTraceAI-CLI/.venv/bin/python
export BUGTRACEAI_HOME=~/projects/BugTraceAI-CLI   # pip install -e . 之后可不设

dsh --profile pentest "授权并扫描 https://bugstore.bugtraceai.com，finding 先验证再上报"
```

agent 会先陈述授权，用 `mcp__bugtrace__start_scan` 起扫描、`get_scan_status` 轮询进度，最后用 `query_findings` 与 `export_report` 确认结果。

## MCP 工具

| 工具 | 用途 |
|---|---|
| `mcp__bugtrace__start_scan` | 起扫描（target / full / 聚焦模式 / auth 配置） |
| `mcp__bugtrace__get_scan_status` | 轮询扫描进度 |
| `mcp__bugtrace__query_findings` | 查漏洞清单（by severity / status） |
| `mcp__bugtrace__stop_scan` | 中止扫描 |
| `mcp__bugtrace__export_report` | 导出 JSON / MD / HTML 报告 |
| `mcp__bugtrace__explain_vulnerability` | 漏洞技术细节 |
| `mcp__bugtrace__suggest_remediation` | 修复建议 |

后端挂掉时 bridge 会放行（`failOnStartupError: false`），agent 自动退回 REST API（`http://127.0.0.1:8000`）或 `bugtraceai-cli` CLI。

## 工作原理

包声明 `"dsh": { "bundle": { "patch": "pentest.patch.yml" } }`。`dsh plugin` 安装后自动把它 reconcile 进 profile 的 `dsh.profile.bundles` layer stack。patch 组合了：

- `system-prompt` persona 覆盖（渗透测试者、授权优先）
- `skill-filesystem` `customSkillDirs` 指向包内 `skills/`
- `insert` 区块：`dsh-code-runtime-worker-thread`、headless startup + runner、BugTraceAI MCP stdio client

MCP server 以 `python3 -m bugtrace mcp`（stdio）启动，必须能被 `BUGTRACE_PYTHON` 指定的解释器 import；长扫描轮询与报告导出有放宽的 per-call 工具 timeout。

## 卸载

```bash
dsh plugin --profile pentest remove dsh-pentest-bugtrace
```

## 故障排查

| 症状 | 解法 |
|---|---|
| `mcp__bugtrace__*` 工具没出现 | 检查 `BUGTRACE_PYTHON` 指向已 `pip install -e .` 的 venv；确认 `python -m bugtrace mcp` 在 pipe 下 stdout 干净（upstream stdout 污染修复在 BugTraceAI-CLI commit `a3d8de8`） |
| 起扫描报 `Provider preset not found` | BugTraceAI 的 `bugtraceaicli.conf` 要有 provider 段；`deepseek` preset 在 BugTraceAI-CLI `data/providers/deepseek.json`（commit `a3d8de8`） |
| git 安装被 pnpm `allowBuilds` 挡 | 本包没有 build scripts，理论上不用放行；pnpm 仍抱怨就把打印出的 key 加进 profile 的 `pnpm-workspace.yaml` `allowBuilds` |

## 授权

只对你明确授权的目标使用。persona 会拒绝未授权扫描、扫描前陈述授权、上报前验证每个 finding。

## License

MIT — 见 [LICENSE](LICENSE)。

🌐 [English](README.md) · [繁體中文](README_zh.md) · [日本語](README_ja.md)