zeroize-audit — Claude Skill

使用する場合

• 暗号化実装の監査（鍵、シード、ノンス、秘密）
• 認証システムのレビュー（パスワード、トークン、セッションデータ）
• PIIまたは機密認証情報を扱うコードの分析
• セキュリティ重要コードベースのセキュアなクリーンアップの検証
• 機密データ処理のメモリセーフティの調査

使用しない場合

• セキュリティフォーカスのない一般的なコードレビュー
• パフォーマンス最適化（セキュアワイプと関連する場合を除く）
• 機密データと関係ないリファクタリングタスク
• 特定可能な秘密または機密値を含まないコード

---

目的

ソースコードの機密データのゼロ化漏れを検出し、コンパイラの最適化（例：デッドストア除去）によって削除または弱められたゼロ化を識別します。LLVM IR/アセンブリエビデンスは必須です。機能には以下が含まれます：

• レジスタスピルとスタック保持のためのアセンブリレベル分析
• 秘密コピーのデータフロー追跡
• ヒープアロケータセキュリティ警告
• ループアンローリングとSSA形式のセマンティックIR分析
• パスカバレッジ検証のための制御フローグラフ分析
• ランタイム検証テスト生成

スコープ

• ターゲットコードベースに対して読み取り専用（監査対象コードを変更せず；分析成果物は一時的な作業ディレクトリに書き込まれます）
• 構造化されたレポート（JSON）を生成
• 有効なビルドコンテキスト（compile_commands.json）とコンパイル可能な翻訳単位が必要
• 「最適化により削除」の検出結果は、コンパイラエビデンス（IR/アセンブリ差分）のみが許可

---

入力

完全なスキーマについては{baseDir}/schemas/input.jsonを参照してください。主要フィールド：

フィールド	必須	デフォルト	説明
path	yes	—	リポジトリルート
compile_db	no	null	C/C++分析用のcompile_commands.jsonへのパス。cargo_manifestが設定されていない場合は必須。
cargo_manifest	no	null	Rustクレート分析用のCargo.tomlへのパス。compile_dbが設定されていない場合は必須。
config	no	—	ヒューリスティックスと承認済みワイプを定義するYAML
opt_levels	no	["O0","O1","O2"]	IR比較用の最適化レベル。O1は診断レベル：ワイプがO1で消失すれば単純なDSE；O2はより積極的な除去をキャッチします。
languages	no	["c","cpp","rust"]	分析する言語
max_tus	no	—	コンパイルDB から処理される翻訳単位の上限
mcp_mode	no	prefer	off、prefer、またはrequire — Serena MCP使用を制御します
mcp_required_for_advanced	no	true	MCPが利用不可の場合、SECRET_COPY、MISSING_ON_ERROR_PATH、およびNOT_DOMINATING_EXITSをneeds_reviewにダウングレード
mcp_timeout_ms	no	—	MCP セマンティッククエリのタイムアウト予算
poc_categories	no	all 11 exploitable	PoC を生成する検出結果カテゴリ。C/C++検出結果：11カテゴリすべて対応。Rust検出結果：MISSING_SOURCE_ZEROIZE、SECRET_COPY、およびPARTIAL_WIPEのみ対応；その他のRustカテゴリはpoc_supported=falseとマーク
poc_output_dir	no	generated_pocs/	生成されたPoCの出力ディレクトリ
enable_asm	no	true	アセンブリ生成と分析を有効にします（ステップ8）；STACK_RETENTION、REGISTER_SPILLを生成。emit_asm.shが見つからない場合は自動無効化
enable_semantic_ir	no	false	セマンティックLLVM IR分析を有効にします（ステップ9）；LOOP_UNROLLED_INCOMPLETEを生成
enable_cfg	no	false	制御フローグラフ分析を有効にします（ステップ10）；MISSING_ON_ERROR_PATH、NOT_DOMINATING_EXITSを生成
enable_runtime_tests	no	false	ランタイムテストハーネス生成を有効にします（ステップ11）

---

前提条件

実行前に、以下を確認してください。それぞれ定義された失敗モードがあります。

C/C++前提条件：

