Skip to content

Commit 479df6b

Browse files
impselfimpself
committed
docs: add Chinese tool safety guide
1 parent b45ef14 commit 479df6b

3 files changed

Lines changed: 365 additions & 3 deletions

File tree

‎docs/tool_safety_guard.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Tool Script Safety Guard
22

3+
[中文版本](tool_safety_guard.zh_CN.md)
4+
35
Pre-execution static safety scanner for Python and Bash scripts invoked by
46
Tools, Skills, MCP tools, and CodeExecutors. Produces a structured
57
``allow`` / ``deny`` / ``needs_human_review`` decision, a redacted report,
@@ -394,7 +396,7 @@ tool/
394396
wrapper.py # SafetyWrappedCallable, SafetyCheckedExecutor
395397
scripts/
396398
tool_safety_check.py # CLI
397-
tests/tool_safety/ # 115 tests
399+
tests/tool_safety/ # safety guard tests
398400
examples/tool_safety/
399401
tool_safety_policy.yaml # sample policy
400402
samples/ # 14 public samples + manifest
@@ -403,4 +405,5 @@ examples/tool_safety/
403405
manifest_run.json # manifest execution summary
404406
docs/
405407
tool_safety_guard.md # this document
408+
tool_safety_guard.zh_CN.md # Chinese version
406409
```

‎docs/tool_safety_guard.zh_CN.md‎

Lines changed: 358 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,358 @@
1+
# Tool Script Safety Guard 设计说明（中文）
2+
3+
[English version](tool_safety_guard.md)
4+
5+
面向 Tool、Skill、MCP Tool 与 CodeExecutor 所执行 Python/Bash 脚本的
6+
执行前静态安全检查器。它输出结构化的 ``allow``、``deny`` 或
7+
``needs_human_review`` 决策、脱敏报告、JSONL 审计事件及 OpenTelemetry
8+
属性；**但它不能替代沙箱隔离。**
9+
10+
## 机制概览
11+
12+
Guard 是一个在代码真正执行前运行的、由策略驱动的静态安全门禁。它扫描
13+
脚本、命令行参数、工作目录、环境变量和 tool 元数据，并按规则目录给出
14+
三态决策。决策及其证据会以脱敏的 ``SafetyReport``、审计事件和 OTel
15+
span 属性/指标输出。
16+
17+
```text
18+
+----------------+ +-------------+ +------------------+
19+
| Tool / Skill / | ---> | Guard | ---> | allow: 执行 |
20+
| CodeExecutor | | (静态扫描) | | deny: 拦截 |
21+
| 输入 | | | | review: 暂停复核 |
22+
+----------------+ +------+------+ +------------------+
23+
|
24+
v
25+
+-----------+-----------+
26+
| Audit | Telemetry | OTel |
27+
+-----------------------+
28+
```
29+
30+
静态检查只是纵深防御中的一层。它补充而不是取代容器/沙箱隔离、网络出口
31+
策略、操作系统权限和运行时资源限制。
32+
33+
## 不解决的问题
34+
35+
* **不是沙箱。** 静态分析无法预测已放行代码在运行时的全部行为。生产环境
36+
仍需使用非特权容器、只读挂载、出口白名单、cgroup/ulimit 及超时限制。
37+
* **不是完美检测器。** 混淆、运行时拼接、反射、原生扩展、下载载荷、符号
38+
链接竞争和依赖运行时状态的行为都可能绕过静态扫描。对不确定构造应返回
39+
``needs_human_review``，而非静默放行。
40+
* **策略文件不是秘密库。** 策略文件是决策来源，应受到保护。能修改
41+
``rule_overrides`` 或允许命令的人也能降低安全门槛。
42+
43+
## 职责边界
44+
45+
| 层 | 职责 |
46+
|---|---|
47+
| **SafetyWrappedCallable / SafetyCheckedExecutor** | 当前可用的强制接入路径：扫描、等待审计写入，仅在允许后委托执行 |
48+
| **ToolScriptSafetyFilter** | 为 wrapper 和未来 SDK 终端钩子归一化并记录决策 |
49+
| **Wrapper / Sandbox / Runtime** | 运行时隔离：CPU、内存、PID、文件系统和网络硬限制 |
50+
| **Audit / Telemetry** | 决策证据；当 ``audit.required`` 为真时，审计持久化属于 wrapper 的失败关闭门禁 |
51+
52+
## 快速开始
53+
54+
```bash
55+
python scripts/tool_safety_check.py \
56+
--policy examples/tool_safety/tool_safety_policy.yaml \
57+
--language python \
58+
--script-file examples/tool_safety/samples/03_dangerous_delete.py \
59+
--output tool_safety_report.json \
60+
--audit-file tool_safety_audit.jsonl
61+
echo $? # 0=allow, 2=deny, 3=review, 4=输入/策略/必需审计错误
62+
```
63+
64+
扫描全部 14 个公开样例：
65+
66+
```bash
67+
python scripts/tool_safety_check.py \
68+
--policy examples/tool_safety/tool_safety_policy.yaml \
69+
--manifest examples/tool_safety/samples/manifest.yaml \
70+
--manifest-output examples/tool_safety/manifest_run.json \
71+
--audit-file examples/tool_safety/tool_safety_audit.jsonl
72+
```
73+
74+
## 作为库使用
75+
76+
```python
77+
from tool.safety import (
78+
ToolSafetyGuard,
79+
load_safety_policy,
80+
SafetyScanRequest,
81+
ScriptLanguage,
82+
)
83+
84+
policy = load_safety_policy("examples/tool_safety/tool_safety_policy.yaml")
85+
guard = ToolSafetyGuard(policy)
86+
87+
request = SafetyScanRequest(
88+
tool_name="workspace_exec",
89+
language=ScriptLanguage.BASH,
90+
script="rm -rf /tmp/x",
91+
cwd="/tmp",
92+
env={"PATH": "/usr/bin"},
93+
)
94+
report = guard.scan(request)
95+
print(report.decision, report.rule_ids)
96+
```
97+
98+
### 包装普通 callable
99+
100+
```python
101+
import subprocess
102+
from tool.wrapper import SafetyWrappedCallable
103+
from tool.safety import ToolSafetyGuard, load_safety_policy, ScriptLanguage
104+
105+
guard = ToolSafetyGuard(load_safety_policy("policy.yaml"))
106+
safe_run = SafetyWrappedCallable(
107+
guard, subprocess.run,
108+
tool_name="subprocess.run",
109+
language=ScriptLanguage.BASH,
110+
script_pos=0,
111+
)
112+
safe_run("ls -la") # 策略拒绝时抛出 BlockedExecutionError
113+
```
114+
115+
若 delegate 或调用方已在事件循环内，应使用
116+
``await safe_run.call_async(...)``。它会在委托执行前等待必需的审计 I/O
117+
完成。对于 tool 风格 callable，请将 ``argv_kw``、``cwd_kw``、``env_kw``、
118+
``metadata_kw`` 和 ``output_bytes_kw`` 映射到实际参数名，以便规范化请求
119+
包含全部可用执行字段。
120+
121+
### 包装 CodeExecutor
122+
123+
```python
124+
from tool.wrapper import SafetyCheckedExecutor
125+
from tool.safety import ToolSafetyGuard, load_safety_policy, ScriptLanguage
126+
127+
guard = ToolSafetyGuard(load_safety_policy("policy.yaml"))
128+
safe_executor = SafetyCheckedExecutor(
129+
guard,
130+
delegate=real_executor,
131+
language=ScriptLanguage.PYTHON,
132+
effective_timeout_seconds=30,
133+
)
134+
await safe_executor.execute_code(code_input)
135+
```
136+
137+
每个 ``CodeBlock.language`` 会独立决定扫描器；当 ``code_blocks`` 为空时，
138+
wrapper 会继续扫描 ``CodeExecutionInput.code``。拒绝和按策略阻断的人工
139+
复核不会到达 delegate；返回的文本输出会被限制在 ``max_output_bytes`` 内。
140+
141+
## 规则目录
142+
143+
规则 ID 是稳定接口，便于策略覆盖与审计聚合。
144+
145+
| Rule ID | 类别 | 默认决策 | 检测内容 |
146+
|---|---|---|---|
147+
| `FILE001_RECURSIVE_DELETE` | file | deny | `shutil.rmtree`、`rm -rf` |
148+
| `FILE002_DENIED_WRITE` | file | deny | 向禁止路径写入 |
149+
| `FILE003_CREDENTIAL_READ` | file | deny | 读取 `.ssh`、`id_rsa`、`.pem`、凭据文件 |
150+
| `FILE004_DOTENV_READ` | file | deny | 读取 `.env` 文件 |
151+
| `NET001_DOMAIN_NOT_ALLOWED` | network | deny | `requests`/curl/wget 访问非白名单主机 |
152+
| `NET002_DYNAMIC_TARGET` | network | review | 运行时计算网络目标 |
153+
| `NET003_IP_LITERAL` | network | deny | 启用 `deny_ip_literals` 时使用 IP 字面量 |
154+
| `PROC001_PROCESS_EXEC` | process | review | 不在允许列表中的子进程或命令 |
155+
| `PROC002_SHELL_INJECTION` | process | deny | 含 shell 语法的 `shell=True` |
156+
| `PROC003_SHELL_OPERATOR` | process | review | `;`、`&&`、`\|`、`&`、命令替换 |
157+
| `PROC004_PRIVILEGE` | process | deny | `sudo`、`su`、`doas` |
158+
| `DEP001_ENV_MUTATION` | dependency | deny | `pip install`、`npm install`、`apt install` |
159+
| `RES001_UNBOUNDED_LOOP` | resource | deny | 无 `break` 的 `while True` |
160+
| `RES002_FORK_BOMB` | resource | deny | 经典 `:(){ :\|:& };:` fork bomb |
161+
| `RES003_LONG_SLEEP` | resource | deny | 超过策略上限的 sleep |
162+
| `RES004_CONCURRENCY` | resource | deny | 超过 `max_parallel_tasks` 或 `max_processes` 的并发 |
163+
| `RES005_LARGE_WRITE` | resource | deny | 超过 `max_file_write_bytes` 的写入 |
164+
| `SECRET001_LOG_SINK` | secret | deny | 污点值流入 print/log |
165+
| `SECRET002_FILE_SINK` | secret | deny | 污点值流入文件写入 |
166+
| `SECRET003_NETWORK_SINK` | secret | deny | 污点值流入网络请求载荷 |
167+
| `PARSE001_UNCERTAIN` | analysis | review | 语法错误或无法可靠分析的构造 |
168+
| `OBF001_DYNAMIC_EXEC` | analysis | review | `eval`、`exec`、间接 Bash 执行、解释器载荷 |
169+
| `SAFE000` | safe | allow | 无规则命中 |
170+
| `GUARD001_INTERNAL_ERROR` | analysis | deny | Guard 内部错误（失败关闭） |
171+
172+
## 策略配置
173+
174+
```yaml
175+
version: "1"
176+
177+
defaults:
178+
unknown_construct: needs_human_review # allow | needs_human_review | deny
179+
guard_error: deny # 默认失败关闭
180+
human_review_blocks_execution: true # review 是否阻断 wrapper
181+
182+
limits:
183+
max_timeout_seconds: 60
184+
max_output_bytes: 1048576
185+
max_script_bytes: 262144
186+
max_sleep_seconds: 30
187+
max_parallel_tasks: 16
188+
max_processes: 8
189+
max_file_write_bytes: 10485760
190+
191+
network:
192+
allow_domains:
193+
- api.github.com
194+
- "*.internal.example.com" # 仅匹配一层子域名
195+
deny_ip_literals: true
196+
197+
commands:
198+
allow: [python, python3, pytest, git]
199+
deny: [sudo, su, doas, chmod, chown, mount]
200+
201+
paths:
202+
deny:
203+
- "~/.ssh"
204+
- "/etc"
205+
- "/root"
206+
- ".env"
207+
- "**/*credentials*"
208+
209+
dependencies:
210+
decision: deny
211+
212+
sensitive_env_key_patterns:
213+
- "*KEY*"
214+
- "*TOKEN*"
215+
- "*PASSWORD*"
216+
- "*SECRET*"
217+
- "*CREDENTIAL*"
218+
219+
tools:
220+
workspace_exec:
221+
execution_capable: true
222+
language: bash
223+
script: command
224+
cwd: cwd
225+
env: env
226+
timeout: timeout_sec
227+
228+
rule_overrides: {}
229+
# 覆盖任一规则决策。例如：
230+
# DEP001_ENV_MUTATION: needs_human_review
231+
232+
audit:
233+
enabled: true
234+
required: true # 审计写入失败时失败关闭
235+
path: tool_safety_audit.jsonl
236+
```
237+
238+
修改 YAML 后无需改代码即可调整域名白名单、命令允许/拒绝列表、禁止路径和
239+
资源阈值。Guard 不会监听文件变化；修改后应新建 ``ToolSafetyGuard``，并重新
240+
注册 wrapper/filter。每份报告和审计事件中的 ``policy_hash`` 可用于关联实际
241+
生效的策略版本。
242+
243+
## 审计与 Telemetry
244+
245+
审计事件至少包含 tool name、decision、risk level、rule ID、扫描耗时、
246+
是否发生脱敏和是否拦截执行。事件不包含原始脚本、环境变量或参数；仅记录
247+
脚本 SHA-256 用于关联。
248+
249+
启用 OpenTelemetry 后，Guard 在当前 span 上写入低基数属性：
250+
251+
```text
252+
tool.safety.decision
253+
tool.safety.risk_level
254+
tool.safety.rule_id # 逗号分隔，最多 8 项
255+
tool.safety.blocked
256+
tool.safety.redacted
257+
tool.safety.scan_duration_ms
258+
tool.safety.policy_hash
259+
```
260+
261+
OTel 不存在时指标会安全地 no-op。可用指标：
262+
263+
```text
264+
trpc_agent.tool_safety.scan_count{decision,risk_level,tool_name}
265+
trpc_agent.tool_safety.block_count{decision,rule_id,tool_name}
266+
trpc_agent.tool_safety.scan_duration_ms{decision,tool_name}
267+
```
268+
269+
证据片段、环境变量、脚本哈希和命令文本均不会作为 span 属性或 metric label
270+
上报。
271+
272+
## CLI 退出码
273+
274+
| 退出码 | 含义 |
275+
|---|---|
276+
| 0 | 最终决策为 ``allow`` |
277+
| 2 | 最终决策为 ``deny`` |
278+
| 3 | 最终决策为 ``needs_human_review`` |
279+
| 4 | 输入、策略或必需审计错误 |
280+
281+
## 与 SDK 的接入关系
282+
283+
当前 SDK 尚未提供位于 ``ToolCallbackFilter`` 之后的终端 Filter 阶段。若把
284+
普通 ``filters=`` 中的检查器作为强制点，后续 callback 仍可能修改参数，造成
285+
TOCTOU 绕过。因此目前必须使用 ``SafetyWrappedCallable`` 或
286+
``SafetyCheckedExecutor``：二者都会先扫描、等待审计事件完成，再调用 delegate。
287+
288+
``ToolScriptSafetyFilter`` 提供了与未来 SDK 终端阶段对应的
289+
``_before``/``_after`` 钩子及 ``terminal_before_handler`` 标记。该标记在 SDK
290+
真正实现“所有可改参 callback 之后”的排序前仅是元数据，不能视为当前的安全
291+
强制点。
292+
293+
## 扩展自定义规则
294+
295+
实现 ``SafetyRule`` 并显式传入规则列表：
296+
297+
```python
298+
from tool.safety import ToolSafetyGuard, SafetyScanRequest
299+
300+
class MyRule:
301+
rule_id = "CUSTOM001_MY_RULE"
302+
303+
def scan(self, request, policy):
304+
# Return an iterable of SafetyFinding.
305+
return []
306+
307+
guard = ToolSafetyGuard(
308+
policy,
309+
rules=[*default_rules(), MyRule()],
310+
)
311+
```
312+
313+
规则必须是纯函数：不得执行文件 I/O、网络访问或创建进程。
314+
315+
## 已知限制与绕过风险
316+
317+
* **混淆。** Base64/十六进制解码等会隐藏意图。Guard 能识别
318+
``eval``、``exec``、``compile`` 和动态导入，但不会尝试静态还原全部载荷。
319+
* **间接数据流。** 污点传播有意保持浅层：字面量、名称、直接赋值、f-string、
320+
拼接和浅层容器。更深的数据流应进入人工复核。
321+
* **符号链接竞争。** 静态路径匹配不能解析符号链接；文件系统边界必须由沙箱
322+
强制执行。
323+
* **原生扩展。** ``ctypes.CDLL(...)``、``cffi.dlopen(...)`` 等原语无法可靠
324+
静态分析。
325+
* **运行时下载。** 分两阶段下载并执行载荷可绕过静态检查；网络出口策略和
326+
沙箱不可省略。
327+
* **运行时资源。** wrapper 会校验声明的 timeout 并限制返回输出，但无法为任意
328+
executor 强制 CPU、内存、PID、文件大小或网络上限。必须在沙箱或
329+
CodeExecutor 运行时同时配置这些限制。
330+
* **Shell 语法缺口。** Bash lexer-lite 是保守实现；不平衡引号或不支持的替换
331+
形式会变成 ``PARSE001_UNCERTAIN``。
332+
333+
当无法确定时，Guard 应输出 ``needs_human_review``，由人工明确批准后再继续。
334+
335+
## 测试
336+
337+
```bash
338+
python -m pytest tests/tool_safety/ -v
339+
```
340+
341+
测试覆盖模型与策略校验、脱敏、Python AST 扫描、Bash lexer-lite、跨字段检查、
342+
审计、Filter/wrapper、CLI、500 行脚本性能预算，以及 14 个样例与预期决策的
343+
集成验证。
344+
345+
## 文件布局
346+
347+
```text
348+
tool/
349+
safety/ # Guard、策略、规则、扫描器、审计和 Telemetry
350+
wrapper.py # SafetyWrappedCallable、SafetyCheckedExecutor
351+
scripts/
352+
tool_safety_check.py # CLI
353+
tests/tool_safety/ # 安全检查器测试
354+
examples/tool_safety/ # 策略、14 个样例、报告和审计样例
355+
docs/
356+
tool_safety_guard.md # English version
357+
tool_safety_guard.zh_CN.md # 本文
358+
```

‎examples/tool_safety/README.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -57,5 +57,6 @@ python ../../scripts/tool_safety_check.py \
5757
* `manifest_run.json` shows expected-vs-actual decisions across all 14
5858
samples.
5959

60-
See [../../docs/tool_safety_guard.md](../../docs/tool_safety_guard.md)
61-
for the full design document.
60+
See the full design document in
61+
[English](../../docs/tool_safety_guard.md) or
62+
[中文](../../docs/tool_safety_guard.zh_CN.md).

0 commit comments

Comments
 (0)