Feat/tool safety

[impself]

关联 Issue

Closes #90

问题背景

tRPC-Agent 的 Tool、MCP Tool、Skill 和 CodeExecutor 可以执行脚本、调用系统命令、读写文件及访问网络。这些能力是 Agent 自动化任务的重要基础，但也可能被恶意或不可信输入利用，例如：

• 递归删除文件、覆盖系统目录
• 读取 .env、SSH 私钥或其他凭据文件
• 向非白名单域名发送请求并外传敏感信息
• 通过 subprocess、os.system、shell 管道或命令注入绕过限制
• 使用 pip、npm、apt 等修改运行环境
• 执行无限循环、fork bomb、长时间 sleep 或大量并发任务
• 将 API Key、Token、Password 或私钥写入日志、文件或网络请求

沙箱负责运行时隔离，但无法独立覆盖执行前策略判断、人工复核、审计记录和可观测性需求。本 PR 新增 Tool Script Safety Guard，在脚本或命令进入真实执行器前进行静态风险扫描和策略决策。

方案摘要

安全扫描

在 trpc_agent_sdk/tools/safety/ 新增安全检查模块，支持：

• Python 脚本扫描
• Bash 命令扫描
• 命令行参数、工作目录、环境变量和 Tool 元数据检查
• allow、deny、needs_human_review 三态决策

覆盖以下风险类型：

• 危险文件操作及敏感文件读取
• 非白名单网络访问
• 进程执行、提权命令、shell 管道和命令注入
• pip install、npm install、apt install 等依赖安装
• 无限循环、长时间 sleep、fork bomb、异常并发和超大文件写入
• API Key、Token、Password 和私钥泄漏

策略配置

提供 tool_safety_policy.yaml 示例，支持配置：

• 网络白名单域名
• 允许和禁止命令
• 禁止访问路径
• 最大执行超时
• 最大输出大小
• 最大脚本大小
• 最大进程数和并发任务数
• 最大 sleep 时间和文件写入大小
• 审计开关、路径及失败关闭行为

修改策略文件即可调整安全边界，无需修改扫描代码。

执行前接入

提供以下接入方式：

• ToolScriptSafetyFilter
• SafetyWrappedCallable
• SafetyCheckedExecutor

wrapper 会在委托真实执行器前完成扫描和审计：

• deny 始终阻止执行
• needs_human_review 根据策略暂停执行或等待人工批准
• 审计为必需时，审计写入失败会执行失败关闭
• CodeExecutor 返回结果会受到最大输出大小限制

结构化报告与审计

每次扫描输出完整的 SafetyReport，包含：

• decision
• risk_level
• rule_ids
• findings[].category
• findings[].rule_id
• findings[].evidence
• findings[].recommendation
• recommendation
• scan_duration_ms
• redacted

审计日志采用 JSONL 格式，每次扫描写入一条事件，包含：

• tool_name
• tool_kind
• decision
• risk_level
• rule_ids
• duration_ms
• redacted
• execution_blocked
• policy_hash
• script_sha256
• timestamp

审计事件不会保存原始脚本、环境变量值、未脱敏参数或原始敏感信息。

示例与文档

在 trpc_agent_sdk/tools/safety/examples/ 提供：

• 示例策略文件
• 14 个公开 Python/Bash 样本
• 单次扫描完整报告
• JSONL 审计日志
• 14 个样本的批量扫描结果

manifest_run.json 中每个样本均保存完整结构化报告，而非仅保存决策摘要。

同时新增：

• 英文设计说明：docs/mkdocs/en/tool_safety_guard.md
• 中文设计说明：docs/mkdocs/zh/tool_safety_guard.zh_CN.md
• 命令行入口：scripts/tool_safety_check.py

测试结果

运行完整测试：

python -m pytest tests/tool_safety -q `
  --basetemp .pytest-tmp `
  -p no:cacheprovider

公开样本验收结果：

• 样本总数：14
• 预期决策匹配：14/14
• allow：4
• deny：8
• needs_human_review：2
• 高危样本检出率：100%
• 安全样本误报率：0%
• 密钥读取检出率：100%
• 危险删除检出率：100%
• 非白名单网络访问检出率：100%
• 审计事件数量：14
• 10 个危险或人工复核报告全部包含规则、证据和处理建议
• 500 行 Python 和 Bash 扫描性能测试通过，p95 小于 1 秒
• Filter 和 wrapper 测试确认高危输入不会进入真实执行器
• 审计事件在委托真实执行器前写入

