explain --json は、コマンドに対する判定と、解析の各段階を記録したトレースを、1 つの JSON オブジェクトとして返します。スクリプトでは最上位のフィールドから判定を読み取り、詳細が必要なときにトレースをたどります。フラグと終了コードについては explain を参照してください。
ExplainResult
effectiveCapabilities
effectiveCapabilities は、fail_closed、paranoid_rm、paranoid_interpreters をキーとするレコードです。各値には次のフィールドがあります。
各機能で何が変わるかはモードを参照してください。
ruleActivation
ruleActivation は、関連するルールを機能が制御している場合にだけ含まれます。関連するルールとは、一致したルール、またはレベルや機能が有効であれば一致するはずだったルールです。
人間向けの出力では、 の 1 行で表示されます。
ExplainTrace
トレースを記録しても判定は変わりません。非常に長いトレースには上限があり、長いテキストの値は切り詰め、上限を超えたステップは破棄します。
TraceStep の種類
ほかのフィールドを読む前に、type で種類を判別してください。
temp-root-relaxation が適用される条件は、一時ルートの緩和を参照してください。
recurse の理由
recurse.reason は、shell-wrapper、interpreter、busybox、shell-eval、shell-trap、shell-stdin、shell-heredoc、heredoc-file の 8 つの値のいずれかです。
heredoc-file は、同じコマンド内で先に heredoc が書き出したスクリプトを、コマンドが実行したことを示します。アナライザーが見抜く書き方を参照してください。
script-file ステップ
script-file ステップは、sh deploy.sh や ./deploy.sh のようなコマンドで現れます。path はコマンドに書かれたとおりのパス、bytes はファイルのサイズです。スクリプト内のコマンドについてはステップが追加されず、スクリプトのテキストを含むフィールドもありません。ファイルから実行するスクリプトを参照してください。
同じコマンド内の heredoc が書き出したスクリプトの場合は、代わりに理由が heredoc-file の recurse ステップを記録します。こちらには本文が含まれます。
transparent-wrapper ステップ
transparent-wrapper ステップは、rule wrapper add で登録したコマンドの中を解析が確認したときに現れます。wrapper はラッパーの名前、output はラップされたコマンドのトークンのリストです。ラップされたコマンドの解析の直前に、候補ごとに 1 つずつ記録されます。
トレースの順序
典型的なトレースはparse で始まります。続いて各セグメントに env-strip または leading-tokens-stripped が現れ、次にラッパーを検出するステップ shell-wrapper、interpreter、busybox、transparent-wrapper、その後に rule-check または custom-rules-check が続きます。入れ子のコマンドは、depth を持つ recurse ステップとして現れます。
次の 4 つの保護は、評価器が動く前にコマンドをブロックします。このときトレースには合成された rule-check ステップが 1 つだけ入り、parse ステップはありません。すべてのトレースが parse で始まることを前提にしたスクリプトは、この場合も処理する必要があります。
トレースを共有する前に
parse ステップは、生のコマンド文字列とパースしたすべてのトークンを記録します。次のフィールドにも生のテキストが入ります。
fallback-scan.tokensScanned、dangerous-text.token、strict-unparseable.rawCommandshell-wrapper.innerCommand、interpreter.codeArg、recurse.innerCommand、transparent-wrapper.outputscript-file.path、worktree-relaxation.gitCwd、temp-root-relaxation.gitCwd、cwd-change.segment
configSource は絶対パスで、通常はホームディレクトリ内を指します。
脆弱性レポートに explain の出力を含めてかまいません。自分で入力したテキストに含まれる資格情報の形式をマスク処理が見逃した場合、それは脆弱性ではなく、公開の GitHub Issue で報告する通常のバグです。