eBPF Fundamentals for Rust Security Engineers

Introduction

Extended Berkeley Packet Filter (eBPF) has revolutionized how we build security monitoring and observability tools in Linux. By allowing safe execution of custom programs in kernel space, eBPF enables unprecedented visibility into system behavior with minimal performance overhead. When combined with Rust’s memory safety guarantees, we get a powerful platform for building robust security tools.

In this comprehensive guide, we’ll explore eBPF fundamentals through the lens of Rust development, using the Aya framework to build our first kernel-level security monitoring tool.

Why eBPF + Rust for Security?

The eBPF Advantage

eBPF programs run directly in the kernel, providing:

• Zero-copy observability: Access kernel data without expensive context switches
• Production safety: Verified programs cannot crash the kernel
• High performance: JIT-compiled to native code
• Dynamic loading: Deploy monitoring without kernel modifications

The Rust Advantage

Rust brings additional benefits to eBPF development:

• Memory safety: Compile-time guarantees prevent common security vulnerabilities
• Type safety: Strong typing catches errors before deployment
• Zero-cost abstractions: High-level code compiles to efficient machine code
• Ecosystem: Growing collection of security-focused libraries

Understanding eBPF Architecture

Core Components

// eBPF architecture components
┌─────────────────────────────────────────────────┐
│                  User Space                      │
│  ┌─────────────┐  ┌─────────────┐              │
│  │ Rust App    │  │ Aya Library │              │
│  └──────┬──────┘  └──────┬──────┘              │
│         │                 │                      │
│         └────────┬────────┘                     │
│                  │                              │
├──────────────────┼──────────────────────────────┤
│                  │         Kernel Space         │
│         ┌────────▼────────┐                    │
│         │   BPF Syscall   │                    │
│         └────────┬────────┘                    │
│                  │                              │
│         ┌────────▼────────┐                    │
│         │  BPF Verifier   │                    │
│         └────────┬────────┘                    │
│                  │                              │
│         ┌────────▼────────┐                    │
│         │   JIT Compiler  │                    │
│         └────────┬────────┘                    │
│                  │                              │
│         ┌────────▼────────┐                    │
│         │ eBPF Program    │                    │
│         │ (Running)       │                    │
│         └─────────────────┘                    │
└─────────────────────────────────────────────────┘

Program Types for Security

eBPF supports various program types relevant to security:

1. kprobe/kretprobe: Trace kernel function calls
2. tracepoint: Monitor predefined kernel events
3. XDP: Process network packets at the earliest stage
4. LSM: Implement custom security policies
5. cgroup: Apply policies to process groups

Setting Up Your Development Environment

Prerequisites

# Install Rust and cargo
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install bpf-linker for compiling eBPF programs
cargo install bpf-linker

# Install dependencies (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install -y \
    llvm \
    clang \
    linux-headers-$(uname -r) \
    linux-tools-common \
    linux-tools-$(uname -r)

# Verify kernel support (requires Linux 5.8+)
uname -r

Project Structure

# Create new project
cargo new --bin rust-ebpf-security
cd rust-ebpf-security

# Project structure
rust-ebpf-security/
├── Cargo.toml
├── src/
│   └── main.rs
├── ebpf/
│   ├── Cargo.toml
│   └── src/
│       └── main.rs
└── xtask/
    ├── Cargo.toml
    └── src/
        └── main.rs

Workspace Configuration

# Cargo.toml (root)
[workspace]
members = ["xtask", "ebpf"]

[dependencies]
aya = "0.12"
aya-log = "0.2"
clap = { version = "4.4", features = ["derive"] }
env_logger = "0.11"
log = "0.4"
tokio = { version = "1.35", features = ["macros", "rt-multi-thread", "signal"] }

[profile.release]
opt-level = 3
lto = true
codegen-units = 1

Building Your First Security Monitor

Let’s build a process execution monitor that tracks all new processes with their command-line arguments.

eBPF Program (Kernel Space)

// ebpf/src/main.rs
#![no_std]
#![no_main]

use aya_ebpf::{
    macros::{kprobe, map},
    maps::HashMap,
    programs::ProbeContext,
    helpers::bpf_get_current_pid_tgid,
    cty::c_long,
};
use aya_log_ebpf::info;

#[repr(C)]
pub struct ProcessInfo {
    pub pid: u32,
    pub ppid: u32,
    pub uid: u32,
    pub gid: u32,
    pub comm: [u8; 16],
}

#[map]
static mut PROCESSES: HashMap<u32, ProcessInfo> = HashMap::with_max_entries(10240, 0);

#[kprobe]
pub fn trace_execve(ctx: ProbeContext) -> u32 {
    match unsafe { trace_execve_inner(&ctx) } {
        Ok(ret) => ret,
        Err(ret) => ret,
    }
}

