eBPF Firewall

The Carapace eBPF firewall provides kernel-level network observability for AI agents. It intercepts SSL/TLS traffic at the kernel level, scans it through the Carapace prompt injection scanner, and can block malicious content before it reaches its destination — all without modifying any running process.

How it works

Application (agent)
  → SSL_write() / SSL_read()
    → eBPF uprobe captures plaintext
      → Ring buffer → Node.js consumer
        → Carapace scanner
          → PASS or BLOCK

The firewall attaches uprobes to SSL_write and SSL_read functions in the system’s SSL library. These probes fire whenever any process makes an SSL call, capturing the plaintext content before encryption (on write) and after decryption (on read).

This means the firewall sees exactly what the LLM sees — no MITM proxy, no certificate manipulation, no process injection.

Key properties

Property	Detail
Zero process modification	No LD_PRELOAD, no proxy config, no code changes
Plaintext capture	Sees content before SSL encryption / after decryption
Ring buffer streaming	Events flow from kernel to userspace via BPF ring buffer
PASS/BLOCK actions	Scanner verdict determines if traffic proceeds
All processes	Captures SSL from any process on the system

Architecture

Kernel space

The eBPF program attaches to two probe points:

• SSL_write uprobe: Captures outbound plaintext (what the agent sends to the LLM)
• SSL_read uretprobe: Captures inbound plaintext (what the LLM returns to the agent)

Each captured buffer is pushed to a BPF ring buffer with metadata (PID, timestamp, direction, length).

User space

A Node.js consumer reads from the ring buffer and processes events:

1. Parse: Extract PID, direction, and plaintext content
2. Scan: Run Carapace scanner on the content
3. Decide: PASS (allow) or BLOCK (reject)
4. Log: Record event for Nectar audit trail

Two backends

Backend	Implementation	Dependencies
ssl-monitor.js	Node.js with vendored node-ebpf native addon	Linux 5.8+, libbpf-dev, clang
ssl-intercept.py	Python with BCC (BPF Compiler Collection)	Python 3, bcc-tools

Both produce identical event streams. The Node.js backend integrates directly with the Carapace scanner. The Python backend is useful for standalone monitoring.

Requirements

• Linux 5.8+ (BPF ring buffer support)
• libbpf-dev and clang (BPF program compilation)
• root or CAP_BPF capability
• OpenSSL or BoringSSL (probe targets)

The firewall does not work on macOS or Windows (no BPF support). For development on those platforms, use the Carapace proxy or MCP proxy instead.

CLI

# Start the firewall
carapace-firewall start

# Stop the firewall
carapace-firewall stop

# Start with proxy mode (intercept + forward)
carapace-firewall proxy

# Run test suite
carapace-firewall test

What it captures

Direction	Content	Example
Outbound	Agent → LLM requests	System prompts, user messages, tool calls
Inbound	LLM → Agent responses	Completions, tool results

Combined with Nectar’s audit trail, this provides complete visibility into what every agent said and what every LLM returned — at the kernel level.

Integration with Nectar

The eBPF firewall feeds events into the Nectar audit layer:

eBPF event → Carapace scan → Nectar record
  ├── trace_id (correlates with agent session)
  ├── direction (outbound / inbound)
  ├── pid (which process)
  ├── content (plaintext, if audit mode)
  ├── scan_result (PASS / BLOCK, score, findings)
  └── timestamp

This creates an unbreakable chain of evidence: you can prove exactly what every agent sent to every LLM, what came back, and whether any prompt injection was detected.

Why eBPF (not a proxy)

Approach	Pros	Cons
HTTP proxy	Easy setup, portable	Requires config per process, adds latency, MITM cert issues
LD_PRELOAD	No process config needed	Fragile, doesn’t work with static linking
eBPF	Zero config, zero latency, zero modification	Linux only, requires root/CAP_BPF

For production Linux deployments (VPS, containers, bare metal), eBPF is strictly superior. For development and non-Linux platforms, the Carapace proxy is the recommended alternative.

Related

• Scanner — how Carapace detection works
• Audit Trail — what Nectar captures
• Carapace product page — full product overview