Autonomous Pentest Agent ローカル導入チュートリアル：インストール設定から自律探索・再テストまで

まずプロジェクトと利用範囲を理解する

Autonomous Pentest Agent は、LLM によるマルチエージェントで駆動する自律型ペネトレーションテストシステムです。Go バックエンド、Next.js フロントエンド、PostgreSQL を採用しています。タスク、アセット、探索チェーン、検出結果、トラフィック記録、ツール承認、人間参加型の対話を管理できます。

重要な安全およびコンプライアンスに関する注意：README では、本プロジェクトを個人学習、ソースコード研究、ローカルの隔離環境における技術検証にのみ使用し、いかなるウェブサイト、オンラインサービス、ネットワーク接続されたシステム、本番環境、実際のペネトレーションテストにも使用しないよう明記しています。自分が管理権限を持つローカルの検証環境でのみ使用し、所在地域のサイバーセキュリティ、データ保護、コンピューター犯罪に関する法令を遵守してください。

プロジェクトには、操作画面を確認するためのオンライン Demoが用意されていますが、実際のデプロイと検証は必ずローカルの隔離環境に限定してください。

主な機能と画面

システムのフロントエンドには、ダッシュボード、タスク一覧、実行セッション、探索チェーン、検出結果、アセット、アセットカバレッジ図、トラフィック録画、Agent 管理、LLM 設定、インターセプト承認、バックエンドログなどのページがあります。

ダッシュボードでは、全体の状態、Token 消費量、アクティビティストリームを確認できます。タスクとセッションのページでは、Agent セッションやツール呼び出しを含むタスクの実行過程を表示します。

探索チェーンでは、ターゲット、意図、事実、検出結果の間にある系譜関係を確認できます。検出結果のページでは脆弱性とその証拠を確認し、アセットのページではシステムが収集・統合したターゲットアセットを閲覧できます。

システムアーキテクチャの概要

システムは、Next.js の静的フロントエンドを内包した Go モノリシックバックエンド、PostgreSQL、Agent エンジン、および複数の補助サブシステムで構成されています。バックエンドは REST API、JWT 認証、SSE を通じてフロントエンドにサービスを提供し、タスクエンジンが planner と複数の worker をスケジューリングします。

プロジェクトは二重グラフアーキテクチャを採用しています。

• アセットグラフ：タスクをまたいで共有されるアセットの正規データベースです。ルートドメイン、サブドメイン、IP、サービス、アプリケーション、エンドポイントなどのノードが含まれます。
• 探索グラフ：タスクごとにターゲット、意図、事実、ヒント、検出結果を記録し、系譜関係によって探索過程を表現します。
• アンカー関係：探索ノードを具体的なアセットに関連付け、アセットのテストカバレッジと探索範囲を確認できるようにします。

Planner は探索状況を読み取り、意図を割り当てます。Worker は意図を取得し、ツールを使用して実行した後、事実、アセット、検出結果を書き戻します。グラフに変化が生じると Planner が再び起動され、イベント駆動の循環処理が形成されます。複数の Worker は他の Worker の実行過程も検索でき、共有 todolist によって複数回にわたる計画を依存関係に沿って連続的に進められます。

インストール前の準備

プロジェクトの実行には、少なくとも PostgreSQL が必要です。探索を実行するには LLM の設定も必要で、ANTHROPIC_API_KEY または OPENAI_API_KEY を使用できます。後から Web インターフェースの「LLM 設定」ページに入力することも可能です。

データベースとアプリケーションをすばやく起動できるよう、Docker の準備を推奨します。どのデプロイ方法を選ぶ場合でも、まず隔離されたローカルテストネットワークを作成し、重要なデータをバックアップして、テスト対象がローカルの実験環境に属していることを確認してください。

方法一：ワンクリックインストールスクリプトを使用する

README で推奨されているインストール方法です。スクリプトは Docker の有無を確認し、必要に応じてインストールしたうえで、完全な Docker デプロイまたはローカルでのビルドと実行を選択できるようにします。

