Content
# trustabl-rulebook
Index and rationale docs for the [trustabl](https://github.com/trustabl/agent-reliability-analyzer)
static analyzer's policy ruleset. Canonical YAML rules live in
[trustabl/agent-reliability-rules](https://github.com/trustabl/agent-reliability-rules) — this
repo links into them and explains the threat model behind each rule.
Coverage spans eight agent frameworks, a protocol-level rule family for the
Model Context Protocol, and a family for Claude Skills:
- **Claude Agent SDK** (`CSDK-*`) — [claude_sdk/](claude_sdk/)
- **OpenAI Agents SDK** (`OAI-*`) — [openai_sdk/](openai_sdk/)
- **Google ADK** (`ADK-*`) — [google_adk/](google_adk/)
- **LangChain / LangGraph** (`LC-*`) — [langchain/](langchain/)
- **CrewAI** (`CREW-*`) — [crewai/](crewai/)
- **AutoGen / AG2** (`AG2-*`) — [autogen/](autogen/)
- **Vercel AI SDK** (`VAI-*`) — [vercel_ai/](vercel_ai/)
- **Pydantic AI** (`PYD-*`) — [pydantic_ai/](pydantic_ai/)
- **Model Context Protocol** (`MCP-*`) — [mcp/](mcp/)
- **Claude Skills** (`CSKILL-*`) — [docs/Policy/claude_skill/](docs/Policy/claude_skill/)
## What lives here
| Path | Purpose |
| ------------------------------------------------------------ | ------------------------------------------------------------- |
| [POLICY_INDEX.md](POLICY_INDEX.md) | Master table of every shipped rule across all SDKs |
| `<sdk>/POLICY_INDEX.md` | Per-SDK rule index |
| [docs/Policy/](docs/Policy/) | Paired rationale docs (threat model, detection, references) |
| [docs/policy-rationale-doc-template-guide.md](docs/policy-rationale-doc-template-guide.md) | Authoring template for new rules + rationale docs |
## ID scheme
ID prefix denotes SDK; numeric range denotes scope.
| Range | Scope |
| ------ | ----------------- |
| `NNN` | tool |
| `1NN` | agent / subagent |
| `2NN` | repo |
`CSKILL-*` is the exception: every rule in that family is `skill`-scope, so its
numeric ranges group rules by topic rather than by scope.
Risk score = `severity_weight × confidence × 100`. Weights: `critical=1.0`,
`high=0.70`, `medium=0.40`, `low=0.15`, `info=0.05`. Higher = worse.
## Current totals
Counts are **generated, not maintained here** — that is what keeps them honest.
[POLICY_INDEX.md](POLICY_INDEX.md) carries the per-family breakdown by scope and
the full rule table; `<sdk>/POLICY_INDEX.md` carries the same for one family.
Both are a pure projection of the shipped pack, regenerated by
`tools/gen_index.py` and verified in CI by `tools/gen_index.py --check`.
Rationale coverage is likewise enforced rather than described:
`tools/check_rulebook.py --strict` fails the build when a shipped rule has no
rationale doc, or when a doc's severity/confidence/scope disagrees with the
pack. A green CI run means every rule in
[trustabl-rules](https://github.com/trustabl/trustabl-rules) is documented here.
## Using the rulebook
This repo is **documentation only** — it contains no rule YAML and the trustabl
engine never reads it. The engine resolves rules from
[trustabl/agent-reliability-rules](https://github.com/trustabl/agent-reliability-rules): at scan
time it clones the configured ref and caches it under
`os.UserCacheDir()/trustabl/rules/<sha>/`. The rulebook exists so a human can
look up *why* a rule fires (the threat model and references) without reading the
engine source.
To run a scan against a different rules pack or pin a version, point the
**engine** at an `agent-reliability-rules` repository/ref with `--rules-repo` /
`--rules-ref` (or the `TRUSTABL_RULES_REPO` env var); `--no-rules-update` uses
the local cache only. See the trustabl engine README for the full flag list.
## Contributing a rule
A rule spans three repos. The YAML lives in `agent-reliability-rules`; the rationale
doc lives here; the test mirror lives in the engine.
1. Read the rule-authoring contract in
[agent-reliability-rules/CLAUDE.md](https://github.com/trustabl/agent-reliability-rules/blob/main/CLAUDE.md)
— required fields, per-scope `applies_to` values, ID conventions, severity
guidance.
2. Add the YAML rule to `agent-reliability-rules` under `<sdk>/<topic>.yaml`.
3. Copy the template from
[docs/policy-rationale-doc-template-guide.md](docs/policy-rationale-doc-template-guide.md),
fill every section, and add the paired rationale **here** at
`docs/Policy/<sdk>/<topic>.md`.
4. Mirror the rule into the engine repo's `testdata/rules-fixture/` with at
least one fire case and one silent case (see the engine's
`testdata/rules-fixture/CLAUDE.md`, "Add a rule for X").
5. Open the PRs. The rule appears in [POLICY_INDEX.md](POLICY_INDEX.md) once
the rulebook PR merges.
## Companion repos
- [trustabl/agent-reliability-rules](https://github.com/trustabl/agent-reliability-rules) —
canonical YAML rules pack. The engine loads this at runtime; rule edits
land here.
- [trustabl/agent-reliability-analyzer](https://github.com/trustabl/agent-reliability-analyzer) — the analyzer
binary that consumes the rules pack.
MCP Store