pentest-engagement

Pentest Engagement

pentest-engagement ワークフローを通じて、範囲を定めたペンテストをエンドツーエンドで実行します。フラグを目標とする htb-solve に対し、幅広い対象を網羅し、カバレッジをゲートとするものです。同じエンジン（coordinator-loop。現在はループに検出事項ごとの検証を交互に組み込んでいます）を使いますが、フラグの代わりに攻撃クラスのカバレッジマトリクスを使い、対象の拡張と根本原因に基づく深刻度評価を組み込んでいます。

使用する場面

スコープで定義された、実際の（CTFではない）エンゲージメントで使用します。スコープは次のいずれかです。

• WEB — アペックスドメイン／アセット URL で定義された Web／API／クラウドアプリ、または
• NETWORK — 稼働中のサービスと脆弱性をスキャンする IP／CIDR／範囲のリスト（例：1500 ホスト）。

ワークフローはセットアップ時に engagement_kind からモードを自動検出します。IP／CIDR が主な場合はネットワーク、アペックスドメイン／アプリ URL が主な場合は Web と判定します。HackTheBox／CTF には、代わりに hackthebox（htb-solve）を使用してください。

実行方法

WEB — スコープファイルまたはインラインで指定します。

Workflow('pentest-engagement', { scope_file: 'projects/pentest/<engagement>-scope.md' })
Workflow('pentest-engagement', { scope: { engagement_name, apex_domains:[], assets:[...], creds_env:[...], roe, business_tier } })

NETWORK — IP／CIDR リストをインラインで指定するか、IP／CIDR を含むスコープファイルを指定します（IP／CIDR を改行区切りで並べたプレーンテキストのリストも使用できます）。

Workflow('pentest-engagement', { targets: ['10.0.0.0/24', '192.0.2.0/24', '198.51.100.7'] })
Workflow('pentest-engagement', { scope_file: 'projects/pentest/<engagement>-ips.txt', scan_profile: 'standard' })

共通オプション：maxConcurrent（デフォルトは慎重に CPU コア数から算出。コア数のおよそ半分を基準に 2～8 で上限を設定します。数百／数千のタスクを並列実行することはありません）、dryRun、max_experiments、business_tier、report（デフォルトは true）。 ネットワーク用オプション：scan_profile は light（範囲を 1-1024 に制限し、厳選した一般的でないポートを追加。大規模かつ高速なスキャン向け）／standard（到達可能なすべてのホストで全ポート範囲 -p- をスキャン。デフォルト。ホスト数のガード付きで、検出したオープンポートに対して SYN スキャンから -sV に進む 2 段階方式。メッセージバスと 443 以外の TLS にも対応）／full（-p- と範囲を制限した UDP）。udp（上位 50 の UDP ポート。light／standard では無効、full では自動的に有効）、slice_size（スキャンワーカーごとのホスト数。IP リストでは自動的に約 64、CIDR が中心の場合は 2）、deepen_top（価値の高い上位 N 件のホストを詳細調査。デフォルトは 10、スキップする場合は 0）、geo_vantages（2 つ目の視点から許可リストを再プローブするための GCP ゾーン。最大 2 つ。米国＋EU のデフォルトを上書きします）、auto_provision（デフォルトは true。false にすると検出とフラグ付けのみを行い、クラウド費用は発生しません）。送信元 IP／地域の許可リストによるフィルタリングのパターンを検出すると、ワークフローは 2 つ目の地域に視点を自動プロビジョニングし、フィルタリングされたホストを再プローブしてから「対象なし」と結論づけます。

reference/scope-file-format.md に従ってスコープファイルを作成してください。認証情報は環境変数名のみで参照し、リポジトリの .env から python3 tools/env-reader.py を使って読み込みます。秘密情報を値のまま直接記述しないでください。

フェーズ（ワークフローの内容）

