attenu-guard

attenu.io · Docs · Attenu Derive — what each agent may do, read from your app · Internet-Draft · Changelog

Works with LangGraph · LangChain create_agent / deepagents · OpenAI Agents SDK · Google ADK · Pydantic AI · CrewAI · AutoGen · Claude Agent SDK · smolagents · AWS Strands · LlamaIndex · Semantic Kernel · Agno · Haystack · CAMEL-AI · Microsoft Agent Framework · AG2 — each integrated unmodified, each with an offline demo and tests (matrix). Enforced live on real applications with Google ADK, CrewAI and LangGraph.

Attenu Guard checks what an AI agent may do — and keeps it narrowing at every handoff. When one agent hands work to another, the child gets only the permissions its task needs, never the parent's full set. Chains have hard ceilings. Any subtree can be revoked in one call. Every decision lands on a tamper-evident log you can verify offline. The alternative most teams live with is handing an agent a person's credentials and reading the logs afterwards.

An open enforcement layer for OWASP ASI07 (insecure inter-agent communication) and ASI08 (cascading failures): delegated authority stays inside the parent's limits, and every decision remains verifiable offline.

pip install attenu-guard                 # zero runtime deps; gives you the `attenu-guard` command too
pip install 'attenu-guard[langgraph]'    # or crewai, google-adk, openai-agents, … — one extra per framework

Have a bundle to check? pipx run attenu-guard verify bundle.json — integrity, child ⊆ parent and containment from the file alone, no account, no network; the auditor's walkthrough has three sample bundles (clean, tampered, widened) and takes a minute.

Just want to see it run? From the repo root, no install needed: python examples/poisoned_summarizer.py — the examples bootstrap the src/ path themselves. python tests/run_properties.py proves the invariants the same way.

from attenu_guard import Authority, Guard, RowLimit, EgressRank

# The orchestrator holds broad authority.
orchestrator = Guard.issue("orchestrator", Authority(
    scopes={"crm.*", "mail.send"},
    ceilings=[RowLimit(100_000), EgressRank("any")], ttl=3600))

# It delegates a narrow task. The child gets the *meet* of what the parent
# held and what the task needs — computed and enforced, not suggested.
summarizer = orchestrator.delegate("summarizer", Authority(
    scopes={"crm.read"},
    ceilings=[RowLimit(5_000), EgressRank("none")], ttl=900),
    task="summarize Q3 pipeline")

decision = summarizer.check("crm.read", context={"rows": 4_200})   # Decision(allowed=True)
if not decision:
    print(decision.explain())

summarizer.enforce("crm.export", context={"egress": "any"})        # raises AuthorityDenied

check() returns a rich Decision (with machine-readable reason codes for your audit trail); enforce() is the hard-stop gate that raises; would_allow() is a dry-run that writes nothing. The crm.export call is refused whatever the agent was talked into trying — the sub-agent never held that permission, so an injected instruction has nothing to widen. That is the default once permissions narrow at the handoff.

What happens at a handoff today

In the frameworks we audited, the handoff itself is not something the system can see: identity tokens describe two parties — user and agent — so "child ⊆ parent" cannot be written down, and policy checks fire when a tool is invoked rather than at the moment permissions are passed down. Verified against released code, and pinned by tests that fail the day the behaviour changes:

attenu-guard makes child ⊆ parent a computed, enforced, offline-verifiable invariant — in your framework, in your process — no proxy, and no network call in the deny path.

What you get

• Authority — an immutable capability (scopes + a list of typed, extensible Ceiling bounds + TTL) with meet, the lattice operation that can only ever shrink, and is_narrower_than, the provable subsumption relation.
• Guard — issue() a root, delegate() a sub-agent with attenuated authority, check() → Decision, enforce() → raises, would_allow() → dry-run, revoke() a whole subtree.
• Typed ceilings — RowLimit, SpendCap, CallLimit, EgressRank, Allow, Deny, Prefix, or your own via register_ceiling. Unknown ceiling types fail closed, never silently unbounded.
• Chain invariants — depth, fanout, and aggregate budget ceilings; cascade revocation (revoke any node, every descendant denies immediately).
• Hash-chained audit log — an open, versioned schema; attenu-guard view log.jsonl renders the tree and verifies it; tampering is provable offline. Every deny says why (disposition: held_pending_grant — waiting on a human · withheld_tier2 · unresolved — no authority known for the tool · out_of_authority — real over-reach), so "held" never reads as "denied"; evidence.export_bundle / verify_bundle / delegation_graph / denials give an auditor an offline-verifiable bundle and the folds a console renders. AuditLog(sinks=…) copies entries to local sinks after the write (never the network) — sinks.SpoolSink is a bounded, fsync'd, resumable write-ahead spool carrying the ingest idempotency key (boot_id, chain_id, seq, hash); attenu_guard.identity gives a product an identity before it has a key (.attenu/product.json, per-process boot_id, assigned chain ids).
• Wire format (attenu_guard.wire) — serialize/load the delegation chain as signed Delegation Tokens and verify child ⊆ parent offline, across services, with no authorization server in the path. This is the reference implementation of the Internet-Draft in docs/; interop test vectors live in tests/vectors/.
• Scenario harness — declarative JSON/YAML authorization tests (attenu-guard scenarios file.json); see scenarios/.
• Adapters — shipped, tested integrations for the major agent frameworks as attenu_guard.adapters.<name>: LangGraph, LangChain create_agent / deepagents, OpenAI Agents SDK, Google ADK, Pydantic AI, CrewAI, AutoGen, Claude Agent SDK, smolagents, AWS Strands, LlamaIndex, Semantic Kernel, Agno — each with an offline demo under examples/integrations/; install one with pip install 'attenu-guard[<extra>]'. Hooks, versions and what each framework enforces itself: docs/INTEGRATIONS.md.

Prove the safety claims yourself

python tests/run_properties.py      # 4,000 random delegation trees per invariant, zero deps
python tests/red_team.py            # 17 adversarial attacks, black- & white-box; 0 must break
python examples/poisoned_summarizer.py
attenu-guard demo

The property suite asserts — over thousands of random chains — that attenuation never widens, holds transitively down a chain, that a revoked subtree authorizes nothing, and that audit tampering is detected. The red-team harness (see docs/RED-TEAM.md) additionally tries to break the protocol — privilege escalation, chain splicing, expired-grant reuse — and every genuine finding is fixed and pinned as a regression. If you can break one, the core claim is false; please tell us.

Standards

The protocol is designed to be IETF-acceptable: it reuses the OAuth/JOSE stack (JWT, RFC 9396 authorization_details, DPoP, Token Status List) and invents only the one missing piece — cryptographically-linked, subsumption-enforced, offline multi-hop attenuation. See docs/STANDARDS-ALIGNMENT.md and the Internet-Draft draft-asor-wimse-agent-delegation-chain (individual submission, WIMSE; source in docs/).

What this is not

This library does not decide authority for you. You write the Authority for each delegation — or you let attenu-derive, the open engine, compute it from your app's declared structure (agents, roster, tools, what each task calls) and approve it before it is enforced. The library is the enforcement shim and the open schema; it is useful entirely on its own, forever, with no account and no network. The Attenu console is optional: a place to see denials, decide, and verify — never in the deny path.

License

Apache-2.0. Contributions under the DCO. Security policy in SECURITY.md.