前提条件	不足時の失敗モード
compile_dbパスのcompile_commands.json	高速失敗 — 進行しない
PATH上のclang	高速失敗 — IR/ASM分析不可
PATH上のuvx（Serena用）	mcp_mode=requireの場合：失敗。mcp_mode=preferの場合：MCPなしで継続；信頼度ゲーティングルールに従い影響を受ける検出結果をダウングレード
{baseDir}/tools/extract_compile_flags.py	高速失敗 — TUごとのフラグ抽出不可
{baseDir}/tools/emit_ir.sh	高速失敗 — IR分析不可
{baseDir}/tools/emit_asm.sh	警告して、アセンブリ検出結果をスキップ（STACK_RETENTION、REGISTER_SPILL）
{baseDir}/tools/mcp/check_mcp.sh	警告して、MCPが利用不可として扱う
{baseDir}/tools/mcp/normalize_mcp_evidence.py	警告して、生のMCP出力を使用

Rust前提条件：

前提条件	不足時の失敗モード
cargo_manifestパスのCargo.toml	高速失敗 — 進行しない
cargo checkが成功する	高速失敗 — クレートはビルド可能である必要があります
PATH上のcargo +nightly	高速失敗 — MIRおよびLLVM IR生成にはnightlyが必要
PATH上のuv	高速失敗 — Pythonスクリプト分析を実行するために必須
{baseDir}/tools/validate_rust_toolchain.sh	警告 — プリフライトを手動で実行してください。すべてのツール、スクリプト、nightly、およびオプションでcargo checkを検証します。マシン可読出力用に--json、クレートがビルドされることも検証するには--manifestを使用
{baseDir}/tools/emit_rust_mir.sh	高速失敗 — MIR分析不可（--opt、--crate、--bin/--lib対応；--outはファイルまたはディレクトリ可）
{baseDir}/tools/emit_rust_ir.sh	高速失敗 — LLVM IR分析不可（--opt必須；--crate、--bin/--lib対応；--outは.llである必要があります）
{baseDir}/tools/emit_rust_asm.sh	警告してアセンブリ検出結果をスキップ（STACK_RETENTION、REGISTER_SPILL）。--opt、--crate、--bin/--lib、--target、--intel-syntax対応；--outは.sファイルまたはディレクトリ可
{baseDir}/tools/diff_rust_mir.sh	警告してMIRレベルの最適化比較をスキップ。2つ以上のMIRファイルを受け入れ、正規化、ペアワイズ差分、ゼロ化/ドロップグル パターンが消失する最初の最適化レベルをレポート
{baseDir}/tools/scripts/semantic_audit.py	警告してセマンティックソース分析をスキップ
{baseDir}/tools/scripts/find_dangerous_apis.py	警告して危険なAPI スキャンをスキップ
{baseDir}/tools/scripts/check_mir_patterns.py	警告してMIR分析をスキップ
{baseDir}/tools/scripts/check_llvm_patterns.py	警告してLLVM IR分析をスキップ
{baseDir}/tools/scripts/check_rust_asm.py	警告してRustアセンブリ分析をスキップ（STACK_RETENTION、REGISTER_SPILL、ドロップグル チェック）。check_rust_asm_x86.py（本番）またはcheck_rust_asm_aarch64.py（試験的 — AArch64検出結果は手動検証が必要）にディスパッチ
{baseDir}/tools/scripts/check_rust_asm_x86.py	check_rust_asm.pyがx86-64分析に必須；不足時は警告してスキップ
{baseDir}/tools/scripts/check_rust_asm_aarch64.py	check_rust_asm.pyがAArch64分析に必須（試験的）；不足時は警告してスキップ

共通前提条件：

前提条件	不足時の失敗モード
{baseDir}/tools/generate_poc.py	高速失敗 — PoC生成は必須

---

承認済みワイプAPI

以下は有効なゼロ化として認識されます。{baseDir}/configs/で追加エントリを設定してください。

C/C++

• explicit_bzero
• memset_s
• SecureZeroMemory
• OPENSSL_cleanse
• sodium_memzero
• 揮発性ワイプループ（パターンベース；{baseDir}/configs/default.yamlのvolatile_wipe_patternsを参照）
• IR内：llvm.memset（揮発性フラグ）、揮発性ストア、または除去不可能なワイプ呼び出し

