Trustabl Rulebook MCP Server

trustabl-rulebook

Index and rationale docs for the trustabl static analyzer's policy ruleset. Canonical YAML rules live in 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/
• OpenAI Agents SDK (OAI-*) — openai_sdk/
• Google ADK (ADK-*) — google_adk/
• LangChain / LangGraph (LC-*) — langchain/
• CrewAI (CREW-*) — crewai/
• AutoGen / AG2 (AG2-*) — autogen/
• Vercel AI SDK (VAI-*) — vercel_ai/
• Pydantic AI (PYD-*) — pydantic_ai/
• Model Context Protocol (MCP-*) — mcp/
• Claude Skills (CSKILL-*) — docs/Policy/claude_skill/

What lives here

Path	Purpose
POLICY_INDEX.md	Master table of every shipped rule across all SDKs
<sdk>/POLICY_INDEX.md	Per-SDK rule index
docs/Policy/	Paired rationale docs (threat model, detection, references)
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 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, when a doc's severity/confidence/scope (front-matter or rule heading) disagrees with the pack, or when a doc omits a required section, a rule heading or the **Rules:** header line. A green CI run means every rule in agent-reliability-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: 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 — 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, 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 once the rulebook PR merges.

Companion repos

• trustabl/agent-reliability-rules — canonical YAML rules pack. The engine loads this at runtime; rule edits land here.
• trustabl/agent-reliability-analyzer — the analyzer binary that consumes the rules pack.