GHOSTCREW

https://github.com/user-attachments/assets/a67db2b5-672a-43df-b709-149c8eaee975

必要条件

• Python 3.10+
• OpenAI、Anthropic、またはその他の LiteLLM 対応プロバイダーの API キー

インストール

# Clone
git clone https://github.com/GH05TCREW/pentestagent.git
cd pentestagent

# Setup (creates venv, installs deps)
.\scripts\setup.ps1   # Windows
./scripts/setup.sh    # Linux/macOS

# Or manual
python -m venv venv
.\venv\Scripts\Activate.ps1  # Windows
source venv/bin/activate     # Linux/macOS
pip install -e ".[all]"
playwright install chromium  # Required for browser tool

設定

プロジェクトのルートに .env を作成します。

ANTHROPIC_API_KEY=sk-ant-...
PENTESTAGENT_MODEL=claude-sonnet-4-20250514

または、OpenAI を使用する場合：

OPENAI_API_KEY=sk-...
PENTESTAGENT_MODEL=gpt-5

LiteLLM 対応モデルならどれでも使用できます。

リレー／カスタム API ベースの使用

OPENAI_API_BASE を使って、PentestAgent を任意の OpenAI 互換エンドポイントに接続します。

OPENAI_API_KEY=your-relay-token
OPENAI_API_BASE=https://relay.example/v1
PENTESTAGENT_MODEL=openai/<model-name-on-your-relay>

Anthropic 互換エンドポイントの場合は、代わりに ANTHROPIC_API_BASE を使用してください。 プロバイダーの詳細と埋め込みオプションについては、.env.example を参照してください。

実行

pentestagent                      # Launch TUI
pentestagent -t 192.168.1.1       # Launch with target
pentestagent tui --docker         # Run tools in Docker container

Docker

分離された環境で、ペネトレーションテストツールがあらかじめインストールされた Docker コンテナ内でツールを実行します。

オプション 1：ビルド済みイメージを取得（最速）

# Base image with nmap, netcat, curl
docker run -it --rm \
  -e ANTHROPIC_API_KEY=your-key \
  -e PENTESTAGENT_MODEL=claude-sonnet-4-20250514 \
  ghcr.io/gh05tcrew/pentestagent:latest

# Kali image with metasploit, sqlmap, hydra, etc.
docker run -it --rm \
  -e ANTHROPIC_API_KEY=your-key \
  ghcr.io/gh05tcrew/pentestagent:kali

オプション 2：ローカルでビルド

# Build
docker compose build

# Run
docker compose run --rm pentestagent

# Or with Kali
docker compose --profile kali build
docker compose --profile kali run --rm pentestagent-kali

コンテナ内では、Linux のペネトレーションテストツールを使用して PentestAgent を実行します。エージェントはターミナルツールを介して、nmap、msfconsole、sqlmap などを直接使用できます。

Docker がインストールされ、実行中である必要があります。

モード

PentestAgent には 3 つのモードがあり、TUI のコマンドから利用できます。

モード	コマンド	説明
アシスト	/assist <task>	ツールを実行しながら、単発の指示を実行します
エージェント	/agent <task>	1 つのタスクを自律的に実行します
クルー	/crew <task>	マルチエージェントモードです。オーケストレーターが専門のワーカーを起動します
インタラクト	/interact <task>	対話モードです。エージェントとチャットし、ペネトレーションテストの手順を支援してもらいながら進められます

TUI コマンド

/assist <task>    One single-shot instruction.
/agent <task>     Run autonomous agent on task
/crew <task>      Run multi-agent crew on task
/interact <task>  Chat with the agent in guided mode
/target <host>    Set target
/tools            List available tools
/notes            Show saved notes
/report           Generate report from session
/memory           Show token/memory usage
/prompt           Show system prompt
/conversations    Browse and restore saved conversations
/mcp <list/add>   Visualizes or adds a new MCP server.
/spawn [target] [--scope CIDR] [--model M] [--no-rag] [--no-mcp]
                  Manually spawn a child MCP agent from the TUI.
/despawn <server_name>
                  Terminate and remove a previously spawned child agent.
/clear            Clear chat and history
/quit             Exit (also /exit, /q)
/help             Show help (also /h, /?)

実行中のエージェントを停止するには Esc を押します。終了するには Ctrl+Q を押します。

プレイブック

PentestAgent には、ブラックボックスセキュリティテスト用の攻撃プレイブックがあらかじめ用意されています。プレイブックでは、特定のセキュリティ評価に対する体系的なアプローチを定義します。

プレイブックの実行：

pentestagent run -t example.com --playbook thp3_web

ツール

PentestAgent には組み込みツールが含まれており、拡張性のために MCP（Model Context Protocol）をサポートしています。

組み込みツール： terminal、browser、notes、web_search（TAVILY_API_KEY が必要）、spawn_mcp_agent

