trustabl/trustabl-rules

本仓库包含了 [**Trustabl**](https://github.com/trustabl/trustabl)（用于 agent 可靠性的静态分析器）的检测规则包。Trustabl 引擎**不内置任何规则** —— 它会在扫描时从本仓库解析这些规则包（克隆到本地缓存，并支持离线回退），因此无需重新构建或重新分发二进制文件即可添加或更改规则。 本仓库中的每个 `.yaml` 文件（顶层 `manifest.yaml` 除外）都定义了一条或多条检测规则。引擎的加载器会递归遍历此目录树，解码每个文件，对其进行验证，并针对在受扫描项目中发现的 SDK 运行匹配的规则。 ## 引擎如何使用本仓库 ``` trustabl scan ./repo # resolves the latest rules, caches, scans trustabl rules pull # download/refresh the cache without scanning trustabl scan ./repo --rules-ref v1.0.0 # pin a tag/branch trustabl scan ./repo --no-rules-update # use the cached pack only (offline) ``` 本仓库解析后的 commit SHA 会记录在每次扫描结果中，并并入扫描的 `ScanID`，因此扫描能如实反映究竟是由哪个规则包生成的结果。 ## `manifest.yaml` —— schema 守卫 `manifest.yaml` 声明了 `schema_version`，即此规则包所针对的规则 schema 契约。如果规则包的 `schema_version` 超出了当前引擎构建版本所支持的范围，引擎将拒绝该规则包，因此针对较旧的二进制文件，较新的规则包绝不会发生悄无声息的加载错误。当引擎发生任何新增 predicate 或 schema 字段的变更时，必须同步提升此版本号。 ## 目录结构 规则按 `/.yaml` 进行分组： ``` manifest.yaml schema_version (metadata, not a rule) claude_sdk/ Claude Agent SDK rules (CSDK-NNN) — 30 rules ├── agent_safety.yaml CSDK-101..105 (agent); CSDK-120/130/131 (agent: permissionMode bypass + query() main-thread grants) ├── code_execution.yaml CSDK-107 (python), CSDK-011 (typescript) ├── error_handling.yaml CSDK-005 ├── idempotency.yaml CSDK-006 (python), CSDK-016 (typescript) ├── network.yaml CSDK-003 ├── path_safety.yaml CSDK-004 (python), CSDK-012 (typescript fs-write) ├── repo.yaml CSDK-201, CSDK-202 (repo scope, permission bypass) ├── repo_hygiene.yaml CSDK-203 (repo scope, CLAUDE.md missing) ├── shell_safety.yaml CSDK-108 (python), CSDK-010 (typescript) ├── ssrf.yaml CSDK-009 (python), CSDK-013 (typescript) ├── subagent_safety.yaml CSDK-110, CSDK-111 (subagent scope) └── tool_definition.yaml CSDK-001, CSDK-002, CSDK-007, CSDK-008 (python), CSDK-014 (typescript) openai_sdk/ OpenAI Agents SDK rules (OAI-NNN) — 32 rules ├── agent_safety.yaml OAI-101..104, OAI-109, OAI-110 (agent); OAI-105 (agent, typescript) ├── approvals.yaml OAI-014, OAI-111 (needs_approval gates) ├── code_execution.yaml OAI-013 (python), OAI-017 (typescript) ├── decorator_config.yaml OAI-003, OAI-004, OAI-015 ├── error_handling.yaml OAI-008 ├── idempotency.yaml OAI-009 (python), OAI-019 (typescript) ├── mcp_safety.yaml OAI-106 (agent scope, MCP-gated) ├── network.yaml OAI-005, OAI-011, OAI-018 (python); OAI-016, OAI-024 (typescript) ├── observability.yaml OAI-010 ├── path_safety.yaml OAI-006 ├── repo_hygiene.yaml OAI-202 (repo scope, CLAUDE.md missing) ├── shell_safety.yaml OAI-012 ├── tool_definition.yaml OAI-001, OAI-002, OAI-007 (python), OAI-022 (typescript) └── tracing.yaml OAI-201 (repo scope) google_adk/ Google ADK rules (ADK-NNN) — 26 rules ├── agent_safety.yaml ADK-101..108, ADK-110 (agent); ADK-109 (agent, typescript) ├── builtin_tools.yaml ADK-008 (BashTool policy gate, agent scope) ├── code_execution.yaml ADK-011 (python), ADK-015 (typescript) ├── error_handling.yaml ADK-005 ├── idempotency.yaml ADK-006 ├── network.yaml ADK-003 ├── path_safety.yaml ADK-004 ├── repo_hygiene.yaml ADK-201 (repo scope, CLAUDE.md missing) ├── shell_safety.yaml ADK-010 ├── ssrf.yaml ADK-012 (python), ADK-016 (typescript) └── tool_definition.yaml ADK-001, ADK-002, ADK-007, ADK-009 (python), ADK-013 (typescript) mcp/ Model Context Protocol rules (MCP-NNN) — 14 rules ├── code_execution.yaml MCP-009, MCP-014 ├── error_handling.yaml MCP-006 ├── idempotency.yaml MCP-007 ├── network.yaml MCP-004 ├── path_safety.yaml MCP-005 ├── shell_safety.yaml MCP-010, MCP-012 ├── ssrf.yaml MCP-008, MCP-013 └── tool_definition.yaml MCP-001, MCP-002, MCP-003, MCP-011 ``` 总计：涵盖 45 个 yaml 文件的 102 条规则。ID 前缀表示 SDK；`NNN` 为工具范围，`1NN` 为 agent / 子 agent 范围，`2NN` 为仓库范围。 category 是路径的第一段。将相关的规则归入一个 topic 文件中；每个文件包含 1-5 条规则时阅读体验最佳。加载器会进行递归遍历，因此只要引擎能识别其 `category:` 值，新的 category 目录即可直接生效。 ## 编写规则 规则 schema（每个被接受的字段及其注解）和 predicate 的实现位于**引擎**仓库中，而不是本仓库： - Schema 参考：[`internal/rules/schema.yaml`](https://github.com/trustabl/trustabl/blob/main/internal/rules/schema.yaml) - Schema 类型（权威定义）：[`internal/rules/schema.go`](https://github.com/trustabl/trustabl/blob/main/internal/rules/schema.go) 在编写规则之前，请先阅读 schema 参考。完整的规则编写契约 —— 包括必填字段、ID 命名规范、各范围的 `applies_to` 值、严重性/置信度指南，以及跨 SDK 的构建准则 —— 位于本仓库的 [`CLAUDE.md`](CLAUDE.md) 中。 如果一条规则需要尚不存在的 predicate，则属于**引擎**仓库（schema.go + predicates.go + evaluator.go + schema.yaml）的变更，而不是本仓库。请同步提升 `manifest.yaml` 中的 `schema_version`，并发布一个需要新版引擎构建的 release tag。

标签：AI智能体, Claude SDK, 云安全监控, 可靠性检测, 日志审计, 静态分析