安全体系

CountBot 当前的安全能力主要围绕远程访问认证、Shell 命令防护、工作空间边界和工具审计展开。本文只描述当前仓库里已经落地的机制。

设计原则

本地直接访问尽量低摩擦，远程访问默认进入受控模式。
高风险能力默认收紧，需要显式放开。
文件与命令执行优先受工作空间边界约束。
工具调用尽量可追踪、可审计。

认证边界

HTTP 与 WebSocket 的远程访问保护由认证模块负责：

中间件：backend/modules/auth/middleware.py
认证路由：backend/modules/auth/router.py
应用挂载：backend/app.py

当前行为重点：

直接本机回环访问可绕过远程认证拦截
远程访问 /api/ 时需要已登录会话
首次初始化管理员密码默认只能在本机完成
如开启远程初始化，会使用临时 setup secret 做一次性放行

Shell 命令防护

Shell 工具实现位于 backend/modules/tools/shell.py。

当前保护手段包括：

危险命令模式拦截
自定义拒绝模式 custom_deny_patterns
可选命令白名单 custom_allow_patterns
工作空间范围限制
超时与输出长度限制

应用启动时会把安全配置传入工具注册流程，入口见：

backend/app.py
backend/modules/tools/setup.py

工作空间隔离

文件系统相关工具通过 backend/modules/tools/filesystem.py 中的校验逻辑约束访问范围。

如果开启 restrict_to_workspace：

读写文件会优先限制在工作空间内
路径穿越类风险会被拦截
Shell 工具也会尽量继承相同边界

这项配置默认值在 backend/modules/config/schema.py 中定义。

审计日志

文件与工具调用的审计能力主要体现在：

backend/modules/tools/file_audit_logger.py
backend/modules/tools/registry.py
backend/api/tools.py

当前可以记录和查看：

文件相关操作日志
按会话聚合的审计信息
最近调用记录与统计信息

如果你需要定位“谁改了文件”或“哪个会话触发了危险操作”，审计日志是第一入口。

当前安全配置

backend/modules/config/schema.py 中的 SecurityConfig 目前包含以下关键项：

dangerous_commands_blocked
custom_deny_patterns
command_whitelist_enabled
custom_allow_patterns
audit_log_enabled
command_timeout
subagent_timeout
max_output_length
restrict_to_workspace

这些字段会直接影响运行时工具行为，而不是停留在文档层面的“建议配置”。

和旧版文档的区别

当前实现里，最值得注意的变化有两点：

安全体系的重点已经从“静态说明”转向“中间件 + 工具注册 + 审计链路”的实际控制。
不应再沿用旧稿中那些仓库里已经不存在的开关或流程描述。

建议排查顺序

当你怀疑是安全配置导致工具不可用时，建议按这个顺序排查：

确认是否命中了远程认证
确认 Shell 是否被危险命令规则拦截
确认是否开启了工作空间限制
查看审计日志和后端日志

文件	说明
`backend/modules/auth/middleware.py`	远程访问认证中间件
`backend/modules/auth/router.py`	登录、初始化、改密等接口
`backend/modules/tools/shell.py`	命令防护与执行限制
`backend/modules/tools/filesystem.py`	工作空间路径边界校验
`backend/modules/tools/file_audit_logger.py`	审计日志记录
`backend/modules/config/schema.py`	安全配置模型

设计原则​

认证边界​

Shell 命令防护​

工作空间隔离​

审计日志​

当前安全配置​

和旧版文档的区别​

建议排查顺序​

相关文件​