Rust

• zeroize::Zeroizeトレイト（zeroize()メソッド）
• Zeroizing<T>ラッパー（ドロップベース）
• ZeroizeOnDrop派生マクロ

---

検出結果機能

検出結果は必要なエビデンスごとにグループ化されます。必要なツール が利用可能な検出結果のみ試行してください。

検出結果ID	説明	必須要件	PoC対応
MISSING_SOURCE_ZEROIZE	ソースにゼロ化が見つからない	ソースのみ	はい（C/C++ + Rust）
PARTIAL_WIPE	不正なサイズまたは不完全なワイプ	ソースのみ	はい（C/C++ + Rust）
NOT_ON_ALL_PATHS	一部の制御フロー パス でゼロ化が不足（ヒューリスティック）	ソースのみ	はい（C/C++のみ）
SECRET_COPY	機密データがゼロ化追跡なしでコピー	ソース + MCP推奨	はい（C/C++ + Rust）
INSECURE_HEAP_ALLOC	秘密が非セキュアアロケータを使用（mallocと secure_malloc）	ソースのみ	はい（C/C++のみ）
OPTIMIZED_AWAY_ZEROIZE	コンパイラがゼロ化を削除	IR差分必須（決してソースのみではない）	はい
STACK_RETENTION	スタックフレームがリターン後に秘密を保持する可能性	アセンブリ必須（C/C++）；LLVM IRalloca+lifetime.endエビデンス（Rust）；アセンブリ補強によりconfirmedにアップグレード	はい（C/C++のみ）
REGISTER_SPILL	秘密がレジスタからスタックにスピル	アセンブリ必須（C/C++）；LLVM IRload+呼び出しサイトエビデンス（Rust）；アセンブリ補強によりconfirmedにアップグレード	はい（C/C++のみ）
MISSING_ON_ERROR_PATH	エラーハンドリングパスにクリーンアップが不足	CFGまたはMCP必須	はい
NOT_DOMINATING_EXITS	ワイプがすべての終了箇所を支配していない	CFGまたはMCP必須	はい
LOOP_UNROLLED_INCOMPLETE	アンロールされたループワイプが不完全	セマンティックIR必須	はい

---

エージェント構成

分析パイプラインは8つのフェーズにおいて11のエージェントを使用します。これらはオーケストレータ（{baseDir}/prompts/task.md）によりTask経由で呼び出されます。エージェントは永続的な検出結果ファイルを共有作業ディレクトリ（/tmp/zeroize-audit-{run_id}/）に書き込み、並列実行を可能にし、コンテキスト圧力から保護します。

エージェント	フェーズ	目的	出力ディレクトリ
0-preflight	フェーズ0	プリフライトチェック（ツール、ツールチェーン、コンパイルDB、クレートビルド）、コンフィグ マージ、workdir作成、TU列挙	{workdir}/
1-mcp-resolver	フェーズ1、Wave 1（C/C++のみ）	Serena MCPを介したシンボル、型、ファイル間参照の解決	mcp-evidence/
2-source-analyzer	フェーズ1、Wave 2a（C/C++のみ）	機密オブジェクトの特定、ワイプ検出、正確性検証、データフロー/ヒープ	source-analysis/
2b-rust-source-analyzer	フェーズ1、Wave 2b（Rustのみ、2aと並列）	Rustdoc JSON トレイト認識分析 + 危険なAPI grep	source-analysis/
3-tu-compiler-analyzer	フェーズ2、Wave 3（C/C++のみ、TU ごとにN並列）	TUごとのIR差分、アセンブリ、セマンティックIR、CFG分析	compiler-analysis/{tu_hash}/
3b-rust-compiler-analyzer	フェーズ2、Wave 3R（Rustのみ、単一エージェント）	クレートレベルのMIR、LLVM IR、アセンブリ分析	rust-compiler-analysis/
4-report-assembler	フェーズ3（暫定）+ フェーズ6（最終）	すべてのエージェントから検出結果を収集、信頼度ゲートを適用；PoC結果をマージし最終レポート生成	report/
5-poc-generator	フェーズ4	ビスポーク検証コード（PoC）プログラムを作成（C/C++：すべてのカテゴリ；Rust：MISSING_SOURCE_ZEROIZE、SECRET_COPY、PARTIAL_WIPE）	poc/
5b-poc-validator	フェーズ5	すべてのPoCをコンパイルして実行	poc/
5c-poc-verifier	フェーズ5	各PoCが主張する検出結果を証明することを検証	poc/
6-test-generator	フェーズ7（オプション）	ランタイム検証テストハーネス生成	tests/

