Sicurezza a livello di kernel e risposta agli attacchi per server Linux.
Intelligence sul traffico a livello kernel e remediation delle minacce per server Linux.
KernelEye è una piattaforma self-hosted di monitoraggio della sicurezza per server Linux. Utilizza eBPF, TC e XDP in un agente Go per osservare i metadati di rete, valutare le attività sospette e applicare la remediation tramite blocco XDP a livello kernel e regole ipset/iptables. Un backend Go memorizza e analizza gli eventi, mentre una dashboard React offre gestione dei server, traffico in tempo reale, visualizzazione delle minacce, IP bloccati, whitelist, report e analisi.
shared/scoring.Monitored Linux host
eBPF traffic probe + TC bandwidth hooks
XDP firewall and ipset/iptables remediation
Go agent (HMAC command verification, audit log)
|
| gRPC (TLS/mTLS) + HMAC-signed block commands
v
Go backend API
Fiber HTTP API
gRPC ingest/block services (TLS/mTLS, command signing)
analysis worker, block manager, retention, reports
integrity report handler
|
v
PostgreSQL
^
|
React dashboard
REST API + WebSocket live updates
L'agente risiede in agent/ ed è il processo dell'host Linux.
agent/main.go avvia la registrazione, il caricamento eBPF, il tracciamento della larghezza di banda, la remediation, lo scoring, l'aggregazione e lo streaming dei comandi di blocco.agent/ebpf/traffic_probe.c cattura i metadati del traffico.agent/ebpf/xdp_firewall.c implementa il filtraggio dei pacchetti XDP.agent/tc.go configura il tracciamento della larghezza di banda TC.agent/aggregator.go raggruppa e invia gli eventi al backend.agent/history_store.go e agent/flush.go gestiscono la persistenza locale e il comportamento di retry.agent/remediation/ contiene l'analizzatore, l'auto-blocco e i remediator XDP, ipset e ibridi.L'agente richiede Linux e privilegi elevati per le operazioni eBPF/XDP.
Il backend risiede in backend/.
backend/cmd/api/main.go avvia l'API HTTP Fiber e i servizi gRPC.backend/internal/api/ contiene autenticazione, handler della dashboard, handler gRPC, API di blocco, API whitelist, gestione WebSocket e rate limiting.backend/internal/analysis/ contiene i worker di scoring, la gestione dei blocchi, la conservazione dei dati e la logica dei report mensili.backend/internal/database/ contiene il codice di accesso al database generato da sqlc.backend/internal/geoip/ gestisce l'arricchimento GeoIP.backend/internal/email/ invia email tramite Mailtrap quando configurato.backend/migrations/ contiene le migrazioni PostgreSQL.L'HTTP utilizza di default la porta 8080; gRPC utilizza di default la porta 9091.
La dashboard risiede in dashboard/ ed è un'applicazione Vite React.
dashboard/src/pages/ include le pagine di panoramica, server, dettaglio server, minacce, avvisi, report, visualizzatore, IP bloccati, whitelist, login, profilo e callback OAuth.dashboard/src/components/ contiene traffico in tempo reale, feed dei blocchi, grafici, elenchi di server, configuratori e componenti di layout condivisi.dashboard/src/api/client.ts definisce il client dell'API REST.dashboard/src/context/WebSocketContext.tsx gestisce gli aggiornamenti degli eventi in tempo reale.Il server di sviluppo è configurato per http://localhost:3000.
Il sito di marketing pubblico risiede in kerneleye-landing-page/. L'immagine frontend di produzione compila sia la landing page sia la dashboard, servendole tramite nginx.
shared/scoring/ contiene il modulo di valutazione delle minacce condiviso, utilizzato sia dall'agente sia dal backend.shared/cmdsigning/ contiene il modulo di firma dei comandi HMAC-SHA256 e di protezione anti-replay con nonce.proto/kerneleye/v1/ contiene le definizioni protobuf per i servizi di ingestione e blocco.proto/gen/go/ contiene il codice Go protobuf generato.KernelEye non ispeziona i payload dei pacchetti né il contenuto delle applicazioni.
I metadati raccolti includono:
Non raccolti:
La valutazione delle minacce è implementata in shared/scoring/scorer.go. Lo scorer attuale è più sfumato di una semplice formula lineare: considera il tasso di SYN, l'accesso a porte uniche, gli handshake falliti, il comportamento a raffica, l'abuso dei servizi, la direzione, la confidenza e il decadimento del punteggio nel tempo.
Soglie di classificazione predefinite:
< 20 normal
20-39 suspicious
>= 40 malicious
>= 40 eligible for auto-blocking when remediation is enabled
Il worker di analisi del backend utilizza inoltre finestre di traffico accumulate e può attivare la gestione dei blocchi per le sorgenti ad alto rischio.
KernelEye supporta la remediation attiva quando è abilitata sull'agente.
| Livello | Implementazione | Scopo |
|---|---|---|
| XDP | agent/remediation/xdp_remediator.go | Drop rapidi a livello kernel prima dello stack di rete |
| IPSet | agent/remediation/ipset_remediator.go | Gestione dei blocchi ipset/iptables |
| Ibrido | agent/remediation/hybrid_remediator.go | Coordina il comportamento di XDP e ipset |
| Auto-blocco | agent/remediation/auto_blocker.go | Blocca le sorgenti al di sopra delle soglie di punteggio configurate |
| Gestore dei blocchi del backend | backend/internal/analysis/block_manager.go | Coordina lo stato dei blocchi e i comandi generati dal backend |
La dashboard espone inoltre la gestione degli IP bloccati e della whitelist.
cp .env.example .env
Imposta almeno:
DATABASE_URL=postgres://kerneleye:<password>@localhost:5432/kerneleye?sslmode=disable
JWT_SECRET=<at-least-32-characters>
API_KEY_SECRET=<strong-secret>
CORS_ORIGINS=http://localhost:3000
Le integrazioni opzionali includono rate limiting Redis, email Mailtrap, OAuth GitHub/Google e GeoIP MaxMind.
cd backend
go mod download
go run cmd/api/main.go
Il backend avvia:
http://localhost:8080localhost:9091cd dashboard
npm install
npm run dev
Apri http://localhost:3000.
L'accesso è disponibile solo tramite OAuth. Imposta AUTH_OWNER_EMAIL e configura almeno un provider OAuth (GitHub o Google) per accedere alla dashboard. Solo l'email del proprietario configurata è autorizzata ad accedere.
cd agent
bpftool btf dump file /sys/kernel/btf/vmlinux format c > ebpf/vmlinux.h
go generate ./...
go build -o kerneleye-agent
sudo KERNELEYE_API_KEY=<server-api-key> \
KERNELEYE_SERVER=localhost:8080 \
KERNELEYE_GRPC_URL=localhost:9091 \
./kerneleye-agent
Flag utili dell'agente:
-enable-remediation enable active blocking and auto-blocking
-xdp enable XDP fast-path blocking
-interface <name> select XDP network interface
--read-only monitor and report only, never block
--insecure disable TLS (dev only)
--tls-ca-file <path> backend CA certificate for TLS verification
--tls-cert-file <path> agent client certificate for mTLS
--tls-key-file <path> agent client private key for mTLS
-list-blocked print current ipset state and exit
-flush-blocklists flush ipset and XDP blocklists and exit
-clear-data remove local agent SQLite stores and exit
-version print build version
Quando --enable-remediation è impostato, è necessario configurare CMD_SIGNING_KEY sia sull'agente sia sul backend. Generala con openssl rand -base64 32.
kerneleye/
├── agent/ Go eBPF/XDP monitoring agent
│ ├── ebpf/ eBPF C programs and compiled objects
│ ├── remediation/ analyzer, XDP, ipset, hybrid remediation
│ ├── assets/ embedded XDP object assets
│ └── scripts/ ipset helper scripts and service files
├── backend/ Go Fiber API and gRPC backend
│ ├── cmd/api/ backend entrypoint
│ ├── internal/api/ HTTP, auth, WebSocket, gRPC, block APIs
│ ├── internal/analysis/ workers, blocking, retention, reports
│ ├── internal/database/ sqlc generated queries and helpers
│ ├── internal/email/ Mailtrap email service
│ ├── internal/geoip/ MaxMind GeoIP service
│ └── migrations/ PostgreSQL migrations
├── dashboard/ React dashboard app
├── kerneleye-landing-page/ React landing page app
├── proto/ protobuf definitions and generated Go code
├── shared/
│ ├── scoring/ shared threat scoring Go module
│ └── cmdsigning/ HMAC command signing and nonce tracking
├── docs/ additional project documentation
├── tests/ traffic simulation shell scripts
├── docker/ frontend nginx and install script templates
├── Dockerfile.backend backend container build
├── Dockerfile.frontend landing + dashboard + agent download image
├── docker-compose.yml production-oriented compose stack
└── Makefile generation, build, and docker targets
| Livello | Tecnologie |
|---|---|
| Agente | Go, cilium/ebpf, XDP, TC, gRPC, SQLite local stores, zap |
| Backend | Go, Fiber, gRPC, PostgreSQL, sqlc, Redis, Mailtrap |
| Dashboard | React, TypeScript, Vite, Ant Design, React Query, Recharts |
| Landing page | React, TypeScript, Vite, Tailwind CSS |
| Protocolli | Protobuf, gRPC |
| Deployment | Docker, Docker Compose, nginx, Traefik labels |
L'agente KernelEye è stato testato sulle seguenti configurazioni. Questa tabella viene aggiornata man mano che nuovi ambienti vengono validati.
| OS | Kernel | CPU | RAM | Arch | Note |
|---|---|---|---|---|---|
| Ubuntu 26.04 LTS | 7.0.0-15-generic | AMD EPYC-Genoa (2 vCPU) | 3.7 GB | x86_64 | — |
Utilizziamo ebpf-go per l'integrazione userspace di eBPF.
Target Make comuni:
make gen-proto
make gen-sql
make gen-ebpf
make build-backend
make build-agent
make build
make docker-build
L'immagine Docker del frontend compila la landing page, la dashboard e un binario Linux dell'agente scaricabile.
KernelEye è open source sotto la Apache License, Version 2.0 (Apache-2.0). Vedi LICENSE.
Copyright 2026 Abdeljalil Aitetaleb.
Il nome KernelEye, i loghi e l'identità visiva non sono concessi in licenza sotto la Apache License. Consulta TRADEMARKS.md per i termini di utilizzo del marchio.