企业官网建设流程全解析

DeepBot安全机制深度剖析：路径白名单如何守住AI Agent的系统安全底线

【免费下载链接】deepbotDeepBot is a system-level AI assistant built for both personal productivity and enterprise workflows — one-click setup, seamless experience, and native Feishu integration.项目地址: https://gitcode.com/gh_mirrors/de/deepbot

DeepBot 是一款系统级 AI 助手，支持一键配置、飞书原生集成与个人/企业工作流自动化。但 AI Agent 拥有读写文件、执行命令的真实系统权限，如何防止它"越界"访问敏感数据？DeepBot 用一套路径白名单机制，从文件系统、命令执行、敏感文件三个层面守住系统安全底线。🔐

为什么 AI Agent 需要安全边界？

AI Agent 的强大之处在于"手"：它能读取文件、修改代码、运行 shell 命令。但这也意味着一个提示词攻击（Prompt Injection）就可能诱使它去读取你的 API Key、删除重要文件。

DeepBot 的设计哲学很清晰：不信任模型的"自觉"，只信任代码层面的硬拦截。安全逻辑不写在提示词里（避免被模型"说服"），而是作为工具调用前的必经关卡，强制执行。

这套机制的核心入口是路径安全工具模块：path-security.ts，其中的isPathAllowed函数是所有文件访问的总闸门。

第一道防线：路径白名单 —— 只允许"点名"的目录

白名单机制的核心思想：默认拒绝，例外放行。系统预先枚举所有允许访问的目录，任何不在名单内的路径直接拒绝。

白名单包含哪些目录？

通过 getAllowedDirectories 可以看到，允许的目录包括：

• 工作目录：用户在设置中配置的workspaceDirs（主战场）
• 数据目录：Electron 模式下的~/.deepbot，Docker 模式下的/data/db
• 功能目录：脚本目录、Skill 目录、图片生成目录、记忆目录、会话目录
• 系统临时目录：跨平台兼容的/tmp、/var/tmp、WindowsTEMP等

匹配时还做了两个关键细节，防止经典绕过手法：

1. 路径规范化：先展开~，再path.resolve+path.normalize，消除../../相对路径穿越
2. 分隔符结尾匹配：目录名强制以路径分隔符结尾再比较，避免/data/workspace被误匹配到/data/workspace-other这类"前缀陷阱"

敏感文件黑名单：白名单目录内的"禁区"

即使路径落在允许目录内，这些文件也一律禁止访问（SENSITIVE_FILE_PATTERNS）：

这是典型的"双保险"设计：白名单管"门"，黑名单管"房间"。

第二道防线：工具调用前的统一拦截钩子

真正精彩的部分在 agent-initializer.ts 的createBeforeToolCall钩子。每次工具调用执行前，都会经过这道关卡，分 Tab 动态构建当前会话的允许目录列表。

文件工具：read / write / edit 逐一检查

• read、write、edit工具调用时，args.path必须落在允许目录内，否则返回{ block: true }并附完整原因说明（路径检查逻辑）
• 文件工具本身的包装层 file-tool.ts 也保留了安全包装位，形成双层防御

写入内容检查：堵住"脚本间接读取"的口子

一个容易被忽略的绕过手法：让 Agent 写一个脚本，在脚本里读取敏感数据库。DeepBot 对write/edit的内容做扫描——只要内容中出现system-config.db等敏感文件名，直接拦截（内容安全检查）。

bash 命令：提取路径参数逐个校验

命令执行是风险最高的入口。DeepBot 的做法是"外科手术式"解析（命令路径检查）：

1. 敏感文件名全命令扫描：不管路径怎么拼接，命令中出现敏感数据库文件名就拦截
2. 引号内容剥离：先移除引号内的字符串，避免误伤数据内容
3. 文件操作命令提取：用正则提取cp/mv/rm/cat/ls/find/grep/python等命令的路径参数，逐个规范化后比对白名单
4. 重定向检查：>和>>的写入目标同样必须落在白名单内
5. 系统路径豁免：/dev/null、/proc/、/sys/等系统路径有专门白名单，不影响正常使用

Docker 模式：更严格的强制边界

在 Docker 容器中运行时，白名单直接收紧为/data/和/tmp/前缀（Docker 限制），把爆炸半径限制在容器数据卷内。

第三道防线：危险命令黑名单与交互命令拦截

路径白名单管"能碰哪里"，命令黑名单管"能做啥"。

exec-tool.ts 内置了跨平台危险命令黑名单，覆盖：

• 毁灭性删除：rm -rf /、rm -rf ~、Windowsdel /f /s /q系列
• 磁盘覆盖：mkfs、dd if=/dev/zero、format c:
• 系统关机重启：shutdown、reboot、halt等
• Fork 炸弹与注册表破坏类命令

判定逻辑在 isDangerousCommand，命令执行前先过这一关。

另外，exec-blocking-check.ts 会拦截vim、ssh、裸python/nodeREPL 等交互式命令——Agent 无法应答交互输入，卡住比出错更糟。这类命令会被拦截并给出替代方案提示。

第四道防线：智能客服 Tab 的安全沙箱

对接真实业务的场景需要更严格的约束。智能客服（smart-kf）Tab 拥有独立的沙箱策略（沙箱实现）：

• 禁止 write / edit：客服会话中 Agent 不可写文件
• Bash 命令白名单：只允许ls、grep、python等约 30 个只读/计算类命令
• 禁止子 shell 语法：$()和反引号会被直接拦截，防止用命令替换绕过白名单

这体现了"最小权限"原则：不同业务场景，授予不同量级的权限。

普通用户如何配置安全边界？

安全机制的配置入口就在设置面板中：

1. 打开系统设置 → 工作区配置，指定你的工作目录——这是 AI 可以操作的主区域
2. 其余功能目录（脚本、Skill、图片、记忆、会话）由 DeepBot 默认管理，无需手动干预
3. 相关配置项定义在 workspace-config.ts 中，设置界面组件见 WorkspaceConfig.tsx

当访问被拦截时，Agent 会收到一条清晰的错误信息（错误提示模板），列出所有允许目录和调整建议——对模型友好，也方便你排查问题。

外部调用同样受保护：gateway-adapter.ts 在处理文件类请求时同样执行isPathAllowed校验，API 入口与本地入口共用同一套闸门。更多接入细节可参考 docs/external-api.md。

小结：一套"纵深防御"的完整闭环

DeepBot 的安全机制可以概括为四层纵深防御：

核心源码地图：安全工具 src/main/utils/path-security.ts、拦截钩子 src/main/agent-runtime/agent-initializer.ts、执行工具 src/main/tools/exec-tool.ts。

对新手而言，记住一句话即可：DeepBot 的 AI 能力再强，也跑不出你划定的目录圈。🛡️

【免费下载链接】deepbotDeepBot is a system-level AI assistant built for both personal productivity and enterprise workflows — one-click setup, seamless experience, and native Feishu integration.项目地址: https://gitcode.com/gh_mirrors/de/deepbot