sapper-v2で自律型ペネトレーションテスト軍団を構築・実行する

sapper-v2とは？

sapper-v2は、許可を得たペネトレーションテスト向けに設計された自律型マルチエージェントシステムです。複雑化を続ける単一のエージェントに依存する代わりに、複数のAIをレギオンとして編成し、作業を分担し、発見事項を共有し、エージェントの交代後も知識を保持します。

このプロジェクトは、第3回Tencent Cloud Intelligent Attack-Defense Challengeのオンライン予選で優勝し、GeekCon 2026 AI ChallengeでFirst Prizeを受賞しました。Tencentの大会では、8時間の無人実行を完了し、約10億トークンを使用して85個のフラグを発見し、80.18点を獲得しました。

sapper-v2は、自分が所有するシステム、またはテストについて明示的な許可を得たシステムでのみ使用してください。インストールまたは操作の前にDISCLAIMER.mdを確認してください。

システムの仕組み

このプロジェクトは、次の3つの基盤機能を中心に構築されています。

• Create：システムはtmuxで新しいAIセッションを開き、タスクの要求に応じて専門ワーカーを作成できます。
• Language：エージェントは、互いの入力セッションにメッセージを入力して通信します。
• History：発見事項は、1つのエージェントのコンテキスト内に残すのではなく、階層化されたfact-intentグラフに保存されます。

履歴システムには、title、summary、evidence documentの3層があります。エージェントはまず簡潔なタイトルを読み、より多くのコンテキストが必要な場合に要約を確認し、詳細な検証のために証拠文書を開けます。この設計により、コンテキストの消費を抑え、不正確な事実による影響を限定できます。

実行時の役割

実行時、sapper-v2は調整、実行、可用性を分離します。

• Commander：ボードを読み、対象を評価し、作業を割り当てます。攻撃自体は実行しません。
• Generals：難度の高い攻撃を担当し、自分の部隊を編成できます。
• Scouts：短時間の偵察を行い、対象に大規模な実行が必要か、より深い調査が必要かを判断する手助けをします。
• Soldiers：割り当てられたタスクを並行して実行します。
• Signalman：未報告のフラグを1か所から収集して提出します。この役割は事前にコード化されたものではなく、運用中に生まれました。
• Watchdog：戦略を持たないスクリプトです。--continueを付けてクラッシュしたCommanderを再起動し、キーをローテーションし、実行終了時の処理を行うことで、システムを稼働し続けます。

READMEでは、Commander、tmuxペインで稼働するAIレギオン、Watchdogという3つの表示される実行ウィンドウについて説明しています。

主な機能

• 並列的な作業分担：Scouts、Soldiers、Generals、Commanderがそれぞれ異なる責任を担って動作します。
• 永続的な組織メモリ：個々のエージェントが交代しても知識が維持されます。
• コンテキストのローテーション：コンテキストが飽和したエージェントは、後任に向けて書面の教訓を残せます。
• モデルの階層化：大会構成では、CommanderとGeneralsにGLM-5.3、ScoutsとSoldiersにDeepSeek V4.1 Flashを使用しました。
• 運用上の耐障害性：Watchdogは戦略的な判断を行わずにCommanderを再起動し、キーをローテーションし、継続性を維持できます。
• チャレンジ間の知識移転：Commanderは構造的に類似したチャレンジ群を特定し、成功したプレイブックを新たに割り当てられたエージェントへ引き継げます。
• Fact-intent CLI：このプロジェクトは、グラフの操作や複数チャレンジのワークフローを実行するためのコマンドとガイダンスを提供します。

sapper CLIをインストールする

クイックスタート用インストーラーは、sapper CLIへのリンクを配置します。READMEによると、CLIは標準ライブラリのみを使用し、追加の依存関係はありません。

リポジトリのルートから次を実行します。

bash install.sh

READMEには、追加のローカル前提条件やプラットフォーム固有のインストール手順は記載されていません。コマンドを実行してもシェルでsapperが利用できない場合は、install.shを確認し、シンボリックリンクの配置先が実行パスに含まれていることを確認してください。

許可を得たアセスメントを開始する

sapper setupで新しいアセスメントを作成します。次の例は、プロジェクトのクイックスタートから引用したものです。

sapper setup --goal "assess http://target" --agents

http://targetは、書面による許可の対象となっているエンドポイントにのみ置き換えてください。エージェントが曖昧さのないミッションを受け取れるよう、目標には承認済みの範囲を明確に記述してください。

--agentsオプションは、プロジェクトで示されているエージェント指向のワークフローを開始します。セットアップ後、ボードと現在のフロンティアを確認します。

sapper status

ステータス画面は、作業の進捗を確認するためのクイックスタートの主要コマンドです。Commanderはボードを使って対象を判断し、専門家を割り当てます。アセスメント作業を直接実行するわけではありません。

最小限のCLIワークフロー

1. 許可を確認する：対象、時間枠、承認された手法、停止条件をツールの外部で文書化します。
2. CLIをインストールする：クローンしたリポジトリからbash install.shを実行します。
3. 目標を定義する：承認済みの対象を指定してsapper setup --goal "assess http://target" --agentsを実行します。
4. ボードを監視する：sapper statusを実行して、ボードとフロンティアを確認します。
5. 保持された知識を確認する：単一グラフの操作や複数チャレンジの一括調査が必要な場合は、SKILL.mdに記載されたfact-intentワークフローを使用します。

