defending-code-reference-harness

脅威モデリング、スキャン、トリアージ、パッチ適用のスキルに加え、カスタマイズ可能な自律型スキャンハーネス

⚠️ セキュリティ: /quickstart、/threat-model、/vuln-scan、/triage はファイルの読み書きのみを行います。静的発見結果（TRIAGE.json または VULN-FINDINGS.json）に対する /patch の実行も同様に読み取り専用および書き込み専用です。/customize は ハーネスコードを編集し、検証コマンドを実行します。これらのスキルは、Claude Code で各ツールの使用を確認・承認する限り、 サンドボックスなしで実行しても安全です。 自律的なリファレンスパイプライン（パイプライン結果に対する /patch を含む）は ターゲットコードを実行する ため、 明示的に上書きしない限り、gVisor サンドボックス外では実行を拒否します。 セットアップするには、scripts/setup_sandbox.sh を一度実行し、その後 bin/vp-sandboxed を介してパイプラインを起動します。 詳細については、docs/security.md および docs/agent-sandbox.md を参照してください。

はじめに

さらに読む

• ブログ記事 · 知見とベストプラクティスをまとめた付随ブログ記事
• パイプライン · 動作の仕組み：図、ステージ、CLI フラグ
• セキュリティ · サンドボックス化、マウントしてはいけないもの
• エージェントサンドボックス · 各エージェントの gVisor 分離と egress 許可リスト
• カスタマイズ · 自分たちのスタックに移植する；変更するファイルとその理由
• パッチ適用 · 検証済みクラッシュに対する修正の生成と検証
• トラブルシューティング · 重複、レート制限、サブエージェントモデルの固定
• セーフガード · 危険なサイバー作業に対するブロック

段階的な立ち上げ

私たちが協業したセキュリティチームの中で最も成功しているのは、できるだけ早く実践に移ったチームです。 完璧なパイプラインを設計するのに何ヶ月も費やしたくなる気持ちは理解できますが、初日は小さく始めて、 学びを得ながら構築していくことをお勧めします。以下の手順はそのパターンに従い、私たちが見てきたものに基づいた 野心的でありながらも妥当なペースを設定しています。

ステップ 1（1日目）：脅威モデルを構築し、最初の静的スキャン + トリアージを実行

1日目は、ループ全体をエンドツーエンドで確認することに焦点を当てます。インタラクティブなスキルのみを使用して、 脅威モデルを構築し、それに基づいてスコープ設定された静的スキャンを実行し、返ってきた結果をトリアージし、 修正候補をドラフトします。一日の終わりには、脅威モデル、ランク付けされた静的発見結果、および修正候補が完成します。

関連するスキルは、リポジトリ内のファイルの 読み取りと書き込みのみ を行います。Claude Code を インタラクティブに実行し、各ツールの使用を承認する限り、サンドボックスは必要ありません。

このフローにより、THREAT_MODEL.md、VULN-FINDINGS.{json,md}、 TRIAGE.{json,md}、および PATCHES/ が生成されます。

ステップ 1 で生成される脆弱性候補は、Claude によるソースの静的レビューに基づいており（何もビルドや実行は行われません）、 そのためカナリア以外のターゲットではより多くの false positive が予想されます。ステップ 2 では、実行検証済み の発見結果を生成します。

注: カナリアターゲットでは、/triage がスキャンの発見結果を false positive として棄却することがあります。 entry.c は意図的に脆弱なデモコードであることを宣言しており、/triage はテスト/フィクスチャコードのバグを 正しく除外します。完全な確認/重複排除/false positive フローを確認するには、代わりにキュレーションされた フィクスチャで実行するか（/triage .claude/skills/triage/fixtures/canary-findings.json --repo targets/canary）、 ステップ 1 のスキルを自分のコードに向けてください。

ステップ 2（2日目）：C/C++ ライブラリでリファレンスパイプラインを実行

2日目は、インタラクティブなスキルから、リファレンスパイプラインを使用した最初の自律実行に移行します。 既知の脆弱性があるオープンソースライブラリに対して、自身の環境で完全な recon → find → verify → report ループを実行し、 発見されたものに対する修正候補を生成します。一日の終わりには、再現可能なクラッシュ、悪用可能性レポート、 修正候補のセットとともに、パイプラインの動作感覚が身につきます。

パイプラインの実行は簡単です：

ループの結果は results/drlibs/<timestamp>/ ディレクトリに保存されます。 --stream フラグを使用すると、最初のレポートが数分以内に reports/bug_NN/ の下に表示されます。

⚠️ run は自律エージェントを起動します。 パイプラインは各エージェントを egress が Claude API に制限された gVisor コンテナ内で実行します。 エージェントを起動するサブコマンドは、明示的に上書きされない限り、その外での起動を拒否します。 詳細については、docs/security.md および docs/agent-sandbox.md を参照してください。

内部的には、パイプラインは 7 つのステージを経ます：

