---

hackingBuddyGPT は、LLM駆動のセキュリティテストエージェントを構築するためのオープンソースフレームワークです。面倒だが不可欠な基盤 — LLM接続、ターゲットコネクタ（SSH / ローカルシェル / WinRM形式のpsexec）、ケイパビリティ／ツールの配線、実行制限、構造化ログ — を提供するため、新しい実験（「ユースケース」）を数十行のコードで表現できます。私たちは、セキュリティテストにLLM（またはLLMベースの自律エージェント）を活用したいセキュリティ研究者やペネトレーションテスターにとっての定番フレームワークとなることを目指しています。

再現可能な研究を支援するため、再利用可能なLinux権限昇格ベンチマークを維持し、調査結果をオープンアクセスのレポートとして公開しています。タスクに適したLLMの選択に支援が必要な場合は、複数のLLMを比較した論文をご用意しています。

⚠️ このソフトウェアは実際のシステム上で実際のコマンドを実行します。 ローカルシェルモードではあなたのマシン上で、SSH/psexecモードでは指定したターゲット上で実行されます。必ず自身が所有するか、テストを明示的に許可されたシステムに対してのみ実行し、隔離されたVMやコンテナの使用を推奨します。免責事項を参照してください。

クイックスタート

# 1. clone and install (uv is recommended; a plain venv + pip works too)
git clone https://github.com/ipa-lab/hackingBuddyGPT.git && cd hackingBuddyGPT
uv sync && source .venv/bin/activate

# 2. configure your LLM key + target
cp .env.example .env && $EDITOR .env

# 3. list the available use-cases
wintermute

# 4. run one — e.g. a minimal Linux privilege-escalation against an SSH target
wintermute MinimalPrivEscLinux \
    --conn=ssh --conn.host=192.168.122.151 \
    --conn.username=lowpriv --conn.password=trustno1

パッケージをインストールすると wintermute コマンドが利用可能になります。引数なしで実行すると、登録されているすべてのユースケースが一覧表示されます。wintermute <UseCase> --help を実行すると、そのユースケースのオプションが表示されます。

練習用のターゲットが必要ですか？Linux Privilege-Escalation Benchmark から脆弱なボックスを入手するか、VulnHub の Lin.Security のような意図的に脆弱な VM を入手してください。

ユースケース

実験はユースケースとして構造化されています。各ユースケースは wintermute のサブコマンドになります。フレームワークには現在、以下が同梱されています：

権限昇格

コマンド	説明
MinimalPrivEscLinux	約20行の最小限の Linux 権限昇格。毎ラウンド、履歴全体を1つのプロンプトにテンプレート化し、応答から素のコマンドを解析します（古典的な hackingBuddyGPT ループ）。絶好の出発点です — 独自のユースケースを作成するを参照してください。
MinimalToolCallPrivEscLinux	上記のツール呼び出し版：実際のチャット履歴を保持し、関数呼び出しを通じてターゲットを操作します。その task_solved ツールはグラウンドトゥルースに対して検証されるため、幻覚や譲歩による「root 取得」が誤った成功としてスコアされることはありません。
PrivEscLinux	オプションの検索拡張生成（--rag_path）、思考の連鎖（--enable_cot）、状態追跡、構造化ガイダンスを備えた、フル機能の戦略ベースの Linux 権限昇格。
PrivEscWindows	戦略ベースの Windows 権限昇格。SSH の代わりに psexec を通じてターゲットを操作します。
ExPrivEscLinuxLSE	最初にターゲット上で lse.sh を実行し、その出力をヒントに変換してから、ヒントごとに PrivEscLinux をオーケストレーションします — 別のユースケースを呼び出すユースケースの例です。

Web

コマンド	説明
WebTestingWithExplanation	LLM に推論を「語らせ」ながら、HTTP 経由で Web ページを自律的にテストします。OWASP スタイルのペネトレーションテストプレイブック機能を含みます。
WebTestingWithShell	Kali スタイルの攻撃者ボックスへのシェルアクセスを伴う Web テスト。
AdvancedWebTesting	ターゲットへの直接アクセスを持たないトップレベルエージェントで、サブエージェント機能を通じて境界付けられたサブエージェントに作業を委任します。

Web API

コマンド	説明
WebAPITesting	ターゲットの表面 — OpenAPI 仕様 または Web サイトのサイトマップ — を検出し、REST API をペネトレーションテストします。--mode の document（仕様を構築）、test（既知の表面をペネトレーションテスト）、auto（両方）で実行できます。

Active Directory

コマンド	説明
AD	自律型 LLM による Active Directory 侵害想定ペネトレーションテスト。攻撃ツール cochise から移植されました。プランナー/エグゼキューター設計を採用しています：永続的な戦略プランナーがタスクツリーと共有ナレッジベースを維持し、各タスクを新しくメモリを持たない戦術エグゼキューターに委任します。

フレームワークの機能

