Explain JSON 跟踪参考

explain --json 以一个 JSON 对象返回命令的决策结果，以及每个分析步骤的跟踪。脚本从顶级字段读取决策，需要细节时再遍历跟踪。选项和退出码见 explain。

npx cc-safety-net explain --json "git checkout -- file.txt"

跟踪并不自动适合分享。请先阅读分享跟踪之前。

ExplainResult

字段	类型	何时出现	描述
`result`	`"blocked" \| "allowed"`	始终	命令的最终结果
`reason`	`string`	仅 blocked	阻止原因
`segment`	`string`	仅 blocked	触发决策的具体片段
`ruleId`	`string`	仅 blocked	产生该阻止的规则或固定拒绝的 ID
`trace`	`ExplainTrace`	始终	跟踪容器，包含顶级步骤和各片段的步骤
`customRule`	`object`	匹配到自定义规则或 rulebook 规则时	`id`，以及可选的 `rulebook`（`name`、`version`）、`source` 和 `override`（`{ type: "reason", reason }`）
`configSource`	`string \| null`	始终	CC Safety Net 加载生效配置时读取的配置文件
`configValid`	`boolean`	始终	加载的配置是否顺利通过校验
`effectiveLevel`	`"standard" \| "strict" \| "paranoid" \| "custom"`	始终	应用环境变量和覆盖之后实际生效的级别
`selectedPreset`	`"standard" \| "strict" \| "paranoid"`	始终	策略中指定的预设，默认为 `standard`
`safetyPresetScope`	`"user" \| "project" \| "default"`	仅在读取到项目策略文件时	提供 `selectedPreset` 的范围
`effectiveCapabilities`	`object`	始终	各项能力的状态，见下文
`destructiveCommandRuleOverrides`	`Record<string, "on" \| "off">`	始终，可能为 `{}`	策略中存储的单条规则覆盖
`ruleActivation`	`object`	视情况而定，见下文	相关规则的开启/关闭状态由什么决定

`effectiveCapabilities`

effectiveCapabilities 是以 fail_closed、paranoid_rm 和 paranoid_interpreters 为键的记录。每个值包含：

字段	类型	描述
`enabled`	`boolean`	该能力是否开启
`source`	`"preset" \| "capability_override" \| "environment"`	决定最终状态的来源
`sources`	`array`	起作用的所有输入，按优先级排序

各项能力改变什么，见模式。

`ruleActivation`

只有当相关规则受某项能力控制时，才会出现 ruleActivation。相关规则指匹配到的规则，或者在其级别或能力开启时就会匹配的规则。

字段	类型	描述
`id`	`string`	规则 ID
`enabled`	`boolean`	该规则当前是否启用
`inheritedEnabled`	`boolean`	仅凭继承，该规则是否会启用
`changesInherited`	`boolean`	生效状态是否与继承来的状态不同
`source`	`string`	由什么决定：`catastrophic`、`master_disabled`、`rule_override`、`preset`、`capability_override`、`environment` 或 `built_in_default`
`activationCapability`	`string`	可选。控制该规则的能力
`override`	`"on" \| "off"`	可选。存在单条规则覆盖时，为其存储值

人类可读输出把它显示为一行：。

`ExplainTrace`

字段	类型	描述
`steps`	`TraceStep[]`	顶级步骤。大多数跟踪以全局的 `parse` 步骤开头，保护短路产生的跟踪没有这一步。
`segments`	`object[]`	各片段的条目，每个条目都有 `index` 和自己的 `steps` 数组

记录跟踪从不改变决策。CC Safety Net 会限制过长的跟踪：缩短较长的文本值，并丢弃超出上限的步骤。

`TraceStep` 变体

先用 type 确定变体，再读取它的其他字段。

`type`	关键字段	何时出现
`parse`	`input`、`segments`	最初的 shell 拆分，得到 token 片段
`env-strip`	`input`、`envVars`、`output`	从片段开头剥离的环境赋值。`envVars` 只含被赋值的变量名，不含值。赋值 token 仍保留在 `input` 中，值已脱敏
`leading-tokens-stripped`	`input`、`removed`、`output`	分析前移除的前导 token，例如 `env` 或 `command`
`shell-wrapper`	`wrapper`、`innerCommand`	分析器解开了 `bash -c` 这类 shell 包装器
`interpreter`	`interpreter`、`codeArg`、`paranoidBlocked`	分析器检查了解释器单行命令。`paranoidBlocked` 标记 paranoid 模式下的直接拒绝
`busybox`	`subcommand`	分析器把 busybox 风格的分派解析为子命令
`transparent-wrapper`	`wrapper`、`output`	分析器看穿了一个已注册的透明包装器，见下文
`recurse`	`reason`、`innerCommand`、`depth`	分析器开始递归重新分析
`script-file`	`path`、`bytes`	分析器从磁盘读取了一个 shell 脚本，见下文
`rule-check`	`rule`、`matched`、`reason?`	分析器评估了一条内置规则
`worktree-relaxation`	`originalReason`、`gitCwd`	目标是 linked worktree，分析器因此放宽了 git 丢弃类命令
`temp-root-relaxation`	`originalReason`、`gitCwd`	git 运行在受信任临时根目录下的一次性仓库中，分析器因此放宽了某条 git 规则
`tmpdir-check`	`tmpdirValue`、`allowTmpdirVar`	`$TMPDIR` 解析和覆盖检测
`fallback-scan`	`tokensScanned`、`embeddedCommandFound?`	对剩余 token 做的危险文本兜底扫描
`custom-rules-check`	`rulesChecked`、`matched`、`reason?`	分析器评估了自定义规则
`cwd-change`	`segment`、`effectiveCwdNowUnknown`	实际 cwd 变为未知，后续分类失去 cwd 锚点。`effectiveCwdNowUnknown` 始终为 `true`，被成功追踪的 `cd` 不记录这一步
`dangerous-text`	`token`、`matched`、`reason?`	分析器按危险文本模式扫描了某个 token
`strict-unparseable`	`rawCommand`、`reason`	strict 模式在无法解析的命令上 fail closed
`segment-skipped`	`index`、`reason`	前面的片段已经阻止了命令，分析器跳过了该片段
`error`	`message`、`partial?`	分析器捕获了分析错误。`partial` 标记部分输出