エージェントの自己生成（spawn_mcp_agent）

spawn_mcp_agent は、実行中のエージェントが、自身の子コピーを標準入出力経由で接続された下位の MCP サーバーとして生成できる組み込みツールです。子プロセスは完全に分離されており、独自のランタイム、LLM クライアント、会話履歴、メモストアを持ちます。生成後、子のツール一式が親エージェントの利用可能なツールに追加されます。

これにより、外部のオーケストレーションなしで、階層型のマルチエージェントワークフローを実現できます。エージェントは、必要に応じて生成した子に範囲を限定したサブタスクを委任し、自律的に編成します。

引数	型	デフォルト	説明
target	string	—	子に渡すペンテストの対象
scope	string[]	—	子のスコープ内の対象／CIDR
model	string	環境変数	子の PENTESTAGENT_MODEL を上書きするモデル識別子
no_rag	boolean	false	子での RAG エンジンの初期化をスキップします
no_mcp	boolean	true	子での外部 MCP サーバーへの接続をスキップします（推奨）

spawn_mcp_agent の戻り後、子のツール（run_task、run_task_async、await_tasks など）は次のツール呼び出しで利用可能になります。子のサーバー名は自動的に割り当てられ（例：child_agent_1）、結果として返されます。

例 — オーケストレーターが 2 つの子に偵察を並行して委任する場合：

# Turn 1: spawn two isolated child agents
spawn_mcp_agent  target="10.0.1.0/24"  scope=["10.0.1.0/24"]
spawn_mcp_agent  target="10.0.2.0/24"  scope=["10.0.2.0/24"]

# Turn 2: children's tools are now available — delegate work asynchronously
child_agent_1__run_task_async  task="Full port scan and service enumeration"
child_agent_2__run_task_async  task="Full port scan and service enumeration"

# Turn 3: wait and collect
child_agent_1__await_tasks  task_ids=["<id1>"]  timeout_seconds=600
child_agent_2__await_tasks  task_ids=["<id2>"]  timeout_seconds=600
child_agent_1__get_task_result  task_id="<id1>"
child_agent_2__get_task_result  task_id="<id2>"

子エージェントの手動制御（/spawn と /despawn）

自動の spawn_mcp_agent ツールに加えて、TUI には、実行中のエージェントループとは独立して子エージェントを手動で生成、終了できる 2 つのコマンドがあります。

/spawn

/spawn [target] [--scope CIDR ...] [--model MODEL] [--no-rag] [--no-mcp]

標準入出力経由で新しい子 MCP エージェントを生成し、現在のセッションに接続します。子は TUI サイドバーに折りたたみ可能なターミナルパネルとして表示され、次のツール呼び出しからそのツールを親エージェントが利用できるようになります。

引数	説明
target	子に渡すペンテストの対象（位置引数または --target）
--scope CIDR	スコープ内の CIDR を 1 つ以上指定します（繰り返し指定可能）
--model MODEL	子エージェントのモデルを上書きします
--no-rag	子での RAG エンジンの初期化をスキップします
--no-mcp	子での外部 MCP サーバーへの接続をスキップします

例：

/spawn 10.0.1.1
/spawn 10.0.1.1 --scope 10.0.1.0/24 --model claude-sonnet-4-20250514
/spawn --target 10.0.1.1 --scope 10.0.1.0/24 --no-rag

/despawn

/despawn <server_name>

server_name で指定した子エージェント（例：child_agent_1）を終了し、TUI からそのターミナルパネルを削除して、親セッションからそのツールを切断します。現在アクティブなすべての子エージェント名を確認するには、/mcp list を使用してください。

例：

/despawn child_agent_1

MCP RAG ツールオプティマイザー

MCP サーバーが128個を超えるツールを公開している場合、PentestAgent は完全なカタログを単一の mcp_<server>_rag_optimizer ツールに自動的に置き換えます。このメタツールは、LiteLLM を介した埋め込みの類似度（デフォルトは text-embedding-3-small）を使用して、そのタスクに最も関連するツールを取得し、エージェントの次のターンに挿入します。これにより、すべてのツールセットにアクセスできる状態を保ちながら、コンテキストウィンドウを管理しやすいサイズに維持できます。

オプティマイザーはエージェントに対して透過的です。エージェントは必要な機能を説明する焦点を絞った自然言語クエリで RAG ツールを呼び出し、一致するツールが次のターンで直接呼び出せるようになります。

エージェント向けの使用ガイダンス：

引数	型	デフォルト	説明
queries	string[]	(必須)	必要な機能ごとに1つの焦点を絞ったクエリを指定します。具体的であるほど精度が高くなります
top_k	integer	20	クエリごとに取得するツール数（最大128）。結果は統合され、重複が除去されます

