eBPF Tools Documentation¶

This directory contains detailed documentation for each eBPF tool in the ebee project. Each tool includes comprehensive information about its purpose, implementation, usage, and technical details.

Available Tools¶

Core Tools¶

rmdetect - Monitor file deletions in real-time
Attaches to ext4_free_inode tracepoint
Captures process ID and command name
Useful for security monitoring and audit trails
execsnoop - Monitor process executions in real-time
Attaches to sched_process_exec tracepoint
Captures process ID, command name, and arguments
Useful for security monitoring and process analysis
tcpconnect - Monitor TCP connections in real-time
Attaches to sys_enter_connect tracepoint
Captures process ID, command name, and destination IP/port
Useful for network monitoring and security analysis

Template¶

template - Template for creating new tool documentation
Use this template when adding new eBPF tools
Includes all required sections and examples

Tool Categories¶

File System Monitoring¶

Tools that monitor file system operations: - rmdetect - File deletion monitoring

Process Monitoring¶

Tools that monitor process lifecycle events: - execsnoop - Process execution monitoring

Network Monitoring¶

Tools that monitor network operations: - tcpconnect - TCP connection monitoring - tcpaccept - TCP accept monitoring (future)

System Monitoring¶

Tools that monitor system-level events (future): - biolatency - Block I/O latency monitoring - syscount - System call counting

Adding New Tools¶

When adding a new eBPF tool to the project:

Create the eBPF C program in bpf/your_tool.c
Create the Go command in cmd/your_tool.go
Generate documentation using the template:
```
make create-tool
```
Update the Makefile generate target to include your C file
Add the command to cmd/root.go
Customize the documentation in docs/tools/your_tool.md
Update this index to include your new tool

Documentation Standards¶

Each tool documentation should include:

Required Sections¶

What it does - Purpose and use cases
How it works - Technical implementation details
Implementation Details - Code examples and explanations
Usage - Command-line examples and options
Technical Deep Dive - Kernel internals and performance
Troubleshooting - Common issues and solutions
Extending - How to enhance the tool
References - Links to relevant documentation

Optional Sections¶

Advanced Features - Complex use cases
Performance Tuning - Optimization tips
Integration - How to integrate with other tools

Common Patterns¶

eBPF Program Structure¶

#include "common.h"

struct data_t {
    // Event data structure
};

struct {
    __uint(type, BPF_MAP_TYPE_RINGBUF);
    __uint(max_entries, 1 << 24);
} events SEC(".maps");

SEC("tracepoint/category/event")
int trace_event(struct trace_event_raw_event *ctx) {
    // Program logic
    return 0;
}

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

Go Command Structure¶

var toolCmd = &cobra.Command{
    Use:   "toolname",
    Short: "Brief description",
    Long:  `Detailed description with examples`,
    Run:   runTool,
}

func init() {
    toolCmd.Flags().StringVar(&option, "option", "", "Option description")
    rootCmd.AddCommand(toolCmd)
}

func runTool(cmd *cobra.Command, args []string) {
    // Implementation
}

Best Practices¶

Documentation¶

Use clear, concise language
Include practical examples
Explain both "what" and "why"
Provide troubleshooting guidance
Keep examples up-to-date

Code¶

Follow existing patterns
Include proper error handling
Use meaningful variable names
Add comments for complex logic
Test thoroughly

Performance¶

Minimize kernel/userspace communication
Use efficient data structures
Consider filtering in kernel space
Monitor resource usage

Contributing¶

When contributing new tools or documentation:

Follow the established patterns
Test on multiple kernel versions
Include comprehensive documentation
Update this index file
Add appropriate tests