hackingBuddyGPT: LLMペンテストエージェントを20行から組み立てる枠組み
Helping Ethical Hackers use LLMs in 50 Lines of Code or less..
ひと目でわかる
- これは何？
- SSH経由のLinux権限昇格からActive Directoryの仮想侵入まで、LLMエージェントの定型処理を肩代わりするPythonフレームワーク。使える場面と、使うべきでない境界をREADMEの記述だけを根拠に整理する。
- 誰に向いている？
- 自分でLLMペンテストの実験を書き、その再現性を他人に示したい研究者に向く。逆に、認可範囲が曖昧なまま本番網へ向けたい運用担当者や、既製のスキャナ出力が欲しいだけの読者には向かない。
- 商用利用できる？
- できます。MIT は寛容なライセンスで、著作権表示とライセンス表示を残せば、使用・改変・販売が可能です。
- 今もメンテナンスされている？
- されています。最後のコミットは 3 日前です。
- 何の言語で書かれている？
- 主に Python です（GitHub の言語統計による）。
回答はプロジェクトの GitHub データ（最終同期：2026年9月15日）と当サイトの分析に基づくもので、法的助言ではありません。
オープンソース詳細解説
誰のためのフレームワークか、何を肩代わりするのか
LLMにセキュリティテストをさせる実験を書こうとすると、攻撃ロジックより先に配管が要る。LLM接続、SSHやローカルシェルへの接続、ツールの配線、暴走を止める上限、実行ログの保存。hackingBuddyGPTはこの配管部分をまとめて提供し、利用者は「ユースケース」と呼ばれる実験だけを数十行で書ける。READMEはこれを「boring-but-essential groundwork」と表現している。
対象読者はセキュリティ研究者とペネトレーションテスト実施者で、READMEには再現可能な研究のためにLinux権限昇格ベンチマークを別リポジトリで維持していると書かれている。つまり、単発の攻撃ツールではなく、比較実験を回して結果を公開する用途を想定した作りだ。READMEの警告文は明確で、このソフトウェアは実システム上で実コマンドを実行する。ローカルシェルモードなら自分のマシン上、SSHやpsexecモードなら指定した対象上で動く。所有しているか明示的に許可されたシステムにのみ向け、隔離されたVMかコンテナを推奨すると記載されている。
wintermute という単一の入口とユースケースの登録
インストールすると wintermute コマンドが使えるようになる。引数なしで実行すると登録済みのユースケースが一覧表示され、wintermute <UseCase> --help でそのユースケース固有のオプションが見られる。ユースケースはそれぞれ wintermute のサブコマンドになる仕組みだ。
READMEのクイックスタートは次の流れを示している。リポジトリをcloneして uv sync で環境を作り、.env.example を .env にコピーしてLLMキーと対象を設定し、wintermute で一覧を確認してから実行する。最小の権限昇格はこう呼ぶ。
wintermute MinimalPrivEscLinux --conn=ssh --conn.host=192.168.122.151 --conn.username=lowpriv --conn.password=trustno1
接続方式は --conn で切り替え、SSH、ローカルシェル、psexecが用意されている。練習台がなければ、同プロジェクトのLinux権限昇格ベンチマークか、VulnHubのLin.Securityのような意図的に脆弱なVMを使うようREADMEは案内している。CLIの引数名がそのまま設定キーになっている点は、後述する実行制限の指定方法と合わせて覚えておくとよい。
2つの実行スタイルと、成功判定をground truthで縛る設計
フレームワークの中核は、同じループの上に2つの実行スタイルを載せていることだ。ひとつはネイティブなツール呼び出しエージェントで、実際のチャット履歴とfunction callingを使う。もうひとつは単純テキストのコマンド戦略で、Makoテンプレートに履歴全体を流し込み、返答からコマンドを1つだけ抜き出す。MinimalPrivEscLinux が後者、MinimalToolCallPrivEscLinux が前者にあたる。
この2つの違いは成功判定に現れる。MinimalToolCallPrivEscLinux の task_solved ツールはground truthと照合されるため、LLMが「rootを取った」と幻覚したり、降参としてそう答えたりしても、誤った成功として記録されない。READMEはここを明示的に説明している。権限昇格を自動で回すとき、最も壊れやすいのはこの自己申告の部分なので、フレームワーク側がそこに手を入れているのは設計上の判断として妥当だ。
より大きな構成の例として AD ユースケースがある。cochiseから移植されたActive Directoryのassumed-breachテストで、planner/executor型を採る。永続的な戦略プランナーがタスクツリーと共有ナレッジベースを保持し、各タスクを記憶を持たない新しい戦術エグゼキュータに委譲する。AdvancedWebTesting は対象へ直接アクセスせず、境界づけられたサブエージェントに作業を委譲するトップレベルエージェントだ。ExPrivEscLinuxLSE は他ユースケースを呼び出す例で、まず対象上で lse.sh を走らせ、その出力をヒントに変換してから、ヒントごとに PrivEscLinux を編成する。ユースケースがユースケースを呼べるという点は、この枠組みの拡張単位がCLIサブコマンド単位であることと整合している。
実行を止める4つの上限と、proxy経由のLLM接続
自律エージェントを実システムに向けるとき、止め方が決まっていないツールは使えない。hackingBuddyGPTはラウンド数、トークン数、金額、実時間の4種類で上限をかける。CLIでは --limits.max_rounds、--limits.max_tokens、--limits.max_cost、--limits.max_duration として指定する。ドル建てのコスト上限が一級の設定項目になっているのは、従量課金のAPIを回す研究では実用的だ。
LLMの接続先はlitellm経由の単一系統で、llm.model の文字列でプロバイダを切り替える。OpenAI、OpenRouter（既定のエンドポイント）、Anthropic、Azure、ローカルのOllamaなどが到達可能だとREADMEは述べている。API通信をBurpやmitmproxyのような傍受プロキシ経由にしたい場合は --llm.proxy を使う。プロンプトと応答の内容をプロキシで観察したい研究用途では、この指定があるかどうかで作業量が変わる。
ログは実行ごとに追記専用のOpenTelemetry/GenAI JSONLトレースとして書き出され、再生と集計のためのCLIツールが付属する。実行モデルはasyncioベースで完全に非同期だ。多数の対象に対する回帰テスト用に、Dockerフリートのベンチマークランチャーも用意されている。ここで注意したいのは、READMEが示しているのは仕組みの説明であって、精度や速度の数値ではないという点だ。どのモデルがどのユースケースで成功するかは、この記事の材料からは判断できない。
向かない場面: 認可の外側と、既製スキャナの代替として
最大の制約は技術ではなく運用にある。このソフトウェアは実コマンドを実行する。ローカルシェルモードでは自分のマシン上で、SSHやpsexecモードでは指定した対象上で実行される。READMEは所有または明示的に許可されたシステムに限り、隔離VMかコンテナを推奨すると書いている。認可の境界が曖昧な組織では、この前提が満たせない限り導入は成立しない。
もうひとつの誤用は、NessusやOpenVASのような既製スキャナの置き換えとして期待することだ。hackingBuddyGPTが提供するのはユースケースを書くための枠組みであり、MinimalPrivEscLinuxはREADME自身が「Minimal ~20-line」と説明する出発点にすぎない。PrivEscLinuxにはRAG（--rag_path）やchain-of-thought（--enable_cot）、状態追跡が入っているが、これらは精度を保証する機能ではなく、実験の条件を増やすスイッチだ。WebAPITestingも、OpenAPIスペックかサイトマップから対象面を検出してREST APIをテストするという手順を踏むので、対象面が機械可読な形で存在しないサイトでは前提が崩れる。
三つ目に、Python 3.13+ という要件がある。uvを推奨しつつ venv + pip でも動くとREADMEは書いているが、社内の標準ランタイムが3.11や3.12で固定されている環境では、この時点で別環境が必要になる。
代替手段との違い: 自作ループか、汎用エージェントフレームワークか
比較対象として素直なのは、OpenAIやAnthropicのSDKで自分でループを書く方法だ。この場合、LLM接続とfunction callingの配線は自分で持ち、実行上限もログ形式も自分で決める。自由度は最大だが、権限昇格の成功判定をground truthと照合する仕組みや、実行をJSONLトレースとして残す部分を毎回作り直すことになる。hackingBuddyGPTの価値はこの再発明を避けられる点にあり、逆に言えば、ループの中身を根本から変えたい研究には枠組みが邪魔になる可能性がある。
もうひとつの比較軸は汎用のエージェントフレームワークだ。汎用側はツール呼び出しやマルチエージェントの抽象を提供するが、セキュリティテスト固有の要素、つまりSSHやpsexecでの対象接続、権限昇格の成功判定、Linux権限昇格ベンチマークとの接続は持たない。hackingBuddyGPTはそこを最初から用意し、代わりに用途をセキュリティテストに絞っている。ADユースケースのplanner/executor構成のように、汎用側にも似たパターンはあるが、タスクツリーと共有ナレッジベースを前提とした実装が同梱されているかどうかは別の話だ。
どちらが優れているかではなく、実験の再現性を誰に示したいかで選ぶ。同じベンチマーク上で複数のLLMを比較した結果を出したいなら、判定と記録の形式が揃っている側に寄せる理由がある。
ライセンスと保守の見通し
ライセンスはMITで、リポジトリのLICENSEファイルに基づくとREADMEのバッジも示している。MITは商用利用を含めて比較的制約が少ない条件だが、これは法的助言ではなく、実際の利用条件は配布物のライセンス全文と自組織の規程で確認する必要がある。加えて、このツールはlitellm経由で外部のLLMプロバイダにプロンプトと応答を送る。対象システムの情報がプロンプトに含まれる以上、ライセンスとは別に、どのプロバイダへ何を送るかの判断が要る。
保守の面では、リリースは v0.3.0 が2024年8月、v0.4.0 が2025年4月、v0.5.0 が2025年8月と、おおよそ年1回の間隔で刻まれている。既定ブランチは main で、アーカイブ済みではない。更新頻度は高くないので、最新のLLM APIの変更にどこまで追従されるかを前提に運用計画を立てるべきだ。LLM接続をlitellmに一本化している設計は、プロバイダ側の仕様変更を吸収する層が1つに集約されている点で保守上は素直だが、そのlitellm自体の更新に依存するという意味でもある。
アップグレードのコストを見積もるなら、自分のユースケースがフレームワークのどの部分に触れているかを先に把握しておきたい。コマンド戦略方式ならMakoテンプレートと返答のパース、ツール呼び出し方式ならツール定義とチャット履歴の扱いが影響範囲になる。実行制限やログ形式に依存した集計スクリプトを書いている場合は、JSONLトレースのスキーマ変更が波及する。
導入前に自分のラボで確かめること
最初に確認すべきは、対象が自分に許可されたホストであることだ。これは技術検証より先に来る。次に、Python 3.13+ の環境を用意し、uv sync で入れて wintermute を引数なしで実行し、ユースケース一覧が出ることを確かめる。ここまでで枠組みが動くことは確認できる。
そのうえで、MinimalPrivEscLinux を隔離VMに向けて走らせ、--limits.max_rounds を小さく設定して止まり方を観察する。次に MinimalToolCallPrivEscLinux を同じ対象で走らせ、task_solved が実コマンド出力と照合される様子をログで確認する。この2つを並べると、テキスト方式とツール呼び出し方式で挙動がどう変わるかが自分の目で見える。
最後に、生成されたJSONLトレースを付属のCLIツールで再生し、集計が自分の求める粒度で取れるかを確かめる。ここで不足があるなら、フレームワークを採用するか、ループを自作するかの判断材料になる。逆に、認可されたラボと対象VMが用意できず、Python 3.13+ も用意できないなら、この時点で採用を見送るのが素直だ。
編集部の結論
自分でLLMペンテストの実験を書き、その再現性を他人に示したい研究者に向く。逆に、認可範囲が曖昧なまま本番網へ向けたい運用担当者や、既製のスキャナ出力が欲しいだけの読者には向かない。導入前に確認すべきは3点で、対象が自分に許可されたホストかどうか、Python 3.13+ と uv で動く環境があるか、そして wintermute MinimalToolCallPrivEscLinux の task_solved が実コマンド出力と照合される挙動を自分のラボで一度観察できるか。ここまで確かめてから本番系の隣に置くかどうかを決めればよい。
コミュニティノート