Dockerで完全なレギオンを実行する

リポジトリには、commander ベースの完全な legion 用 Dockerfile が含まれています。リポジトリのルートからイメージをビルドします。

docker build -f docker/Dockerfile.commander -t sapper:latest .

コンテナを起動する前に、docker/ENV.md に記載されているモデルゲートウェイ、キープール、予算に関する環境変数を設定してください。アーキテクチャではモデル層ごとに異なる責任を割り当て、キーのローテーションと予算を考慮した運用を行うため、これらの設定は重要です。

README では、コンテナの起動方法を概略として次のように示しています。

docker run -d --name sapper ... sapper:latest

省略記号は、そのまま実行できる引数ではありません。リポジトリの環境設定ドキュメントに従い、必要な環境変数やその他の Docker オプションに置き換えてください。安全なシークレット管理方法を利用できる場合は、本番用認証情報を推測したり、シェル履歴に直接シークレットを記録したりしないでください。

commander の原則を理解する

commander の運用原則は docker/commander/SKILL.md に記載されています。README では、次の原則が強調されています。

• 容易な対象を優先した並列スケジューリング: 1つの難しい経路に legion 全体を集中させるのではなく、解決しやすい対象を並行して処理できるように作業を割り当てます。
• ボトルネック時間帯のサルベージ: 作業の終盤では、既存の証拠から迅速に結果を得られる可能性がある、部分的に解決済みの対象を再確認します。
• ストップロスの徹底: 進展を生まない作業に、無制限の時間やトークンを費やさないようにします。
• 役割の分離: 直接実行ではなく、ボードの確認、判断、作業の割り当てに commander の注意を集中させます。

正式なアーキテクチャ契約については、docker/commander/SPEC.md を読んでください。競技中にシステムがどのように動作したかを説明する振り返りについては、BATTLE-REPORT.md を参照してください。

高度な運用のヒント

許可された範囲に合う目標を書く

セットアップ時の目標が、エージェントが取り組む任務になります。承認済みの対象を正確に記述し、無関係なホストやサービスを調査する許可と解釈される可能性のある広範な表現は避けてください。外部の承認文書を唯一の基準とします。

過大な要約ではなく、階層化された証拠を使う

高レベルの事実は簡潔に保ちながら、その下に詳細な証拠を保持します。タイトルでは要点を伝え、要約では関連性を説明し、証拠文書では検証を裏付けます。これは sapper-v2 の設計に沿ったもので、すべての詳細をエージェントのコンテキストに繰り返し読み込むことを避けられます。

エージェントの交代時に知見を維持する

このプロジェクトでは、キャンペーン中の兵士のコンテキスト飽和が約260,000トークンに達したと測定されました。その対策として、後任者向けのプレイブックを残したままワーカーを再作成しました。作戦の出力を確認する際は、検証済みの発見、試行したアプローチ、未解決の疑問、再利用可能な手順を含む明示的な引き継ぎメモを重視してください。

戦略と可用性を分離する

watchdog には意図的に戦略上の役割を与えていません。復旧処理、キーのローテーション、プロセスの再起動を、対象や戦術に関する判断から分離してください。これにより、ある操作が commander によるものか、キープアライブ自動化によるものかを把握しやすくなります。

トークンとモデルのコストを管理する

sapper-v2 の競技用アーキテクチャでは、高レベルの意思決定に強力なモデルを、大量の偵察と実行に軽量なモデルを割り当てました。文書化された構成を再現する場合は、Docker の環境設定ガイダンスに従ってゲートウェイ、キープール、予算を設定し、許可された実行中は消費量を監視してください。

移管された知識を信頼する前に証拠を確認する

対象が構造を共有している場合、チャレンジ間の知識移転によって作業を加速できますが、類似性を検証の代わりにしてはいけません。継承したプレイブックを別のチャレンジに適用する前に、階層化されたグラフを使って要約と裏付けとなる証拠を確認してください。

安全性と責任ある利用

sapper-v2 は攻撃的セキュリティツールであり、不正アクセスに使用してはなりません。README では、AI が攻撃的ツールによる被害を増幅する可能性があると明確に警告しています。適用される法律に従い、明示的な許可を取得し、対象範囲を限定し、予算と停止条件を定め、環境に応じた人間による監督を維持してください。

このプロジェクトでは、将来的な taggant メカニズムも提案しています。これは攻撃用ハーネスに結び付けられたマーキングで、違法な侵入中に被害者へ識別情報を漏えいさせ、帰属の特定を支援する可能性があります。README では、これを暗号技術とコミュニティによる設計を必要とする提案として示しており、現在ユーザーが頼れる既存の保護機能ではないとしています。

まとめ

sapper-v2 は、自律的なセキュリティ評価への協調的なアプローチを示しています。commander が作業を委任し、専門家が並行して活動し、watchdog が継続性を維持し、階層化された事実グラフが組織の知識を保存します。軽量な CLI から始め、sapper status でボードを監視し、完全な legion が必要な場合は Docker セットアップを使用してください。すべての実行を明示的な許可とプロジェクトの免責事項の範囲内に必ず収めてください。