Interbolt documentation

A defense that judges whether a piece of text is an attack only has to be beaten once: an attacker who can see how the defense works can study it and write around it. The Attacker Moves Second (Nasr et al., 2025) measured the size of this gap, bypassing twelve published defenses, several of which had reported near-zero attack success against static payloads, at rates above 90% once the attacker was allowed to adapt.

The attacker controls what their text says, but not where it came from. Interbolt enforces on that second property. It marks data as untrusted at the point it enters your agent, propagates that mark through your code, and gates each guarded tool call on the provenance of its arguments rather than on their content. A tool call can be blocked, or routed through approval, without Interbolt ever having to recognize an attack, which makes security a property of the system around the model rather than of the model's ability to resist being talked into something. The Threat model page carries the full argument, including the class of injections that read as ordinary work and give a classifier nothing to flag, and links the research this is based on.

Concretely, taint() marks untrusted data (a web search result, an email, a tool's output) at ingress, and a YAML+CEL policy is evaluated at each guarded tool call. The resulting decision to allow, block, or require approval is deterministic and computed in-process, with no model and no network call involved.

Interbolt is not a prompt-injection classifier, a content filter, or a sandbox. The Threat model page lists explicitly what it does and does not cover, and is worth reading before you adopt it.

Start here

• Quickstart: install, write a policy, taint a value, guard a tool, define agents and tools across modules, track a model call as a new source, and get the decision (and why) at the sink.
• Writing a policy: the sequence from taint() at ingress to the decision at the sink, then a policy built step by step for a real agent, with the rule patterns and the pitfalls.

Concepts

• Threat model: the lethal-trifecta attack pattern Interbolt targets, and an explicit list of what it does not do.
• Taint propagation: what taint() marks, what survives a transformation, and how derived_from makes a model call or agent handoff a trust-aware new source rather than a fresh, unrelated ingress point.
• Policies: the policy DSL (YAML structure, CEL conditions, and the rule fields), the CEL context a when expression can reference, and the evaluation semantics behind every decision.
• Identity: the agent_id / run_id / session_id triple, why run_id binding is what keeps run.tainted working, and the thread-pool and custom-dispatch cases that break it.

Guides

• Writing a policy: the end-to-end walkthrough, from naming sources to validating and rolling out.
• Testing: how to assert on policy decisions with InMemoryReporter and a fake approval resolver.
• Auditing: finding the places a transformation laundered a taint label that should have been re-tainted, and endorse() as the sanctioned alternative.
• CI: checking a policy file with interbolt validate in CI or pre-commit.
• Explain: answering "what can this agent do" with interbolt explain --agent/--group/--tool instead of reading every rule by hand.
• OpenTelemetry: mapping Interbolt's setup, factory, and decorator patterns onto Phoenix/OpenTelemetry vocabulary, and wiring OTelReporter next to an already-instrumented app.
• Troubleshooting: fixes for the most common surprises, such as an unexpected block, every call requiring approval, and run.tainted staying false.

Reference

• API reference: every name re-exported from interbolt, plus the command line.
• Reporters: the Reporter protocol and the six shipped implementations.
• Events: the stable, versioned JSON shape of Event/Finding/Endorsement, the OpenTelemetry attribute mapping, and the EVENT_SCHEMA_VERSION history.
• Performance: the published check() and propagation-path benchmark numbers, and what they do not cover.
• Taint propagation internals: the exact CPython mechanism behind every propagates/launders case.
• Policy evaluation internals: the CEL rewrite mechanism, the full trifecta derivation, and what interbolt validate does and does not catch.
• Glossary: one-line definitions for the vocabulary used throughout these docs.

Design

• Design lineage: the proven patterns (Casbin, OpenTelemetry, CEL, Django SafeString, Resin) the architecture assembles, and how Interbolt diverges from each.