PolicyTLB GitHub

RESEARCH PROTOTYPE · LINUX eBPF LSM

Runtime policy control for
local MCP agents.

PolicyTLB is an in-progress research prototype that uses BPF LSM hooks and a TLB-hit-modeled three-tier decision pipeline to detect and block dangerous local agent behavior.

Inspect source Read the design
ENFORCEMENT
exec · file · socket
DECISION PATH
L1 → L2 → L3
INVALIDATION
global epoch
runtime decision pathBPF LSM
LOCAL MCP AGENTtool invocation
local activity
L1FAST PATH
Decision cache

epoch-valid lookup

0.018µs
L2SEMI-FAST
Cheap resource checks

safe & cacheable cases

0.023µs
L3DEEP CHECK
Policy match

path · command · socket

0.989µs
ENFORCEMENT RESULTallow / deny / audit

Documented cost-model values from the repository.

THE SECURITY GAP

Tool access needs
runtime policy control.

MCP gives LLM agents access to local tools, files, databases, and network resources. Prompt injection or agent hijacking can lead to unauthorized command execution, sensitive-file access, or outbound connections.

01

Command execution

Command-prefix policy matching is part of the exec decision path.

bprm_check_security
02

File access

File-path policy matching and resource-id lookups support the file access path.

file_open · file_permission
03

Socket connections

IPv4 and port rules are evaluated for socket connection decisions.

socket_connect

CACHE-FIRST ENFORCEMENT

Do not repeat the full
policy walk on every event.

PolicyTLB evaluates a resource at allocation, open, connect, or exec time, then stores the decision with the current global epoch. Repeated events can reuse an epoch-valid entry; misses fall through to a deeper layer.

  1. 01

    L1 · FAST PATH

    Look up the decision cache

    The cache key contains tgid, pid, hook, and resource id. An entry is used only when its epoch equals the current global epoch.

    hit → return
  2. 02

    L2 · SEMI-FAST PATH

    Check low-cost resource classes

    Some cases, such as selected non-regular files, can be handled without deep path or string matching.

    cheap → return
  3. 03

    L3 · SLOW PATH

    Run deep policy evaluation

    Generation-aware indexes evaluate path, command, socket, and resource rules and emit deny or audit events.

    match → cache

IMPLEMENTATION MAP

Attach L1 first.
Tail-call deeper only when needed.

Only the L1 programs are attached to LSM hooks. Internal L2 and L3 programs are reached through per-hook BPF tail-call program arrays.

PolicyTLB architectureeBPF LSM · user space control
PolicyTLB system architecture showing an MCP agent flowing through Linux system calls, LSM hooks, the L1/L2/L3 policy pipeline, policy maps, event output, loader, and GUI.
Architecture diagram from the PolicyTLB repository. It is documentation material under the repository's CC-BY-4.0 policy.

BUILT FOR INSPECTION

Keep the policy, measurement,
and validation paths inspectable.

The repository includes policy files, tests, metrics, and a controlled experiment harness for hook-internal policy-path latency and end-to-end workload overhead.

Inspect the repository
POLICY

Generation-aware lookups

LPM trie policy lookup covers file paths, command prefixes, and IPv4/port rules.

OBSERVABILITY

Events and metrics

Ring-buffer events are delivered to user space, while per-CPU metrics track hook, layer, and action.

VALIDATION

Controlled experiments

The harness keeps hook-internal policy latency separate from end-to-end workload time.

SCOPE

MCP agent scoping

A profile file and comm, pid, and tgid selectors can scope enforcement to an agent.

IMPORTANT CONTEXT

An in-progress research prototype.

The implementation, GUI, policy format, and experiment harness are intended for academic evaluation and controlled development environments, not production deployment.

Read the limits