cordon

Capability-based containment for autonomous agents.

An agent runs under a Bundle of unforgeable capability tokens. Resource access goes through check(resource, op), which either succeeds (the bundle grants the requested capability) or raises Denied. Ambient permission is not available inside the cordon.

The research question this repo studies is whether containment reduces unauthorized resource access in agent workloads, and what task-success penalty it imposes when the bundle is computed by an imperfect bundler.

At a glance

from cordon.adapters import fs
from cordon.bundle import Bundle
from cordon.runtime import cordon
from cordon.token import mint

SECRET = b"k" * 32
b = Bundle(secret=SECRET)
b.grant(mint("fs:/tmp/data.txt", "read", SECRET, ttl=60))

with cordon(b) as rt:
    fs.read_text("/tmp/data.txt")        # allowed
    # fs.read_text("/etc/passwd")        # raises Denied
    print(rt.audit.summary())

Layout

cordon/        library code
tests/         pytest suite (>140 tests)
experiments/   evaluation harness and results
benchmarks/    microbenchmarks (mint/verify, bundle vs index)
examples/      runnable end-to-end demos
paper.md       short paper reporting measured findings

Core API

Module	Purpose
cordon.token	HMAC-signed (resource, op, expiry, nonce) tokens.
cordon.bundle	Bundle algebra (merge, scope, intersect, ...).
cordon.runtime	Context manager + per-thread active runtime.
cordon.audit	Append-only log with filters and summary.
cordon.ratelimit	Token-bucket per (resource, op).
cordon.budget	Global op-count budget per run.
cordon.quota	Per (resource, op) usage counter.
cordon.nonce	Sliding-window nonce tracker for replay defense.
cordon.policy	Declarative {capabilities: [...]} loader.
cordon.replay	Derive minimum bundle from an audit log.
cordon.redact	Resource-string redaction rules for export.
cordon.delegate	Mint narrower child tokens from a parent.
cordon.index	O(1) exact-resource bundle lookups.
cordon.pretty	Human-readable bundle / audit rendering.
cordon.adapters.fs	read_text, write_text, stat, ...
cordon.adapters.net	fetch, post, post_json with injectable transport.
cordon.adapters.proc	spawn(argv), spawn_shell(cmd).
cordon.adapters.env	get, set, unset.
cordon.adapters.clock	now(), monotonic().
cordon.adapters.random	bytes(n), token_hex(n).

Running

PYTHONPATH=. pytest -q
PYTHONPATH=. python -m experiments.run > experiments/run.log
PYTHONPATH=. python -m experiments.analyze
PYTHONPATH=. python benchmarks/bench_token.py
PYTHONPATH=. python benchmarks/bench_index.py
PYTHONPATH=. python examples/safe_file_read.py