オーケストレータは{baseDir}/workflows/から一度に1つのフェーズあたりのワークフロー ファイルを読み込み、コンテキスト圧縮後の復旧用にorchestrator-state.jsonを保持します。エージェントはコンフィグを値ではなくファイルパス（config_path）で受け取ります。

実行フロー

フェーズ0: 0-preflight エージェント — プリフライト + コンフィグ + workdir作成 + TU列挙
           → orchestrator-state.json、merged-config.yaml、preflight.json を出力
フェーズ1: Wave 1:  1-mcp-resolver              (mcp_mode=off または language_mode=rust の場合スキップ)
         Wave 2a: 2-source-analyzer           (C/C++のみ；compile_db がない場合スキップ)  ─┐ 並列
         Wave 2b: 2b-rust-source-analyzer     (Rustのみ；cargo_manifest がない場合スキップ) ─┘
フェーズ2: Wave 3:  3-tu-compiler-analyzer x N  (C/C++のみ；TUごとに並列)
         Wave 3R: 3b-rust-compiler-analyzer   (Rustのみ；単一クレートレベルエージェント)
フェーズ3: Wave 4:  4-report-assembler          (mode=interim → findings.json；すべてのエージェント出力を読む)
フェーズ4: Wave 5:  5-poc-generator             (C/C++：すべてのカテゴリ；Rust：MISSING_SOURCE_ZEROIZE、SECRET_COPY、PARTIAL_WIPE；その他のRustカテゴリ：poc_supported=false)
フェーズ5: PoC検証と検証
           ステップ1: 5b-poc-validator エージェント      (すべてのPoCをコンパイルして実行)
           ステップ2: 5c-poc-verifier エージェント       (各PoCが主張する検出結果を証明することを検証)
           ステップ3: オーケストレータが AskUserQuestion 経由で検証失敗をユーザーに提示
           ステップ4: オーケストレータがすべての結果を poc_final_results.json にマージ
フェーズ6: Wave 6: 4-report-assembler           (mode=final → PoC結果をマージ、final-report.md)
フェーズ7: Wave 7: 6-test-generator             (オプション)
フェーズ8: オーケストレータ — final-report.md を返す

相互参照規約

ID は並列実行中の衝突を防ぐためにエージェントごとに名前空間化されます：

エンティティ	パターン	割り当て者
機密オブジェクト（C/C++）	SO-0001–SO-4999	2-source-analyzer
機密オブジェクト（Rust）	SO-5000–SO-9999（Rust名前空間）	2b-rust-source-analyzer
ソース検出結果（C/C++）	F-SRC-NNNN	2-source-analyzer
ソース検出結果（Rust）	F-RUST-SRC-NNNN	2b-rust-source-analyzer
IR検出結果（C/C++）	F-IR-{tu_hash}-NNNN	3-tu-compiler-analyzer
ASM検出結果（C/C++）	F-ASM-{tu_hash}-NNNN	3-tu-compiler-analyzer
CFG検出結果	F-CFG-{tu_hash}-NNNN	3-tu-compiler-analyzer
セマンティックIR検出結果	F-SIR-{tu_hash}-NNNN	3-tu-compiler-analyzer
Rust MIR検出結果	F-RUST-MIR-NNNN	3b-rust-compiler-analyzer
Rust LLVM IR検出結果	F-RUST-IR-NNNN	3b-rust-compiler-analyzer
Rustアセンブリ検出結果	F-RUST-ASM-NNNN	3b-rust-compiler-analyzer
翻訳単位	TU-{hash}	オーケストレータ
最終検出結果	ZA-NNNN	4-report-assembler

