nullclaw 安全补丁计划（2026-05-10）实战解读：Telegram Webhook 认证、进程 argv 泄密、Cron 逃逸与空白名单默认拒绝

• 人工智能
• AI Agent
• 大模型
• 自主智能体
• 工具调用
• RAG
• Agent 记忆
• MCP Clients

本篇技术指南以 nullclaw 仓库中的 SECURITY-PATCH-PLAN-2026-05-10.md 为骨架，逐一剖析该计划覆盖的四类安全缺陷：Telegram Webhook 伪造与认证缺失、curl子进程 argv 中的密钥暴露、Cron Shell 作业绕过 Shell 工具安全控制、入站通道空allow_from造成的开放机器人行为。文中不仅完整保留了原计划的整改范围、实施步骤与验证命令，还结合当前仓库源码（src/gateway.zig、src/http_util.zig、src/cron.zig、src/channels/root.zig、src/config_types.zig、config.example.json等）展开底层实现讲解。读完本文，你将理解这套“默认拒绝（deny-by-default）”安全加固的具体落地方式、每个修复点对应的测试验证手段，以及如何在本地用 Zig 0.16.0 完成全量验证。

一、补丁范围与原则：小而专注的安全修复

该安全补丁计划发布于 2026-05-10，明确划定四类安全发现（Security Findings）的修复范围：

1. Telegram Webhook 伪造与 Webhook 认证缺失——当网关暴露在公网或通过隧道（tunnel）转发时，伪造的 Telegram Webhook 更新可以直接驱动 Agent 及其工具；
2. 通过curl进程 argv 泄露密钥——本地用户、进程监控工具或容器宿主机可以从进程参数列表中读取 API Key、Bearer Token、机器人 Token、代理凭据与 Webhook URL；
3. Cron Shell 作业绕过 Shell 工具安全控制——任何能创建或更新 Cron 作业的人，都可以在正常的 Shell 工具策略、沙箱、环境清洗（environment scrub）、超时与输出限制之外获得持久化的 Shell 执行能力；
4. 入站通道空白名单——空的allow_from会形成“开放机器人”行为，与仓库“默认拒绝”的安全姿态冲突。

受影响区域被明确限定为：

