Claude Code Harness 审计日志完全指南用 JSONL 数清每一次安全拦截【免费下载链接】claude-code-harnessClaude Code Dedicated Development Harness - Achieving High-Quality Development Through an Autonomous Plan→Work→Review Cycle项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-harness在 Claude Code Harness 中guardrail护栏会在 AI 执行工具调用前自动做出 deny / ask / warn 等决策但拦截发生了只是故事的一半。Harness 内置的Claude Code Harness 审计日志auditlog 模块会把每一次护栏触发写入项目内的.claude/state/audit/guardrail-fires.jsonl文件——一行一条 JSONL 记录不保存原始命令、不落盘敏感路径让你可以用grep和wc -l数清每一次拦截。本指南带你读懂字段、看懂决策类型并掌握隐私保护的设计细节。审计日志是什么在哪里生成审计日志Audit Log是 Harness 护栏系统的事件流水账。它的核心实现在 auditlog.go 中包注释一句话就说明了设计目标记录护栏与运行时底线runtime floor的决策但不持久化原始命令或文件路径。关键常量定义在 auditlog.go#L17-L20schemaVersion guardrail-fire.v1 auditLogPath .claude/state/audit/guardrail-fires.jsonl也就是说日志固定写入你的项目根目录/.claude/state/audit/guardrail-fires.jsonl采用JSONL格式每行一条独立 JSON 记录天然适合追加写入、逐行解析目录以0700、文件以0600权限创建只有项目属主可读只有护栏实际开火deny / ask / defer / warn时才会追加纯 approve 不产生任何日志避免噪声一条审计记录长什么样每次护栏触发Record 函数 会追加一条记录。字段结构见 guardrailFire 结构体字段含义何时出现schema_version固定为guardrail-fire.v1方便未来演进总是ts触发时间UTCRFC3339 格式总是tool被拦截的工具名如Bash、Write、Read总是rule_id触发的规则如R01:no-sudo、R04:confirm-write-outside-project总是decision决策结果deny/ask/defer/warn总是host触发来源的宿主如codex、claude有值时category运行时底线类别如prod-deploy仅 RUNTIME_FLOOR 规则command_sha256命令/路径的 SHA-256 摘要指纹非敏感类别command_len原始命令或路径的字节长度非敏感类别一条真实形态的记录大致如下{schema_version:guardrail-fire.v1,ts:2026-09-01T02:00:00Z,host:codex,tool:Bash,rule_id:R01:no-sudo,decision:deny,command_sha256:9f86d081…,command_len:23}注意原始命令sudo xxx本身永远不出现在日志里只留下指纹和长度。四种决策拦截如何被记账auditDecision 函数 决定了哪些结果值得留痕deny—— 直接拒绝执行例如R01:no-sudo禁止 sudoask—— 暂停并请求用户确认例如R04写项目外文件⏸️defer—— 推迟到后续再决策⚠️warn—— 放行但附带警示只有当决策是 approve且带有system_message时才记为 warn如R09:warn-secret-file-read读取疑似密钥文件反过来说普通放行approve 且无提示不会写日志。这条测试明确验证了这一点audit_test.go 的 TestEvaluatePreTool_PureApproveDoesNotCreateAuditLog。这意味着日志行数 ≈ 值得你关注的风险事件数wc -l就是最朴素的拦截次数统计。隐私设计为什么日志里没有命令原文这是 Harness 审计日志最值得称道的设计。核心逻辑在 auditSubject 与敏感类别判断默认不存原文非敏感事件只记录命令的SHA-256 摘要command_sha256与字节长度command_len。摘要可用于去重和关联同一条命令的指纹相同但无法反推出命令本身敏感类别连指纹都不留当category是secret-read读取密钥或money-billing涉及资金时command_sha256和command_len字段会被整体省略——因为哪条命令被拦过这个事实本身可能就是敏感信息测试用例 TestEvaluatePreTool_SensitiveFloorCategoriesOmitCommandDerivedFields 用cat ~/.aws/credentials和stripe charges list两个场景严格验证了这一点日志中既无原文、也无指纹。并发安全与失败容错护栏永远优先写日志时还有两个工程细节保证了审计可靠但不碍事文件锁保证行完整追加写入在 WithFileLock 的保护下进行Unix 与 Windows 各有实现见 file_lock_unix.go / file_lock_windows.go。即使多个会话并发触发护栏并发写入测试 也确保每行都是完整合法的 JSON不会出现两行记录挤成一行的脏数据失败则静默跳过fail-openRecord 的注释 写得很直白——任何文件系统或序列化错误都会被忽略可观测性不允许改变护栏决策。对应测试 TestEvaluatePreTool_AuditFailureIsFailOpen 验证即使日志目录不可写deny 决策依然照常生效一句话总结审计日志坏了护栏照常工作。快速上手三步数清拦截次数假设你已经在本项目完成过安装流程见 install.md可以用下面三个命令快速体检① 日志在哪看文件cat .claude/state/audit/guardrail-fires.jsonl② 总共被拦了多少次wc -l .claude/state/audit/guardrail-fires.jsonl③ 哪条规则开火最多grep -o rule_id:[^]* .claude/state/audit/guardrail-fires.jsonl | sort | uniq -c | sort -rn如果输出里R01:no-sudo或RUNTIME_FLOOR:prod-deploy排名很高说明 AI 频繁试图执行危险操作——这正是审计日志的价值把感觉不太安全变成可数、可归类、可回溯的事实。延伸阅读相关模块与文档护栏规则实现go/internal/guardrail/其中 pre_tool.go#L474 是工具调用前触发auditlog.Record的位置计划预审批的留痕逻辑plan_preapproval.go端到端审计行为测试audit_test.go运行时底线机制说明runtime-floor-secret-allowlist.md跨项目审计日志另一条线cross-project-audit-log.sh功能演进记录CHANGELOG.md常见问题FAQQ审计日志会泄露我的命令吗不会。非敏感事件只存 SHA-256 指纹secret-read、money-billing类事件连指纹都省略。测试会断言日志全文不包含任何原始命令或路径。Q为什么有些会话结束后日志没有新增正常行为。只有 deny / ask / defer / warn 才会写日志完全顺路的 approve 不记账。Q日志文件可以提交到版本库吗不建议。它记录的是本机行为细节建议将其加入.gitignore。Qhost字段是干什么的标记触发来源如codex、claude方便在 Claude Code Codex 多宿主混用时按来源过滤统计。结语Claude Code Harness 的审计日志用最小的代价换来了最大的可观测性一行 JSONL 一条拦截记录JSONL 格式易统计SHA-256 指纹保隐私文件锁保并发fail-open 保护栏优先。配合wc -l和uniq -c任何人都能在 30 秒内回答AI 今天被我拦了多少次、都是哪些规则。审计不是为了追责而是让信任有据可查——这正是 Plan → Work → Review 循环中证据驱动理念的落地。【免费下载链接】claude-code-harnessClaude Code Dedicated Development Harness - Achieving High-Quality Development Through an Autonomous Plan→Work→Review Cycle项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Claude Code Harness 审计日志完全指南：用 JSONL 数清每一次安全拦截
Claude Code Harness 审计日志完全指南用 JSONL 数清每一次安全拦截【免费下载链接】claude-code-harnessClaude Code Dedicated Development Harness - Achieving High-Quality Development Through an Autonomous Plan→Work→Review Cycle项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-harness在 Claude Code Harness 中guardrail护栏会在 AI 执行工具调用前自动做出 deny / ask / warn 等决策但拦截发生了只是故事的一半。Harness 内置的Claude Code Harness 审计日志auditlog 模块会把每一次护栏触发写入项目内的.claude/state/audit/guardrail-fires.jsonl文件——一行一条 JSONL 记录不保存原始命令、不落盘敏感路径让你可以用grep和wc -l数清每一次拦截。本指南带你读懂字段、看懂决策类型并掌握隐私保护的设计细节。审计日志是什么在哪里生成审计日志Audit Log是 Harness 护栏系统的事件流水账。它的核心实现在 auditlog.go 中包注释一句话就说明了设计目标记录护栏与运行时底线runtime floor的决策但不持久化原始命令或文件路径。关键常量定义在 auditlog.go#L17-L20schemaVersion guardrail-fire.v1 auditLogPath .claude/state/audit/guardrail-fires.jsonl也就是说日志固定写入你的项目根目录/.claude/state/audit/guardrail-fires.jsonl采用JSONL格式每行一条独立 JSON 记录天然适合追加写入、逐行解析目录以0700、文件以0600权限创建只有项目属主可读只有护栏实际开火deny / ask / defer / warn时才会追加纯 approve 不产生任何日志避免噪声一条审计记录长什么样每次护栏触发Record 函数 会追加一条记录。字段结构见 guardrailFire 结构体字段含义何时出现schema_version固定为guardrail-fire.v1方便未来演进总是ts触发时间UTCRFC3339 格式总是tool被拦截的工具名如Bash、Write、Read总是rule_id触发的规则如R01:no-sudo、R04:confirm-write-outside-project总是decision决策结果deny/ask/defer/warn总是host触发来源的宿主如codex、claude有值时category运行时底线类别如prod-deploy仅 RUNTIME_FLOOR 规则command_sha256命令/路径的 SHA-256 摘要指纹非敏感类别command_len原始命令或路径的字节长度非敏感类别一条真实形态的记录大致如下{schema_version:guardrail-fire.v1,ts:2026-09-01T02:00:00Z,host:codex,tool:Bash,rule_id:R01:no-sudo,decision:deny,command_sha256:9f86d081…,command_len:23}注意原始命令sudo xxx本身永远不出现在日志里只留下指纹和长度。四种决策拦截如何被记账auditDecision 函数 决定了哪些结果值得留痕deny—— 直接拒绝执行例如R01:no-sudo禁止 sudoask—— 暂停并请求用户确认例如R04写项目外文件⏸️defer—— 推迟到后续再决策⚠️warn—— 放行但附带警示只有当决策是 approve且带有system_message时才记为 warn如R09:warn-secret-file-read读取疑似密钥文件反过来说普通放行approve 且无提示不会写日志。这条测试明确验证了这一点audit_test.go 的 TestEvaluatePreTool_PureApproveDoesNotCreateAuditLog。这意味着日志行数 ≈ 值得你关注的风险事件数wc -l就是最朴素的拦截次数统计。隐私设计为什么日志里没有命令原文这是 Harness 审计日志最值得称道的设计。核心逻辑在 auditSubject 与敏感类别判断默认不存原文非敏感事件只记录命令的SHA-256 摘要command_sha256与字节长度command_len。摘要可用于去重和关联同一条命令的指纹相同但无法反推出命令本身敏感类别连指纹都不留当category是secret-read读取密钥或money-billing涉及资金时command_sha256和command_len字段会被整体省略——因为哪条命令被拦过这个事实本身可能就是敏感信息测试用例 TestEvaluatePreTool_SensitiveFloorCategoriesOmitCommandDerivedFields 用cat ~/.aws/credentials和stripe charges list两个场景严格验证了这一点日志中既无原文、也无指纹。并发安全与失败容错护栏永远优先写日志时还有两个工程细节保证了审计可靠但不碍事文件锁保证行完整追加写入在 WithFileLock 的保护下进行Unix 与 Windows 各有实现见 file_lock_unix.go / file_lock_windows.go。即使多个会话并发触发护栏并发写入测试 也确保每行都是完整合法的 JSON不会出现两行记录挤成一行的脏数据失败则静默跳过fail-openRecord 的注释 写得很直白——任何文件系统或序列化错误都会被忽略可观测性不允许改变护栏决策。对应测试 TestEvaluatePreTool_AuditFailureIsFailOpen 验证即使日志目录不可写deny 决策依然照常生效一句话总结审计日志坏了护栏照常工作。快速上手三步数清拦截次数假设你已经在本项目完成过安装流程见 install.md可以用下面三个命令快速体检① 日志在哪看文件cat .claude/state/audit/guardrail-fires.jsonl② 总共被拦了多少次wc -l .claude/state/audit/guardrail-fires.jsonl③ 哪条规则开火最多grep -o rule_id:[^]* .claude/state/audit/guardrail-fires.jsonl | sort | uniq -c | sort -rn如果输出里R01:no-sudo或RUNTIME_FLOOR:prod-deploy排名很高说明 AI 频繁试图执行危险操作——这正是审计日志的价值把感觉不太安全变成可数、可归类、可回溯的事实。延伸阅读相关模块与文档护栏规则实现go/internal/guardrail/其中 pre_tool.go#L474 是工具调用前触发auditlog.Record的位置计划预审批的留痕逻辑plan_preapproval.go端到端审计行为测试audit_test.go运行时底线机制说明runtime-floor-secret-allowlist.md跨项目审计日志另一条线cross-project-audit-log.sh功能演进记录CHANGELOG.md常见问题FAQQ审计日志会泄露我的命令吗不会。非敏感事件只存 SHA-256 指纹secret-read、money-billing类事件连指纹都省略。测试会断言日志全文不包含任何原始命令或路径。Q为什么有些会话结束后日志没有新增正常行为。只有 deny / ask / defer / warn 才会写日志完全顺路的 approve 不记账。Q日志文件可以提交到版本库吗不建议。它记录的是本机行为细节建议将其加入.gitignore。Qhost字段是干什么的标记触发来源如codex、claude方便在 Claude Code Codex 多宿主混用时按来源过滤统计。结语Claude Code Harness 的审计日志用最小的代价换来了最大的可观测性一行 JSONL 一条拦截记录JSONL 格式易统计SHA-256 指纹保隐私文件锁保并发fail-open 保护栏优先。配合wc -l和uniq -c任何人都能在 30 秒内回答AI 今天被我拦了多少次、都是哪些规则。审计不是为了追责而是让信任有据可查——这正是 Plan → Work → Review 循环中证据驱动理念的落地。【免费下载链接】claude-code-harnessClaude Code Dedicated Development Harness - Achieving High-Quality Development Through an Autonomous Plan→Work→Review Cycle项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考