elliseang0000-lang/dsh-pentest-bugtrace

dsh-pentest-bugtrace

License: MIT
Validate

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

一个用于 deepseek-harness（dsh）的渗透测试模式插件。一条命令即可将任意 dsh profile 转变为 BugTraceAI 渗透测试代理。

- 渗透测试人员角色 — 授权优先的操作规则；未经用户明确授权不进行扫描，每项发现均在报告前经过验证
- 内置 runbook 技能 — bugtrace-pentest 技能随包提供：扫描工作流、聚焦模式、认证配置（TOTP）、WAF 绕过、模型切换、报告格式
- BugTraceAI MCP 桥接 — 7 个原生工具（mcp__bugtrace__）直接驱动引擎
- 无头运行器 — 内置一次性任务执行器，因此仅基于 dsh-base 构建的 profile 也能启动完整代理

安装

前置条件：dsh CLI（从 deepseek-harness 构建），以及一个带有 Python venv 的 BugTraceAI-CLI 检出：

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

一条命令即可安装该插件（若 pentest profile 不存在则创建）：

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

快速开始

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"

代理会声明授权，使用 mcp__bugtrace__start_scan 启动扫描，轮询 get_scan_status，然后通过 query_findings 和 export_report 进行确认。

MCP 工具

| 工具 | 用途 |
|---|---|
| mcp__bugtrace__start_scan | 启动扫描（target / full / 聚焦模式 / 认证配置） |
| mcp__bugtrace__get_scan_status | 轮询扫描进度 |
| mcp__bugtrace__query_findings | 列出发现（按严重程度 / 状态） |
| mcp__bugtrace__stop_scan | 中止扫描 |
| mcp__bugtrace__export_report | 导出 JSON / MD / HTML 报告 |
| mcp__bugtrace__explain_vulnerability | 对某项发现进行技术解析 |
| mcp__bugtrace__suggest_remediation | 修复建议 |

当后端不可用时，桥接会以失败开放方式处理（failOnStartupError: false），代理会回退到 REST API（http://127.0.0.1:8000）或 bugtraceai-cli shell 命令。

工作原理
该包声明了 "dsh": { "bundle": { "patch": "pentest.patch.yml" } }。dsh plugin 会安装该依赖，并自动将其协调到配置文件的 dsh.profile.bundles 层栈中。该补丁组合了：

- 一个 system-prompt 人设覆盖（渗透测试人员，授权优先），
- skill-filesystem 的 customSkillDirs 指向本包的 skills/，
- insert 条目：dsh-code-runtime-worker-thread、无头启动 + 运行器，以及 BugTraceAI MCP stdio 客户端。

MCP 服务器以 python3 -m bugtrace mcp（stdio）方式启动。它必须能从 BUGTRACE_PYTHON 指定的解释器中导入；长时间扫描轮询和报告导出会获得提高的每次调用工具超时。

卸载

dsh plugin --profile pentest remove dsh-pentest-bugtrace

故障排查

| 症状 | 修复方法 |
|---|---|
| mcp__bugtrace__ 工具缺失 | 检查 BUGTRACE_PYTHON 是否指向已完成 pip install -e . 的 venv；验证 python -m bugtrace mcp 在管道上能干净启动（上游 stdout 污染修复位于 BugTraceAI-CLI 提交 a3d8de8） |
| 扫描启动时出现 Provider preset not found | BugTraceAI 自身的 bugtraceaicli.conf 需要一个 provider 段；deepseek 预设随 BugTraceAI-CLI data/providers/deepseek.json 提供（提交 a3d8de8） |
| git 托管的安装被 pnpm allowBuilds 阻止 | 本包没有构建脚本，因此无需允许任何内容；如果 pnpm 仍然报错，请将打印出的键添加到配置文件的 pnpm-workspace.yaml 中的 allowBuilds 下 |

授权

仅可针对你明确获授权测试的目标使用。该人设会拒绝未授权的扫描，在开始前声明授权，并在报告前验证每一项发现。

许可证

MIT — 参见 LICENSE。

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