pentest-kb MCP Server

侵入テストの経験ナレッジベースを扱う MCP サーバーです。MCP (Model Context Protocol) に基づき、検索・追加・一覧表示などのツールを提供し、侵入テストの実戦経験を蓄積・再利用するためのものです。

このプロジェクトが解決する問題

背景となる課題：

• 侵入テストの経験がノート、チャット履歴、個人の記憶に散在しており、検索や再利用が難しい。同種の問題（WAF バイパス、403 バイパスなど）に直面するたびに、再度検索しなければならないことが多い

• Agent はデフォルトでは個人のナレッジベースにアクセスできないため、侵入テストの質問に対して汎用的な知識に頼るしかなく、実戦経験による裏付けがないまま、具体性に欠けたアドバイスになりがち

• 経験を蓄積できず、シーンをまたいで再利用できないため、個人やチームが積み上げた知識を体系化することが難しい

このプロジェクトの解決策：

• 侵入テストの経験を PostgreSQL（Supabase）データベースに一元蓄積し、構造化して保存する

• MCP プロトコルを通じてナレッジベースを Agent に接続し、Agent が経験を直接検索（search_experience）、追加（add_experience）、一覧表示（list_all_experiences）できるようにする

• 検索は BM25 関連性ランキング（jieba による中国語分かち書き）に基づいており、単純な曖昧一致よりも正確

• 実戦シーンでは、Agent が汎用知識だけに頼るのではなく、個人のナレッジベースに基づいて回答できるようにする

Related MCP server: Nümtema Private Knowledge MCP

機能

• search_experience(keyword, tags_filter)：BM25 関連性ランキングに基づきナレッジベースを検索します（承認済みレコードのみ）。中国語の分かち書きに対応し、Top 10 を返します。tags_filter でシナリオタグによる精密フィルタリングが可能です（例：["WAF绕过"]）

• add_experience(title, detail, scenario_tags, tool_code, tool_type, status)：経験を追加します。status='draft' の場合は承認待ちの下書きとして保存し（デフォルト）、status='approved' の場合は直接本登録します。書き込み前に自動でマスキング検証を実行します（実在 IP、ドメイン、認証情報、クラウドベンダーの AccessKey、JWT、秘密鍵、電話番号を検出し、該当する場合は拒否）

• list_all_experiences(limit, offset)：ナレッジベース内の承認済み全レコードのタイトルをページングで一覧表示します（デフォルト 1 ページ 50 件、最大 200 件）

• find_similar(title, detail)：重複チェックを行い、指定された内容に類似する登録済みレコードを検索します

• get_experience(experience_id)：id で経験 1 件の完全な内容（タイトル、詳細、タグ、ツールコード、ステータスなど）を取得します

• update_experience(experience_id, title, detail, scenario_tags, tool_code, tool_type, status)：経験のフィールドを更新します（渡されたフィールドのみ更新し、渡されていないフィールドは変更しません。変更前には自動でマスキング検証を実行します）

• list_pending_experiences()：承認待ちの下書きを一覧表示し、各下書きについて重複する可能性のある登録済みレコードを提示します

• approve_experience(experience_id, merge_with_id)：下書きを承認します。merge_with_id を指定すると、指定レコードにマージしてから（詳細を追記、タグを統合、ツール情報を補完）下書きを削除します

• reject_experience(experience_id)：下書きを拒否します（ソフト削除。レコードは rejected として保持され、復元可能）

• delete_experience(experience_id)：承認済みの経験をソフト削除します（ステータスを deleted に設定。検索対象には含まれず、復元可能）

• restore_experience(experience_id)：ソフト削除されたレコードを復元します（拒否された下書き→draft、削除された経験→approved）

• list_deleted_experiences()：ソフト削除された全レコード（ゴミ箱）を一覧表示します。復元や完全削除に利用できます

• purge_experiences(days)：ソフト削除されてから指定日数を超えたレコードを物理削除します（デフォルト 30 日、復元不可。注意して実行してください）

経験の蓄積と承認

自動蓄積による冗長な内容の生成や機密情報の漏えいを防ぐため、「半自動蓄積 + 強制マスキング + 人による承認」のフローを採用しています：

实战结束 → Agent 生成经验草稿（status='draft'，结构化 + 限长 + 脱敏）
        → 草稿进入待审批状态（不直接入库，不参与检索）
        → 用户审批（list_pending 查看 → approve / reject / merge）
        → 通过后才正式入库（status='approved'）

マスキング対策：add_experience は書き込み前に、実在 IP アドレス、ドメイン、メールアドレス、認証情報（中国語の「密码/口令/密钥/账号」など）、クラウドベンダーの AccessKey（AWS/Aliyun/Tencent）、JWT、秘密鍵ブロック、電話番号を自動検出し、該当する場合は書き込みを拒否して、プレースホルダー（例：<目标URL>、<目标域名>）への置換を要求します。プライベート/ループバック/リンクローカルなどの特殊な IP と、ホワイトリスト登録されたドメイン（example.com など）は本登録可能です。