埋め込みは起動時に一度だけ計算され、キャッシュされるため、繰り返しのクエリは高速です。オプティマイザーはサーバーごとに構築されるため、ツールのカタログが大きい各 MCP サーバーには、それぞれ独立したインデックスが作成されます。

ヒント： すべてを1つのクエリにまとめるのではなく、機能ごとにクエリを1つ指定してください。["list open ports on a host", "get process memory usage"] のほうが、["list ports and memory and CPU"] より良い結果を取得できます。

MCP 統合

PentestAgent は MCP（Model Context Protocol）を2つの方向でサポートしています。外部 MCP サーバーをツールソースとして利用する方法と、外部クライアント（Claude Desktop、Cursor など）が PentestAgent をプログラムから操作できるよう、PentestAgent 自身を MCP サーバーとして公開する方法です。

---

外部 MCP サーバーの利用（クライアントモード）

mcp_servers.json を設定して、PentestAgent を任意の外部 MCP サーバーに接続します。設定例：

{
  "mcpServers": {
    "nmap": {
      "command": "npx",
      "args": ["-y", "gc-nmap-mcp"],
      "env": {
        "NMAP_PATH": "/usr/bin/nmap"
      }
    }
  }
}

---

PentestAgent を MCP サーバーとして公開（サーバーモード）

PentestAgent は MCP サーバーとして実行できます。これにより、MCP 互換クライアントはタスクを送信し、結果を確認し、エージェントをリモートから制御できます。次の2種類のトランスポートに対応しています。

STDIO — ローカルクライアント向け（例：Claude Desktop、Cursor）：

pentestagent mcp_server --type stdio
pentestagent mcp_server --type stdio --target 192.168.1.1 --scope 192.168.1.0/24
pentestagent mcp_server --type stdio --model claude-sonnet-4-20250514 --docker

SSE（HTTP） — リモートクライアントまたはネットワーク接続されたクライアント向け：

pentestagent mcp_server --type sse
pentestagent mcp_server --type sse --host 0.0.0.0 --port 8080
pentestagent mcp_server --type sse --target 10.0.0.1 --scope 10.0.0.0/24 --docker

SSE トランスポートは単一の /mcp エンドポイントを公開し、POST（リクエスト）、GET（サーバー起点のプッシュ用の永続的な SSE ストリーム）、DELETE（セッションの終了）をサポートします。セッションは Mcp-Session-Id ヘッダーを使用して追跡されます。

mcp_server の全フラグ：

フラグ	デフォルト	説明
--type	(必須)	トランスポート：stdio または sse
--host	0.0.0.0	SSE のバインド先ホスト
--port	8080	SSE のバインド先ポート
--target	なし	主なペンテスト対象（IP / ホスト名）
--scope	[]	スコープ内の対象／CIDR（スペース区切り）
--model	環境変数	モデル識別子。PENTESTAGENT_MODEL を上書きします
--docker	false	LocalRuntime の代わりに DockerRuntime を使用します
--no-rag	false	RAG エンジンの初期化をスキップします
--no-mcp	false	外部 MCP サーバーへの接続をスキップします

例：Claude Desktop の設定（claude_desktop_config.json）

{
  "mcpServers": {
    "pentestagent": {
      "command": "pentestagent",
      "args": ["mcp_server", "--type", "stdio"]
    }
  }
}

---

MCP サーバーのツールリファレンス

MCP サーバーとして動作する場合、PentestAgent は以下のツールを公開します。

サーバーの状態と設定

ツール	説明
get_server_status	サーバーのリアルタイムの状態：準備状況、状態別のタスク数、プライマリターゲット／スコープ、メモリストアのサイズ
get_config	プライマリエージェントの設定：ターゲット、スコープ、最大反復回数、ツール一覧
update_config	後続のすべてのタスクに適用するターゲット、スコープ、または最大反復回数を更新します

タスクの実行

ツール	説明
run_task	タスクを送信し、完了するまでブロックします。結果全体、使用したツール、メモのスナップショットを返します
run_task_async	タスクを送信し、task_id を返して直ちに戻ります。get_task_status でポーリングします

タスクの確認

ツール	説明
list_tasks	ステータス、ターゲット、概要とともにすべてのタスクを一覧表示します。ステータスで絞り込み可能です
get_task_status	タスクの現在のステータスと結果のプレビューをポーリングします
get_task_result	タスク結果全体：最終出力、思考ステップ、すべてのツール呼び出しと結果、メモのスナップショット
await_tasks	指定した非同期タスク ID のすべてが完了するまでブロックします（500 ms ごとにポーリングし、タイムアウトを設定可能です）

タスクの制御

ツール	説明
cancel_task	ID を指定して、実行中または保留中のタスクをキャンセルします

ツールの管理

ツール	説明
list_tools	エージェントが利用できるすべてのツールを一覧表示します
enable_tool	プライマリエージェントで指定したツールを有効にします
disable_tool	プライマリエージェントで指定したツールを無効にします

