agentcontainment 0.1.0__tar.gz

agentcontainment-0.1.0/LICENSE

@@ -0,0 +1,87 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of fifty percent (50%) or more of the outstanding shares, or (iv) beneficial ownership of fifty percent (50%) or more of the outstanding shares.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work.
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner.
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License.
+
+Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License.
+
+Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work.
+
+4. Redistribution.
+
+You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or within a display generated by the Derivative Works, if and wherever such third-party notices normally appear.
+
+(e) You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions.
+
+Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions.
+
+6. Trademarks.
+
+This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty.
+
+Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+8. Limitation of Liability.
+
+In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law shall any Contributor be liable to You for damages arising from this License or out of the use or inability to use the Work.
+
+9. Accepting Warranty or Additional Liability.
+
+While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+Copyright 2026 Danny / Therealdk8890
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

agentcontainment-0.1.0/PKG-INFO

@@ -0,0 +1,364 @@
+Metadata-Version: 2.4
+Name: agentcontainment
+Version: 0.1.0
+Summary: Controller-owned authorization and independently verifiable containment for AI agents
+Author: Daniel Kissel
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/Therealdk8890/AgentContainment
+Project-URL: Repository, https://github.com/Therealdk8890/AgentContainment
+Project-URL: Issues, https://github.com/Therealdk8890/AgentContainment/issues
+Keywords: ai-agents,agent-security,agent-containment,ai-safety,runtime-security,authorization,policy-enforcement,ebpf,cgroups,cilium,governance
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# 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
+
+```text
+                    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`](docs/GOVERNANCE_PLATFORM.md) for the platform architecture and implementation roadmap.
+
+### Governance integration contract
+
+The open-source stack is intentionally modular:
+
+```text
+             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:
+
+```text
+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:
+
+```bash
+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:
+
+```bash
+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:
+
+```text
+                    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:
+
+```text
+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.
+
+```python
+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:
+
+```text
+download_file → ALLOW
+upload_file   → ALLOW
+```
+
+while halting the third action when the complete sequence is observed:
+
+```text
+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.
+
+```text
+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.
+
+```text
+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`](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