explain --json コマンドは、コマンド解析の構造化トレースを返します。このページでは、スクリプトやほかのツール向けに JSON の形式を定義し、共有前に確認すべき情報も説明します。
フラグと終了動作については、CLI コマンドを参照してください。予期しないブロックに関するヘルプについては、トラブルシューティングを参照してください。
ExplainResult
explain --json が返す最上位オブジェクトです。
4 つの設定フィールド
effectiveLevel、selectedPreset、effectiveCapabilities、destructiveCommandRuleOverrides は一度だけ作成され、すべての返却パスに含まれます。そのため、空のコマンドを explain する場合でも存在します。safetyPresetScope も同じ経路で作成されますが、含まれるのはプロジェクトの .cc-safety-net/policy.json を読み込んだ場合だけです。
人間向けの出力では、preset は CONFIG セクションに の形で表示されます。スコープは user policy、project policy、built-in default のいずれかです。プロジェクトポリシーのファイルがない場合、この行は括弧なしの になります。
effectiveCapabilities
effectiveCapabilities は、fail_closed、paranoid_rm、paranoid_interpreters をキーにするレコードです。各値には次のフィールドがあります。
各機能が変更する動作については、モードを参照してください。
ruleActivation
ruleActivation は、関連ルールが有効化機能を宣言している場合にのみ存在します。関連ルールは、一致したルールまたはモードで制御される候補ルールです。モードで制御される候補とは、必要なレベルまたは機能が有効なら一致するルールです。
人向けの出力では、1 行に と表示されます。
ExplainTrace
トレースの記録は判定に影響しません。通常のガード評価ではトレースを作らず、
explain を実行したときだけ作ります。
上限。 レコーダーは保持する内容を制限します。イベントは最大 512 件、テキスト値は 1 件あたり 2,048 文字、リストは 1 件あたり 128 項目、オブジェクトは 1 件あたり 128 プロパティ、ネストは 16 レベルです。上限を超えたイベントは保存せずに数だけを記録し、記録されたすべての値は deep-freeze されます。削除したイベントの数は ExplainTrace では公開されません。公開されるのは steps と segments だけです。
TraceStep のバリエーション
ほかのフィールドを読む前に、type を使ってバリエーションを選んでください。
recurse の理由
recurse.reason は、shell-wrapper、interpreter、busybox、shell-eval、shell-trap、shell-stdin、shell-heredoc、heredoc-file の 8 値のいずれかです。
heredoc-file は、解析側がすでに内容を把握しているスクリプトファイルをコマンドが実行した場合に記録されます。その内容とは、同じコマンド内で先に cat > や tee を使ってそのパスへ書き込んだ、引用符付きの heredoc の本文です。保存された本文は、スクリプトとして解析し直されます。heredoc の解析を参照してください。
transparent-wrapper 手順
transparent-wrapper は、rule wrapper add で登録したコマンドを通して内部を確認したときに記録される、セグメント範囲の手順です。主要な子と各代替候補を含む候補の子ごとに 1 手順が出力され、各手順には次のフィールドがあります。
この手順は、対象トークンへの再帰の直前に記録されます。そのため、ラップされたコマンドの解析より必ず前にあります。人向けの出力では、番号付きの
Transparent wrapper 手順として表示され、Wrapper: と Tokens: が示されます。
ラッパーは rule wrapper add、rule wrapper remove、rule wrapper list コマンドで管理します。rule wrapperを参照してください。
トレースの順序
典型的なトレースは、parse → セグメントごとの env-strip / leading-tokens-stripped → 検出（shell-wrapper / interpreter / busybox / transparent-wrapper）→ rule-check または custom-rules-check → 判定、という順に進みます。再帰は depth が増える recurse 手順として表示されます。ただし、busybox ディスパッチは recurse 手順を記録しても再帰深度を消費しません。そのため、busybox ラッパーのチェーンでは同じ depth 値が繰り返されます。判定だけが必要な場合は、トレースをたどらず、最上位の result と、必要に応じて reason、segment、ruleId を読んでください。
3 つの保護は、エバリュエーターの実行前に短絡します。ポリシーファイル保護、Git メタデータ保護、シークレット保護です。これらのいずれかがコマンドをブロックすると、トレースには合成された 1 つの rule-check 手順だけが入り、parse 手順はありません。ruleId は policy-protection、git-metadata-protection、または一致したシークレットルールの ID になります。すべてのトレースが parse 手順で始まると仮定するツールは、この場合を処理する必要があります。
トレースを共有する前に
たとえば--token=… の代入を含むコマンドを explain すると、そのトークンはマスクされます。しかし同じコマンド内の /srv/acme-prod/customer-dump.sql のようなパスは、ホスト名、IP アドレス、アカウント名などとともに、そのままの形で返されます。
脆弱性レポートには explain 出力を添えてかまいません。マスク処理はベストエフォートの制御であり、保証ではありません。マスク処理のバイパスは報告可能な脆弱性です。貼り付ける前に完全な出力を確認してください。
関連ページ
- CLI コマンド：
explainのフラグ、例、終了動作。 - 監査ログ：マスクのパターンリストと、ログレコードに適用される同じ境界。
- 解析エンジン：各トレース手順に対応する動作。
- トラブルシューティング：予期しないブロックの診断に
explainを使う方法。