git clone https://github.com/kutukam/autonomous-pentest-agent.git
cd autonomous-pentest-agent
./install.sh

完全な Docker デプロイを選択すると、スクリプトは PostgreSQL パスワードの入力を求めます。Enter キーを押してランダムなパスワードを生成することもできます。その後、.env に書き込み、docker compose up -d を実行します。ローカル実行を選択した場合は、既存のデータベースに接続するか、Docker でデータベースを起動できます。スクリプトは config.json を生成し、フロントエンドを内包した Go 単一バイナリをビルドしてサービスを起動します。

インストール完了後、http://localhost:8787 にアクセスします。初回アクセス時に /setup を開き、管理者パスワードを設定してください。

方法二：Docker Compose を使用する

環境を手動で管理したい場合は、Compose を直接使用できます。

git clone https://github.com/kutukam/autonomous-pentest-agent.git
cd autonomous-pentest-agent
cp .env.example .env
docker compose up -d

.env を編集して POSTGRES_PASSWORD を入力し、必要に応じて ANTHROPIC_API_KEY を設定してください。起動後、http://localhost:8787 にアクセスします。

Docker イメージには一般的なツールが含まれています。./skills と ./data はバインドマウントを使用してデータを保存します。リモート MCP はシステム設定で Streamable HTTP または旧版 SSE を選択できます。旧版 SSE を使用する場合、URL には通常 /sse を入力し、サービスの要件に従って Authorization=Bearer <token> リクエストヘッダーを設定します。

方法三：プリコンパイル済みバイナリを使用する

Releases から対応するプラットフォーム用の圧縮パッケージをダウンロードすることもできます。展開すると、通常は apagent、start.sh または Windows 用の start.bat、skills/、config.example.json が含まれています。

cp config.example.json config.json
./start.sh

起動には start.sh または start.bat を使用し、./apagent を直接実行しないでください。起動スクリプトは、プログラム終了後に終了コードに基づいて再起動するかどうかを判断します。ページ内のワンクリック更新機能もこの仕組みに依存しています。バックグラウンドで実行する場合は、次のコマンドを使用できます。

nohup ./start.sh >apagent.log 2>&1 &

方法四：ソースコードからビルドする

ソースコードからビルドする場合は、まずフロントエンドの静的ファイルをビルドし、それをバックエンドの内包用ディレクトリにコピーした後、embedui タグを付けて Go プログラムをビルドします。

cd web && npm ci && npm run build:static && cd ..
cp -r web/out server/webui/dist
CGO_ENABLED=0 go build -tags embedui -o apagent ./cmd/apagent
./start.sh

クロスプラットフォーム用のリリースパッケージをビルドする場合は、次のコマンドを実行できます。

./build.sh --release

デフォルトでは、Linux、macOS、Windows 向けの複数のパッケージが生成されます。APAGENT_TARGETS で対象をカスタマイズすることもできます。UPX はデフォルトで無効です。圧縮された自己解凍バイナリは、一部の Linux カーネル、仮想化環境、セキュリティポリシーと互換性がない可能性があるためです。

データベースと LLM の設定

ローカルビルドまたはバイナリ実行時は、config.json で PostgreSQL を設定できます。

{
  "database": {
    "host": "127.0.0.1",
    "port": 5432,
    "user": "apagent",
    "password": "yourpass",
    "dbname": "apagent",
    "sslmode": "disable"
  }
}

APAGENT_PG_DSN を使用してデータベース接続設定を上書きすることもできます。LLM は環境変数で設定できます。

export ANTHROPIC_API_KEY=sk-...
# または
export OPENAI_API_KEY=...

オプションパラメーターには APAGENT_LLM_PROVIDER、APAGENT_LLM_MODEL、APAGENT_LLM_BASE_URL、APAGENT_LLM_PROXY があります。環境変数を使用しない場合は、UI の「LLM 設定」ページに入力できます。各タスクの Worker 数は「システム設定」で調整でき、デフォルト値は 3 です。

基本的な使用フロー

