Skip to content

feat(safety): add static tool script safety guard - #278

Open
xwzmonster wants to merge 1 commit into
trpc-group:mainfrom
xwzmonster:feat/tool-script-safety-guard
Open

feat(safety): add static tool script safety guard#278
xwzmonster wants to merge 1 commit into
trpc-group:mainfrom
xwzmonster:feat/tool-script-safety-guard

Conversation

@xwzmonster

Copy link
Copy Markdown

功能概述

本 PR 针对 Issue #90,实现了一套静态 Tool Script Safety Guard,主要包括:

  • 基于 Python AST 的脚本安全扫描
  • Bash/Shell 和结构化 argv 安全扫描
  • 严格、带版本的 YAML 安全策略
  • allowdenyneeds_human_review 三态决策
  • Tool Filter 执行前拦截
  • CodeExecutor 执行前安全包装器
  • Callable、Workspace 和 MCP 接入适配器
  • 统一脱敏、JSONL 审计和可选 OpenTelemetry
  • CLI、12 个公开样例和中英文文档
  • 独立评估语料和性能测试

安全决策

  • 决策优先级:deny > needs_human_review > allow
  • 第一版中,needs_human_review 默认阻断执行
  • Scanner 内部失败采用 fail-closed
  • denyneeds_human_review 路径下,被保护的 Tool 或 Executor 调用次数为 0
  • Audit、Monitor 和 Telemetry 失败不会改变已经完成的安全决策
  • 原始脚本、环境变量、完整 argv 和执行输出不会写入 Audit 或 OpenTelemetry

该功能属于静态执行前检查机制,并不替代 Sandbox。CPU、内存、进程、文件系统、网络和权限隔离仍由底层 Executor 或 Sandbox 负责。

测试与验收结果

  • tests/safety:165 项测试全部通过
  • 12 个公开样例:12/12 匹配
  • 独立评估语料:
    • 危险样本:56/56 正确识别、分类并阻断
    • 安全样本:0/24 误报
    • 诊断样本:4/4 符合预期
  • 三个必检类别:
    • 密钥或凭据读取:10/10
    • 危险删除:16/16
    • 非白名单网络外连:16/16
  • 500 行 Python 扫描:最大 94.888 ms
  • 500 行 Shell 扫描:最大 18.299 ms
  • Filter、Telemetry、MCP 相关回归:372 项通过
  • Tool、Executor、Workspace、Skill 范围回归:140 项通过
  • YAPF、flake8 和 git diff --check 均通过

尚未验证的内容

  • 当前虚拟环境没有安装 MkDocs,因此未运行 mkdocs build --strict
  • 一个已有 Skills 测试使用了 Python 3.11 才支持的 ZipFile.mkdir,在当前 Python 3.10.12 环境中失败
  • 未运行包含真实本地 Shell、Docker 和 Cube 执行路径的完整测试套件

已知边界

当前 Scanner 不是完整的 Python 解释器或 Bash Parser。复杂动态反射、运行时生成代码、复杂 Shell expansion、MCP Server 内部执行、MCP discovery/stdio 启动以及 Workspace start_program 不在完整覆盖范围内。

Related to #90

@github-actions

github-actions Bot commented Jul 31, 2026

Copy link
Copy Markdown

CLA Assistant Lite bot All contributors have signed the CLA ✍️ ✅

@xwzmonster

Copy link
Copy Markdown
Author

I have read the CLA Document and I hereby sign the CLA

Rook1ex added a commit to trpc-group/cla-database that referenced this pull request Jul 31, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant