安全沙箱与 SSRF 防护

安全沙箱与 SSRF 防护

学习目标

理解 Nanobot 的多层安全防护：工作区限制、SSRF 防护、重复违规升级与 Python 3.14 安全加固。

前置知识

• 安全沙箱设计 — 多层防御架构
• 护栏协议 — 安全边界处理

下文假设你已理解上述概念，直接聚焦 Nanobot 的具体实现。

项目实践

工作区限制

通过 restrict_to_workspace 配置和 WorkspaceScopeResolver 实现文件系统的访问控制：

workspace_scopes = WorkspaceScopeResolver(
    default_workspace=workspace,
    default_restrict_to_workspace=restrict_to_workspace,
)

违规检测通过字符串匹配识别：

_WORKSPACE_VIOLATION_MARKERS = (
    "outside the configured workspace",
    "outside allowed directory",
    "working_dir is outside",
    "working_dir could not be resolved",
    "path outside working dir",
    "path traversal detected",
)

SSRF 防护

AgentRunner 在工具边界检测 SSRF 违规：

_SSRF_MARKERS = (
    "internal/private url detected",
    "private/internal address",
    "private address",
)

SSRF 违规的处理方式：

1. 硬拦截：不可重试
2. 告知 LLM：这是不可逾越的安全边界，禁止尝试绕过
3. 不返回真实错误：避免信息泄露

重复违规升级

对于重复的工作区违规，Nanobot 会升级提示强度：

escalation = repeated_workspace_violation_error(
    tool_call.name, tool_call.arguments, workspace_violation_counts,
)

从简单的错误提示逐步升级为更强烈的指令，防止 LLM 持续试探边界。

安全入口点防护

nanobot/security/ 目录包含：

• PTH 文件防护：防止 Python PTH 文件注入
• CLI 入口安全校验：所有 CLI 命令经过安全检查

Python 3.14 与 Windows 兼容

Nanobot 的 CI 覆盖 Python 3.14 和 Windows 平台，确保：

• Windows 路径安全（防止 C:\ 目录遍历）
• Python 3.14 兼容性测试

设计取舍

为什么在工具边界做 SSRF 检查

原因：SSRF 防护是工具边界的安全护栏，而非应用层功能。在 _run_tool() 中检查确保了所有通过工具发起的网络请求都经过防护，而不是在个别工具中各自实现。

参考来源

• Nanobot Runner 安全源码
• Nanobot Security 目录
• 安全沙箱设计
• 护栏协议