• 1つの共有ループ上での2つの実行スタイル：ネイティブなツール呼び出しエージェント（実際のチャット履歴 + 関数呼び出し）と、シンプルテキストのコマンド戦略（Mako テンプレート → 単一の解析済みコマンド）。
• 統一された実行制限 — ラウンド数、トークン数、コスト（ドル）、および実時間（--limits.max_rounds/max_tokens/max_cost/max_duration）で任意の実行を制限できます。
• 単一の LLM アップストリーム：litellm。 llm.model 文字列を通じて任意のプロバイダーに到達できます — OpenAI、OpenRouter（デフォルトのエンドポイント）、Anthropic、Azure、ローカルの Ollama など。--llm.proxy で API トラフィックを傍受プロキシ（Burp/mitmproxy）経由にルーティングできます。
• 構造化された自己完結型ログ — すべての実行は追記専用の OpenTelemetry/GenAI JSONL トレースとして書き出され、実行の再生と集計のための CLI ツールが付属します。
• asyncio 上に構築された完全非同期の実行モデル。
• 権限昇格のためのグラウンドトゥルース検証済みの成功検出（「root 取得」の主張は実際のコマンド出力に対して検証されます）。
• 多数のターゲットに対して一度に回帰テストを行うための Docker フリートベンチマークランチャー。

インストールとセットアップ

要件: Python 3.13+。このプロジェクトは uv ビルドバックエンドを使用しています。環境管理には uv の使用を推奨しますが、通常の python -m venv + pip でも動作します。

git clone https://github.com/ipa-lab/hackingBuddyGPT.git
cd hackingBuddyGPT

# option A (recommended): uv creates .venv and installs the project
uv sync
source .venv/bin/activate

# option B: a plain virtual environment + pip
python -m venv venv && source ./venv/bin/activate
pip install -e .

オプションの依存関係グループ: testing (pytest など)、dev (ruff)、rag (PrivEscLinux --rag_path 用の RAG スタック)。インストールするには、例えば uv sync --extra testing または pip install '.[testing]' を実行します。

設定

設定は4つのレイヤーから解決され、それぞれが前のレイヤーを上書きします:

1. 環境変数、
2. カレントディレクトリの .env ファイル (cp .env.example .env から始めてください)、
3. --config config.json で渡される JSON ファイル、
4. --key=value コマンドラインフラグ (最優先)。

コマンドラインで渡せるオプションは、.env または JSON 設定でも指定できます。LLM の選択は litellm を通じてプロバイダーに依存しません:

オプション	備考
llm.api_key	プロバイダーの API キー (シークレット)。
llm.model	litellm 形式のモデル。例: gpt-4o、openrouter/anthropic/claude-3.5-sonnet、ollama_chat/llama3。
llm.context_size	最大コンテキストサイズ。プロンプトのトリミングに使用されます。
llm.api_base	エンドポイントのベース URL。デフォルトは OpenRouter (https://openrouter.ai/api) です。OpenAI やローカルの Ollama などを指定してください。
llm.provider	OpenRouter のプロバイダールーティング (それ以外の場合は空のままにします)。
llm.proxy / llm.proxy_insecure	Burp や mitmproxy などのインターセプトプロキシ経由でリクエストをルーティングします。

💡 エンドポイントはデフォルトで OpenRouter になるため、OpenAI に直接接続したい場合やローカルモデルを使用したい場合は、llm.api_base (または対応する llm.model プレフィックス) を設定してください。

各ユースケースの全オプションセットは --help で確認できます:

$ wintermute PrivEscLinux --help
usage: wintermute PrivEscLinux [--help] [--config config.json] [options...]

    --log.log_dir='logs'         directory for the per-run JSONL log files
    --log.tag=''                 tag for your current run
    --limits.max_rounds=100      maximum number of rounds (0 = no limit)
    --limits.max_tokens=0        maximum number of tokens (0 = no limit)
    --limits.max_cost=10.0       maximum cost in dollars (0 = no limit)
    --limits.max_duration=0      maximum run duration in seconds (0 = no limit)
    --llm.api_key                API key for the upstream
    --llm.model                  model name in litellm format
    --llm.context_size           maximum context size of the model
    --llm.api_base='https://openrouter.ai/api'   base URL of the API
    --llm.api_timeout=300        per-request timeout in seconds
    --llm.proxy=''               proxy URL for the API calls (e.g. Burp/mitmproxy)
    --conn.host / --conn.username / --conn.password
    --conn.hostname='' --conn.keyfilename='' --conn.port=22
    # PrivEscLinux extras: --hints, --enable_cot, --enable_structured_guidance,
    #                      --enable_update_state, --enable_explanation, --rag_path

接続モード

ターゲットを操作するほとんどのユースケースでは、--conn モードを受け付けます:

ローカルシェル (tmux セッション経由でお使いのマシン上で実行されます — 開発に便利です):

# terminal 1: create a named tmux session
tmux new-session -s hacking_session