すべての検出結果JSONオブジェクトはrelated_objects、related_findings、およびevidence_filesフィールドを含み、エージェント間の相互参照を可能にします。

---

検出戦略

分析は2つのフェーズで実行されます。ステップバイステップのガイダンスについては、{baseDir}/references/detection-strategy.mdを参照してください。

フェーズ	ステップ	生成される検出結果	必須ツール
フェーズ1（ソース）	1–6	MISSING_SOURCE_ZEROIZE、PARTIAL_WIPE、NOT_ON_ALL_PATHS、SECRET_COPY、INSECURE_HEAP_ALLOC	ソース + コンパイルDB
フェーズ2（コンパイラ）	7–12	OPTIMIZED_AWAY_ZEROIZE、STACK_RETENTION、REGISTER_SPILL、LOOP_UNROLLED_INCOMPLETE†、MISSING_ON_ERROR_PATH‡、NOT_DOMINATING_EXITS‡	clang、IR/ASMツール

* enable_asm=trueが必要（デフォルト） † enable_semantic_ir=trueが必要 ‡ enable_cfg=trueが必要

---

出力形式

各実行は2つの出力を生成します：

1. final-report.md — 包括的なマークダウンレポート（主要な人間可読出力）
2. findings.json — {baseDir}/schemas/output.jsonに一致する構造化JSON（マシン処理および下流ツール用）

マークダウンレポート構造

マークダウンレポート（final-report.md）には、これらのセクションが含まれます：

• ヘッダー：実行メタデータ（run_id、タイムスタンプ、リポジトリ、compile_db、コンフィグ概要）
• エグゼクティブサマリー：重要度、信頼度、カテゴリ別の検出結果数
• 機密オブジェクトインベントリ：すべての特定されたオブジェクトのテーブル（ID、型、場所）
• 検出結果：重要度で、その後信頼度でグループ化。各検出結果には場所、オブジェクト、すべてのエビデンス（ソース/IR/ASM/CFG）、コンパイラエビデンスの詳細、推奨修正が含まれます
• 後継検出結果：CFGに基づく検出結果に置き換えられたソース検出結果
• 信頼度ゲートサマリー：適用されたダウングレードと拒否されたオーバーライド
• 分析範囲：分析されたTU、エージェント成功/失敗、有効な機能
• 付録：エビデンスファイル：検出結果IDからエビデンスファイルパスへのマッピング

構造化JSON

findings.jsonファイルは{baseDir}/schemas/output.jsonのスキーマに従います。各Findingオブジェクト：

{
  "id": "ZA-0001",
  "category": "OPTIMIZED_AWAY_ZEROIZE",
  "severity": "high",
  "confidence": "confirmed",
  "language": "c",
  "file": "src/crypto.c",
  "line": 42,
  "symbol": "key_buf",
  "evidence": "store volatile i8 0 count: O0=32, O2=0 — ワイプはDSEにより除去された",
  "compiler_evidence": {
    "opt_levels": ["O0", "O2"],
    "o0": "key_buf を対象とした32個の揮発性ストア",
    "o2": "0個の揮発性ストア（すべて除去された）",
    "diff_summary": "すべての揮発性ワイプストアはO2で削除 — 典型的なDSEパターン"
  },
  "suggested_fix": "memsetを explicit_bzero に置き換えるか、ワイプ後に compiler_fence(SeqCst) を追加します",
  "poc": {
    "file": "generated_pocs/ZA-0001.c",
    "makefile_target": "ZA-0001",
    "compile_opt": "-O2",
    "requires_manual_adjustment": false,
    "validated": true,
    "validation_result": "exploitable"
  }
}

完全なスキーマと列挙値については{baseDir}/schemas/output.jsonを参照してください。

---

信頼度ゲーティング

エビデンス閾値

検出結果がconfirmedとマークされるには、最低2つの独立したシグナルが必要です。1つのシグナルでlikelyとマーク。強いシグナルがない（名前パターンマッチのみ）場合はneeds_reviewとマーク。

