人工智能AI Agent大模型自主智能体工具调用RAGAgent 记忆MCP Clients【免费下载链接】nullclawFastest, smallest, and fully autonomous AI assistant infrastructure written in Zig项目地址https://gitcode.com/gh_mirrors/nu/nullclaw点击查看免费下载本篇技术指南以 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的修复范围Telegram Webhook 伪造与 Webhook 认证缺失——当网关暴露在公网或通过隧道tunnel转发时伪造的 Telegram Webhook 更新可以直接驱动 Agent 及其工具通过curl进程 argv 泄露密钥——本地用户、进程监控工具或容器宿主机可以从进程参数列表中读取 API Key、Bearer Token、机器人 Token、代理凭据与 Webhook URLCron Shell 作业绕过 Shell 工具安全控制——任何能创建或更新 Cron 作业的人都可以在正常的 Shell 工具策略、沙箱、环境清洗environment scrub、超时与输出限制之外获得持久化的 Shell 执行能力入站通道空白名单——空的allow_from会形成“开放机器人”行为与仓库“默认拒绝”的安全姿态冲突。受影响区域被明确限定为src/gateway.zigsrc/http_util.zigsrc/providers/**src/channels/telegram_api.zigsrc/channels/discord.zigsrc/channels/line.zigsrc/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 Telegrams 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的默认值是nullallow_from默认是空切片.{}——这正是“默认拒绝”语义的体现。Webhook 路由处理器handleTelegramWebhookRoutesrc/gateway.zig的执行顺序清晰地展示了“先认证、后解析”的原则构建选项未启用 Telegram 通道 → 返回 404非 POST 方法 → 返回 405按网关 Webhook 限流器检查allowScopedWebhook→ 超限返回 429从配置选择器selectTelegramConfig获取bot_token、allow_from、webhook_secret调用telegramWebhookSecretMatches校验 Secret Token不匹配直接返回 401 Unauthorized此时尚未解析消息体通过后才解析消息、执行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_secretnull或配置为空字符串时校验一律返回false。这意味着升级后未配置 Secret 的/telegram路由默认拒绝所有请求——这是补丁计划的“默认拒绝”策略在认证层的体现。extractHeadersrc/gateway.zig对头部名称大小写不敏感有对应单元测试test extractHeader case insensitive能正确处理 Telegram 服务器发送的请求头。2.4 发送者白名单语义变更配合第一项修复telegramSenderAllowedsrc/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 的isAllowedisAllowedScoped上。该函数的匹配语义非常明确src/channels/root.zig#L461-L476列表中出现*时视为显式“允许所有”warnWildcardAllowAll会发出警告日志否则按忽略大小写逐条比较发送者标识列表为空时matched保持false天然返回拒绝。仓库中还配套了针对性的单元测试src/channels/root.zigtest 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.Client3.1 风险场景进程 argv/proc/pid/cmdline或ps输出对同机所有用户可见。nullclaw 此前大量使用curl子进程完成带凭据的 HTTP 请求——API Key、Bearer Token、机器人 Token、代理凭据甚至包含 Token 的 URL例如https://api.telegram.org/bottoken/sendMessage都可能出现在子进程 argv 中被本地用户、进程监控器或容器宿主读取。3.2 修复方案补丁计划给出的修复路径是审计共享 HTTP 助手及所有携带凭据的调用方将带凭据的curl执行路径替换为std.http.ClientZig 标准库原生 HTTP 客户端凭据仅存在于进程内存与套接字中确保 Provider 请求不会把Authorization、API Key 或 Bearer Token 放入子进程 argv停止向子进程 URL 传递 Telegram Bot Token即不再构造bottoken形式的 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 headersOpenAI 与 Gemini 请求路径不会通过子进程 argv 传递 Bearer TokenTelegram API 调用不会通过子进程 argv 传递 Bot Token敏感值不会出现在命令构造错误信息或日志中。计划还特别指出一个务实原则如果某条路径的 argv 暴露无法直接做单元测试应在代码附近添加简短注释说明覆盖范围的局限以及预期由集成测试覆盖的内容——避免为了“形式上可测”而引入脆弱测试。四、Cron Shell 作业安全强制回归 ShellTool 与 SecurityPolicy4.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.SecurityPolicysrc/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 修复方案三种明确语义补丁计划将入站通道的白名单语义统一为三条规则空allow_from→ 拒绝所有发送者显式*→ 允许所有发送者精确配置的发送者 ID → 仅允许匹配的发送者。这一语义需要应用到Telegram 网关处理、Discord 与 LINE三个通道对应 src/gateway.zig、src/channels/discord.zig、src/channels/line.zig。5.3 源码层面的落地证据在 src/channels/root.zig 的isAllowedScoped中空列表返回false、*触发显式放行前面已经分析过。在网关侧TelegramtelegramSenderAllowed首行if (allow_from.len 0) return false;LINElineSenderAllowedsrc/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 中已经可见在相关配置 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 } } }测试与示例中使用中性占位符如test-secret、user_a避免把真实密钥写进仓库正常配置加载过程中不得静默生成密钥——密钥必须由部署者显式提供更新暗示“空白名单安全或宽松”的文档与示例所有示例都要展示显式的发送者白名单明确声明“允许所有”必须使用显式*。从 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 -DoptimizeReleaseSmallzig build test --summary all运行全量单元测试并输出完整摘要覆盖本文所述各安全模块的针对性测试zig build -DoptimizeReleaseSmall以 ReleaseSmall 优化级别构建发布二进制nullclaw 强调体积与资源占用小体积发布构建是它的标准产物形态。计划还要求安全敏感改动在跑全量测试之前应先对修改过的模块编写并运行针对性测试以便快速定位回归。7.2 环境版本注意2026-05-10 记录计划特别标注了一条环境事实当时系统上的zig实测为0.14.1而本仓库固定使用0.16.0。因此全量验证必须使用 Zig0.16.0执行否则可能因工具链差异得到错误结论。这也是zig-installation相关文档存在的意义——部署/开发环境应当锁定与仓库一致的 Zig 版本。八、交接清单Handoff Checklist在将改动交接给 reviewer 或发起 PR 之前补丁计划要求交付以下六项内容这一清单同样适用于任何后续安全补丁What changed——本次改了什么按四类修复逐项说明What did not change——明确哪些未改动防止补丁范围蔓延Threat notes for each fixed class——每个修复类别的威胁说明攻击路径、影响面Validation commands and results——验证命令与实际结果zig build test --summary all、zig build -DoptimizeReleaseSmallRemaining risks or unknowns——剩余风险与未知项如无法直接单测的 argv 暴露路径需以注释形式记录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大模型自主智能体工具调用RAGAgent 记忆MCP Clients【免费下载链接】nullclawFastest, smallest, and fully autonomous AI assistant infrastructure written in Zig项目地址https://gitcode.com/gh_mirrors/nu/nullclaw点击查看免费下载相关推荐NullClaw 安全加固实战从默认安全基线到沙箱、脱敏与密钥审计NullClaw 安全加固实战从默认安全基线到沙箱、脱敏与密钥审计 NullClaw用 Zig 编写、默认以 127.0.0.1 本地绑定运行的全自主 AI人工智能AI Agent大模型自主智能体工具调用RAGAgent 记忆MCP ClientsAgent 沙箱多智能体语音Apereo CAS 拒绝认证Deny Authentication用 cas.authn.reject 拦截黑名单账号的实战指南Apereo CAS 拒绝认证Deny Authentication用 cas.authn.reject 拦截黑名单账号的实战指南 导读 拒绝认证De后端认证鉴权单点登录impeccable 的质量底线 craft-floor把界面验证清单与默认拒绝写进 AI 构建流程impeccable 的质量底线 craft floor把界面验证清单与默认拒绝写进 AI 构建流程 impeccable 是一套把 AI 从能写出AI 技能前端CLIdsh-plugin上一篇cartographer社区问答精选解决常见技术难题下一篇AMD-Quark量化工具实战手把手教你将MiniMax-M2.5转换为NVFP4格式创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
nullclaw 安全补丁计划（2026-05-10）实战解读：Telegram Webhook 认证、进程 argv 泄密、Cron 逃逸与空白名单默认拒绝
人工智能AI Agent大模型自主智能体工具调用RAGAgent 记忆MCP Clients【免费下载链接】nullclawFastest, smallest, and fully autonomous AI assistant infrastructure written in Zig项目地址https://gitcode.com/gh_mirrors/nu/nullclaw点击查看免费下载本篇技术指南以 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的修复范围Telegram Webhook 伪造与 Webhook 认证缺失——当网关暴露在公网或通过隧道tunnel转发时伪造的 Telegram Webhook 更新可以直接驱动 Agent 及其工具通过curl进程 argv 泄露密钥——本地用户、进程监控工具或容器宿主机可以从进程参数列表中读取 API Key、Bearer Token、机器人 Token、代理凭据与 Webhook URLCron Shell 作业绕过 Shell 工具安全控制——任何能创建或更新 Cron 作业的人都可以在正常的 Shell 工具策略、沙箱、环境清洗environment scrub、超时与输出限制之外获得持久化的 Shell 执行能力入站通道空白名单——空的allow_from会形成“开放机器人”行为与仓库“默认拒绝”的安全姿态冲突。受影响区域被明确限定为src/gateway.zigsrc/http_util.zigsrc/providers/**src/channels/telegram_api.zigsrc/channels/discord.zigsrc/channels/line.zigsrc/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 Telegrams 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的默认值是nullallow_from默认是空切片.{}——这正是“默认拒绝”语义的体现。Webhook 路由处理器handleTelegramWebhookRoutesrc/gateway.zig的执行顺序清晰地展示了“先认证、后解析”的原则构建选项未启用 Telegram 通道 → 返回 404非 POST 方法 → 返回 405按网关 Webhook 限流器检查allowScopedWebhook→ 超限返回 429从配置选择器selectTelegramConfig获取bot_token、allow_from、webhook_secret调用telegramWebhookSecretMatches校验 Secret Token不匹配直接返回 401 Unauthorized此时尚未解析消息体通过后才解析消息、执行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_secretnull或配置为空字符串时校验一律返回false。这意味着升级后未配置 Secret 的/telegram路由默认拒绝所有请求——这是补丁计划的“默认拒绝”策略在认证层的体现。extractHeadersrc/gateway.zig对头部名称大小写不敏感有对应单元测试test extractHeader case insensitive能正确处理 Telegram 服务器发送的请求头。2.4 发送者白名单语义变更配合第一项修复telegramSenderAllowedsrc/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 的isAllowedisAllowedScoped上。该函数的匹配语义非常明确src/channels/root.zig#L461-L476列表中出现*时视为显式“允许所有”warnWildcardAllowAll会发出警告日志否则按忽略大小写逐条比较发送者标识列表为空时matched保持false天然返回拒绝。仓库中还配套了针对性的单元测试src/channels/root.zigtest 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.Client3.1 风险场景进程 argv/proc/pid/cmdline或ps输出对同机所有用户可见。nullclaw 此前大量使用curl子进程完成带凭据的 HTTP 请求——API Key、Bearer Token、机器人 Token、代理凭据甚至包含 Token 的 URL例如https://api.telegram.org/bottoken/sendMessage都可能出现在子进程 argv 中被本地用户、进程监控器或容器宿主读取。3.2 修复方案补丁计划给出的修复路径是审计共享 HTTP 助手及所有携带凭据的调用方将带凭据的curl执行路径替换为std.http.ClientZig 标准库原生 HTTP 客户端凭据仅存在于进程内存与套接字中确保 Provider 请求不会把Authorization、API Key 或 Bearer Token 放入子进程 argv停止向子进程 URL 传递 Telegram Bot Token即不再构造bottoken形式的 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 headersOpenAI 与 Gemini 请求路径不会通过子进程 argv 传递 Bearer TokenTelegram API 调用不会通过子进程 argv 传递 Bot Token敏感值不会出现在命令构造错误信息或日志中。计划还特别指出一个务实原则如果某条路径的 argv 暴露无法直接做单元测试应在代码附近添加简短注释说明覆盖范围的局限以及预期由集成测试覆盖的内容——避免为了“形式上可测”而引入脆弱测试。四、Cron Shell 作业安全强制回归 ShellTool 与 SecurityPolicy4.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.SecurityPolicysrc/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 修复方案三种明确语义补丁计划将入站通道的白名单语义统一为三条规则空allow_from→ 拒绝所有发送者显式*→ 允许所有发送者精确配置的发送者 ID → 仅允许匹配的发送者。这一语义需要应用到Telegram 网关处理、Discord 与 LINE三个通道对应 src/gateway.zig、src/channels/discord.zig、src/channels/line.zig。5.3 源码层面的落地证据在 src/channels/root.zig 的isAllowedScoped中空列表返回false、*触发显式放行前面已经分析过。在网关侧TelegramtelegramSenderAllowed首行if (allow_from.len 0) return false;LINElineSenderAllowedsrc/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 中已经可见在相关配置 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 } } }测试与示例中使用中性占位符如test-secret、user_a避免把真实密钥写进仓库正常配置加载过程中不得静默生成密钥——密钥必须由部署者显式提供更新暗示“空白名单安全或宽松”的文档与示例所有示例都要展示显式的发送者白名单明确声明“允许所有”必须使用显式*。从 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 -DoptimizeReleaseSmallzig build test --summary all运行全量单元测试并输出完整摘要覆盖本文所述各安全模块的针对性测试zig build -DoptimizeReleaseSmall以 ReleaseSmall 优化级别构建发布二进制nullclaw 强调体积与资源占用小体积发布构建是它的标准产物形态。计划还要求安全敏感改动在跑全量测试之前应先对修改过的模块编写并运行针对性测试以便快速定位回归。7.2 环境版本注意2026-05-10 记录计划特别标注了一条环境事实当时系统上的zig实测为0.14.1而本仓库固定使用0.16.0。因此全量验证必须使用 Zig0.16.0执行否则可能因工具链差异得到错误结论。这也是zig-installation相关文档存在的意义——部署/开发环境应当锁定与仓库一致的 Zig 版本。八、交接清单Handoff Checklist在将改动交接给 reviewer 或发起 PR 之前补丁计划要求交付以下六项内容这一清单同样适用于任何后续安全补丁What changed——本次改了什么按四类修复逐项说明What did not change——明确哪些未改动防止补丁范围蔓延Threat notes for each fixed class——每个修复类别的威胁说明攻击路径、影响面Validation commands and results——验证命令与实际结果zig build test --summary all、zig build -DoptimizeReleaseSmallRemaining risks or unknowns——剩余风险与未知项如无法直接单测的 argv 暴露路径需以注释形式记录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大模型自主智能体工具调用RAGAgent 记忆MCP Clients【免费下载链接】nullclawFastest, smallest, and fully autonomous AI assistant infrastructure written in Zig项目地址https://gitcode.com/gh_mirrors/nu/nullclaw点击查看免费下载相关推荐NullClaw 安全加固实战从默认安全基线到沙箱、脱敏与密钥审计NullClaw 安全加固实战从默认安全基线到沙箱、脱敏与密钥审计 NullClaw用 Zig 编写、默认以 127.0.0.1 本地绑定运行的全自主 AI人工智能AI Agent大模型自主智能体工具调用RAGAgent 记忆MCP ClientsAgent 沙箱多智能体语音Apereo CAS 拒绝认证Deny Authentication用 cas.authn.reject 拦截黑名单账号的实战指南Apereo CAS 拒绝认证Deny Authentication用 cas.authn.reject 拦截黑名单账号的实战指南 导读 拒绝认证De后端认证鉴权单点登录impeccable 的质量底线 craft-floor把界面验证清单与默认拒绝写进 AI 构建流程impeccable 的质量底线 craft floor把界面验证清单与默认拒绝写进 AI 构建流程 impeccable 是一套把 AI 从能写出AI 技能前端CLIdsh-plugin上一篇cartographer社区问答精选解决常见技术难题下一篇AMD-Quark量化工具实战手把手教你将MiniMax-M2.5转换为NVFP4格式创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