批量样本验证：

python scripts/tool_safety_check.py `
  --policy trpc_agent_sdk/tools/safety/examples/tool_safety_policy.yaml `
  --manifest trpc_agent_sdk/tools/safety/examples/samples/manifest.yaml `
  --manifest-output trpc_agent_sdk/tools/safety/examples/manifest_run.json `
  --audit-file .pytest-tmp/tool_safety_audit.jsonl

manifest 中包含 deny 和 needs_human_review，因此 CLI 返回非零退出码属于预期安全决策；验收结果以 matches_expected 为准。

风险和限制

• Safety Guard 是执行前静态安全门禁，不能替代容器或沙箱隔离。
• 静态扫描无法完整识别代码混淆、动态拼接、反射、原生扩展、运行时下载载荷、符号链接竞争及依赖运行时状态的行为。
• CPU、内存、PID、文件系统和网络硬限制仍应由沙箱、容器、操作系统权限和运行时超时机制负责。
• 规则匹配仍可能产生误报或漏报；无法确定的执行模式会进入 needs_human_review。
• 策略文件会直接影响安全边界，应限制修改权限并纳入配置审计。
• 当前主要通过 wrapper 强制执行安全决策。接入新的 Tool、Skill、MCP Tool 或 CodeExecutor 时，需要确保真实执行只能经过安全 wrapper。
• tool_kind 无法根据脚本内容可靠推断。CLI 样本未声明来源时使用 unknown；真实接入应明确设置为 tool、mcp、skill 或 code_executor。
• OpenTelemetry 埋点当前使用 trpc_agent_sdk.tools.safety.* 前缀，后续可以统一为与 Python 包路径无关的稳定属性名。

Release Notes

新增 Tool Script Safety Guard：

• 支持执行前扫描 Python 脚本和 Bash 命令
• 支持 allow、deny 和 needs_human_review 三态安全决策
• 新增可配置 YAML 安全策略
• 新增结构化扫描报告和 JSONL 审计事件
• 新增 OpenTelemetry span attributes 和指标接入能力
• 新增 callable 与 CodeExecutor 安全 wrapper
• 新增 CLI、14 个公开样本及完整批量扫描报告
• 新增中英文设计文档和完整测试覆盖

该功能提供执行前风险识别、拦截和审计能力。生产环境仍需配合沙箱隔离、最小权限、网络出口控制及运行时资源限制。

[codecov]

Codecov Report

❌ Patch coverage is 80.13245% with 540 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@e113610). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
trpc_agent_sdk/tools/safety/_python_scanner.py	75.16667%	149 Missing ⚠️
trpc_agent_sdk/tools/safety/_bash_scanner.py	73.96313%	113 Missing ⚠️
trpc_agent_sdk/tools/safety/_rules.py	80.32258%	61 Missing ⚠️
trpc_agent_sdk/tools/safety/_filter.py	67.04545%	58 Missing ⚠️
trpc_agent_sdk/tools/safety/wrapper.py	78.68020%	42 Missing ⚠️
trpc_agent_sdk/tools/safety/_policy.py	85.20000%	37 Missing ⚠️
trpc_agent_sdk/tools/safety/_tool_adapter.py	72.28916%	23 Missing ⚠️
trpc_agent_sdk/tools/safety/_telemetry.py	78.48101%	17 Missing ⚠️
trpc_agent_sdk/tools/safety/_guard.py	90.98361%	11 Missing ⚠️
...rpc_agent_sdk/tools/safety/_cross_field_scanner.py	89.36170%	10 Missing ⚠️
... and 4 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main        #188   +/-   ##
==========================================
  Coverage        ?   87.11262%           
==========================================
  Files           ?         483           
  Lines           ?       46821           
  Branches        ?           0           
==========================================
  Hits            ?       40787           
  Misses          ?        6034           
  Partials        ?           0           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

CLA Assistant Lite bot:
Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment same as the below format.

---

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

---

_{You can retrigger this bot by commenting recheck in this Pull Request}