重複チェック対策：承認時に list_pending_experiences が、各下書きについて重複する可能性のある登録済みレコードを自動的に提示します。ユーザーはスキップ、マージ、またはそのまま新規登録を選択できます。

直接本登録 vs 下書き承認：add_experience は status='approved' で直接本登録できますが、これはユーザーが手動で確認した入力シーンにのみ使用します。AI ワークフロー（SKILL.md を参照）では、必ず draft 下書きを生成して承認を受ける必要があり、直接本登録してはいけません。

依存関係

• Python 3.10+

• mcp（MCP Python SDK）

• psycopg2（PostgreSQL ドライバ）

• jieba（中国語分かち書き。起動時にルートディレクトリの pentest_dict.txt 分野辞書を自動ロード）

• rank_bm25（BM25 検索アルゴリズム）

• PostgreSQL データベース（Supabase など）

依存関係のインストール：

pip install -r requirements.txt

依存リストは requirements.txt を参照してください（バージョン範囲を固定済み。mcp は 2.x である必要があります）。

データベース初期化

PostgreSQL（Supabase など）で、リポジトリルートの schema.sql を実行します（冪等で、繰り返し実行可能）：

# 方式一：Supabase 控制台 → SQL Editor → 粘贴 schema.sql 内容执行
# 方式二：命令行（需已配置 psql）
psql "$PENTEST_KB_DB_CONNECTION_STRING" -f schema.sql

テーブル構造は以下のとおりです（schema.sql が唯一の保守元であり、README では SQL を重複掲載しません）：

オプション：セマンティック検索列（現在のコードでは未使用。将来用に予約） ベクトルセマンティック検索を導入する場合は、schema.sql 末尾のコメントを解除して実行してください（事前に pgvector 拡張を有効にする必要があります）。

設定

データベース接続情報は環境変数で注入します。コード内に認証情報をハードコードしないでください：

MCP クライアント設定

MCP クライアントでサーバーを登録します。mcp.example.json を参照してください：

{
  "mcpServers": {
    "pentest-kb": {
      "command": "python",
      "args": ["/absolute/path/to/pentest_kb_mcp.py"],
      "env": {
        "PENTEST_KB_DB_HOST": "your-supabase-host.pooler.supabase.com",
        "PENTEST_KB_DB_PORT": "5432",
        "PENTEST_KB_DB_NAME": "postgres",
        "PENTEST_KB_DB_USER": "postgres.your-project-ref",
        "PENTEST_KB_DB_PASSWORD": "your-database-password"
      }
    }
  }
}

使用方法

MCP クライアントでツールを呼び出すだけです。例：

搜索：search_experience(keyword="WAF绕过")   # BM25 相关性排序
搜索+标签过滤：search_experience(keyword="绕过", tags_filter=["WAF绕过"])   # 只看 WAF 相关
新增（直接入库，仅手动操作）：add_experience(title="Nginx 403 绕过", detail="...", scenario_tags=["WAF绕过"], tool_type="burp", status="approved")
新增草稿：add_experience(title="...", detail="...")   # 默认 status='draft'，待审批
查重：find_similar(title="...", detail="...")
查看单条：get_experience(experience_id="...")
修改：update_experience(experience_id="...", detail="...")   # 只更新传入字段
查看草稿：list_pending_experiences()
审批：approve_experience(experience_id="...")   # 或 merge_with_id 合并
拒绝：reject_experience(experience_id="...")   # 软删除，可恢复
删除：delete_experience(experience_id="...")   # 软删除已审批经验
恢复：restore_experience(experience_id="...")
回收站：list_deleted_experiences()
清理：purge_experiences(days=30)   # 物理删除超期软删记录
列出：list_all_experiences(limit=50, offset=0)   # 分页

Skill のカプセル化

カスタム Skill としてカプセル化済みです。ファイルはプロジェクトルートの SKILL.md にあり、実行フローに沿って 6 つのフェーズに整理されています：

• フェーズ 1：意図の判断

• フェーズ 2：情報収集の優先

• フェーズ 3：ナレッジベース検索のトリガー

• フェーズ 4：結果の引用と回答

• フェーズ 5：実行と適用除外の規定

• フェーズ 6：経験の蓄積

SKILL.md をカスタム Skill ディレクトリに配置すれば読み込まれます。

セキュリティについて

• データベース認証情報は環境変数を通じてのみ注入され、リポジトリには実際の接続情報は一切含まれません

• データベースのパスワードは定期的にローテーションし、弱いパスワードを避けてください