シグナルには：名前パターンマッチ、型ヒントマッチ、明示的なアノテーション、IRエビデンス、ASMエビデンス、MCP相互参照、CFGエビデンス、PoC検証が含まれます。

PoC検証をエビデンスシグナルとして

すべての検出結果は、ビスポークPoCに対して検証されます。コンパイルと実行の後、各PoCも検証され、実際に主張された脆弱性をテストすることが確認されます。結合された結果はエビデンスシグナルです：

PoC結果	検証済み	影響
終了コード 0（exploitable）	はい	強いシグナル — likelyをconfirmedにアップグレード可能
終了コード 1（not exploitable）	はい	重要度をlowにダウングレード（情報提供）；レポートに保持
終了コード 0 または 1	いいえ（ユーザーが受け入れ）	より弱いシグナル — エビデンスに検証失敗を注記
終了コード 0 または 1	いいえ（ユーザーが拒否）	信頼度変更なし；エビデンスにrejectedと注記
コンパイル失敗 / PoC なし	—	信頼度変更なし；エビデンスに注記

MCP利用不可ダウングレード

mcp_mode=preferでMCPが利用不可の場合、MCP なしで独立したIR/CFG/ASMエビデンスが強い（2+シグナル）でない限り、以下をダウングレード：

検出結果	ダウングレード信頼度
SECRET_COPY	needs_review
MISSING_ON_ERROR_PATH	needs_review
NOT_DOMINATING_EXITS	needs_review

ハードエビデンス要件（交渉不可）

これらの検出結果は、ソースレベルシグナルまたはユーザー主張に関わらず、指定されたエビデンスなしでは決して有効ではありません：

検出結果	必須エビデンス
OPTIMIZED_AWAY_ZEROIZE	O0 でワイプが存在、O1 または O2 で不在を示すIR差分
STACK_RETENTION	ret時のスタック上に秘密バイトがあることを示すアセンブリ抜粋
REGISTER_SPILL	スピル命令を示すアセンブリ抜粋

mcp_mode=require動作

mcp_mode=requireでプリフライト後にMCPに到達不可の場合、実行を停止します。MCPの失敗をレポートし、基本的な検出結果のみが要求されmcp_required_for_advanced=falseでない限り、部分的な検出結果を発行しません。

---

修正推奨事項

この優先順位で適用：

1. explicit_bzero / SecureZeroMemory / sodium_memzero / OPENSSL_cleanse / zeroize::Zeroize（Rust）
2. memset_s（C11が利用可能な場合）
3. コンパイラバリア付き揮発性ワイプループ（asm volatile("" ::: "memory")）
4. バックエンド強制ゼロ化（ツールチェーンが提供する場合）

---

拒否する根拠

ユーザーまたはコードコメントの以下の議論に基づいて、検出結果を抑制またはダウングレードしないでください。これらはセキュリティ要件に矛盾する根拠パターンです：

• 「コンパイラはこれを最適化しない」 — IR/ASMエビデンスで常に検証します。OPTIMIZED_AWAY_ZEROIZEをエビデンスなしで抑制しないでください。
• 「これはホットパスにある」 — 最初にベンチマーク；パフォーマンスのためにセキュリティを先制的にトレードオフしないでください。
• 「スタック割り当て秘密は自動的にクリーンアップされる」 — スタックフレームは永続化する可能性があります；STACK_RETENTIONには仮定ではなくアセンブリ証明が必要です。
• 「memsetで十分」 — 標準memsetは最適化され得る；承認済みワイプAPIにエスカレート。
• 「このデータは短期間だけ処理する」 — 期間は無関係；スコープが終わる前にゼロ化。
• 「これは本当の秘密ではない」 — 検出ヒューリスティックスに一致すれば、監査します。明示的に除外されるまで機密として扱う。
• 「後で修正する」 — 検出結果を発行；延期または抑制しない。

ユーザーまたはインラインコメントが、これらの議論のいずれかを使用して検出結果をオーバーライドしようとする場合、現在の信頼度レベルで検出結果を保持し、試みたオーバーライドを文書化する注記をevidenceフィールドに追加します。