• src/gateway.zig
• src/http_util.zig
• src/providers/**
• src/channels/telegram_api.zig
• src/channels/discord.zig
• src/channels/line.zig
• src/cron.zig
• 以及配置示例、文档与测试

计划明确要求：将补丁严格限制在这些安全修复之内，不要与无关的重构、功能开发或 Zig 工具链变更混在一起。这一原则保证了安全修复的可审计性——每个 commit 都只解决一个安全问题，便于 code review 与回归定位。

二、Telegram Webhook 认证：用 Secret Token 堵住伪造入口

2.1 风险场景

nullclaw 的网关（gateway）暴露/telegram路由接收 Telegram Bot API 的 Webhook 推送（见 src/gateway.zig 中webhook_route_descriptors的/telegram路由注册，handler 为handleTelegramWebhookRoute）。当网关部署在公网或经隧道转发时，任何人只要知道这个 URL，就可以向它 POST 伪造的 Telegram Update 对象。由于伪造的“消息”看起来来自合法会话，Agent 会被驱动执行工具调用，形成未授权远程操控。

2.2 修复方案：兼容 Telegram 官方的 Secret Token 头

Telegram Bot API 本身支持通过setWebhook的secret_token参数下发一个秘密令牌，之后 Telegram 服务器在每次 Webhook 推送时都会携带X-Telegram-Bot-Api-Secret-Token请求头。补丁计划的修复思路正是复用这一机制：

• 在配置中新增 Telegram Webhook Secret 字段，与X-Telegram-Bot-Api-Secret-Token头对齐；
• 在解析或分发请求体之前，要求/telegramWebhook POST 必须携带该 Secret Token 头；
• 对缺失或不匹配的 Webhook Secret 返回明确的未授权响应；
• 将telegramSenderAllowed改为：空的allow_from默认拒绝；
• 仅允许显式的"*"作为“允许所有发送者”的唯一配置方式；
• Webhook 失败信息在日志与响应中保持非敏感（不泄露内部细节）。

2.3 源码层面的落地证据

在当前仓库源码中，该方案已经落地。配置类型 src/config_types.zig 中TelegramConfig定义了：

pub const TelegramConfig = struct { account_id: []const u8 = "default", bot_token: []const u8, /// Secret required in Telegram's X-Telegram-Bot-Api-Secret-Token header for webhook delivery. webhook_secret: ?[]const u8 = null, allow_from: []const []const u8 = &.{}, group_allow_from: []const []const u8 = &.{}, ... };

注意webhook_secret的默认值是null，allow_from默认是空切片&.{}——这正是“默认拒绝”语义的体现。

Webhook 路由处理器handleTelegramWebhookRoute（src/gateway.zig）的执行顺序清晰地展示了“先认证、后解析”的原则：

1. 构建选项未启用 Telegram 通道 → 返回 404；
2. 非 POST 方法 → 返回 405；
3. 按网关 Webhook 限流器检查（allowScopedWebhook）→ 超限返回 429；
4. 从配置选择器selectTelegramConfig获取bot_token、allow_from、webhook_secret；
5. 调用telegramWebhookSecretMatches校验 Secret Token，不匹配直接返回 401 Unauthorized（此时尚未解析消息体）；
6. 通过后才解析消息、执行telegramSenderAllowed发送者白名单校验。

其中核心校验函数（src/gateway.zig）实现如下：

fn telegramWebhookSecretMatches(raw_request: []const u8, configured_secret: ?[]const u8) bool { const secret = configured_secret orelse return false; if (secret.len == 0) return false; const header = extractHeader(raw_request, "X-Telegram-Bot-Api-Secret-Token") orelse return false; const trimmed = std.mem.trim(u8, header, " \t\r\n"); return constantTimeEq(trimmed, secret); }

该实现有两个值得注意的安全细节：

• 常量时间比较：constantTimeEq直接复用自 src/security/pairing.zig（在 src/gateway.zig 处导入），避免基于时序差异的侧信道攻击；
• 缺失即拒绝：未配置webhook_secret（null）或配置为空字符串时，校验一律返回false。这意味着升级后未配置 Secret 的/telegram路由默认拒绝所有请求——这是补丁计划的“默认拒绝”策略在认证层的体现。

extractHeader（src/gateway.zig）对头部名称大小写不敏感（有对应单元测试test "extractHeader case insensitive"），能正确处理 Telegram 服务器发送的请求头。

2.4 发送者白名单语义变更

配合第一项修复，telegramSenderAllowed（src/gateway.zig）被改为空列表直接拒绝：

fn telegramSenderAllowed(allocator: std.mem.Allocator, allow_from: []const []const u8, body: []const u8) bool { if (allow_from.len == 0) return false; ... }

白名单匹配最终落在 src/channels/root.zig 的isAllowed（isAllowedScoped）上。该函数的匹配语义非常明确（src/channels/root.zig#L461-L476）：

• 列表中出现"*"时视为显式“允许所有”（warnWildcardAllowAll会发出警告日志）；
• 否则按忽略大小写逐条比较发送者标识；
• 列表为空时matched保持false，天然返回拒绝。

仓库中还配套了针对性的单元测试（src/channels/root.zig）：

test "isAllowed wildcard" { ... } // ["*"] 允许 anyone test "isAllowed specific" { ... } // 精确匹配 Alice/bob，拒绝 eve test "isAllowed empty denies all" { ... } // 空列表拒绝 anyone test "isAllowed empty sender" { ... } // 空发送者被拒绝

这正是补丁计划测试清单中“Empty Telegramallow_fromdenies”与“Explicit"*"allows all senders”两条用例在共享工具层的直接对应。

2.5 针对 Telegram 的测试要求

补丁计划要求为本项修复补充的测试包括：

• 缺失 Telegram Secret-Token 头 → 拒绝；
• Secret-Token 头不正确 → 拒绝；
• Secret-Token 头正确 → 接受；
• 空 Telegramallow_from→ 拒绝所有发送者；
• 显式"*"→ 允许所有发送者；
• 伪造的 sender 或 chat ID 无法绕过 Webhook Secret 校验（即认证与授权是两套独立检查，先过 Secret 再过白名单）。

三、清除子进程参数中的密钥：从 curl 迁移到 std.http.Client

3.1 风险场景

进程 argv（/proc//cmdline或ps输出）对同机所有用户可见。nullclaw 此前大量使用curl子进程完成带凭据的 HTTP 请求——API Key、Bearer Token、机器人 Token、代理凭据甚至包含 Token 的 URL（例如https://api.telegram.org/bot/sendMessage）都可能出现在子进程 argv 中，被本地用户、进程监控器或容器宿主读取。

3.2 修复方案

补丁计划给出的修复路径是：

• 审计共享 HTTP 助手及所有携带凭据的调用方；
• 将带凭据的curl执行路径替换为std.http.Client（Zig 标准库原生 HTTP 客户端，凭据仅存在于进程内存与套接字中）；
• 确保 Provider 请求不会把Authorization、API Key 或 Bearer Token 放入子进程 argv；
• 停止向子进程 URL 传递 Telegram Bot Token（即不再构造bot形式的 URL）；
• 若仍保留不携带密钥的 curl 助手，必须在 spawn 前拒绝任何携带凭据的请求头与敏感 URL；
• 保持出站 URL 校验的“安全默认”行为，包括目前要求的 HTTPS-only 约束。

3.3 源码层面的当前状态

src/http_util.zig 的文件头注释明确记录了这条迁移路线的意图：

Keeps legacy curl helpers for non-secret requests, but routes credentialed ...

也就是说，仓库已经进入“过渡态”：非敏感请求仍可走遗留 curl 助手，带凭据请求必须走内存内 HTTP 客户端路径。可以从源码结构推断：curlPost、curlGet、curlPut、curlPostForm等遗留助手（src/http_util.zig 中大量argv_buf[argc] = "curl"的构造点）应只服务于无凭据场景，任何传入Authorization之类凭据头的调用路径都会被视为待清理对象。

同样地，src/gateway.zig 中构造 Telegram 回复时使用的：

const url = try std.fmt.allocPrint(allocator, "https://api.telegram.org/bot{s}/sendMessage", .{bot_token});

这类“Token 内嵌 URL”的调用路径正是计划中“Stop passing Telegram bot tokens in URLs to child processes”所要消灭的模式。

3.4 测试要求

本项修复的测试清单包括：

• 任何保留下来的子进程 HTTP 助手都会拒绝凭据头（credential headers）；
• OpenAI 与 Gemini 请求路径不会通过子进程 argv 传递 Bearer Token；
• Telegram API 调用不会通过子进程 argv 传递 Bot Token；
• 敏感值不会出现在命令构造错误信息或日志中。

计划还特别指出一个务实原则：如果某条路径的 argv 暴露无法直接做单元测试，应在代码附近添加简短注释，说明覆盖范围的局限以及预期由集成测试覆盖的内容——避免为了“形式上可测”而引入脆弱测试。

四、Cron Shell 作业安全强制：回归 ShellTool 与 SecurityPolicy

4.1 风险场景

Cron 调度器（src/cron.zig）支持shell类型的作业。如果这类作业绕过了常规 Shell 工具调用所经过的ShellTool与SecurityPolicy，那么任何能够创建或更新 Cron 作业的人，都能在策略之外获得持久的 Shell 执行能力——这等同于权限提升。

4.2 修复方案

• 将 Cron Shell 执行路由到与普通 Shell 工具调用相同的ShellTool与SecurityPolicy路径；
• 在作业创建或更新时校验 Shell 命令；
• 在执行时重新校验命令，确保升级前已存储的不安全作业无法在升级后绕过策略；
• 保留现有 Agent 作业（agent类型）行为，除非它依赖不安全的 Shell 执行；
• 如果完整集成ShellTool对第一版补丁过于侵入，退而求其次：在独立审计的管理 Shell 模式出现之前，将 Cron REST 端点限制为仅接受 Agent 作业；
• 对 Cron Shell 执行施加与 Shell 工具相同的超时、输出上限、沙箱行为与环境清洗。

4.3 源码层面的落地证据

src/cron.zig 的当前实现已经体现了这套双校验（写入时校验 + 执行时重校验）架构：

• CronScheduler携带shell_policy: security_policy.SecurityPolicy（src/cron.zig#L485），并可通过setShellPolicy注入策略（src/cron.zig#L510-L512）；
• 写入校验：作业创建/更新时调用validateShellCommand，内部执行self.shell_policy.validateCommandExecution(command, false)（src/cron.zig#L520）；
• 执行校验：tick 调度到.shell作业时，再次检查命令是否违反策略（src/cron.zig#L918-L926），一旦被拦截，last_output会记录"cron shell command blocked by security policy"并调用deliverResult通知结果投递方；
• 执行参数上配置了shell_cwd、shell_timeout_ns（默认DEFAULT_CRON_SHELL_TIMEOUT_NS）与shell_max_output_bytes（默认DEFAULT_CRON_SHELL_MAX_OUTPUT_BYTES）等与 Shell 工具对齐的约束字段（src/cron.zig#L481-L498）。

仓库中的测试直接对应计划的测试清单：

test "cron shell add rejects command blocked by security policy" // 创建时拒绝 test "cron shell update rejects command blocked by security policy" // 更新时拒绝 test "cron shell tick blocks previously stored command when policy changes" // 执行时拒绝历史不安全作业

第三个测试尤其重要：它验证了“策略变更后，已存储的旧作业在下次 tick 时同样被拦截”的升级安全语义——这正是计划中“Revalidate commands at execution time so previously stored unsafe jobs cannot bypass policy after upgrade”的落地。

4.4 测试要求汇总

• 创建时拒绝不允许的 Cron Shell 命令；
• 更新时拒绝不允许的 Cron Shell 命令；
• 已存储的不允许命令无法执行；
• 超时与输出上限对 Cron Shell 执行生效；
• Cron Shell 作业不继承环境密钥（环境清洗生效）；
• Agent Cron 作业继续正常工作（不回归）。

五、拒绝空入站白名单：统一“默认拒绝”语义

5.1 风险场景

allow_from为空时，如果被解释为“未配置即放行”，机器人就会处于开放状态——任何发送者都能与 Agent 交互。这与仓库整体的 deny-by-default 安全姿态直接冲突。

5.2 修复方案：三种明确语义

补丁计划将入站通道的白名单语义统一为三条规则：

1. 空allow_from→ 拒绝所有发送者；
2. 显式"*"→ 允许所有发送者；
3. 精确配置的发送者 ID → 仅允许匹配的发送者。

这一语义需要应用到Telegram 网关处理、Discord 与 LINE三个通道（对应 src/gateway.zig、src/channels/discord.zig、src/channels/line.zig）。

5.3 源码层面的落地证据

在 src/channels/root.zig 的isAllowedScoped中，空列表返回false、"*"触发显式放行，前面已经分析过。在网关侧：

• Telegram：telegramSenderAllowed首行if (allow_from.len == 0) return false;；
• LINE：lineSenderAllowed（src/gateway.zig）直接复用channels.isAllowed(allow_from, user_id)，同样继承“空即拒绝”语义：

  fn lineSenderAllowed(allow_from: []const []const u8, evt: channels.line.LineEvent) bool { const user_id = evt.user_id orelse return false; return channels.isAllowed(allow_from, user_id); }

• LINE Webhook 路由中，line_allow_from从ctx.state或匹配到的账号配置加载后（src/gateway.zig#L4313-L4358），由if (!lineSenderAllowed(line_allow_from, evt)) continue;完成过滤（src/gateway.zig#L4358）。

Discord 通道的白名单逻辑位于 src/channels/discord.zig，同样依赖channels.isAllowed的共享语义。可以推断，补丁测试清单中针对三个通道的 9 条用例（空列表拒绝 /"*"放行 / 精确匹配放行与不匹配拒绝）正是对这三条归一化语义的逐一验证。

5.4 测试要求

• Discord：空allow_from拒绝；显式"*"放行所有；匹配发送者放行、不匹配拒绝；
• LINE：同上三组用例；
• Telegram 网关：同上三组用例。

六、配置与文档同步更新

补丁计划对配置与文档提出了明确要求，这些改动在 config.example.json 中已经可见：

1. 在相关配置 schema 与示例中新增 Telegram Webhook Secret 字段。config.example.json的 Telegram 账号示例：

"telegram": { "accounts": { "main": { "bot_token": "YOUR_TELEGRAM_BOT_TOKEN", "webhook_secret": "replace-with-random-telegram-webhook-secret", "allow_from": ["YOUR_TELEGRAM_USER_ID"], "draft_previews": false } } }

1. 测试与示例中使用中性占位符，如"test-secret"、"user_a"，避免把真实密钥写进仓库；
2. 正常配置加载过程中不得静默生成密钥——密钥必须由部署者显式提供；
3. 更新暗示“空白名单安全或宽松”的文档与示例，所有示例都要展示显式的发送者白名单；
4. 明确声明“允许所有”必须使用显式"*"。

从 src/config_types.zig 可以看到，webhook_secret的默认值是null，即未配置时绝不自动生成或猜测——与“Avoid generating secrets silently during normal config loading”的要求一致。

七、验证流程与 Zig 版本注意事项

7.1 必须执行的验证命令

代码变更后，完整验证包含两条命令：

zig build test --summary all zig build -Doptimize=ReleaseSmall

• zig build test --summary all：运行全量单元测试并输出完整摘要，覆盖本文所述各安全模块的针对性测试；
• zig build -Doptimize=ReleaseSmall：以 ReleaseSmall 优化级别构建发布二进制（nullclaw 强调体积与资源占用，小体积发布构建是它的标准产物形态）。

计划还要求：安全敏感改动在跑全量测试之前，应先对修改过的模块编写并运行针对性测试，以便快速定位回归。

7.2 环境版本注意（2026-05-10 记录）

计划特别标注了一条环境事实：当时系统上的zig实测为0.14.1，而本仓库固定使用0.16.0。因此全量验证必须使用 Zig0.16.0执行，否则可能因工具链差异得到错误结论。这也是zig-installation相关文档存在的意义——部署/开发环境应当锁定与仓库一致的 Zig 版本。

八、交接清单（Handoff Checklist）

在将改动交接给 reviewer 或发起 PR 之前，补丁计划要求交付以下六项内容，这一清单同样适用于任何后续安全补丁：

1. What changed——本次改了什么（按四类修复逐项说明）；
2. What did not change——明确哪些未改动（防止补丁范围蔓延）；
3. Threat notes for each fixed class——每个修复类别的威胁说明（攻击路径、影响面）；
4. Validation commands and results——验证命令与实际结果（zig build test --summary all、zig build -Doptimize=ReleaseSmall）；
5. Remaining risks or unknowns——剩余风险与未知项（如无法直接单测的 argv 暴露路径，需以注释形式记录）；
6. Next recommended action——下一步建议动作。

九、总结：一套可复用的“默认拒绝”安全加固范式

回看这四类修复，可以提炼出 nullclaw 安全加固的统一方法论：

• 认证先行：Webhook 请求先校验 Secret Token（常量时间比较），认证失败即 401，不进入任何解析与分发逻辑；
• 凭据不入子进程：凡携带凭据的 HTTP 请求一律走进程内存内的std.http.Client，让密钥只存在于内存与套接字，而非对全机可见的 argv；
• 策略双校验：Cron Shell 命令在写入时与执行时各校验一次，堵住“升级后旧作业逃逸”的漏洞窗口，并复用 Shell 工具的超时、输出上限、沙箱与环境清洗；
• 空即拒绝：allow_from空列表 = 拒绝，只有显式"*"才表示放行，并以单元测试固化该语义；
• 补丁纪律：安全补丁不与无关改动混编，测试先于全量验证，交接必须附带威胁说明与剩余风险。

对于部署 nullclaw 网关的用户，本文对应的即时行动包括：为 Telegram 账号配置强随机webhook_secret并在 Bot API 侧设置一致的secret_token、用显式发送者 ID 或"*"填充allow_from、将 Cron 作业限定为 Agent 类型（或确认已走SecurityPolicy校验路径）、使用 Zig 0.16.0 运行全量验证。相关实现与测试均可继续在 src/gateway.zig、src/cron.zig、src/channels/root.zig、src/http_util.zig 与 config.example.json 中深入研读。

• 人工智能
• AI Agent
• 大模型
• 自主智能体
• 工具调用
• RAG
• Agent 记忆
• MCP Clients