AgentContainment

Control and enforcement layer for an AI agent governance stack.

AgentContainment provides the control side of a broader agent-governance loop: authorize actions, detect policy violations, halt compromised runs, revoke authority, contain blast radius, verify external enforcement, and preserve verifiable incident evidence.

Paired with provenance and claim-verification layers such as DProvenanceKit and ClaimProofKit, it forms a closed governance loop:

Observe → Prove → Authorize → Enforce → Contain → Recover → Regression

The architectural goal is not a collection of unrelated security libraries. It is a composable governance stack in which DProvenanceKit explains what happened, AgentContainment enforces what was allowed, ClaimProofKit verifies what is supported by evidence, and incidents become durable inputs to future regression tests. It is intentionally provider-neutral: platform enforcement can be supplied by cgroup v2/eBPF, Cilium, Tetragon, or another independently verifiable enforcement system.

Keywords: AI agent security, agent containment, autonomous agent security, AI runtime security, agent security control plane, AI agent firewall, agent firewall, AI agent sandbox, agent sandboxing, AI guardrails, agent governance, AI safety, runtime enforcement, action authorization, policy enforcement, kill switch, incident response, blast radius containment, enforcement verification, Cilium, CiliumNetworkPolicy, Kubernetes network policy, Tetragon, eBPF, Linux cgroups, cgroup v2, zero trust, defense in depth, tamper-evident audit, security engineering, open source AI security.

Governance stack

                    AI GOVERNANCE STACK
                           |
              +------------+------------+
              |                         |
        PROVENANCE / PROOF        CONTROL / ENFORCEMENT
        DProvenanceKit            AgentContainment
              |                         |
        What happened?             What is allowed?
        Evidence                   Halt / revoke
        Regression                 Contain / recover
              |                         |
              +------------+------------+
                           |
                    GOVERNANCE LOOP
                           |
                 Incident → Evidence
                           |
                    Regression gate

The integration point is intentional:

• Provenance records the action, decision, evidence, and resulting incident state.
• Containment can consume provenance-linked incident context while retaining independent authority to halt the runtime.
• Recovery remains controller-authorized rather than agent-authorized.
• Incidents can be converted into deterministic regression cases so a previously observed failure becomes a future release gate.

See docs/GOVERNANCE_PLATFORM.md for the platform architecture and implementation roadmap.

Governance integration contract

The open-source stack is intentionally modular:

             GOVERNANCE CONTRACT
                    │
        +-----------+-----------+
        ▼           ▼           ▼
 DProvenanceKit  AgentContainment  ClaimProofKit
    PROVE           CONTROL          VERIFY
        \             │             /
         \            │            /
          +------ regression ------+

AgentContainment emits controller-owned GovernanceEvent records and can export incidents as RegressionFixture cases. Downstream provenance and claim-verification systems can attach evidence and support decisions without becoming the containment or recovery authority.

Why this is interesting

This project is deliberately trying to solve a harder problem than “put guardrails around the agent.”

The interesting boundary is what happens when the agent itself is no longer trustworthy.

An agent can request an action. A verification layer can determine whether the supporting claim is acceptable. A controller can make the authorization decision. An external mechanism can enforce containment at the host or network boundary. Independent evidence can then show what actually happened.

That gives the stack a concrete chain:

ACTION
  ↓
CLAIM VERIFICATION
  ↓
AUTHORIZATION
  ↓
EXTERNAL ENFORCEMENT
  ↓
INDEPENDENT VERIFICATION
  ↓
PROVENANCE / EVIDENCE
  ↓
WARDEN OBSERVATION

The important part is that no step is allowed to quietly impersonate another step.

• ClaimProofKit answers: Is the action supported by acceptable claims?
• AgentContainment answers: Was the action authorized, and what happens when containment is required?
• The external enforcer answers: Was the boundary actually applied?
• DProvenanceKit answers: Can the decision and resulting state be reconstructed and proved?
• Warden answers: Can an operator see the chain without being given authority to change it?

Milestone 7 also moved the project beyond a purely simulated enforcement story: the trusted CI path exercises the Linux/eBPF containment boundary on a real Linux host and independently verifies the pinned enforcement link and post-containment behavior.

That does not make the system production-ready. It makes the engineering question more interesting: the project is now testing the boundary between an agent's intent, a controller's authority, an external enforcement mechanism, and independently reconstructable evidence.

