安全测试¶

📎 引用文件

本文引用的文件 - agent/src/security/scanner.py - agent/src/security/network.py - agent/src/security/workspace_access.py - agent/src/api/security.py - agent/src/tools/path_utils.py - agent/tests/test_backtest_runner_security.py - agent/tests/test_file_tool_sandbox_security.py - agent/tests/test_security_scanner.py - agent/tests/test_security_auth_api.py - agent/tests/test_special_token_neutralization.py - agent/tests/test_sse_ticket_and_headers.py

简介¶

本文件面向 Vibe-Trading 的安全测试，覆盖以下关键主题： - 安全漏洞扫描：外部内容注入检测、特殊控制令牌中和、敏感信息泄露提示。 - 权限验证测试：API 鉴权、回环/跨站请求防护、SSE 票据机制。 - 输入验证测试：路径沙箱、运行目录白名单、参数校验。 - 沙箱执行测试：回测执行器代码注入防护、工具沙箱边界。 - 数据泄露防护：日志脱敏、CORS/CSP 策略、网络目标校验。 - 认证授权与会话安全：Bearer 鉴权、单票票据、跨站浏览器请求拒绝。 - 自动化与审计：回归测试、报告生成、合规检查建议。

项目结构¶

围绕安全能力，仓库在 agent 层提供了安全模块与大量安全回归测试： - 安全能力 - 注入扫描与内容中和：scanner.py - 网络目标校验桥接：network.py - 工作区范围异常定义：workspace_access.py - API 鉴权、CORS/CSP、DNS 重绑定防护、SSE 票据：api/security.py - 文件路径沙箱与白名单：tools/path_utils.py - 安全测试 - 回测执行器安全：test_backtest_runner_security.py - 文件工具沙箱安全：test_file_tool_sandbox_security.py - 注入扫描与内容过滤：test_security_scanner.py、test_special_token_neutralization.py - 认证授权与 SSE：test_security_auth_api.py、test_sse_ticket_and_headers.py

graph TB subgraph "安全能力" A["注入扫描 scanner.py"] B["网络目标校验 network.py"] C["工作区范围异常 workspace_access.py"] D["API 鉴权/安全头/SSE api/security.py"] E["路径沙箱/白名单 tools/path_utils.py"] end subgraph "安全测试" T1["回测执行器安全 test_backtest_runner_security.py"] T2["文件工具沙箱安全 test_file_tool_sandbox_security.py"] T3["注入扫描测试 test_security_scanner.py"] T4["特殊令牌中和测试 test_special_token_neutralization.py"] T5["认证授权与 SSE 测试 test_security_auth_api.py"] T6["SSE 票据与安全头测试 test_sse_ticket_and_headers.py"] end T1 --> D T2 --> E T3 --> A T4 --> A T5 --> D T6 --> D A --> B A --> E

图示来源 - agent/src/security/scanner.py:1-264 - agent/src/security/network.py:1-11 - agent/src/security/workspace_access.py:1-15 - agent/src/api/security.py:1-670 - agent/src/tools/path_utils.py:1-404

章节来源 - agent/src/security/scanner.py:1-264 - agent/src/security/network.py:1-11 - agent/src/security/workspace_access.py:1-15 - agent/src/api/security.py:1-670 - agent/src/tools/path_utils.py:1-404

核心组件¶

注入扫描与内容中和
对外部文本进行模式匹配，标注“prompt_injection”类型告警，并对聊天模板控制令牌插入零宽空格以破坏角色伪造。
提供字段选择器遍历，对嵌套 JSON 中的多个字符串字段进行扫描与中和。
API 鉴权与安全头
统一鉴权依赖：支持 Bearer Token、本地回环信任、Docker 网关白名单；禁止凭据型 CORS 通配符。
响应头：CSP（区分文档页与应用页）、X-Content-Type-Options、X-Frame-Options、Permissions-Policy、Referrer-Policy。
DNS 重绑定防护：拒绝不可信 Host 的本地请求。
SSE 票据：短生命周期、一次性票据，避免长密钥落入 URL。
访问日志脱敏：对查询串中的敏感键值进行遮蔽。
路径沙箱与白名单
三类路径安全：工具沙箱 safe_path、用户导入路径 safe_user_path/safe_document_path、运行目录 safe_run_dir。
通过环境变量配置允许写入/读取/运行根目录，拒绝 UNC 路径与越界路径。
resolve_safe_path 支持 run_dir 优先解析，失败时回退到允许根集合。

