ebee - eBPF the Hard Way!

This repository contains various eBPF tools originally from the BCC project, reimplemented from scratch to help users learn eBPF development step by step.

🎯 Project Goal

The idea for this project is to help users learn creating eBPF tools with a comprehensive step-by-step guide. Each tool includes detailed documentation explaining the underlying concepts, kernel hooks, data structures, and implementation details.

🧠 What is eBPF?

eBPF (extended Berkeley Packet Filter) is a revolutionary technology that allows you to run sandboxed programs in the Linux kernel without changing kernel source code or loading kernel modules. It enables:

Real-time system monitoring - Track processes, files, network activity
Performance analysis - Measure latency, throughput, resource usage
Security monitoring - Detect malicious behavior and policy violations
Custom debugging - Create tailored debugging tools for your applications

🎓 What You'll Learn

By working through this project, you'll gain hands-on experience with:

eBPF fundamentals - Understanding the eBPF virtual machine and verifier
Kernel programming - Writing C programs that run in kernel space
Tracepoints and kprobes - Hooking into kernel events and functions
Data structures - Using eBPF maps for efficient data sharing
Go integration - Building userspace applications with the Cilium eBPF library
Performance optimization - Creating efficient monitoring tools
Security analysis - Building tools for system security and compliance

⚙️ Prerequisites

System Requirements

Linux Kernel: 4.18+ (5.0+ recommended for full feature support)
Architecture: x86_64, arm64
BTF Support: Required for modern eBPF development
Root Access: Required for loading eBPF programs

🚀 Quick Start

Prerequisites Setup

Linux

# Install all requirements using the Makefile
make install

macOS

Since eBPF development requires Linux kernel headers and tools, we use Lima to run Ubuntu:

# Install/upgrade Lima + guest agents
brew install lima lima-additional-guestagents || brew upgrade lima lima-additional-guestagents

# Start Ubuntu VM with our configuration
limactl start scripts/default.yaml --name=default --timeout 30m

# Connect to the VM
limactl shell default

# Now run the Linux setup
make install

Build ebee

# Generate kernel headers (required for eBPF development)
make gen_vmlinux

# Install dependencies and build
make deps
make build

🔧 Quick Examples

# Monitor all process executions
sudo ./ebee execsnoop

# Monitor file deletions  
sudo ./ebee rmdetect

# Filter by specific process
sudo ./ebee execsnoop --comm bash

📚 Available Tools

Tool	Status	Category	Description	Kernel Hook
execsnoop	✅ Available	Process Monitoring	Monitor process executions in real-time	`sched_process_exec` tracepoint
rmdetect	✅ Available	File System	Monitor file deletions in real-time	`ext4_free_inode` tracepoint
opensnoop	🚧 Planned	File System	Monitor file opens in real-time	`vfs_open` kprobe
tcpconnect	🚧 Planned	Network	Monitor TCP connections	`tcp_connect` kprobe
tcpaccept	🚧 Planned	Network	Monitor TCP accepts	`tcp_accept` kprobe
biolatency	🚧 Planned	Storage	Monitor block I/O latency	`block_rq_insert/complete`
syscount	🚧 Planned	System	Count system calls by process	syscall tracepoints
funclatency	🚧 Planned	Performance	Measure function latency	kprobes/kretprobes
stackcount	🚧 Planned	Performance	Count stack traces	perf events
profile	🚧 Planned	Performance	CPU profiling	perf events

Tool Categories

Process Monitoring - Track process lifecycle and execution
File System - Monitor file operations and changes
Network - Analyze network connections and traffic
Storage - Monitor disk I/O and storage performance
System - Track system calls and kernel events
Performance - Measure latency, throughput, and resource usage

Each tool includes comprehensive documentation in the docs/ folder with implementation details, usage examples, and troubleshooting guides.

🛠️ Development

Adding New Commands

Create the eBPF C program in bpf/your_tool.c
Create the Go command in cmd/your_tool.go
Update Makefile generate target to include your C file
Add documentation in docs/your_tool.md following the template
Update this README to include your new tool

Documentation Structure

Each tool should include:

What it does - Purpose and use cases
How it works - Technical implementation details
Kernel hooks used - Which tracepoints/kprobes are attached
Data structures - eBPF maps and event structures
Step-by-step guide - Implementation walkthrough
Usage examples - Command-line examples

📖 Documentation

Comprehensive documentation covering everything from basics to advanced production deployment:

📚 Learning Materials

Complete Documentation - Full learning guide
Getting Started - Environment setup and eBPF introduction
Core Concepts - eBPF fundamentals and architecture
First Tool Tutorial - Step-by-step tool creation

🚀 Advanced Topics

CO-RE & BTF - Portable eBPF development with CO-RE
Network Programming - XDP, TC, packet processing
Security Monitoring - LSM hooks, security events
Testing Strategies - Unit/integration testing frameworks
Performance Optimization - Production optimization techniques

🛠️ Tool Documentation

execsnoop - Process execution monitoring
rmdetect - File deletion detection
Network Tools - DDoS protection, load balancing
Security Tools - File access, process monitoring

📋 Reference & Troubleshooting

Troubleshooting Guide - Debug techniques, common issues
Best Practices - Production deployment patterns
API Reference - Helper functions and APIs