1. セットアップ — env-reader の認証情報を取得し、スコープを解析し、対象種別を分類（web|network）し、CPU コア数を読み取り → 慎重な並列タスク上限を設定し、OUTPUT_DIR = projects/pentest/<date>_<engagement>/ を設定し、STARTED を Slack に通知します（ゲートあり）。
2. 拡張 (WEB、最大の修正点) — スコープ内のすべての apex に対して、CT ログ／パッシブ DNS／オリジン検出を必ず実施します（crt.sh、certspotter、subfinder、CDN/WAF の背後にあるホストのオリジン検出）。スコープは引き継がれた範囲ではなく、検出された対象領域です。アセットごとの作業リストを作成し、各アセットのカバレッジマトリクスのシードを設定します。 スキャン (NETWORK、拡張を置き換え) — IP/CIDR セットをマシンに適したバッチに分割します。スライスごとに nmap ワーカーを 1 つ割り当て（エージェント数は IP 数ではなく、数十程度のスライス数に応じて増やします）、同じパイプラインを実行します。ホスト検出（到達可能性は不明）→ 一般的なポートとあまり一般的でないポート／サービスの範囲を限定したスキャン → CVE の検出（nmap --script vulners、nuclei、各 CVE-ID を tools/nvd-lookup.py で詳細化）→ 均一な IP ごとのツリー hosts/<ip>/{recon,host.json,findings} と統合済みの recon/inventory/ を書き出します。
3. 評価 (単一の並行ステージ — 後続の個別検証パスはありません) — WEB：各アセットで coordinator-loop（カバレッジモード）を実行します。候補が生成された時点で直ちに、新しいブラインドエージェントで検証します（検証結果ごとに厳密な修正／破棄ループを実施）。その後、検索を続けます。NETWORK：価値の高い上位 deepen_top ホストのみを対象に、範囲を限定した coordinator-loop による詳細調査を行い、同じく検証を並行して実施します（それ以外は均一なツールスキャンであり、ホストごとにエージェントを割り当てることはありません）。VALID によるカバレッジ：クラスがカバー済みとなるのは、VALID／REPAIRED の検出結果、根拠のある N/A、または実際の陰性判定がある場合だけです。候補がすべて却下／破棄されたクラスは pending のままとなり、検索を続けます。
4. 相関 — 検証済みのすべての検出結果を対象に attack-path-stitcher と risk-prioritiser を実行し、優先順位付けされた組織のロードマップを作成します。
5. レポート (決定論的 — エージェントはレポートを作成しません) — JS は確定済みのエンゲージメントブロックと正確なコマンドを 1 つの finalize runner に渡します。tools/report_data_build.py が名前空間付きの中間 finding-JSON を正規の report_data.json に統合し（組み立てを一元管理）、続いて形式に応じたレンダラーを実行します。transilience → 正規の generate_report.py PDF スキル、custom → custom_report_cmd（または Markdown にフォールバック）。JS はその後、厳格なゲートを適用します。report_data が組み立て済みで、さらに（transilience の場合は WROTE ∧ bytes>0 ∧ [assets: …/formats/transilience-report-style] の来歴タグ）が満たされること。1 回だけ再試行し、その後は BLOCKED とします。レポートに含まれるのは VALID／REPAIRED の検出結果のみです（全体を破棄します。構造上、validated/ には確認済みのものだけが含まれます）。REJECTED（false-positives/）と、修正されなかった DROPPED（dropped/）は決して含めず、ギャップ／保証セクションもありません。finalize runner はさらに、network_coverage_map.py（スキャン済みホストの末尾）と、エンゲージメント全体に対する coverage_gate.py を実行し、reports/coverage-matrix.json を書き出します。成果物には決定論的な 攻撃パターンのカバレッジ セクション（対象領域単位 × 攻撃クラス）が含まれます。COMPLETE には厳格な 100% ゲートがあります。レポートの組み立てとレンダリングが完了し、かつカバレッジゲートが complete:true（該当するすべてのセルがカバー済み）を報告する必要があります。これは WEB と NETWORK の両方に適用されます（NETWORK ではスキャン完了も必要です）。未テストの該当セルが 1 つでもあれば、INCOMPLETE_coverage／BLOCKED となります。
6. パッケージ化と納品 — 検証済みの <report_id>_deliverable.zip（reports/ input/ logs/ artifacts/）、簡潔な統計サマリー（summary.md：エージェント数、重大度別の検出数、経過時間。トークン数／コストは unavailable — no runtime token counter と表示）を用意し、ワークフローは slack_offer: true を返します。

実行後（ワークフロー外のメインループ）： コーディネーターは AskUserQuestion を呼び出せないため、呼び出し元のエージェントが返された summary を表示し、deliverable_zip を Slack に投稿するかどうかを尋ねます。はいの場合は、成功して COMPLETE となったエンゲージメントを条件として、python3 tools/slack-send.py --channel "$PENTEST_SLACK_CHANNEL_ID" を実行します。 レポートのオプション： report_format transilience（デフォルト） | custom；custom_report_cmd（カスタムレンダラー。report_data.json のパスと reports/ ディレクトリを受け取ります）；prior_report（以前の PDF または report_data.json。そのタイトル／セクター／スコープはメタデータのみであり、作業リストの初期設定には使用されません）＋カバーバージョンを付与する version ＋「Supersedes」の行。

決定性（正直に説明）

判定レイヤーは凍結された純粋な JavaScript の computeVerdict（パリティガード済み、フィクスチャで固定済み）であり、そのオペランドは NVD／KEV の --cache-dir スナップショット（artifacts/nvd-cache/、artifacts/kev-snapshot.json）によってエンゲージメントごとに凍結され、敵対的クォーラムは 3 に引き上げられています。同一の入力であれば、判定結果は証明可能な形で同一になります。ただし、新規のライブ実行は再現性が非常に高いものの、100％ではありません。LLM のサンプリングによって判定に使われるブール値や数値が生成され、ライブターゲットの変化によって入力が変わるためです。この上限は本質的なものであり、隠さず明記しています。バイト単位で同一の結果が 100％保証されるのは、凍結された証拠セット（Phase-2 リプレイキャッシュ、artifacts/validation-cache/）をリプレイする場合のみです。「同じリクエスト → 同じ結果」が強い傾向ではなく保証となるのは、この場合に限られます。

境界

• オーケストレーターのみを使用します。コーディネーターループをインラインで実行してはいけません。カバレッジと記録管理の規律には、ワークフローの境界が必要です。
• 認証情報がないことは、全体的なブロックの理由にはなりません。認証されていないサーフェスは常にテストされます。到達可能なアセットがないスコープのみがブロックされます。
• 自組織／自テナントへの可逆的な書き込みは、デフォルトで許可されています（作成後に削除する操作は破壊的ではありません）。破壊的な操作、DoS、ブルートフォース、およびスコープ外のテナントは禁止されています（RoE で設定）。

参考資料

• scope-file-format.md — スコープファイルのスキーマと具体例
• coverage-matrix.md — 攻撃クラスの正規のカバレッジ契約（完了ゲート）
• principles.md — スコープがサーフェスであること、可逆的なアクティブエクスプロイト、実ツール優先、根本原因に基づく重大度
• pentest-report.md — Transilience レポートの構成と §7.1 の根本原因に基づく重大度
• validator-role.md — エンゲージメントバリデーターによる攻撃クラスのカバレッジ確認（8）