unsafe fn trace_execve_inner(ctx: &ProbeContext) -> Result<u32, u32> {
    // Get current process info
    let pid_tgid = bpf_get_current_pid_tgid();
    let pid = (pid_tgid >> 32) as u32;
    let tgid = pid_tgid as u32;

    // Get process comm (command name)
    let mut comm = [0u8; 16];
    if let Err(e) = bpf_probe_read_kernel_buf(&mut comm, ctx.regs.di as *const u8) {
        return Err(1);
    }

    // Create process info structure
    let info = ProcessInfo {
        pid,
        ppid: 0, // Would need additional syscall to get parent
        uid: 0,  // Would need bpf_get_current_uid_gid()
        gid: 0,
        comm,
    };

    // Store in map
    PROCESSES.insert(&pid, &info, 0).map_err(|_| 2)?;

    info!(&ctx, "New process: PID={} COMM={:?}", pid, core::str::from_utf8(&comm));

    Ok(0)
}

#[panic_handler]
fn panic(_info: &core::panic::PanicInfo) -> ! {
    unsafe { core::hint::unreachable_unchecked() }
}

User Space Application

// src/main.rs
use aya::{
    include_bytes_aligned,
    maps::HashMap,
    programs::KProbe,
    Bpf,
};
use aya_log::BpfLogger;
use clap::Parser;
use log::{info, warn, debug};
use std::time::Duration;
use tokio::signal;

#[derive(Debug, Parser)]
struct Args {
    /// Path to the eBPF program
    #[clap(short, long, default_value = "./target/bpfel-unknown-none/release/ebpf")]
    bpf_path: String,
}

#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct ProcessInfo {
    pub pid: u32,
    pub ppid: u32,
    pub uid: u32,
    pub gid: u32,
    pub comm: [u8; 16],
}

#[tokio::main]
async fn main() -> Result<(), anyhow::Error> {
    env_logger::init();
    let args = Args::parse();

    // Load eBPF program
    let mut bpf = Bpf::load(include_bytes_aligned!(
        "../target/bpfel-unknown-none/release/ebpf"
    ))?;

    // Initialize eBPF logger
    if let Err(e) = BpfLogger::init(&mut bpf) {
        warn!("Failed to initialize eBPF logger: {}", e);
    }

    // Load and attach kprobe
    let program: &mut KProbe = bpf.program_mut("trace_execve").unwrap().try_into()?;
    program.load()?;
    program.attach("__x64_sys_execve", 0)?;

    info!("eBPF program attached. Monitoring process execution...");

    // Get reference to the process map
    let mut processes: HashMap<_, u32, ProcessInfo> = HashMap::try_from(
        bpf.map_mut("PROCESSES").unwrap()
    )?;

    // Monitor processes
    let mut interval = tokio::time::interval(Duration::from_secs(1));

    loop {
        tokio::select! {
            _ = interval.tick() => {
                // Read and display process information
                for item in processes.iter() {
                    if let Ok((pid, info)) = item {
                        let comm = std::str::from_utf8(&info.comm)
                            .unwrap_or("<invalid>")
                            .trim_end_matches('\0');

                        info!(
                            "Process detected - PID: {}, Command: {}, UID: {}, GID: {}",
                            pid, comm, info.uid, info.gid
                        );

                        // Remove from map after reading
                        let _ = processes.remove(&pid);
                    }
                }
            }
            _ = signal::ctrl_c() => {
                info!("Received Ctrl-C, shutting down...");
                break;
            }
        }
    }

    Ok(())
}

Building and Running

# Build eBPF program
cargo xtask build-ebpf

# Build user space application
cargo build --release

# Run with elevated privileges
sudo ./target/release/rust-ebpf-security

# In another terminal, trigger some process executions
ls
ps aux
echo "Hello, eBPF!"

Advanced Security Monitoring Patterns

1. File Access Monitoring

// Monitor sensitive file access
#[kprobe]
pub fn trace_openat(ctx: ProbeContext) -> u32 {
    match unsafe { trace_openat_inner(&ctx) } {
        Ok(ret) => ret,
        Err(ret) => ret,
    }
}

unsafe fn trace_openat_inner(ctx: &ProbeContext) -> Result<u32, u32> {
    // Get filename from syscall arguments
    let filename_ptr = ctx.arg::<*const u8>(1).ok_or(1)?;
    let mut filename = [0u8; 256];

    // Read filename from user space
    bpf_probe_read_user_str_bytes(filename_ptr, &mut filename)
        .map_err(|_| 2)?;

    // Check if it's a sensitive file
    const SENSITIVE_FILES: &[&[u8]] = &[
        b"/etc/passwd",
        b"/etc/shadow",
        b"/root/.ssh/",
    ];

    for sensitive in SENSITIVE_FILES {
        if filename.starts_with(sensitive) {
            // Log security event
            let pid = bpf_get_current_pid_tgid() >> 32;
            info!(&ctx, "SECURITY: PID {} accessed sensitive file: {:?}",
                  pid, core::str::from_utf8(&filename));
        }
    }

    Ok(0)
}

2. Network Connection Monitoring

