企业官网建设流程全解析

🔐 当你用 AI Agent 帮你跑命令、读文件、发请求时，日志里会留下AKIA...这样的 AWS 密钥、.env内容和带签名的 URL。numbat是一款面向终端的 AI Agent 行为可见性工具，提供本机检测、可选的预行动拦截和取证重建；其内置的redact脱敏机制会在记录输出前自动把密钥替换为[redacted]，是防止"为了调查 Agent 泄漏，反而泄漏更多密钥"的关键防线。

1. 为什么 AI Agent 日志是天然的密钥富矿 🗝️

AI Agent 的一次会话可能涉及：

• 命令：cat .env、env、aws configure set ...——直接把凭证打进命令行；
• 文件路径与 URL：预签名 URL（X-Amz-Signature=...）、user:password@host形式的连接串；
• 对话内容：用户把密钥粘进 prompt 的场景并不罕见；
• MCP 工具配置：server 参数里常带api_key=...。

numbat 通过本地 hook、OTLP/HTTP 日志和磁盘会话文件收集这些行为（覆盖 Codex、Claude Code、Cursor、Gemini CLI 等 30+ 种 Agent，见 docs/agent-coverage.md）。问题在于：收集这些高敏感产物的工具，自己输出的记录也可能成为二次泄漏源。

2. redact 脱敏机制：四道防线如何拦截密钥 🛡️

核心实现位于 internal/redact/ 包。所有要"离开 numbat"的内容——命令、文件路径、URL、内容预览——默认都会经过 redact.String() 处理，命中即替换为固定掩码[redacted]（定义见 redact.go#L14-L15）。

2.1 已知令牌格式：高精度整段替换

对"自我标识"的密钥形态做正则命中，一处不漏（redact.go#L17-L30）：

2.2 密钥形赋值：KEY=VALUE一律遮值

只要键名含SECRET、TOKEN、PASSWORD、API_KEY、ACCESS_KEY等词根（redact.go#L32），无论写成API_KEY=xxx、"api_key": "xxx"还是password: xxx，都只遮值、保留键名与引号结构（redact.go#L517-L561）——这样脱敏后的命令仍可读懂"谁拿到了什么"，而不是变成一坨乱码。

2.3 URL 凭据：userinfo 密码 + 精确签名参数

• URL 中user:password@host的密码段被替换为***（redact.go#L104-L135）；
• Basic/BearerAuthorization 值整体打码；
• 预签名 URL 的凭据参数按精确键名匹配（x-amz-signature、access_token、signature、api_key、password等，清单见 redact.go#L55-L76）。

这里有个值得学习的设计：id_token、mytoken、presignature这类"长得像但不是"的参数故意不遮，避免误伤正常排查。

2.4 对抗混淆：编码、空格、嵌套引号都逃不掉

这是 redact 最"硬核"的部分。攻击者（或被诱导的 Agent）可能用%253d双重百分号编码、api<空格>_<空格>key=...中间塞 256 个空格、token="SECRET"嵌套在另一个值里等手段躲检测。numbat 先构造一个规范化解视图：反复百分号解码到不动点、控制字符折叠、ASCII 小写化，并保留每个 token 的原始字节跨度（redact.go#L249-L276）；匹配在规范化空间做，打码回写到原始位置。对应的回归用例见 redact_test.go，覆盖了嵌套引号、编码填充、长前缀冲刷等刁钻场景。

3. 输出投影：脱敏只发生在出口，绝不影响检测 🎯

这是整条管线中最容易被做错的点，numbat 的选择是：

规则先对未脱敏的原始事件求值，再脱敏后输出。

redact_event.go#L5-L17 明确注释了这一契约：脱敏只作用于输出，检测精度不受影响。具体投影规则：

• 默认只出预览：事件携带最多 200 个 Unicode 码点的content_preview，完整正文（Content）默认直接丢弃（redact_event.go#L18-L34）；
• 显式开启才有全文：--content full会输出经过脱敏、且限制在 1 MiB 的content字段（见 docs/cli.md）；
• finding 自带"是否打码"标记：每条 finding 记录的redacted布尔字段表示"至少一个输出字段被遮过"（schema 定义见 finding-record.schema.json#L138-L141），接收方一眼就能判断证据是否被处理过；
• finding 不落原始转录：项目路径在 finding 中输出为不可逆的project_path_hash，命令/路径/URL 等观察字段逐一过redact.String（finding.go#L163-L198）。

