eBPF MCP

Um servidor MCP seguro para eBPF, projetado para integração com IA, introspecção do kernel e automação.

Documentação

🐝 ebpf-mcp: Controle de eBPF Compatível com IA via Model Context Protocol

Um servidor MCP seguro, mínimo e com esquema validado para eBPF — projetado especificamente para integração com IA, introspecção de kernel e automação.

🧠 O Que É Isso?

ebpf-mcp é um servidor Model Context Protocol (MCP) seguro que expõe um conjunto mínimo de ferramentas estruturadas para interagir com eBPF — otimizado para controle seguro por IA, agentes de automação e operadores humanos.

Ele permite carregar, anexar, inspecionar e transmitir programas eBPF — tudo por meio de contratos JSON Schema estritos validados em tempo de execução. Sem APIs REST, sem escapes de shell e sem wrappers de bpftool.

🚀 Início Rápido

📦 Instalação em Uma Linha

# Install ebpf-mcp server
curl -fsSL https://raw.githubusercontent.com/sameehj/ebpf-mcp/main/install.sh | sudo bash

# Start the service (runs on port 8080 by default)
sudo systemctl start ebpf-mcp
sudo systemctl enable ebpf-mcp

# Get your auth token
cat /etc/ebpf-mcp-token

# Check service status
sudo systemctl status ebpf-mcp

# View logs if needed
sudo journalctl -u ebpf-mcp -f

Para ambientes isolados ou de desenvolvimento:

git clone https://github.com/sameehj/ebpf-mcp.git
cd ebpf-mcp
sudo ./install.sh v1.0.2

🧪 Teste a Instalação

# Run the complete test suite
cd scripts/
chmod +x test-ebpf-mcp-server.sh
./test-ebpf-mcp-server.sh <your-token>

Se nenhum token for fornecido, o script solicitará interativamente.

🤖 Integração com Claude CLI

Após a instalação, conecte o Claude ao seu servidor eBPF (executando na porta 8080):

# Add MCP server to Claude CLI
claude mcp add ebpf http://localhost:8080/mcp \
  -t http \
  -H "Authorization: Bearer $(cat /etc/ebpf-mcp-token)"

# Start Claude with eBPF tools
claude --debug

# Optional: Test with MCP Inspector (requires Node.js)
npx @modelcontextprotocol/inspector http://localhost:8080/mcp

📘 Tutoriais

Procurando começar em ambientes específicos ou com a IDE Cursor?

🧰 Guia de Configuração do VirtualBox

Aprenda como configurar e executar o ebpf-mcp dentro de uma VM VirtualBox, com encaminhamento de portas, acesso SSH e dicas práticas.

🖥️ Integração Cursor IDE + eBPF-MCP

Guia passo a passo para executar o servidor MCP eBPF com a IDE Cursor para observabilidade orientada por IA.

Exemplos de prompts:

> Get system info and kernel version
> Load and attach a kprobe program to monitor sys_execve
> Show me all active eBPF programs and their types
> Stream events from ringbuffer maps for 10 seconds
> Trace kernel errors for the next 5 seconds

📥 Opções de Instalação

Método	Comando	Caso de Uso
Uma linha	`curl ... \| sudo bash`	Sistemas de produção
Manual	`git clone && sudo ./install.sh`	Desenvolvimento/isolado
Compilar do código-fonte	`make build`	Modificações personalizadas
Docker	Em breve	Ambientes conteinerizados

🔧 Conjunto Mínimo de Ferramentas

Cada ferramenta é projetada para ser validável por esquema, orquestrável por IA e segura por padrão. Elas cobrem mais de 80% dos fluxos de trabalho reais de observabilidade e controle.