// Monitor outbound connections
#[kprobe]
pub fn trace_tcp_connect(ctx: ProbeContext) -> u32 {
    match unsafe { trace_tcp_connect_inner(&ctx) } {
        Ok(ret) => ret,
        Err(ret) => ret,
    }
}

unsafe fn trace_tcp_connect_inner(ctx: &ProbeContext) -> Result<u32, u32> {
    // Get socket structure
    let sk = ctx.arg::<*const sock>(0).ok_or(1)?;

    // Read destination address
    let daddr = (*sk).sk_daddr;
    let dport = (*sk).sk_dport;

    // Convert to human-readable format
    let addr = u32::from_be(daddr);
    let port = u16::from_be(dport);

    // Check for suspicious ports
    const SUSPICIOUS_PORTS: &[u16] = &[22, 23, 3389, 4444, 5555];

    if SUSPICIOUS_PORTS.contains(&port) {
        let pid = bpf_get_current_pid_tgid() >> 32;
        info!(&ctx, "SECURITY: PID {} connected to {}:{}",
              pid, addr, port);
    }

    Ok(0)
}

3. Syscall Filtering

// Block specific syscalls based on security policy
#[lsm]
pub fn block_ptrace(ctx: LsmContext) -> i32 {
    // Check if it's a ptrace syscall
    if ctx.function_name() == b"ptrace_access_check" {
        // Get calling process info
        let pid = bpf_get_current_pid_tgid() >> 32;

        // Check against allowlist
        const ALLOWED_PIDS: &[u32] = &[1, 2]; // systemd, kernel threads

        if !ALLOWED_PIDS.contains(&pid) {
            info!(&ctx, "BLOCKED: PID {} attempted ptrace", pid);
            return -1; // EPERM
        }
    }

    0 // Allow
}

Performance Considerations

Optimization Techniques

1. Use per-CPU maps for high-frequency events:

#[map]
static mut EVENTS: PerCpuArray<EventData> = PerCpuArray::with_max_entries(1, 0);

2. Implement sampling to reduce overhead:

// Only process every Nth event
if count % SAMPLE_RATE != 0 {
    return Ok(0);
}

3. Use ring buffers for efficient data transfer:

#[map]
static mut EVENTS: RingBuf = RingBuf::with_byte_size(1024 * 1024, 0);

Benchmarking Results

Security Best Practices

1. Validate All Input

// Always validate data from kernel
let len = core::cmp::min(filename.len(), MAX_PATH_LEN);
bpf_probe_read_user_str_bytes(ptr, &mut filename[..len])?;

2. Handle Errors Gracefully

// Never panic in eBPF programs
match operation() {
    Ok(result) => process(result),
    Err(_) => return 0, // Silent fail
}

3. Implement Rate Limiting

// Prevent DoS through excessive logging
#[map]
static mut RATE_LIMIT: HashMap<u32, u64> = HashMap::with_max_entries(1024, 0);

// Check rate limit before processing
if should_rate_limit(pid)? {
    return Ok(0);
}

4. Use Proper Permissions

// Check capabilities before loading
if !capabilities::has_cap_bpf() {
    return Err("Requires CAP_BPF capability");
}

Troubleshooting Common Issues

Verifier Errors

# Enable verbose verifier output
sudo bpftool prog load program.o /sys/fs/bpf/program type kprobe \
    pinmaps /sys/fs/bpf/map -d

# Common fixes:
# - Ensure bounded loops
# - Validate all pointer access
# - Check stack usage (<512 bytes)

Performance Issues

// Profile your eBPF programs
#[kprobe]
pub fn profile_overhead(ctx: ProbeContext) -> u32 {
    let start = bpf_ktime_get_ns();

    // Your monitoring logic here

    let duration = bpf_ktime_get_ns() - start;
    LATENCY_HISTOGRAM.increment(duration);

    0
}

Real-World Applications

1. Runtime Security

• Process behavior analysis
• Anomaly detection
• Container escape prevention
• Rootkit detection

2. Compliance Monitoring

• File integrity monitoring
• Access control audit
• Network policy enforcement
• Data loss prevention

3. Threat Hunting

• Suspicious process detection
• Lateral movement tracking
• Command and control detection
• Forensic data collection

Next Steps

Now that you understand eBPF fundamentals in Rust, you’re ready to:

1. Explore advanced program types (XDP, TC, LSM)
2. Build production monitoring systems
3. Integrate with SIEM platforms
4. Contribute to the Aya ecosystem

Resources

• Aya Book - Official Aya documentation
• eBPF.io - eBPF community resources
• Linux Kernel BPF Docs - Kernel documentation
• Awesome eBPF - Curated eBPF resources

Conclusion

eBPF with Rust provides a powerful platform for building next-generation security tools. The combination of kernel-level visibility, performance efficiency, and memory safety makes it ideal for production security monitoring.

Start with simple monitors, validate thoroughly, and gradually build more complex security tools. The kernel is your playground - use it wisely and securely!

Ready to build production eBPF security tools? Check out our next article on Building Production eBPF Security Monitors where we’ll create a complete security monitoring system.