KernelEye Logo

KernelEye

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.

Cosa Fa

Monitoraggio in tempo reale del traffico Linux con eBPF.
Tracciamento della larghezza di banda con hook TC.
Valutazione delle minacce tramite la logica di scoring Go condivisa in shared/scoring.
Analisi lato agente e remediation automatica opzionale.
Blocco dei pacchetti sul fast-path XDP e fallback ipset/iptables.
Worker di analisi lato backend, gestione dei blocchi, conservazione dei dati e report mensili.
Ingestione gRPC e streaming dei comandi di blocco tra agente e backend con crittografia TLS/mTLS e firma HMAC dei comandi.
Protezione anti-replay con nonce monotone e logging di audit strutturato per tutte le azioni di remediation.
Verifica periodica dell'integrità delle mappe eBPF e report di attestazione dello stato.
Dashboard React con aggiornamenti WebSocket, viste di dettaglio dei server, gestione degli IP bloccati, whitelist, report e analisi.
Arricchimento GeoIP quando i database MaxMind sono configurati.
Supporto OAuth per GitHub e Google (accesso self-hosted a proprietario singolo).
Raccolta privacy-first: solo metadati, nessun payload dei pacchetti.

Architettura

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

Componenti Principali

Agente

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.

Backend

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.

Dashboard

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.

Landing Page

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.

Codice Condiviso e Protocolli

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.

Privacy

KernelEye non ispeziona i payload dei pacchetti né il contenuto delle applicazioni.

I metadati raccolti includono:

Indirizzi IP di origine e destinazione.
Porte e protocolli.
Flag TCP e contatori di connessione.
Conteggi di pacchetti e byte.
Direzione del traffico.
Timestamp.
Arricchimento GeoIP/ASN opzionale.

Non raccolti:

Payload dei pacchetti.
Corpo o header delle richieste HTTP.
Credenziali utente.
Dati applicativi.

Valutazione delle Minacce

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.

Remediation

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.

Avvio Rapido

Prerequisiti

Go 1.25.x per i moduli attuali di backend e agente.
Node.js/npm per le app React.
PostgreSQL 14+ o 15+.
Per l'agente: Linux con supporto BTF, privilegi di root, clang/LLVM, bpftool, header libbpf, ipset e iptables.

Configurare l'Ambiente

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.

Più Popolari

kerneleye