Nome da Ferramenta	Status	Descrição	Capacidades Necessárias
`info`	✅	Introspecção do sistema: kernel, arquitetura, BTF	`CAP_BPF` ou nenhuma (somente leitura)
`load_program`	✅	Carregar e validar arquivos `.o` (com suporte a CO-RE)	`CAP_BPF` ou `CAP_SYS_ADMIN`
`attach_program`	✅	Anexar programa a hooks XDP, kprobe, tracepoint	Depende do tipo (ex.: `CAP_NET_ADMIN` para XDP)
`inspect_state`	✅	Listar programas, mapas, links e metadados de ferramentas	`CAP_BPF` (somente leitura)
`stream_events`	✅	Transmitir eventos de mapas ringbuf/perfbuf	`CAP_BPF` (somente leitura)
`trace_errors`	✅	Monitorar tracepoints do kernel para condições de erro	`CAP_BPF` (somente leitura)

Todas as ferramentas retornam saída JSON estruturada — pronta para IA, compatível com streaming e validada por esquema.

🔍 Consulte docs/TOOL_SPECS.md para definições completas de esquema.

🚀 O Que Você Pode Fazer

✅ Consultar versão do kernel, arquitetura e disponibilidade de BTF
✅ Carregar programas do disco ou base64 inline com BTF opcional
✅ Anexar a sistemas ativos com restrições de tipo seguro
✅ Inspecionar objetos fixados, versão do kernel, estado do verificador
✅ Transmitir eventos em tempo real com filtros por pid/comm/cpu
✅ Rastrear erros do kernel e anomalias do sistema
✅ Descobrir ferramentas disponíveis e seus esquemas
✅ Integrar com Claude, Ollama ou clientes compatíveis com MCP

🛡️ Modelo de Segurança

Camada	Controles
Execução eBPF	Verificador do kernel + limites de recursos
Sistema de arquivos	Sem shell, sem exec, caminhos validados
Isolamento em tempo de execução	Limpeza por sessão, entradas estritas
Segurança para IA	Esquemas com ciência de capacidades + limites de saída
Autenticação	Bearer token + pronto para HTTPS

🧼 Todos os recursos são limpos automaticamente quando um cliente desconecta (sem necessidade de descarregar/desanexar manualmente, a menos que fixado).

📦 Estrutura do Projeto

.
├── cmd/              # MCP server + CLI client
├── internal/         # Core logic: eBPF, tools, kernel adapters
├── pkg/types/        # JSON schema bindings + shared types
├── docs/             # Tool specs, design notes, schemas
├── scripts/          # Install script + test suite
└── schemas/          # JSON Schema files for each tool

🧠 Notas Avançadas de Design

✅ Gerenciamento do Ciclo de Vida

🔒 Sem desanexação manual: Links são fechados automaticamente, a menos que fixados
🧹 Limpeza automática: FDs e memória são liberados na desconexão
📎 Fixação: Caminhos de fixação opcionais (/sys/fs/bpf/...) para mapas/programas/links

🤖 Compatibilidade com Ferramentas de IA

Todas as ferramentas são estritamente tipadas com esquemas publicados e retornam saída JSON estruturada
Prontas para IA: Sem necessidade de análise — integração direta com modelos de linguagem
Compatíveis com streaming: Fluxos de dados em tempo real para fluxos de trabalho de observabilidade
As respostas incluem:
- tool_version
- verifier_log (para depuração)
- error estruturado com context

🔗 Extensibilidade

Ferramentas opcionais futuras:

pin_object / unpin_object
detach_link
map_batch_op

Elas são omitidas do padrão por segurança e simplicidade.

📚 Referências

🧪 Consulte scripts/test-ebpf-mcp-server.sh para a suíte completa de validação.

Arquitetura Básica:

Claude / Ollama / AI Client
          ↓
     MCP JSON-RPC
          ↓
   ebpf-mcp server
          ↓
     Kernel APIs

📜 Licenciamento

Componente	Licença
`internal/ebpf/`	GPL-2.0
Todo o resto	Apache-2.0

✉️ Contato

📬 GitHub – sameehj/ebpf-mcp 🛠 Contribuições, problemas e PRs são bem-vindos!

Estruturado. Seguro. Nativo de esquema. ebpf-mcp traz o eBPF para a era da IA.