Don't ask the agent to obey the boundary. Put the boundary outside the agent — then prove the boundary was actually enforced.

Installation

AgentContainment is packaged as a standard Python distribution. The first public PyPI release is planned after release validation; until then, install the current development version directly from GitHub:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install "git+https://github.com/Therealdk8890/AgentContainment.git"

After the first PyPI release, the intended installation path will be:

python -m pip install agentcontainment

The core package has no third-party runtime dependencies. Linux-specific enforcement providers may require host capabilities and external tools such as eBPF/libbpf or Cilium/Kubernetes; those are deployment requirements rather than core Python dependencies.

Core model

Detect → Prove → Halt → Contain → Map → Recover

The containment plane is designed to sit outside the agent's trust boundary. An agent must not control its own kill switch, containment policy, credentials, or incident evidence.

Why AgentContainment

Traditional agent guardrails often operate inside the application or framework executing the agent. AgentContainment is designed around a different security boundary:

The agent requests an action. The controller decides whether it is allowed. The enforcement layer can then stop the runtime and its network egress independently of the agent.

This separation is intended to remain useful when an agent is compromised, misbehaving, or attempting to bypass its normal tool wrapper.

cgroup v2 provider

The optional CgroupV2Enforcer adapts a dedicated Linux cgroup v2 workload boundary to the provider-neutral enforcement interface. It uses cgroup.kill for containment and verifies state through cgroup.events. Configured cgroups are identity-bound using filesystem metadata so a deleted-and-recreated path is not silently accepted as the original workload boundary. An empty cgroup is treated as evidence that the current workload has exited; the AgentContainment durable admission fence remains the controller-owned authority that prevents recovery without explicit authorization.

This adapter is a Linux enforcement integration, not a claim that the Python control plane alone provides kernel-level isolation. Production deployments should provision and protect the cgroup hierarchy outside the agent trust boundary and validate the privileged integration on the target host.

Cilium provider

The optional CiliumNetworkPolicyEnforcer integrates the same provider contract with Kubernetes/Cilium. It creates a namespace-scoped CiliumNetworkPolicy for the configured workload selector and denies ingress and egress. It does not add a Kubernetes client dependency to the core library; the adapter invokes kubectl without a shell and verifies the live policy object before reporting containment. Release deletes the policy and verifies that it is absent. The enforcer also queries matching CiliumEndpoint resources and requires realized policy enforcement for both ingress and egress before certifying containment. A Kubernetes policy object alone is therefore not treated as sufficient proof of enforcement. Production deployments should still pair this with Cilium health checks and an independent process-containment mechanism.

Enforcement layers

AgentContainment uses defense in depth:

1. Action authorization — deterministic policy decisions before tool execution.
2. Stateful policy — controller-owned action history can detect sequences where individually permitted actions become dangerous collectively.
3. Epoch fencing — containment invalidates outstanding execution and egress leases.
4. Capability revocation — application-level authority is revoked during containment.
5. Process containment — Linux cgroup v2 can terminate the contained cgroup with cgroup.kill.
6. Kernel egress enforcement — the Linux eBPF integration can attach a cgroup egress program that drops outbound packets.
7. Tamper-evident evidence — controller-owned audit events are recorded in a hash chain.

No single layer is treated as sufficient.

Provider-neutral enforcement architecture

AgentContainment owns the containment decision, durable admission fence, recovery authority, and enforcement verification state. It does not require a particular kernel or network security product.

The enforcement boundary is intentionally pluggable:

                    AgentContainment
             control plane / recovery authority
                          |
                 containment decision
                          v
              +-----------+-----------+
              |           |           |
           Cilium      Tetragon    cgroup/eBPF
           network      runtime       process/
          enforcement  enforcement    egress
              |           |           |
              +-----------+-----------+
                          v
                    OS / network
                          |
                          v
                     Verification

The controller follows:

REQUEST CONTAINMENT → ENFORCE → VERIFY → CERTIFY CONTAINED

A provider is not considered successfully enforced merely because a command or API request was accepted. Providers return an explicit status such as ENFORCED, VERIFICATION_FAILED, DEGRADED, or NOT_CONFIGURED.

