{"id":24979731,"url":"https://github.com/xmigrate/ebee","last_synced_at":"2025-09-11T00:33:28.676Z","repository":{"id":192991584,"uuid":"687839780","full_name":"xmigrate/ebee","owner":"xmigrate","description":"CLI tool for eBPF application development","archived":false,"fork":false,"pushed_at":"2024-06-14T05:02:19.000Z","size":558,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-25T13:46:35.743Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xmigrate.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-06T05:46:33.000Z","updated_at":"2025-02-23T13:22:03.000Z","dependencies_parsed_at":"2024-06-14T06:23:31.064Z","dependency_job_id":"3336940f-12dc-4825-9c9a-9e9500c52d5c","html_url":"https://github.com/xmigrate/ebee","commit_stats":null,"previous_names":["xmigrate/ebee"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xmigrate%2Febee","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xmigrate%2Febee/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xmigrate%2Febee/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xmigrate%2Febee/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xmigrate","download_url":"https://codeload.github.com/xmigrate/ebee/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248455711,"owners_count":21106596,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-02-04T02:16:56.594Z","updated_at":"2025-09-11T00:33:28.663Z","avatar_url":"https://github.com/xmigrate.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ebee - eBPF the Hard Way!\n\nThis repository contains various eBPF tools originally from the BCC project, reimplemented from scratch to help users learn eBPF development step by step.\n\n## 🎯 Project Goal\n\nThe 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.\n\n## 🧠 What is eBPF?\n\neBPF (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:\n\n- **Real-time system monitoring** - Track processes, files, network activity\n- **Performance analysis** - Measure latency, throughput, resource usage  \n- **Security monitoring** - Detect malicious behavior and policy violations\n- **Custom debugging** - Create tailored debugging tools for your applications\n\n## 🎓 What You'll Learn\n\nBy working through this project, you'll gain hands-on experience with:\n\n- **eBPF fundamentals** - Understanding the eBPF virtual machine and verifier\n- **Kernel programming** - Writing C programs that run in kernel space\n- **Tracepoints and kprobes** - Hooking into kernel events and functions\n- **Data structures** - Using eBPF maps for efficient data sharing\n- **Go integration** - Building userspace applications with the Cilium eBPF library\n- **Performance optimization** - Creating efficient monitoring tools\n- **Security analysis** - Building tools for system security and compliance\n\n## ⚙️ Prerequisites\n\n### System Requirements\n- **Linux Kernel**: 4.18+ (5.0+ recommended for full feature support)\n- **Architecture**: x86_64, arm64\n- **BTF Support**: Required for modern eBPF development\n- **Root Access**: Required for loading eBPF programs\n\n## 🚀 Quick Start\n\n### Prerequisites Setup\n\n#### Linux\n```bash\n# Install all requirements using the Makefile\nmake install\n```\n\n#### macOS\nSince eBPF development requires Linux kernel headers and tools, we use Lima to run Ubuntu:\n\n```bash\n# Install/upgrade Lima + guest agents\nbrew install lima lima-additional-guestagents || brew upgrade lima lima-additional-guestagents\n\n# Start Ubuntu VM with our configuration\nlimactl start scripts/default.yaml --name=default --timeout 30m\n\n# Connect to the VM\nlimactl shell default\n\n# Now run the Linux setup\nmake install\n```\n\n### Build ebee\n\n```bash\n# Generate kernel headers (required for eBPF development)\nmake gen_vmlinux\n\n# Install dependencies and build\nmake deps\nmake build\n```\n\n## 🔧 Quick Examples\n\n```bash\n# Monitor all process executions\nsudo ./ebee execsnoop\n\n# Monitor file deletions  \nsudo ./ebee rmdetect\n\n# Filter by specific process\nsudo ./ebee execsnoop --comm bash\n```\n\n## 📚 Available Tools\n\n| Tool | Status | Category | Description | Kernel Hook |\n|------|--------|----------|-------------|-------------|\n| **execsnoop** | ✅ Available | Process Monitoring | Monitor process executions in real-time | `sched_process_exec` tracepoint |\n| **rmdetect** | ✅ Available | File System | Monitor file deletions in real-time | `ext4_free_inode` tracepoint |\n| **opensnoop** | 🚧 Planned | File System | Monitor file opens in real-time | `vfs_open` kprobe |\n| **tcpconnect** | 🚧 Planned | Network | Monitor TCP connections | `tcp_connect` kprobe |\n| **tcpaccept** | 🚧 Planned | Network | Monitor TCP accepts | `tcp_accept` kprobe |\n| **biolatency** | 🚧 Planned | Storage | Monitor block I/O latency | `block_rq_insert/complete` |\n| **syscount** | 🚧 Planned | System | Count system calls by process | syscall tracepoints |\n| **funclatency** | 🚧 Planned | Performance | Measure function latency | kprobes/kretprobes |\n| **stackcount** | 🚧 Planned | Performance | Count stack traces | perf events |\n| **profile** | 🚧 Planned | Performance | CPU profiling | perf events |\n\n### Tool Categories\n\n- **Process Monitoring** - Track process lifecycle and execution\n- **File System** - Monitor file operations and changes  \n- **Network** - Analyze network connections and traffic\n- **Storage** - Monitor disk I/O and storage performance\n- **System** - Track system calls and kernel events\n- **Performance** - Measure latency, throughput, and resource usage\n\nEach tool includes comprehensive documentation in the `docs/` folder with implementation details, usage examples, and troubleshooting guides.\n\n## 🛠️ Development\n\n### Adding New Commands\n\n1. **Create the eBPF C program** in `bpf/your_tool.c`\n2. **Create the Go command** in `cmd/your_tool.go`\n3. **Update Makefile** generate target to include your C file\n4. **Add documentation** in `docs/your_tool.md` following the template\n5. **Update this README** to include your new tool\n\n### Documentation Structure\n\nEach tool should include:\n- **What it does** - Purpose and use cases\n- **How it works** - Technical implementation details\n- **Kernel hooks used** - Which tracepoints/kprobes are attached\n- **Data structures** - eBPF maps and event structures\n- **Step-by-step guide** - Implementation walkthrough\n- **Usage examples** - Command-line examples\n\n## 📖 Documentation\n\nDetailed documentation for each tool and eBPF concepts can be found in the `docs/` folder:\n\n- [Development Setup](docs/development-setup.md)\n- [eBPF Fundamentals](docs/ebpf-fundamentals.md)\n- [Tool Documentation](docs/tools/)\n  - [rmdetect](docs/tools/rmdetect.md)\n  - [execsnoop](docs/tools/execsnoop.md)\n\n## 🏗️ Project Structure\n\n```\nebee/\n├── cmd/                    # CLI commands\n├── bpf/                   # eBPF C programs\n│   └── headers/           # BPF headers\n├── docs/                  # Documentation\n│   ├── tools/            # Tool-specific docs\n│   └── development-setup.md\n├── scripts/              # Setup scripts\n├── main.go               # Application entry point\n└── Makefile              # Build and development tasks\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Whether you're fixing bugs, adding new tools, or improving documentation, your help makes this project better for everyone.\n\n### 🚀 Quick Start for Contributors\n\n1. **Fork and clone** the repository\n2. **Set up your development environment** following our [Development Setup Guide](docs/development-setup.md)\n3. **Pick an issue** or propose a new tool from our [planned tools table](#-available-tools)\n4. **Follow our contribution guidelines** below\n\n### 📋 Contribution Types\n\n#### 🔧 Adding New eBPF Tools\nPerfect for learning eBPF development:\n\n**Step-by-step process:**\n1. **Choose a tool** from our planned tools table or propose a new one\n2. **Create an issue** describing the tool's purpose and implementation approach\n3. **Implement the tool** following our patterns:\n   ```bash\n   # 1. Create eBPF C program\n   touch bpf/yourtool.c\n   \n   # 2. Create Go command\n   mkdir -p cmd\n   touch cmd/yourtool.go\n   \n   # 3. Add to Makefile generate target\n   # 4. Create documentation\n   touch docs/tools/yourtool.md\n   ```\n4. **Test thoroughly** on multiple kernel versions\n5. **Submit a pull request** with comprehensive documentation\n\n#### 📖 Documentation Improvements\nGreat for first-time contributors:\n- Fix typos or unclear explanations\n- Add more examples and use cases\n- Improve troubleshooting guides\n- Translate documentation\n\n#### 🐛 Bug Fixes\nHelp make the project more reliable:\n- Fix compilation issues\n- Resolve runtime errors\n- Improve error handling\n- Fix documentation inconsistencies\n\n#### ⚡ Performance Optimizations\nFor advanced contributors:\n- Optimize eBPF program efficiency\n- Improve memory usage\n- Reduce kernel/userspace communication overhead\n\n### 📝 Code Standards\n\n#### eBPF C Code\n```c\n// File header with purpose\n#include \"common.h\"\n\n// Clear data structures with comments\nstruct data_t {\n    u32 pid;        // Process ID\n    char comm[16];  // Command name\n};\n\n// Descriptive function names\nSEC(\"tracepoint/category/event\")\nint trace_event_name(struct trace_event_raw_event *ctx) {\n    // Error handling first\n    struct data_t *data = bpf_ringbuf_reserve(\u0026events, sizeof(struct data_t), 0);\n    if (!data) {\n        return 0;\n    }\n    \n    // Clear logic with safe memory access\n    data-\u003epid = bpf_get_current_pid_tgid() \u0026 0xFFFFFFFF;\n    bpf_get_current_comm(\u0026data-\u003ecomm, sizeof(data-\u003ecomm));\n    \n    bpf_ringbuf_submit(data, 0);\n    return 0;\n}\n\nchar _license[] SEC(\"license\") = \"GPL\";\n```\n\n#### Go Code\n```go\n// Follow Go conventions\nvar toolCmd = \u0026cobra.Command{\n    Use:   \"toolname\",\n    Short: \"Brief description\",\n    Long: `Detailed description with examples:\n\nExamples:\n  ebee toolname                    # Basic usage\n  ebee toolname --pid 1234        # Filter by PID\n  ebee toolname --comm bash       # Filter by command`,\n    Run: runTool,\n}\n\n// Clear error handling\nfunc runTool(cmd *cobra.Command, args []string) {\n    if err := doSomething(); err != nil {\n        log.Fatalf(\"Error: %v\", err)\n    }\n}\n```\n\n### 🧪 Testing Requirements\n\n#### Before Submitting\n```bash\n# 1. Build and test\nmake clean\nmake gen_vmlinux\nmake deps\nmake build\n\n# 2. Test your tool\nsudo ./ebee yourtool\n\n# 3. Test with different filters\nsudo ./ebee yourtool --pid $$\nsudo ./ebee yourtool --comm bash\n\n# 4. Test on different kernel versions (if possible)\n```\n\n#### Documentation Testing\n- Verify all links work\n- Test all code examples\n- Check formatting renders correctly\n- Ensure examples produce expected output\n\n### 🔄 Pull Request Process\n\n#### Before Opening a PR\n- [ ] **Code compiles** without warnings\n- [ ] **Tool works** as documented\n- [ ] **Documentation is complete** (following [template](docs/tools/template.md))\n- [ ] **Examples are tested** and produce expected output\n- [ ] **Commit messages** are clear and descriptive\n\n#### PR Description Template\n```markdown\n## Summary\nBrief description of changes\n\n## Type of Change\n- [ ] New eBPF tool\n- [ ] Bug fix\n- [ ] Documentation improvement\n- [ ] Performance optimization\n\n## Testing\n- [ ] Tested on Linux (kernel version: X.X.X)\n- [ ] Tested on macOS via Lima\n- [ ] All examples work as documented\n- [ ] No regression in existing tools\n\n## Documentation\n- [ ] Updated tool table in README\n- [ ] Created/updated tool documentation\n- [ ] Included usage examples\n- [ ] Added troubleshooting section\n```\n\n### 📚 Resources for Contributors\n\n#### Learning eBPF\n- [eBPF Fundamentals](docs/ebpf-fundamentals.md) - Start here!\n- [Development Setup](docs/development-setup.md) - Environment setup\n- [Existing tools](docs/tools/) - Learn from working examples\n\n#### External Resources\n- [Cilium eBPF Library](https://github.com/cilium/ebpf) - Go eBPF library we use\n- [BCC Tools](https://github.com/iovisor/bcc) - Reference implementations\n- [eBPF.io](https://ebpf.io/) - Comprehensive eBPF resources\n- [Linux Kernel Documentation](https://www.kernel.org/doc/html/latest/)\n\n### 🆘 Getting Help\n\n- **Documentation questions**: Open an issue with the `documentation` label\n- **Development help**: Open an issue with the `help wanted` label  \n- **Bug reports**: Use the bug report template\n- **Feature requests**: Use the feature request template\n\n### 🌟 Recognition\n\nContributors will be:\n- Listed in our contributors section\n- Mentioned in release notes for significant contributions\n- Invited to review related PRs\n- Given credit in tool documentation they create\n\n**Thank you for contributing to ebee! Every contribution helps others learn eBPF development.** 🚀\n\n## 📄 License\n\nThis project is licensed under the same license as the original project.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxmigrate%2Febee","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxmigrate%2Febee","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxmigrate%2Febee/lists"}