# 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_CN.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_CN.md) · [日本語](README_ja.md)