🏗️ Project Structure

ebee/
├── cmd/                    # CLI commands
├── bpf/                   # eBPF C programs
│   └── headers/           # BPF headers
├── docs/                  # Documentation
│   ├── tools/            # Tool-specific docs
│   └── development-setup.md
├── scripts/              # Setup scripts
├── main.go               # Application entry point
└── Makefile              # Build and development tasks

🤝 Contributing

We welcome contributions! Whether you're fixing bugs, adding new tools, or improving documentation, your help makes this project better for everyone.

🚀 Quick Start for Contributors

Fork and clone the repository
Set up your development environment following our Development Setup Guide
Pick an issue or propose a new tool from our planned tools table
Follow our contribution guidelines below

📋 Contribution Types

🔧 Adding New eBPF Tools

Perfect for learning eBPF development:

Step-by-step process:

Choose a tool from our planned tools table or propose a new one
Create an issue describing the tool's purpose and implementation approach

Implement the tool following our patterns:

# 1. Create eBPF C program
touch bpf/yourtool.c

# 2. Create Go command
mkdir -p cmd
touch cmd/yourtool.go

# 3. Add to Makefile generate target
# 4. Create documentation
touch docs/tools/yourtool.md

Test thoroughly on multiple kernel versions
Submit a pull request with comprehensive documentation

📖 Documentation Improvements

Great for first-time contributors:

Fix typos or unclear explanations
Add more examples and use cases
Improve troubleshooting guides
Translate documentation

🐛 Bug Fixes

Help make the project more reliable:

Fix compilation issues
Resolve runtime errors
Improve error handling
Fix documentation inconsistencies

⚡ Performance Optimizations

For advanced contributors:

Optimize eBPF program efficiency
Improve memory usage
Reduce kernel/userspace communication overhead

📝 Code Standards

eBPF C Code

// File header with purpose
#include "common.h"

// Clear data structures with comments
struct data_t {
    u32 pid;        // Process ID
    char comm[16];  // Command name
};

// Descriptive function names
SEC("tracepoint/category/event")
int trace_event_name(struct trace_event_raw_event *ctx) {
    // Error handling first
    struct data_t *data = bpf_ringbuf_reserve(&events, sizeof(struct data_t), 0);
    if (!data) {
        return 0;
    }
    
    // Clear logic with safe memory access
    data->pid = bpf_get_current_pid_tgid() & 0xFFFFFFFF;
    bpf_get_current_comm(&data->comm, sizeof(data->comm));
    
    bpf_ringbuf_submit(data, 0);
    return 0;
}

char _license[] SEC("license") = "GPL";

Go Code

// Follow Go conventions
var toolCmd = &cobra.Command{
    Use:   "toolname",
    Short: "Brief description",
    Long: `Detailed description with examples:

Examples:
  ebee toolname                    # Basic usage
  ebee toolname --pid 1234        # Filter by PID
  ebee toolname --comm bash       # Filter by command`,
    Run: runTool,
}

// Clear error handling
func runTool(cmd *cobra.Command, args []string) {
    if err := doSomething(); err != nil {
        log.Fatalf("Error: %v", err)
    }
}

🧪 Testing Requirements

Before Submitting

# 1. Build and test
make clean
make gen_vmlinux
make deps
make build

# 2. Test your tool
sudo ./ebee yourtool

# 3. Test with different filters
sudo ./ebee yourtool --pid $$
sudo ./ebee yourtool --comm bash

# 4. Test on different kernel versions (if possible)

Documentation Testing

Verify all links work
Test all code examples
Check formatting renders correctly
Ensure examples produce expected output

🔄 Pull Request Process

Before Opening a PR

Code compiles without warnings
Tool works as documented
Documentation is complete (following template)
Examples are tested and produce expected output
Commit messages are clear and descriptive

PR Description Template

## Summary
Brief description of changes

## Type of Change
- [ ] New eBPF tool
- [ ] Bug fix
- [ ] Documentation improvement
- [ ] Performance optimization

## Testing
- [ ] Tested on Linux (kernel version: X.X.X)
- [ ] Tested on macOS via Lima
- [ ] All examples work as documented
- [ ] No regression in existing tools

## Documentation
- [ ] Updated tool table in README
- [ ] Created/updated tool documentation
- [ ] Included usage examples
- [ ] Added troubleshooting section

📚 Resources for Contributors

Learning eBPF

eBPF Fundamentals - Start here!
Development Setup - Environment setup
Existing tools - Learn from working examples

External Resources

Cilium eBPF Library - Go eBPF library we use
BCC Tools - Reference implementations
eBPF.io - Comprehensive eBPF resources
Linux Kernel Documentation

🆘 Getting Help

Documentation questions: Open an issue with the documentation label
Development help: Open an issue with the help wanted label
Bug reports: Use the bug report template
Feature requests: Use the feature request template

🌟 Recognition

Contributors will be:

Listed in our contributors section
Mentioned in release notes for significant contributions
Invited to review related PRs
Given credit in tool documentation they create

Thank you for contributing to ebee! Every contribution helps others learn eBPF development. 🚀

📄 License

This project is licensed under the same license as the original project.