Cilium and Tetragon are optional integration targets, not dependencies of the core library. AgentContainment is not intended to replace either project's kernel-level enforcement or telemetry capabilities. Its role is to provide an agent-level safety state machine and independent recovery boundary above those mechanisms.

For the current provider API, see src/agent_containment/enforcer.py.

Stateful policy enforcement

Policies can reason about action sequences rather than only individual actions.

from agent_containment.policy import PolicyEngine, SequenceRule

policy = PolicyEngine(sequence_rules=[
    SequenceRule(
        "prevent-download-upload-delete",
        ("download_file", "upload_file", "delete_file"),
    )
])

The controller can therefore allow:

download_file → ALLOW
upload_file   → ALLOW

while halting the third action when the complete sequence is observed:

delete_file → HALT

The policy history is maintained by the controller rather than being supplied by the agent.

Standalone control plane

The repository includes a Unix-domain control transport and client for separating the agent from the controller process.

Agent
  |
  | Unix domain socket
  v
agentcontainmentd
  |
  +-- peer credential authorization
  +-- action policy
  +-- stateful policy history
  +-- containment authority
  +-- audit/evidence
  |
  v
OS enforcement boundary
  |
  +-- cgroup v2
  +-- eBPF cgroup egress enforcement

The daemon exposes a deliberately narrow control protocol for registration, authorization, status, containment, reports, and snapshots.

OS-level containment

On Linux, production deployments can place an agent and its descendants in a dedicated cgroup v2. Containment can then:

• invalidate application and egress leases;
• revoke application capabilities;
• activate the eBPF egress blocker;
• terminate the contained cgroup;
• preserve controller-owned evidence and telemetry paths.

The strongest guarantees depend on deployment privileges, cgroup configuration, kernel support, and correct isolation. AgentContainment does not claim that completed external side effects can be reversed.

See docs/OS_LEVEL_CONTAINMENT.md and docs/EGRESS_CONTAINMENT.md for the security model and limitations.

Audit evidence

The controller can maintain a JSONL hash chain linking each event to the previous event. Verification detects edits, deletion, and reordering of the recorded chain.

This is tamper-evident, not immutable storage: an attacker with authority to rewrite both the audit file and its trusted reference can rewrite the evidence. External anchoring is a future hardening layer.

Agent hierarchy

AgentTree models parent/child agents and propagates containment through currently registered descendants. Child capabilities are attenuated to the intersection requested by the child and held by the parent.

This provides a foundation for multi-agent containment without assuming that every child has the same authority as its parent.

Milestone 8 — Warden observation

Milestone 7 established real-host Linux/eBPF containment and independent enforcement verification. Milestone 8 adds the observability boundary above that control path.

Warden gets eyes, not hands. Warden observes and displays the governance chain; it does not authorize actions, contain agents, release containment, mutate enforcement state, or approve recovery.

ACTION
  ↓
CLAIM VERIFICATION
  ↓
AUTHORIZATION
  ↓
EXTERNAL ENFORCEMENT
  ↓
EVIDENCE
  ↓
WARDEN OBSERVATION

The security invariant is:

Warden observation must be incapable of changing authorization or containment state.

The provider-neutral observation contract is implemented by WardenObservation. See docs/MILESTONE_8_WARDEN.md for the acceptance criterion and integration plan.

Status

Early research/prototype, with real-host enforcement proof established for the current Linux/eBPF path. The project is currently focused on deterministic authorization, stateful action policy, runtime fencing, provider-neutral enforcement verification, containment, child-agent propagation, OS-level Linux enforcement, incident evidence, and the Milestone 8 observation boundary. Cilium/Tetragon remain optional integrations rather than core dependencies.

The project should not yet be treated as a production security boundary without validating the host deployment, privilege model, identity binding, policy coverage, and kernel enforcement configuration.

Repository layout

• src/agent_containment/ — core library and controller components
• ebpf/ — Linux eBPF enforcement program and controller
• policies/ — example policy
• demo/ — controlled rogue-agent demonstration
• tests/ — security and behavior tests
• tests/integration/ — opt-in privileged Linux integration tests
• docs/ — architecture, threat model, and containment notes
• scripts/ — build and development helpers

Safety

The demo uses a simulated environment. It does not execute destructive actions against real infrastructure.

Privileged integration tests are opt-in and intended for isolated Linux environments.

License

Apache-2.0