https://github.com/eunomia-bpf/ActPlane
eBPF-Based Information Flow Policy Engine for AI Agent Harnesses
https://github.com/eunomia-bpf/ActPlane
Last synced: 13 days ago
JSON representation
eBPF-Based Information Flow Policy Engine for AI Agent Harnesses
- Host: GitHub
- URL: https://github.com/eunomia-bpf/ActPlane
- Owner: eunomia-bpf
- License: mit
- Created: 2026-05-22T23:19:43.000Z (about 2 months ago)
- Default Branch: master
- Last Pushed: 2026-06-22T23:02:40.000Z (19 days ago)
- Last Synced: 2026-06-22T23:14:17.666Z (19 days ago)
- Language: C
- Homepage:
- Size: 119 MB
- Stars: 50
- Watchers: 0
- Forks: 5
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: docs/security_model.md
- Agents: AGENTS.md
Awesome Lists containing this project
- awesome-cli-coding-agents - ActPlane - level agent harness that compiles a policy DSL to an eBPF engine for labeled information-flow control at the syscall boundary, with corrective feedback. MIT. (Harnesses & orchestration / Agent infrastructure)
- awesome-agent-runtime-security - ActPlane - LSM, information-flow | eBPF-based policy engine for agent harnesses: labeled information-flow rules in a compact DSL enforced at the kernel level across entire process lineage trees. Supports block/kill/notify modes with corrective feedback to the agent via hooks (Claude Code, Codex). Causal ordering (`since` clauses), data-flow tracking across fork/exec/file edges. From the [AgentSight](https://github.com/eunomia-bpf/agentsight) team. | (Provenance, Instrumentation & Observability)
README
# ActPlane: eBPF-Based IFC Policy Engine for AI Agent Harnesses
[](https://opensource.org/licenses/MIT)
**Runtime `enforcement` and `observability` for AI agent harnesses and sandboxing: declare information-flow policies for safety, security and compliance, and ActPlane enforces them in the kernel with eBPF.**
Prompt constraints and model guardrails are probabilistic. ActPlane is deterministic. Tool call check cannot see indirect system behavior, e.g. a sh script.
**What you can express:**
- **"No `codex` may run `git push` or write outside `/src`"**: fine-grained sandboxing rules follow process lineage, no bypass via bash scripts or python.
- **"Never remove the build cache in makefile unless explicitly asked or debugging"**: bypassable with a specific argument when necessary, not just sandbox.
- **"When changing `specs/*`, also update the server, SDK, and docs"**: ActPlane never blocks the edit, it notifies the agent that downstream outputs are now stale.
- **"Run `make check` & `npm tests` before committing"**: causal ordering, not just per-operation checks.
## Quickstart
Install with one command. The eBPF program ships prebuilt (CO-RE, architecture
independent), so there is **no clang/llvm/libbpf to install** — just a Rust
toolchain:
```bash
cargo install actplane
```
Write a policy and run an agent (or any command) under the harness:
```bash
actplane init # write a starter actplane.yaml
actplane compile # validate rules (no privileges)
actplane doctor # diagnose hooks, MCP, kernel support
codex # MCP auto-attach tries passwordless sudo
sudo -E actplane run claude -p "review this repo"
```
When a rule matches, ActPlane kills the action and tells the agent why:
```
🚫 KILLED: process 'git' (pid 4213, ppid 4210) — /usr/bin/git
effect: kill
reason: no git under the agent; use the review workflow
```
The agent receives this reason through its hook integration, understands the
constraint, and takes a different path to complete the task.
**Requirements:** Linux kernel 5.8+ with BTF (`/sys/kernel/btf/vmlinux`). `run`
and `watch` load the eBPF engine, so they need root (or `CAP_BPF` +
`CAP_SYS_ADMIN`); ActPlane drops the target command back to your user. With
BPF-LSM enabled, rules can `block` before the action commits; otherwise they
`notify` (report) or `kill`.
## Why an OS-level harness?
Agent constraints today come in three forms. Each solves a real problem but
leaves a gap that the next layer down needs to cover.
| Approach | What it does | What it can't cover |
|----------|-------------|---------------------|
| **Prompt constraints** (`CLAUDE.md`, `AGENTS.md`) | Tell the agent what to do and not do | Probabilistic: long-context agents forget or route around them, often non-maliciously |
| **Tool-layer guards** (MCP gateways, AgentSpec) | Intercept and authorize at the tool API | Bypassed the moment the agent shells out, links an SDK, or spawns a subprocess |
| **Sandboxes** (containers, VMs, E2B, Daytona) | Isolate the entire execution environment | All-or-nothing: can't express "file A must only be accessed via script A" or "run tests before committing" |
ActPlane sits below all three, at the OS level. Every `exec`, file open, and
network connect goes through the kernel, so a rule like *"nothing descended from
`codex`, however many hops, may run `git` or modify files outside `/work`"*
holds regardless of which tool path the agent takes.
The key differences:
- **OS-level coverage**: observation and enforcement happen at the kernel, not the tool API. Bash, Python subprocess, direct SDK calls, all covered.
- **Call-chain granularity**: rules follow process lineage, not just single operations. "Codex's entire subprocess tree cannot touch git" is one rule.
- **Data-flow constraints**: rules express "data read from A must never flow to B", tracked across arbitrary fork/exec and file read/write edges, not just at a boundary.
- **Causal ordering**: rules express "run tests before committing" via `since` clauses and gate invalidation, not just per-operation checks.
- **Corrective feedback, not just blocking**: rule matches feed a human-readable reason back to the agent, so it can retry a different way. This is what makes it a harness, not a sandbox.
- **Agent-maintained rules**: the rule language is designed so agents can write, validate (`actplane check`), and evolve their own policies.
## Harness, not just a sandbox
A sandbox draws an isolation boundary: everything inside is allowed, everything
outside is denied. That works for untrusted code, but agents need something
richer — the data-flow, causal-ordering, and corrective-feedback properties
above are things no isolation boundary can express.
Sandboxes answer "can this process access this resource?" A harness answers a
broader set of questions: not just security ("secret data must not reach the
network") but also software engineering discipline ("run tests before
committing", "don't mix data from independent tasks in one commit", "use the
migration tool to access prod.db"). These are workflow constraints, not access
control, and they are exactly the kind of rules agents need to operate
autonomously in real codebases.
A harness also subsumes sandboxing when you need it. When an agent spawns a
sub-agent or runs an untrusted command, you can write a rule that confines the
entire subtree to read-only, no-network, or a specific directory. This is
especially important when agents cross vendor boundaries: Codex calling Claude
Code, or the other way around. Framework-level guards from different vendors
don't compose, but OS-level rules follow process lineage regardless of which
runtime is underneath.
## How rules work
Rules are **labeled information-flow policies**, not static allow-lists.
Labels propagate along fork/exec edges and file read/write edges, so
constraints follow derived data across processes and files.
```yaml
# actplane.yaml
version: 1
policy: |
source AGENT = exec "claude"
# Track when protocol schema files are modified
source SCHEMA_CHANGED = file "src/protocol/**/*.proto"
rule no-git-branch:
kill exec "git" "branch" if AGENT
kill exec "git" "worktree" if AGENT
because "This workspace forbids creating git branches or worktrees. Use other git commands, or ask the user to manage branches."
rule regenerate-after-schema:
notify exec "git" "commit"
if SCHEMA_CHANGED unless after exec "protoc" since write "src/protocol/**"
because "Protocol schema changed — generated code may be stale. Run `make proto` to regenerate, then commit."
rule test-before-commit:
block exec "git" "commit"
if AGENT unless after exec "pnpm" "test" since write "src/**"
because "Source files changed since last test run. Run `pnpm test:changed`, then commit."
```
Three rules, three effects, three patterns:
- **`no-git-branch`** (kill): per-event rule — anything in the agent's
process tree that tries `git branch` is terminated immediately.
- **`regenerate-after-schema`** (notify): cross-event conditional — if
the agent modified a `.proto` file, ActPlane reminds it to run `protoc`
before committing. The `since` clause re-arms the gate whenever the
schema changes again.
- **`test-before-commit`** (block): cross-event temporal with staleness —
the agent must run tests before committing, and editing any `src/`
file invalidates the previous test run.
See [`docs/rule-language.md`](docs/rule-language.md) for the full rule language and
worked examples.
## Agent integration
ActPlane feeds rule-match reasons back to agents via their hook systems.
`actplane init --with-codex` writes a ready-to-use Codex hook at
`.codex/hooks.json`. It runs `actplane feedback-hook` after each tool call and
injects any new `.actplane/last-violation.txt` content into the next model turn.
**Claude Code** (`.claude/settings.local.json`):
```json
{
"hooks": {
"PostToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "actplane feedback-hook" }] }],
"PostToolUseFailure": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "actplane feedback-hook" }] }]
}
}
```
**Codex** (`.codex/hooks.json`):
```json
{
"hooks": {
"PostToolUse": [{ "matcher": ".*", "hooks": [{ "type": "command", "command": "actplane feedback-hook" }] }]
}
}
```
The adapter forwards new rule matches as hook context. The kernel remains the sole
authority for observation and enforcement. See [`script/CLAUDE.snippet.md`](script/CLAUDE.snippet.md)
for the agent instruction snippet.
ActPlane also ships an MCP server:
```bash
actplane mcp --auto-attach-parent
```
It exposes `actplane:///policy` for live policy validation and
`actplane:///feedback` for the latest corrective feedback. When started by Codex,
`--auto-attach-parent` tries passwordless sudo, loads the eBPF engine, and seeds
the parent Codex process so directly running `codex` is protected.
Attach an already-started agent with a foreground engine:
```bash
sudo -E actplane attach --pid
```
Once an MCP auto-attach or `actplane watch` engine is already running, bind an
already-started subagent into a child runtime domain with:
```bash
actplane attach --pid --child-domain --domain-id
actplane attach --pid --child-domain --delta child-policy.dsl
```
`attach` is post-hoc: future events from that process tree enter ActPlane, but
ActPlane does not reconstruct labels or file/network history from before the
attach. For strict launch-time enforcement, start the process with
`actplane run ... -- ` or `actplane control launch-child ... -- `.
`actplane init --with-mcp` also writes project `.mcp.json`:
```json
{
"mcpServers": {
"actplane": {
"type": "stdio",
"command": "actplane",
"args": ["mcp", "--auto-attach-parent"]
}
}
}
```
Prefer the project `.mcp.json` that `actplane init --with-mcp` writes. If your Codex build
does not read project MCP config, use a global `codex mcp add actplane -- actplane
mcp --auto-attach-parent` entry instead, but do not keep both or auto-attach can
start twice.
## How it works
```
actplane.yaml ─▶ policy compiler ─▶ runtime/control ─▶ eBPF kernel engine
policy: | parse + lower DSL load + seed propagate labels,
domains match rules,
matches ◀─────── feedback/report ◀── ring buffer ◀──── emit on match only
```
- **Kernel** (`bpf/`): hooks `fork / exec / exit / open / unlink / rename / connect`,
keeps a per-node label set (process / file / endpoint), propagates labels,
evaluates compiled rules, emits only match events.
- **Policy compiler** (`crates/actplane-ifc-compiler/`): parses the ActPlane IFC
policy language and lowers it to the fixed kernel config ABI.
- **Runtime library** (`crates/actplane-runtime/`): resolves `actplane.yaml`,
loads the prebuilt eBPF object in-process via
[`ebpf-ifc-engine`](bpf/) (aya) — no libbpf/clang at runtime — seeds the target
process lineage, and reports rule matches with policy reasons.
- **CLI frontend** (`crates/actplane-cli/`): provides the `actplane` command,
project setup, policy review, MCP, and command dispatch.
## Build from source
`cargo install actplane` is all most users need. To hack on ActPlane:
```bash
git clone --recurse-submodules https://github.com/eunomia-bpf/ActPlane
cd ActPlane
cargo build --release -p actplane
```
Editing the kernel eBPF (`bpf/*.bpf.c`) requires the BPF toolchain
(clang/llvm, libelf, zlib) and the `libbpf`/`bpftool` submodules. Rebuild and
refresh the committed object with:
```bash
ACTPLANE_REBUILD_BPF=1 cargo build -p ebpf-ifc-engine # regenerates bpf/prebuilt/process.bpf.o
```
Run the tests:
```bash
make test # bpf C unit tests + Rust workspace unit tests
sudo bash script/e2e_examples.sh # live E1–E12 enforcement
```
## LICENSE
MIT License. See [LICENSE](LICENSE).