会話履歴

ツール	説明
get_conversation_history	タスクまたはプライマリエージェントのメッセージ履歴を返します。limit パラメーターに対応しています
reset_conversation	タスクまたはプライマリエージェントの会話履歴を消去します

メモリ

ツール	説明
store_memory	キーと値のペアをプロセス内のメモリストアに永続化します
retrieve_memory	完全一致するキーで取得するか、部分文字列で検索するか、すべてのキーを一覧表示します
clear_memory	特定のキーを削除するか、scope='all' ですべてのメモリを消去します

可観測性

ツール	説明
get_logs	最近の実行ログを返します。レベル（info / warning / error）で絞り込み可能です
get_metrics	ランタイムメトリクス：タスク数、成功率、ツール呼び出し総数、メモリとログのサイズ

---

非同期タスクのワークフロー例

時間のかかる偵察タスクには、非同期パターンを使用します。

# 1. Submit tasks without blocking
run_task_async  task="Enumerate subdomains of example.com"  target="example.com"
run_task_async  task="Run nmap SYN scan on example.com"     target="example.com"

# 2. Block until both finish (up to 5 minutes)
await_tasks  task_ids=["<id1>", "<id2>"]  timeout_seconds=300

# 3. Retrieve full results
get_task_result  task_id="<id1>"
get_task_result  task_id="<id2>"

---

CLI ツールの管理

pentestagent tools list         # List all tools
pentestagent tools info <name>  # Show tool details
pentestagent mcp list           # List MCP servers
pentestagent mcp add <name> <command> [args...]  # Add MCP server
pentestagent mcp test <name>    # Test MCP connection

会話履歴の制御

TUI では、各ユーザーメッセージにインラインアクションボタン rewind と fork が表示されます。

Rewind

任意のユーザーメッセージで rewind をクリックすると、会話がそのメッセージの直前まで切り詰められます。これは UI とエージェントのメモリ内履歴の両方に適用されます。破棄した経路を保存せずに、クエリを最初からやり直す場合に使用します。

Fork

任意のユーザーメッセージで >> fork をクリックすると、その時点から会話を分岐します。

1. 現在の会話全体が会話ストアに保存され、短いスナップショット ID が表示されます。
2. その後、会話は選択したメッセージの直前まで切り詰められます（rewind と同じです）。

これにより、元のスレッドを /conversations から再取得できる状態に保ちながら、任意の時点から別の方法を試せます。

---

会話履歴

PentestAgent はすべての会話を自動的に保存するため、過去のセッションを確認、比較、復元できます。

自動保存は、各 /assist、/agent、/crew、/interact タスクの後、および /clear の前に実行されます。最大 20 件の会話が保持され、古いものは自動的に削除されます。

**保存場所：**ワークスペースがアクティブな場合は workspaces/<active>/memory/conversations/、それ以外の場合はプロジェクトルートの conversations/ です。各会話は JSON ファイルとして保存されます。

/conversations で閲覧・復元：

/conversations コマンドを実行すると、TUI 内に分割ペインのモーダルが開きます。

• 左パネル — タイトルと日付が表示された、保存済み会話の一覧です。
• 右パネル — メタデータのプレビューと最初の 5 件のメッセージ（ユーザーメッセージは青、エージェントの応答は緑、ツール呼び出しは黄、ツールの結果は灰色）が表示されます。追加のメッセージ数も表示されます。

会話を選択して Restore を押すと、現在のセッションに読み込まれます。Close を押すと、モーダルが閉じます。

ナレッジ

• **RAG：**方法論、CVE、ワードリストを pentestagent/knowledge/sources/ に配置すると、コンテキストに自動的に注入されます。
• **メモ：**エージェントは調査結果をカテゴリ（credential、vulnerability、finding、artifact）とともに loot/notes.json に保存します。メモはセッションをまたいで保持され、エージェントのコンテキストに注入されます。
• **シャドウグラフ：**Crew モードでは、オーケストレーターがメモからナレッジグラフを構築し、戦略的な洞察（例：「ホスト X の認証情報を取得しています」）を導き出します。

プロジェクト構成

pentestagent/
  agents/         # Agent implementations
  config/         # Settings and constants
  interface/      # TUI and CLI
  knowledge/      # RAG system and shadow graph
  llm/            # LiteLLM wrapper
  mcp/            # MCP client and server configs
  playbooks/      # Attack playbooks
  runtime/        # Execution environment
  tools/          # Built-in tools

開発

pip install -e ".[dev]"
pytest                       # Run tests
pytest --cov=pentestagent    # With coverage
black pentestagent           # Format
ruff check pentestagent      # Lint

法的事項

明示的にテストの許可を得たシステムに対してのみ使用してください。許可のないアクセスは違法です。

ライセンス

MIT