Kernel-level behavioral containment for AI agents using eBPF/LSM.

---

NeuronTrace enforces default-deny policies on AI agent processes at the kernel level. Unlike application-layer sandboxes, agents cannot bypass enforcement — the kernel blocks syscalls before they execute.

Key Features

• BPF-LSM hooks: Intercepts exec, file open, unlink, rename, connect, ptrace, and task_kill at kernel level
• Default-deny: No policy rule = blocked. Agents start with zero permissions
• Generation tagging: Invalidate stale permissions when an agent starts a new task — no data leaks across generations
• Cgroup scoping: Enforcement targets only the agent process tree, not your entire system
• Path/glob filtering: Fine-grained rules with glob patterns (e.g. allow /usr/bin/git, block everything else)
• Self-protection: BPF programs pinned to survive userspace crash; task_kill hook prevents agents from killing the controller
• Audit-only mode: Observe agent behavior without blocking — safe onboarding before enforcement
• Starter policies: Pre-built YAML policies for Claude Code, Codex, and generic agents

Installation

Pre-built binaries (recommended)

Download the latest release for your architecture:

# x86_64
curl -LO https://github.com/yasindce1998/NeuronTrace/releases/latest/download/neurontrace-x86_64-unknown-linux-gnu.tar.gz
tar xzf neurontrace-x86_64-unknown-linux-gnu.tar.gz
sudo mv neurontrace /usr/local/bin/

# aarch64
curl -LO https://github.com/yasindce1998/NeuronTrace/releases/latest/download/neurontrace-aarch64-unknown-linux-gnu.tar.gz
tar xzf neurontrace-aarch64-unknown-linux-gnu.tar.gz
sudo mv neurontrace /usr/local/bin/

Build from source

git clone https://github.com/yasindce1998/NeuronTrace.git
cd NeuronTrace
cargo xtask build --release

Requires Rust nightly and a working eBPF toolchain. See the Development Guide for full setup.

Requirements

• Linux kernel 5.15+ with BTF enabled
• BPF-LSM enabled (CONFIG_BPF_LSM=y, lsm=bpf in boot params)
• Root privileges (for BPF program loading)

Quick Start

# If built from source:
cargo xtask build --release

# See enforcement in action — one command, handles everything
sudo ./scripts/demo.sh

The demo creates a cgroup, starts NeuronTrace, runs test commands that get blocked by the kernel, shows the violation log, and cleans up. No second terminal needed.

Full quickstart guide →

Manual usage

# Run with a specific policy
sudo ./target/release/neurontrace run \
  --policy policies/claude-code.yaml \
  --cgroup /sys/fs/cgroup/neurontrace

# Observe without blocking (audit-only mode)
sudo ./target/release/neurontrace run \
  --policy policies/claude-code.yaml \
  --cgroup /sys/fs/cgroup/neurontrace \
  --audit-only

# Check enforcement status
sudo ./target/release/neurontrace status

# Validate a policy without loading BPF
cargo run --package neurontrace -- validate --policy policies/generic-agent.yaml

# Bump generation (invalidate stale labels)
sudo ./target/release/neurontrace bump

# Stop enforcement and unpin BPF programs
sudo ./target/release/neurontrace unload

Project Structure

neurontrace/          Userspace binary — CLI, BPF loader, policy engine
neurontrace-ebpf/    BPF programs — LSM hooks (no_std, runs in kernel)
neurontrace-common/  Shared types between kernel and userspace
xtask/               Build automation
policies/            Starter policy packs (YAML)

How It Works

1. Load: The userspace binary loads BPF programs into the kernel via aya
2. Attach: LSM hooks fire on every relevant syscall within the target cgroup
3. Check: Each hook looks up the policy map — no match means block
4. Report: Violations emit events via ring buffer back to userspace
5. Feedback: Violations are serialized as JSON and delivered to a Unix socket (or JSONL file), so the agent can self-correct

Writing Policies

Policies are YAML files with a list of rules. Each rule maps an event type to an action, with optional path/argv glob filters:

name: my-policy
description: Custom policy for my agent
rules:
  - event_type: exec
    action: allow
    path: "/usr/bin/git"
  - event_type: exec
    action: block
  - event_type: open
    action: allow
  - event_type: connect
    action: audit

Actions: allow, block, kill, audit

Event types: exec, open, unlink, rename, connect, ptrace, task_kill

Rules support path and argv glob patterns for fine-grained filtering. See Policy Reference.

Documentation

Doc	Description
Quick Start	Install and see enforcement in one command
Architecture	System design, data flow, BPF maps, security model
Policy Reference	Schema, event types, actions, examples
Feedback Protocol	Structured violation events for agent self-correction
Use Cases	8 real-world scenarios with ready-to-use policies
Agent Adapters	Hook scripts for Claude Code, Codex, Gemini CLI
Development Guide	Kernel setup, building, VM testing, debugging
Contributing	How to contribute, code style, CI
Security Policy	Reporting vulnerabilities
Changelog	What's changed

License

MIT