1. Build: ターゲットを ASAN（C および C++ 用のメモリエラー検出器）を使用した Docker イメージにコンパイルします。パイプラインは、初回実行時にターゲットの Dockerfile を使用してこのイメージを自動的にビルドします。
2. Recon: 軽量なエージェントがネットワーク分離されたコンテナ内でソースを読み取り、パーティションを提案します。つまり、「ここに別々に攻撃する価値のある N 個の異なる入力解析サブシステムがあります」という形で、並列 find エージェントが同じバグに収束するのではなく、異なる領域を探索するようにします。--auto-focus フラグがない場合、パイプラインはターゲットの config.yaml の focus_areas リストを使用します。
3. Find: N 個のエージェントが並列実行され、それぞれが独自の分離コンテナ内で動作します。各エージェントはソースを読み取り、不正な入力を生成し、ASAN バイナリを実行して、特定の入力が 3 回中 3 回クラッシュを引き起こすまで続けます。
4. Verify: 別の grader エージェントが、find エージェントが触れていない新しいコンテナ内で各クラッシュを再現します。find エージェントから grader に引き継がれるのは、生成された proof of concept のみです。
5. Dedupe: judge エージェントが、検証済みクラッシュを既に報告されたバグと比較し、それぞれが新しいバグか、既知のバグのより良い例か、スキップすべき重複かを判断します。
6. Report: report エージェントが、脆弱性クラス、到達可能性、エスカレーションパス、深刻度などの詳細を含む、一意のバグごとに構造化された悪用可能性分析を記述します。
7. Patch（上記の別個の patch コマンド）：patch エージェントが修正案を作成し、grader エージェントが新しいコードがビルドされること、元の proof of concept 入力がもはやクラッシュしないこと、ターゲットのテストスイートが引き続き合格すること、および新しい find エージェントが修正を回避する方法を見つけられないことを確認します。

詳細については、docs/pipeline.md を参照してください。

ステップ 3（3～5日目）：ターゲット向けにパイプラインをカスタマイズ

3～5日目では、ハーネスを自身のターゲットに合わせてカスタマイズします。まず、ステップ 1 のスキルを自身のコードに向け、次に /customize を使用してパイプラインを自身のスタックに移植します。週末までに、パイプラインが実行可能な targets/<your-service>/ ディレクトリが作成され、パイプラインの単一のスモーク実行で検証され、ステップ 4 でスケールアップする準備が整います。

リファレンスパイプラインは C および C++ コードのメモリ脆弱性の発見向けに設計されていますが、その構造は汎用的です。新しい脆弱性クラスや言語に移植するには、ターゲットスタックに対して次の質問に答えるだけです：

カスタマイズする前に、ステップ 1 のスキルを自身のコードに向けてください。繰り返しになりますが、これらのスキルは読み取り専用および書き込み専用であるため、サンドボックスなしで実行できます。

次に、それらのスキルによって生成されたアーティファクトを /customize スキルで使用します。このスキルはハーネスをコードベース用に変更します。

/customize が完了すると、targets/my-service/ ディレクトリがセットアップされます。スケールアップする前に、パイプラインのスモーク実行で検証してください。

詳細については、docs/customizing.md を参照してください。

ステップ 4（第 2 週）：自律スキャン、トリアージ、パッチ適用を開始

第 2 週では、ステップ 3 でカスタマイズしたパイプラインを自身のターゲットに対して使用し、内部パイプラインループに 外側 のループを追加します。つまり、複数のパイプラインスキャンを実行し、それらの実行全体から発見結果をトリアージし、優先順位に基づいてパッチを適用し、繰り返します。

⚠️ ステップ 2 と同じサンドボックス化ガイドラインに従ってください。

特定のパイプライン実行は、すでに自身の発見結果を検証および重複排除します。 /triage は複数のパイプライン実行にわたって機能します。results/ ディレクトリを指定すると、すべての実行（および存在する場合は /vuln-scan からの静的発見結果も）にわたって重複を統合し、脅威モデルに照らして深刻度評価を再調整し、すべての発見結果をコンポーネント所有者にルーティングしようとします。

可能な限り、発見結果に迅速にパッチを適用することは、外側のループを可能な限り生産的に保つのに役立ちます。発見結果が修正されると、モデルはそれらを再発見することができなくなり、代わりに正味の新しい、通常はより深い問題を表面化します。パイプラインの波をさらに実行するにつれて、発見結果の数はおそらく減少しますが、複雑さはおそらく増加します。迅速なパッチ適用が不可能な場合でも、ターゲットの known_bugs に以前の発見結果を記録するだけでも、将来の実行を新しいバグに向けるのに役立ちます。

自律的なトリアージとパッチ適用は依然として未解決の問題であり、このリファレンスハーネスはそれらを完全に解決するものではありません。/patch の検証戦略はハードルを上げるのに役立ちますが、深刻度と優先順位付けは最終的には環境に関する判断であり、検証済みパッチが常にアップストリームに送信できるとは限りません。多くのパートナーがこれらのステップを現在のボトルネックとして報告しており、それらに実際のエンジニアリング時間を割り当てるべきです。

詳細については、docs/triage.md および docs/patching.md を参照してください。

今後の展望

最初の立ち上げ後、私たちが協力してきたチームは、いくつかの方向性に投資する傾向がありました。

1. すべての内部リポジトリと主要なオープンソース依存関係をレビューし、スキャンするのに最も重要なものをランク付けし（例：露出、CVE の履歴、ビジネスクリティカル性に基づく）、優先順位順にスキャンのリストを消化していく。
2. スキャンをラップトップやアドホックな VM から移動させるための、スキャン専用のインフラストラクチャをセットアップする。最も成功しているチームは、スケールアップする前に完璧なスキャンプラットフォームを構築しようとする衝動を抑えている。
3. スキャンを SDLC に組み込む。一部のチームは定期的なスキャン（例：毎日、毎週）を設定したり、スキャンを CI パイプラインに追加したりしている。
4. モデルをテストおよび実験して、自分たちに最適なものを見つける。