temp-root-relaxation 何时适用，见临时根目录放宽。

`recurse` 原因

recurse.reason 取以下八个值之一：shell-wrapper、interpreter、busybox、shell-eval、shell-trap、shell-stdin、shell-heredoc 或 heredoc-file。 heredoc-file 表示命令运行了一个脚本，而该脚本由同一命令中前面的 heredoc 写出。见分析器能看穿的写法。

`script-file` 步骤

sh deploy.sh 或 ./deploy.sh 这类命令会产生 script-file 步骤。path 就是命令中书写的那个路径，bytes 是文件大小。脚本内部的命令不再产生后续步骤，也没有任何字段携带脚本文本。见从文件运行的脚本。如果脚本由同一命令中的 heredoc 写出，记录的则是原因为 heredoc-file 的 recurse 步骤，这一步会携带正文。

`transparent-wrapper` 步骤

分析过程看穿用 rule wrapper add 注册的命令时，会出现 transparent-wrapper 步骤。wrapper 是包装器名称，output 是被包装命令的 token 列表。每个候选各产生一个步骤，紧接在被包装命令的分析之前。

跟踪顺序

典型的跟踪以 parse 开头。之后每个片段依次出现 env-strip 或 leading-tokens-stripped，然后是包装器检测步骤 shell-wrapper、interpreter、busybox 和 transparent-wrapper，最后是 rule-check 或 custom-rules-check。嵌套命令表现为带 depth 的 recurse 步骤。下面四种保护会在评估器运行之前阻止命令。此时跟踪只含一个合成的 rule-check 步骤，没有 parse 步骤，假定每条跟踪都以 parse 开头的脚本必须处理这种情况：

保护	`ruleId`
策略文件保护	`guard.policy-config`
`policy apply` 保护	`guard.policy-apply`
Git 元数据保护	`guard.git-metadata`
机密保护	匹配到的机密规则的 ID

分享跟踪之前

脱敏只移除可识别的凭证形式，使用的模式列表与审计日志相同。文件路径、主机名、IP 地址、用户名、项目或客户名称，以及格式无法识别的机密都会原样保留。请用占位凭证和占位路径复现问题，通读完整输出后再分享。

parse 步骤会记录原始命令字符串和解析出的每个 token。以下字段同样携带原始文本：

fallback-scan.tokensScanned、dangerous-text.token、strict-unparseable.rawCommand
shell-wrapper.innerCommand、interpreter.codeArg、recurse.innerCommand、transparent-wrapper.output
script-file.path、worktree-relaxation.gitCwd、temp-root-relaxation.gitCwd、cwd-change.segment

configSource 是绝对路径，通常位于你的主目录内。漏洞报告中可以附上 explain 输出。如果你提供的文本中某种凭证格式没有被脱敏，这属于普通 bug，请提交公开的 GitHub issue，不必按漏洞报告。

开始使用

指南

配置

故障排除

CLI 命令

规则与保护

日志与追踪

更多参考

概念

项目

Explain JSON 跟踪参考

ExplainResult

`effectiveCapabilities`

`ruleActivation`

`ExplainTrace`

`TraceStep` 变体

`recurse` 原因

`script-file` 步骤

`transparent-wrapper` 步骤

跟踪顺序

分享跟踪之前

​ExplainResult

​effectiveCapabilities

​ruleActivation

​ExplainTrace

​TraceStep 变体

​recurse 原因

​script-file 步骤

​transparent-wrapper 步骤

​跟踪顺序

​分享跟踪之前

ExplainResult

`effectiveCapabilities`

`ruleActivation`

`ExplainTrace`

`TraceStep` 变体

`recurse` 原因

`script-file` 步骤

`transparent-wrapper` 步骤

跟踪顺序

分享跟踪之前