explain --json コマンドは、コマンド解析の構造化トレースを返します。このページでは、スクリプトやほかのツール向けに JSON の形式を定義します。また、共有前にトレースから明らかになる可能性がある情報も説明します。
フラグと終了動作については、CLI コマンドを参照してください。予期しないブロックに関するヘルプについては、トラブルシューティングを参照してください。
ExplainResult
explain --json が返す最上位オブジェクトです。
4 つの設定フィールド
effectiveLevel、selectedPreset、effectiveCapabilities、destructiveCommandRuleOverrides は一度だけ作成され、すべての返却パスに含まれます。そのため、空のコマンドを explain する場合でも存在します。
effectiveCapabilities
effectiveCapabilities は、fail_closed、paranoid_rm、paranoid_interpreters をキーにするレコードです。各値には次のフィールドがあります。
各機能が変更する動作については、モードを参照してください。
ruleActivation
ruleActivation は、関連ルールが有効化機能を宣言している場合にのみ存在します。関連ルールは、一致したルールまたはモードで制御される候補ルールです。モードで制御される候補とは、必要なレベルまたは機能が有効なら一致するルールです。
人向けの出力では、
Rule activation: <id> — on|off via <source> という 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を使う方法。