章节来源 - agent/src/security/scanner.py:16-220 - agent/src/api/security.py:69-253 - agent/src/api/security.py:300-622 - agent/src/tools/path_utils.py:46-240

架构总览¶

下图展示了从外部输入到安全边界的处理流程：外部内容经注入扫描与令牌中和后进入下游；API 请求先经过 DNS 重绑定与 CORS/CSP 校验，再进行鉴权；文件操作走路径沙箱与白名单校验。

sequenceDiagram participant U as "调用方" participant API as "API 鉴权与安全头 api/security.py" participant SCAN as "注入扫描/令牌中和 scanner.py" participant FS as "路径沙箱/白名单 path_utils.py" participant APP as "业务逻辑" U->>API : "HTTP 请求(含Host/Origin)" API->>API : "CORS/CSP/DNS重绑定校验" API-->>U : "安全响应头" API->>APP : "鉴权通过后进入路由" APP->>SCAN : "处理外部内容(网页/文档/搜索)" SCAN-->>APP : "带 security_warnings 的结果" APP->>FS : "读写/编辑文件" FS-->>APP : "允许或拒绝(越界/UNC)" APP-->>U : "最终结果"

图示来源 - agent/src/api/security.py:166-253 - agent/src/security/scanner.py:145-220 - agent/src/tools/path_utils.py:185-240

详细组件分析¶

组件A：注入扫描与内容过滤¶

设计要点
规则集：指令覆盖、系统提示泄露、角色冒充、密钥泄露、工具滥用等模式。
特殊令牌中和：识别 ChatML/Llama/Gemma 等控制标记并插入零宽空格，使其无法被分词器识别为角色边界。
字段选择器：支持 results.*.snippet 等路径，批量扫描与原地中和。
测试覆盖
指令覆盖与系统提示泄露检测。
普通金融文本不被误报。
web_reader/web_search/doc_reader 返回体中注入 security_warnings。
特殊令牌中和前后对比，确保原 token 不再可被识别。

flowchart TD Start(["入口"]) --> Scan["扫描外部文本"] Scan --> Match{"命中规则?"} Match -- 否 --> Neutralize["中和特殊令牌"] Match -- 是 --> Warn["记录告警(含field/规则/严重级别)"] --> Neutralize Neutralize --> Return["返回带 security_warnings 的载荷"]

图示来源 - agent/src/security/scanner.py:145-220

章节来源 - agent/src/security/scanner.py:16-220 - agent/tests/test_security_scanner.py:17-108 - agent/tests/test_special_token_neutralization.py:20-38

组件B：API 鉴权、CORS/CSP 与 SSE 票据¶

设计要点
鉴权优先级：已配置 API_KEY 时所有客户端均需 Bearer；未配置时仅信任本地回环（含受信任 Docker 网关）。
跨站浏览器请求拒绝：基于 sec-fetch-site 与 Origin 校验。
CSP：应用页严格限制，文档页放宽至 CDN；支持 Report-Only 开关。
SSE 票据：一次一签、短时有效，避免长密钥出现在 URL。
访问日志脱敏：遮蔽 api_key/ticket 等查询参数值。
测试覆盖
远程写操作在无 Key 时拒绝；本地开发模式允许。
配置 Key 后，本地/远程均需 Bearer。
DNS 重绑定 Host 被拒绝，阻止敏感写操作。
SSE 事件流不接受长密钥查询串，但接受票据。
关闭/开启 CSP Report-Only 的行为差异。

