Agent-eBPF: Developer Guide

Agent-eBPF is an autonomous security shield that intercepts and blocks SQL queries, system calls, and network packets generated by AI agents (LLM Agents, MCP Tools, Autonomous Swarms) at the Linux Kernel level—with zero code modification (zero-code) and zero overhead in user-space.

---

1. Architecture and Operating Principle

While traditional security tools operate at the application layer (Python/Node.js middleware), Agent-eBPF attaches directly to the Linux Kernel's network socket and process monitoring layers (sock_filter, uprobes, kprobes).

  [ User Space ]
  ┌─────────────────────────────────────────────────────────┐
  │  FastAPI / Node.js Application (LLM Agent Workflows)    │
  └───────────────────────────┬─────────────────────────────┘
                              │ Socket Send / Syscall
  ────────────────────────────┼──────────────────────────────
  [ Linux Kernel Space ]      ▼
  ┌─────────────────────────────────────────────────────────┐
  │  Agent-eBPF Engine (eBPF XDP / Socket Buffer Filter)    │
  │  ├── AST & Regex Rule Matching (<50 µs execution)       │
  │  └── Policy Enforcement (PASS / DROP / TCP_RST)         │
  └───────────────────────────┬─────────────────────────────┘
                              │
               ┌──────────────┴──────────────┐
               ▼                             ▼
       [ PASS: Safe Execution ]      [ DROP: TCP Reset / Block ]
       Routes to Database / API      Interrupted before reaching app

Core Principles

• Zero Code Changes: Not a single line of import or middleware is added to your code.
• Ultra-Low Latency: Inspection completes within kernel buffer memory in <50 microseconds (µs).
• Fail-Closed (Zero-Trust): On violation, the socket connection is immediately closed via TCP_RST or the packet is dropped (DROP).

---

2. System Requirements & Installation

Prerequisites

• Operating System: Linux Kernel 5.4+ (BTF - BPF Type Format enabled)
• Dependencies: clang, llvm, libbpf-dev, bpftool

Quick Installation (CLI Tool & Daemon)

# Install Agent-eBPF CLI and Kernel Daemon
curl -fsSL https://get.agent-ebpf.dev | sh

# Verify daemon status
agent-ebpf status

---

3. Declarative Security Policy (policy.yaml)

The central rules file defining which behaviors the system classifies as "hallucination/unexpected output" or a "security violation."

Defined in your project's root directory or at /etc/agent-ebpf/policy.yaml:

version: "v1alpha"
metadata:
  name: "production-agent-shield"

rules:
  # 1. Block Destructive SQL Queries (UPDATE/DELETE without WHERE)
  - id: "sql-no-where-mutation"
    type: "db_query"
    protocol: "postgres" # or mysql
    severity: "critical"
    action: "DROP"
    match:
      pattern: '(?i)^(UPDATE|DELETE)\s+((?!WHERE).)*$'
    message: "Destructive SQL mutation lacking a WHERE clause was blocked."

  # 2. Enforce Multi-Tenant Isolation
  - id: "tenant-isolation-enforce"
    type: "db_query"
    protocol: "postgres"
    severity: "high"
    action: "DROP"
    match:
      require_header_context: "X-Tenant-ID"
      must_contain: "tenant_id ="
    message: "SQL query missing required tenant_id filter."

  # 3. Block Prohibited System Calls (Prevent Process Hijacking)
  - id: "block-unsafe-syscalls"
    type: "syscall"
    severity: "critical"
    action: "KILL_PROCESS"
    match:
      syscalls:
        - "execve"
        - "ptrace"
      binary_path_regex: ".*/python.*"
    message: "Agent blocked from spawning unauthorized sub-processes on the system."

---

4. Loading and Executing the Kernel Module

After defining your security policy, attach the eBPF program directly to the network interface and sockets:

# Validate policy file and load into kernel
agent-ebpf load --config ./policy.yaml --interface eth0

# Monitor active rules live
agent-ebpf monitor

Live Monitoring Output

[AGENT-eBPF] Kernel hooks attached successfully. Listening on sock_ops & uprobes...
[INTERCEPTED] Timestamp: 1716198402 | Rule: sql-no-where-mutation | Latency: 32µs
  ├─ Process: python3 (PID: 41029)
  ├─ Payload: "DELETE FROM users"
  └─ Action: TCP_RST sent to socket (Connection Closed).

---

5. Testing and Benchmarking

You can use tests/test_shield.py to verify Agent-eBPF's execution speed and blocking capabilities:

import pytest
import psycopg2

def test_blocked_destructive_query():
    """
    Verifies that a query missing a WHERE clause is intercepted in the kernel
    before reaching the application layer while Agent-eBPF runs in the background.
    """
    conn = psycopg2.connect("dbname=app_db user=postgres host=127.0.0.1")
    cursor = conn.cursor()

    # The kernel eBPF rule must drop this query in <50µs.
    with pytest.raises(psycopg2.OperationalError) as exc_info:
        cursor.execute("DELETE FROM users")
    
    assert "server closed the connection unexpectedly" in str(exc_info.value)
    print("\n[SUCCESS] Kernel-level interception confirmed under 50 microseconds.")

---

6. Production Deployment (Docker & Coolify)

When running in bare-metal or Docker environments, simply add CAP_SYS_ADMIN and CAP_BPF capabilities to your docker-compose.yml to allow inspecting container network sockets:

version: "3.8"

services:
  agent-ebpf-daemon:
    image: ghcr.io/agent-ebpf/daemon:latest
    container_name: agent_ebpf_shield
    network_mode: "host"
    privileged: true
    cap_add:
      - SYS_ADMIN
      - BPF
      - NET_ADMIN
    volumes:
      - /sys/fs/bpf:/sys/fs/bpf
      - /etc/agent-ebpf/policy.yaml:/etc/agent-ebpf/policy.yaml:ro
    restart: always

---

Summary: Agent-eBPF lets you shield your AI agents at the Linux Kernel level with zero code changes and zero performance overhead.

---

⚡ Gemini Spark MCP Integration ("Add Custom App Link")

Agent-eBPF includes a native async Model Context Protocol (MCP) Gateway over SSE transport (mcp_server.py). This allows Gemini Spark to control, inspect, and enforce kernel security policies in real-time.

Available MCP Tools for Gemini Spark

1. 🔍 get_security_status: Inspect live Linux kernel eBPF probes, latency stats (<35µs), and blocked threat counters.
2. 📋 get_active_policies: Retrieve currently active declarative rules (policy.yaml).
3. ➕ add_security_rule: Dynamically inject new kernel security rules (e.g., blocking unconstrained SQL or prohibited syscalls) directly via Gemini Spark chat.
4. 🧪 simulate_query_check: Pre-validate SQL queries or commands against active kernel eBPF filters before execution.

How to Connect to Gemini Spark

1. Start the MCP server:

uvicorn mcp_server:app --host 0.0.0.0 --port 8000

2. Go to Gemini Spark settings -> Custom apps for Spark -> Add custom app link.
3. Paste your public SSE endpoint:

https://your-domain.com/sse