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

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.

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

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

• 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

# Install all requirements using the Makefile
make install

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

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

# Install dependencies and build
make deps
make build

# Monitor all process executions
sudo ./ebee execsnoop

# Monitor file deletions  
sudo ./ebee rmdetect

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

• 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.

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

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

Comprehensive documentation covering everything from basics to advanced production deployment:

• 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

• 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

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

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

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

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

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

Perfect for learning eBPF development:

Step-by-step process:

1. Choose a tool from our planned tools table or propose a new one
2. Create an issue describing the tool's purpose and implementation approach
3. 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

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

Great for first-time contributors:

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

Help make the project more reliable:

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

For advanced contributors:

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

// 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";

// 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)
    }
}

# 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)

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

• 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

## 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

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

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

• 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

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. 🚀

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