Skip to content

Commit 75e0a47

Browse files
sameehjsameehj
committed
update README.md
Signed-off-by: sameeh.jubran <[email protected]>
1 parent f02acc8 commit 75e0a47

File tree

1 file changed

+112
-49
lines changed

1 file changed

+112
-49
lines changed

‎README.md‎

Lines changed: 112 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
> A secure, minimal, and schema-enforced MCP server for eBPF — purpose-built for AI integration, kernel introspection, and automation.
44
5+
[![Version](https://img.shields.io/github/v/release/sameehj/ebpf-mcp?label=version)](https://github.com/sameehj/ebpf-mcp/releases)
56
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-orange)](https://modelcontextprotocol.io)
67
[![eBPF Support](https://img.shields.io/badge/eBPF-Linux%205.8%2B-green)](https://ebpf.io)
78
[![License: GPL v2 (eBPF)](https://img.shields.io/badge/License-GPL%20v2-blue.svg)](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html)
@@ -17,60 +18,117 @@ It enables **loading, attaching, introspecting, and streaming** eBPF programs
1718

1819
---
1920

21+
## 🚀 Quick Start
22+
23+
### 📦 One-liner Installation
24+
25+
```bash
26+
# Install ebpf-mcp server
27+
curl -fsSL https://raw.githubusercontent.com/sameehj/ebpf-mcp/main/install.sh | sudo bash
28+
29+
# Start the service (runs on port 8080 by default)
30+
sudo systemctl start ebpf-mcp
31+
sudo systemctl enable ebpf-mcp
32+
33+
# Get your auth token
34+
cat /etc/ebpf-mcp-token
35+
36+
# Check service status
37+
sudo systemctl status ebpf-mcp
38+
39+
# View logs if needed
40+
sudo journalctl -u ebpf-mcp -f
41+
```
42+
43+
**For air-gapped or development environments:**
44+
```bash
45+
git clone https://github.com/sameehj/ebpf-mcp.git
46+
cd ebpf-mcp
47+
sudo ./install.sh v1.0.2
48+
```
49+
50+
### 🧪 Test the Installation
51+
52+
```bash
53+
# Run the complete test suite
54+
cd scripts/
55+
chmod +x test-ebpf-mcp-server.sh
56+
./test-ebpf-mcp-server.sh <your-token>
57+
```
58+
59+
If no token is provided, the script will prompt for it interactively.
60+
61+
---
62+
63+
## 🤖 Claude CLI Integration
64+
65+
Once installed, connect Claude to your eBPF server (runs on port 8080):
66+
67+
```bash
68+
# Add MCP server to Claude CLI
69+
claude mcp add ebpf http://localhost:8080/mcp \
70+
-t http \
71+
-H "Authorization: Bearer $(cat /etc/ebpf-mcp-token)"
72+
73+
# Start Claude with eBPF tools
74+
claude --debug
75+
76+
# Optional: Test with MCP Inspector (requires Node.js)
77+
npx @modelcontextprotocol/inspector http://localhost:8080/mcp
78+
```
79+
80+
**Example prompts:**
81+
- `> Get system info and kernel version`
82+
- `> Load and attach a kprobe program to monitor sys_execve`
83+
- `> Show me all active eBPF programs and their types`
84+
- `> Stream events from ringbuffer maps for 10 seconds`
85+
- `> Trace kernel errors for the next 5 seconds`
86+
87+
---
88+
89+
## 📥 Install Options
90+
91+
| Method | Command | Use Case |
92+
|--------|---------|----------|
93+
| **One-liner** | `curl ... \| sudo bash` | Production systems |
94+
| **Manual** | `git clone && sudo ./install.sh` | Development/air-gapped |
95+
| **Build from source** | `make build` | Custom modifications |
96+
| **Docker** | *Coming soon* | Containerized environments |
97+
98+
---
99+
20100
## 🔧 Minimal Toolset
21101

22102
Each tool is designed to be schema-validatable, AI-orchestrable, and safe-by-default. They cover 80%+ of real-world observability and control workflows.
23103

24-
| Tool Name | Description | Capabilities Required |
25-
| ---------------- | ----------------------------------------------- | ---------------------------------------------- |
26-
| `load_program` | Load and validate `.o` files (CO-RE supported) | `CAP_BPF` or `CAP_SYS_ADMIN` |
27-
| `attach_program` | Attach program to XDP, kprobe, tracepoint hooks | Depends on type (e.g. `CAP_NET_ADMIN` for XDP) |
28-
| `inspect_state` | List programs, maps, links, and tool metadata | `CAP_BPF` (read-only) |
29-
| `stream_events` | Stream events from ringbuf/perfbuf maps | `CAP_BPF` (read-only) |
104+
| Tool Name | Status | Description | Capabilities Required |
105+
| ---------------- | ------ | ----------------------------------------------- | ---------------------------------------------- |
106+
| `info` | ✅ | System introspection: kernel, arch, BTF | `CAP_BPF` or none (read-only) |
107+
| `load_program` | ✅ | Load and validate `.o` files (CO-RE supported) | `CAP_BPF` or `CAP_SYS_ADMIN` |
108+
| `attach_program` | ✅ | Attach program to XDP, kprobe, tracepoint hooks | Depends on type (e.g. `CAP_NET_ADMIN` for XDP) |
109+
| `inspect_state` | ✅ | List programs, maps, links, and tool metadata | `CAP_BPF` (read-only) |
110+
| `stream_events` | ✅ | Stream events from ringbuf/perfbuf maps | `CAP_BPF` (read-only) |
111+
| `trace_errors` | ✅ | Monitor kernel tracepoints for error conditions | `CAP_BPF` (read-only) |
112+
113+
> **All tools return structured JSON output** — AI-ready, streaming-compatible, and schema-validated.
30114
31115
> 🔍 See [`docs/TOOL_SPECS.md`](./docs/TOOL_SPECS.md) for full schema definitions.
32116
33117
---
34118

35119
## 🚀 What You Can Do
36120

121+
* ✅ Query kernel version, architecture, and BTF availability
37122
* ✅ Load programs from disk or inline base64 with optional BTF
38123
* ✅ Attach to live systems with type-safe constraints
39124
* ✅ Inspect pinned objects, kernel version, verifier state
40125
* ✅ Stream real-time events with filtering by pid/comm/cpu
126+
* ✅ Trace kernel errors and system anomalies
41127
* ✅ Discover available tools and their schemas
42128
* ✅ Integrate with Claude, Ollama, or MCP-compatible clients
43129

44130
---
45131

46-
## ⚡ Quick Start
47-
48-
```bash
49-
# Clone + build
50-
git clone https://github.com/sameehj/ebpf-mcp.git
51-
cd ebpf-mcp
52-
make build
53-
```
54-
55-
```bash
56-
# Run locally with MCP Inspector
57-
npx @modelcontextprotocol/inspector ./bin/ebpf-mcp-server
58-
```
59-
60-
```jsonc
61-
// ~/.config/Claude/claude_desktop_config.json
62-
{
63-
"mcpServers": {
64-
"ebpf": {
65-
"command": "/absolute/path/to/ebpf-mcp-server",
66-
"args": ["-t", "stdio"]
67-
}
68-
}
69-
}
70-
```
71-
72-
---
73-
74132
## 🛡️ Security Model
75133

76134
| Layer | Controls |
@@ -79,6 +137,7 @@ npx @modelcontextprotocol/inspector ./bin/ebpf-mcp-server
79137
| Filesystem | No shell, no exec, path-validated |
80138
| Runtime isolation | Session-scoped cleanup, strict inputs |
81139
| AI safety | Capability-aware schemas + output limits |
140+
| Authentication | Bearer token + HTTPS ready |
82141

83142
🧼 All resources are automatically cleaned up when a client disconnects (no manual unload/detach required unless pinned).
84143

@@ -92,22 +151,12 @@ npx @modelcontextprotocol/inspector ./bin/ebpf-mcp-server
92151
├── internal/ # Core logic: eBPF, tools, kernel adapters
93152
├── pkg/types/ # JSON schema bindings + shared types
94153
├── docs/ # Tool specs, design notes, schemas
154+
├── scripts/ # Install script + test suite
95155
└── schemas/ # JSON Schema files for each tool
96156
```
97157

98158
---
99159

100-
## 📈 Tool Spec Coverage
101-
102-
| Tool | Status | Notes |
103-
| ---------------- | ------ | ---------------------------------------- |
104-
| `load_program` | ✅ | Supports CO-RE, verify-only mode |
105-
| `attach_program` | ✅ | Supports XDP, kprobe, tracepoint |
106-
| `inspect_state` | ✅ | Introspects maps, programs, links, tools |
107-
| `stream_events` | ✅ | Streams ringbuf/perfbuf with filters |
108-
109-
---
110-
111160
## 🧠 Advanced Design Notes
112161

113162
### ✅ Lifecycle Management
@@ -118,17 +167,17 @@ npx @modelcontextprotocol/inspector ./bin/ebpf-mcp-server
118167

119168
### 🤖 AI Tooling Compatibility
120169

121-
* All tools are **strictly typed** with published schemas
170+
* All tools are **strictly typed** with published schemas and return **structured JSON output**
171+
* **AI-ready**: No parsing required — direct integration with language models
172+
* **Streaming-compatible**: Real-time data flows for observability workflows
122173
* Responses include:
123-
124174
* `tool_version`
125175
* `verifier_log` (for debugging)
126176
* Structured `error` with `context`
127177

128178
### 🔗 Extensibility
129179

130180
Future optional tools:
131-
132181
* `pin_object` / `unpin_object`
133182
* `detach_link`
134183
* `map_batch_op`
@@ -141,10 +190,24 @@ These are omitted from the default for security and simplicity.
141190

142191
* [Linux Kernel eBPF Docs](https://docs.kernel.org/bpf/)
143192
* [Model Context Protocol](https://modelcontextprotocol.io)
193+
* [MCP Inspector Tool](https://github.com/modelcontextprotocol/inspector)
144194
* [JSON Schema Spec (2020-12)](https://json-schema.org/)
145195
* [eBPF Security Best Practices](https://ebpf.io/security/)
146196
* [Cilium for Kubernetes Observability](https://cilium.io/)
147197

198+
🧪 See [`scripts/test-ebpf-mcp-server.sh`](./scripts/test-ebpf-mcp-server.sh) for full validation suite.
199+
200+
**Basic Architecture:**
201+
```
202+
Claude / Ollama / AI Client
203+
↓
204+
MCP JSON-RPC
205+
↓
206+
ebpf-mcp server
207+
↓
208+
Kernel APIs
209+
```
210+
148211
---
149212

150213
## 📜 Licensing
@@ -164,4 +227,4 @@ These are omitted from the default for security and simplicity.
164227
---
165228

166229
> **Structured. Safe. Schema-native.**
167-
> `ebpf-mcp` brings eBPF to the age of AI.
230+
> `ebpf-mcp` brings eBPF to the age of AI.

0 commit comments

Comments
 (0)