JSON 脱敏：打码不破坏语法

对结构化 JSON（如 case bundle 里的证据副本），redact.JSON() 递归遍历，把api_key这类键的值换成[redacted]，同时保护 LLM 用量指标（input_tokens、output_tokens等白名单，见 json.go#L14-L44）不被误判为"token 密钥"而打码——输出保证仍是合法 JSON，且有 fuzz 测试守护（json_test.go#L45-L54）。

全链路"金丝雀"测试

cmd/numbat/redact_emit_test.go 在命令、文件路径、URL、prompt 四个字段各埋一枚"金丝雀"密钥，断言scan --emit events、scan --emit all等每一条输出路径都不允许任何一枚泄漏。这种"输出端可证伪"的测试设计，是把脱敏当安全边界而不是最佳努力来对待的信号。

4. 威胁模型剖析：脱敏不是终点，而是防线之一 ⚠️

官方威胁模型写在 SECURITY.md，值得每位运维者逐条对照：

1. 脱敏 ≠ 数据防泄漏（DLP）边界。它只遮掉"已识别的密钥模式"，记录中仍可能保留命令形态、路径、主机名、用户、模型名等敏感上下文。官方明确要求：分享记录前先人工审查。
2. project_path_hash是伪匿名，不是匿名。它是稳定、无盐的 join 键，可以关联同一项目的多条记录，但对可预测的路径并不能真正去标识（SECURITY.md#L42-L43）。
3. 原始证据进 case bundle 是显式 opt-in。case build默认只带引用和 SHA-256 摘要；--include-raw-evidence原样拷贝（可能含.env明文），--include-redacted-evidence才做尽力而为打码，且清单为原始/脱敏副本分别记录哈希，防止"脱敏版被误当成原件"（docs/cli.md#L840-L868）。
4. numbat 自身不外联。它只向操作者配置的 HTTP sink 发请求，且非回环地址强制 HTTPS；collect默认绑定127.0.0.1:4318，不应暴露到不受信网络。
5. hook 以 Agent 进程的权限运行，用户级配置与输出文件默认对该用户可读——需要更强隔离时要用 OS 层控制。

与检测规则的关系：脱敏是"出口治理"，规则是"入口洞察"

脱敏负责让记录可以安全流转；而像 rules/secrets/agent_read_env.yaml（检测读取.env）或 rules/exfil/env_capture_to_network.yaml（检测env/cat .env的输出被喂给curl外传）这样的内置规则，负责在密钥"进入网络前"把它揪出来——high 级别告警。规则评估用的是未脱敏内容（docs/rules.md），所以"读.env→ 外传"这类链条即使值已被 URL 签名混淆也能命中。

5. 新手实践清单：拿到 numbat 后先做这 5 件事 ✅

1. 保持默认输出策略：只用默认 findings/预览模式，除非确有需要才开--content full；
2. 把输出当敏感数据管：~/.numbat/records.ndjson、序列状态库、case bundle 都要按敏感端点数据设访问控制；
3. 分享前看redacted字段 + 人工过一遍：redacted:false不代表记录不含敏感上下文；
4. 需要交接取证时用case build默认模式（仅引用+摘要），确需证据正文时选--include-redacted-evidence并复审；
5. 启用 enforce 前先读docs/enforcement.md：拦截是 opt-in、只作用于支持同步预行动 hook 的enforce: true规则，宿主 Agent 才是最终执行点。

6. 写在最后

numbat 的设计哲学可以用一句话概括：它解析的东西越敏感，出口就越要严格——默认丢弃全文、只出 200 字符预览、四道脱敏防线、逐条输出路径的金丝雀测试、外加一份毫不含糊的威胁模型。对普通用户而言，理解"脱敏能遮什么、遮不住什么"比记住任何命令都重要：redact 是你的安全网，不是免检通行证。

📚 延伸阅读：docs/cli.md（完整 CLI 与记录契约）· docs/event-model.md（事件模型）· SECURITY.md（安全策略）· README.md（快速上手）