explain --json 命令返回命令分析的结构化跟踪。此页面定义了用于脚本和其他工具的 JSON 形状。它还解释了在共享跟踪之前可以揭示的内容。
有关标志和退出行为，请参阅 CLI 命令。有关意外阻止的帮助，请参阅 故障排除。
ExplainResult
explain --json 返回的顶级对象。
四个配置字段 —
effectiveLevel、selectedPreset、effectiveCapabilities 和 destructiveCommandRuleOverrides — 会一次性构建并包含在每个返回路径中，因此即使解释空命令时它们也存在。
effectiveCapabilities
effectiveCapabilities 是一个记录，键为 fail_closed、paranoid_rm 和 paranoid_interpreters。每个值包含：
请参阅 模式，了解每个功能会改变什么。
ruleActivation
ruleActivation 仅在相关规则声明激活功能时存在。相关规则是要么匹配的规则，要么是受模式限制的候选规则。受模式限制的候选规则是指如果其所需的级别或功能处于活动状态就会匹配的规则。
在人类可读的输出中，这会渲染为一行：
Rule activation: <id> — on|off via <source>。
ExplainTrace
跟踪是被动的：记录它永远不会改变决策，普通的保护评估也永远不会构建它。它仅用于
explain。
边界。 记录器会限制其保留的内容：最多 512 个事件，每个文本值最多 2,048 个字符，每个列表最多 128 个项，每个对象最多 128 个属性，以及 16 个嵌套级别。超出限制的事件会被计数而不是存储，并且每个记录的值都会被深度冻结。丢弃事件的数量不会在 ExplainTrace 中暴露 — 仅暴露 steps 和 segments。
TraceStep 变体
在读取其其他字段之前，请使用 type 来选择变体。
recurse 原因
recurse.reason 有八个值之一：shell-wrapper、interpreter、busybox、shell-eval、shell-trap、shell-stdin、shell-heredoc 或 heredoc-file。
当命令运行一个分析引擎已知的脚本文件时（通过 cat > 或 tee 在同一命令的早期通过 quoted heredoc body 写入该路径），并且存储的 body 被作为脚本重新分析时，会记录 heredoc-file；请参阅 Heredoc 分析。
transparent-wrapper 步骤
transparent-wrapper 是一个片段范围的步骤，当看到您使用 rule wrapper add 注册的命令被看穿时会记录。每个候选子命令 — 主要子命令加上每个替代项 — 会发出一个步骤，每个步骤携带：
该步骤在递归进入这些 token 之前立即记录，因此它总是出现在包装命令的分析之前。人类可读的输出将其渲染为编号的
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），而不是遍历跟踪。
三个保护措施在评估器运行之前会短路：策略文件保护、Git 元数据保护和秘密保护。当其中一个阻止命令时，跟踪将包含一个单一的合成 rule-check 步骤，没有 parse 步骤，ruleId 设置为 policy-protection、git-metadata-protection 或匹配的秘密规则的 ID。假定每个跟踪都以 parse 步骤开始的工具需要处理这种情况。
共享跟踪之前
例如，解释一个包含--token=… 赋值的命令会隐藏 token，但同一命令中的路径 /srv/acme-prod/customer-dump.sql 会完整返回，以及命令文本中的任何主机名、IP 地址或帐户名。
您可以将 explain 输出包含在漏洞报告中。隐藏是一种尽力而为的控制，而不是保证。隐藏绕过是可报告的漏洞。粘贴之前请检查完整输出。