1. 初期化を完了する：ローカルサービスにアクセスし、/setup で管理者パスワードを設定して、データベース接続を確認します。
2. LLM を設定する：システム環境変数または「LLM 設定」ページで、利用可能なモデルと必要なパラメーターを設定します。
3. ローカルのターゲットを準備する：隔離された実験環境で自分が管理しているアセットのみを追加し、オンラインシステムや本番サービスにアクセスしないことを確認します。
4. タスクを作成して監視する：タスクページでタスクを管理し、ダッシュボードとアクティビティストリームで実行状態を確認します。
5. 探索結果を確認する：探索チェーンで意図、事実、検出結果の関係を確認し、アセットグラフで統合済みのアセットを確認します。
6. 実行証拠を確認する：セッション、ツール呼び出し、トラフィックの各ページで実行記録を確認します。人による確認が必要な操作が発生した場合は、インターセプト承認ページで処理します。

アセットカバレッジ図は、力学ベースのレイアウトで対象範囲内のアセットとテスト済みノードを表示し、ノードの折りたたみと展開に対応しています。ローカルの実験範囲内で、どのアセットがすでに探索されたかをすばやく判断するのに適しています。

ScopeSentry からアセットを同期する

プロジェクトはScopeSentry からアセットを同期でき、重複した収集を減らせます。「アセット同期」ページを開き、ScopeSentry のアドレスと API Key を入力してから、プロジェクトまたはタスク単位で同期するターゲットとアセットタイプを選択します。

• 範囲を指定して、ドメイン、サブドメイン、IP、ポート、サイト、エンドポイントなどのアセットタイプを選択できます。
• インポート後は、企業のアセット範囲に基づいてまとめられます。
• 同期結果は Autonomous Pentest Agent のアセットグラフに追加され、以後のローカル実験タスクで使用できます。

トラフィックの記録と承認

システムにはトラフィック録画プロキシが用意されており、./start.sh -addr :8787 -proxy :8788 のようにしてフロントエンド、API、トラフィックプロキシのアドレスを指定できます。Worker によるツール実行の過程はアクティビティとして記録され、インターセプト承認機能を使うと、必要に応じて人間がツール操作を確認できます。

承認記録は、グローバル承認記録、タスク内のインターセプト承認、会話内の承認カードから展開して詳細を確認できます。使用時は操作対象とパラメータを慎重に確認し、対象を常に隔離された実験環境に限定してください。

脆弱性の再テスト

タスク詳細の「再テスト」タブでは、脆弱性をページ単位で選択し、過去の結論と証拠を確認して、独立した再テスト Agent セッションを開始できます。脆弱性一覧、脆弱性詳細、アセットビューのいずれにも再テストの入口があります。

再テストの結論には「再現可能」「修正済み」「確認不能」があります。各再テストの結論、証拠、セッションリンクは脆弱性詳細に保存されます。再テストが成功し、結論が「修正済み」の場合、システムは脆弱性の対応ステータスを自動更新します。実行中、失敗、停止、その他の結論では、元のステータスは自動的に変更されません。

バックエンドの初回起動時には、編集可能な「脆弱性再テスト」Agent、つまり retester があらかじめ用意されます。Agent 管理画面で、プロンプト、LLM、実行予算、ツールを設定できます。同じ脆弱性が再テスト中の場合、システムは既存のセッションを再利用します。停止、失敗、サービス再起動の後は、再度開始できます。README には、過去の再テスト記録は現時点では脆弱性レポートのエクスポートやタスクアーカイブパッケージに含まれず、トラフィックパッケージにも自動関連付けされないことも記載されています。

リバースプロキシのデプロイ

フロントエンド、API、SSE はデフォルトで同じバックエンドポートから提供されるため、通常は NEXT_PUBLIC_SSE_BASE を設定する必要はありません。Nginx 経由で HTTPS を公開する場合は、SSE のバッファリングを無効にし、読み取りタイムアウトを長く設定してください。

server {
    listen 443 ssl;
    server_name your.domain.com;

    location / {
        proxy_pass http://127.0.0.1:8787;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 3600s;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
    }
}