sequenceDiagram participant B as "浏览器" participant S as "API 服务器 api/security.py" participant K as "票据服务(内存)" B->>S : "POST /auth/sse-ticket (Bearer)" S->>K : "签发一次性票据" K-->>S : "ticket" S-->>B : "返回 ticket" B->>S : "GET /sessions/{id}/events?ticket=..." S->>K : "消费并失效票据" K-->>S : "有效/无效" S-->>B : "建立事件流或 401"

图示来源 - agent/src/api/security.py:300-340 - agent/src/api/security.py:591-622

章节来源 - agent/src/api/security.py:69-253 - agent/src/api/security.py:300-622 - agent/tests/test_security_auth_api.py:43-224 - agent/tests/test_security_auth_api.py:414-449 - agent/tests/test_sse_ticket_and_headers.py:161-194

组件C：路径沙箱与文件工具安全¶

设计要点
三类路径校验：safe_path（工具沙箱）、safe_user_path/safe_document_path（导入/文档）、safe_run_dir（运行目录）。
白名单：通过环境变量配置允许的读/写/运行根目录，默认包含 uploads/runs/import 等。
resolve_safe_path：优先按 run_dir 解析，失败则回退到允许根集合；拒绝 UNC 与越界路径。
测试覆盖
未配置 run_dir 时写操作拒绝。
read/write/edit 在允许根内成功，越界拒绝。
读写隔离：只读根不能写，写根可写。
tilde 展开与相对路径正确解析。

flowchart TD In["输入路径 + run_dir"] --> CheckRun{"run_dir 存在?"} CheckRun -- 是 --> TryRun["safe_path(file, run_dir)"] TryRun --> RunOK{"是否越界?"} RunOK -- 否 --> Out["返回绝对路径"] RunOK -- 是 --> Fallback["尝试 allowed_write_roots"] Fallback --> Found{"是否在允许根?"} Found -- 是 --> Out Found -- 否 --> Err["抛出错误(越界/需run_dir)"] CheckRun -- 否 --> Direct["直接校验 allowed_*_roots"] Direct --> Found

图示来源 - agent/src/tools/path_utils.py:185-240 - agent/src/tools/path_utils.py:243-404

章节来源 - agent/src/tools/path_utils.py:46-240 - agent/tests/test_file_tool_sandbox_security.py:21-165

组件D：回测执行器安全性（代码注入防护）¶

设计要点
对生成的策略代码进行 AST 级扫描：拒绝顶层/类级可执行语句、危险函数调用、动态导入、对象图遍历、文件系统写入等。
保留合法数学/量化库导入与只读文件访问。
针对绕过手段（别名、importlib、sys.modules、pickle/marshal、shutil、webbrowser、gc）进行阻断。
测试覆盖
顶层/类级执行、方法体内危险操作、动态模块可达性、Pathlib 写、os 文件系统变更、对象图遍历均被拒绝。
正常策略（pandas/numpy 计算、只读文件、纯辅助函数）可通过。

flowchart TD Load["加载策略模块"] --> Walk["AST 遍历与方法体可达性分析"] Walk --> Detect{"发现危险节点?"} Detect -- 是 --> Reject["拒绝并报错"] Detect -- 否 --> Allow["允许执行"]

图示来源 - agent/tests/test_backtest_runner_security.py:17-725

章节来源 - agent/tests/test_backtest_runner_security.py:17-725

组件E：网络通信安全与 SSRF 防护¶

设计要点
network.py 暴露 validate_url_target / validate_resolved_url，用于通道适配器的目标校验。
API 层设置严格的 CSP/Permissions-Policy，限制资源加载与功能使用。
拒绝跨站浏览器请求，防止 CSRF 与同源策略绕过。
测试覆盖
文档页与应用页 CSP 差异。
Report-Only 模式切换。
跨站请求被拒。

