# 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_zh_CN.md)

[deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）向けのペネトレーションテストモードプラグイン。1コマンドで任意の dsh プロファイルを BugTraceAI ペンテストエージェントに変えます。

- **ペンテスター persona** — 認可優先：明示的な認可なしにスキャンしない、finding は検証してから報告
- **同梱 runbook skill** — `bugtrace-pentest` 操作マニュアルがパッケージ内に同梱：スキャンワークフロー、フォーカスモード、auth 設定（TOTP）、WAF バイパス、モデル切替、レポート形式
- **BugTraceAI MCP bridge** — 7 つのネイティブツール（`mcp__bugtrace__*`）でエンジンを直接操作
- **内蔵 headless runner** — `dsh-base` だけのプロファイルでも完全なエージェントが起動

## インストール

前提：`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 可能に
```

1コマンドでインストール（profile が無ければ自動作成）：

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

## クイックスタート

```bash
export DEEPSEEK_API_KEY=sk-...                # dsh のモデルキー
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 は検証後に報告"
```

エージェントはまず認可を述べ、`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` | finding 一覧（severity / status 別） |
| `mcp__bugtrace__stop_scan` | スキャン中止 |
| `mcp__bugtrace__export_report` | JSON / MD / HTML レポート出力 |
| `mcp__bugtrace__explain_vulnerability` | finding の技術詳細 |
| `mcp__bugtrace__suggest_remediation` | 修正提案 |

バックエンド停止時は bridge がフォールオープン（`failOnStartupError: false`）し、REST API（`http://127.0.0.1:8000`）または `bugtraceai-cli` CLI に自動フォールバックします。

## 動作原理

パッケージは `"dsh": { "bundle": { "patch": "pentest.patch.yml" } }` を宣言。`dsh plugin` がインストール後、プロファイルの `dsh.profile.bundles` layer stack へ自動 reconcile します。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 ツールタイムアウトを延長しています。

## アンインストール

```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 は無いので通常不要。それでもブロックされたら profile の `pnpm-workspace.yaml` `allowBuilds` に表示されたキーを追加 |

## 認可

明示的に認可されたターゲットのみに使用してください。persona は未認可スキャンを拒否し、開始前に認可を述べ、報告前に各 finding を検証します。

## License

MIT — [LICENSE](LICENSE) 参照。

🌐 [English](README.md) · [繁體中文](README_zh.md) · [简体中文](README_zh_CN.md)