SSE がページと異なるオリジンを使用する場合に限り、ビルド時に NEXT_PUBLIC_SSE_BASE を設定する必要があります。この変数は next build 時に静的パッケージへ埋め込まれるため、コンテナの実行時に設定しても反映されません。

アップグレードとデータ保護

プロジェクトをアップグレードしても、PostgreSQL のデータボリューム、./data、./skills が自動的に削除されることはありません。アプリケーションの起動時にデータベース構造の初期化とマイグレーションが冪等的に実行されるため、通常はマイグレーションスクリプトを手動で実行する必要はありません。ただし、アップグレード前には ./data とデータベースをバックアップしてください。

システム設定ページの「バージョンと更新」カードから更新を実行することを推奨します。プログラムは現在のプラットフォーム向けリリースパッケージをダウンロードし、SHA256 を検証してスモークテストを実行した後、起動スクリプトによって置き換えられます。検証に失敗した場合は一時ファイルを破棄し、新版の起動に連続して失敗した場合は自動的にロールバックします。更新によってサービスが再起動され、実行中のタスクが中断されるため、アイドル時に実施してください。

Docker でデプロイする場合、ページからの更新ではプログラムのみが置き換えられ、イメージ内の Playwright、nmap などのツールチェーンは更新されません。イメージを更新するには、次を実行してください。

docker compose pull apagent
docker compose up -d apagent

リポジトリにある更新スクリプトも使用できます。

./update.sh

ローカル開発とテスト

開発モードでは、バックエンド、トラフィックプロキシ、Next.js 開発サーバーを同時に起動できます。

./dev.sh

デフォルトのアクセス先は http://localhost:5173 です。個別に実行することもできます。

go run ./cmd/apagent
cd web && npm run dev
go test ./...

-tags embedui を付けない場合、バックエンドにフロントエンドは埋め込まれません。バックエンドを起動せずにフロントエンドだけをプレビューする場合は、次を使用できます。

cd web && NEXT_PUBLIC_MOCK=1 npm run dev

よくある注意事項

• PostgreSQL が起動していることを確認し、ユーザー名、パスワード、データベース名、ポートを確認してください。
• アクティビティストリームの接続に成功しているのにイベントがない場合は、リバースプロキシでバッファリングが無効になっているか、長時間接続のタイムアウトが十分に長いかを確認してください。
• プリコンパイル版を使用する場合は、start.sh や start.bat を介さずに起動しないでください。そうしないと、ページ更新後の自動切り替えと再起動の仕組みが正常に動作しない可能性があります。
• フロントエンドの静的リソースを変更した後は、必ず npm run build:static を再実行し、server/webui/dist にコピーしてから再コンパイルしてください。
• アップグレード前にデータベース、./data、./skills をバックアップしてください。データベース構造は自動的にマイグレーションされますが、自動的にロールバックされることはありません。
• 実際の本番アセット、本番環境の認証情報、機密データをローカル実験システムにインポートしないでください。

まとめ

Autonomous Pentest Agent は、Go サービス、Next.js インターフェース、PostgreSQL の二重グラフデータモデル、LLM によるマルチ Agent スケジューリングを組み合わせ、タスク管理、探索フロー、アセットカバレッジ、トラフィックの記録、承認、脆弱性の再テスト機能を提供します。まず Docker またはインストールスクリプトを使用してローカルの隔離環境で起動し、データベースと LLM を設定してから、タスク、アセットグラフ、実行セッションを通じてシステムの動作を段階的に理解できます。使用中は、プロジェクトが定めるローカル学習用途およびすべての法令・コンプライアンス要件を必ず遵守してください。

このプロジェクトは AGPL-3.0 ライセンスを採用しています。変更を加え、ネットワーク経由でユーザーにサービスを提供する場合は、ライセンスの要件に従って対応する完全なソースコードを公開する必要があります。実装の詳細については、リポジトリのソースコード、norma SDK、およびプロジェクトの LICENSE ファイルを参照してください。