章节来源 - agent/src/security/network.py:1-11 - agent/src/api/security.py:180-253 - agent/tests/test_sse_ticket_and_headers.py:161-194

依赖关系分析¶

低耦合高内聚
scanner.py 不依赖网络与文件系统，专注文本扫描与中和。
path_utils.py 封装路径安全，供各工具复用。
api/security.py 集中鉴权与安全头，作为网关式中间件。
外部依赖
FastAPI/HTTP 框架用于鉴权与中间件。
标准库 re/ipaddress/secrets/time 用于正则、IP 判断、票据生成与过期。
潜在循环依赖
通过延迟导入（如 get_env_config）避免启动期循环。

graph LR API["api/security.py"] --> CFG["config.accessor"] API --> SECHEAD["安全头/鉴权"] PATH["tools/path_utils.py"] --> CFG SCAN["security/scanner.py"] --> NONE["无外部依赖"]

图示来源 - agent/src/api/security.py:1-670 - agent/src/tools/path_utils.py:1-404 - agent/src/security/scanner.py:1-264

章节来源 - agent/src/api/security.py:1-670 - agent/src/tools/path_utils.py:1-404 - agent/src/security/scanner.py:1-264

性能与安全特性¶

注入扫描
正则匹配与零宽空格插入均为 O(n)，对大文本影响有限；字段选择器按需遍历，避免全量扫描。
鉴权与票据
票据内存存储+单调时钟过期，清理与消费加锁，避免竞争；HMAC 比较常量时间。
路径校验
基于 pathlib.resolve 与 is_relative_to，开销小且准确；默认根集合固定，查找线性。
安全头
每次响应设置必要头部，开销极低；Report-Only 便于灰度。

[本节为通用指导，无需特定文件引用]

故障排查指南¶

常见问题
401/403：检查是否配置 API_AUTH_KEY；本地/远程来源是否符合预期；Host/Origin 是否可信。
路径越界：确认 run_dir 或 allowed_*_roots 配置；检查 UNC 路径与 ~ 展开。
注入告警：查看 security_warnings 的 rule_id 与 field，定位外部内容来源。
SSE 连接失败：确认已通过 /auth/sse-ticket 获取票据；票据是否已过期或被重复使用。
修复验证
使用对应测试用例复现并验证修复：例如 test_security_auth_api.py 中的 DNS 重绑定与 SSE 票据用例；test_file_tool_sandbox_security.py 的路径越界用例；test_security_scanner.py 的注入扫描用例。

章节来源 - agent/tests/test_security_auth_api.py:237-340 - agent/tests/test_file_tool_sandbox_security.py:46-165 - agent/tests/test_security_scanner.py:17-108

结论¶

Vibe-Trading 在安全方面形成了“扫描—鉴权—沙箱—审计”的闭环： - 外部内容注入通过模式扫描与令牌中和降低风险。 - API 层通过严格鉴权、CORS/CSP、DNS 重绑定防护与 SSE 票据保障通信安全。 - 文件与运行目录通过白名单与路径沙箱限制执行面。 - 回测执行器采用 AST 级静态分析与可达性检查，阻断代码注入。 - 丰富的回归测试覆盖常见攻击面，便于持续集成与快速修复。

[本节为总结性内容，无需特定文件引用]

附录：合规与自动化¶

安全测试自动化
将安全相关测试纳入 CI：pytest 运行全部安全用例，失败即阻断合并。
新增规则/路径白名单时，同步补充对应测试用例。
安全审计报告
利用 with_security_warnings 输出结构化告警，便于审计与溯源。
结合访问日志脱敏，避免密钥泄漏。
合规性检查建议
强制启用 CSP 严格模式（非 Report-Only），仅在灰度阶段临时开启。
生产环境必须配置 API_AUTH_KEY，禁用无 Key 的远程访问。
定期审查 allowed_*_roots 与环境变量，最小化权限面。

[本节为通用指导，无需特定文件引用]

← 单元测试性能测试 →