KernelEye

Intelligence du trafic au niveau noyau et remédiation des menaces pour les serveurs Linux.

KernelEye est une plateforme de surveillance de sécurité auto-hébergée pour serveurs Linux. Elle utilise eBPF, TC et XDP dans un agent Go pour observer les métadonnées réseau, évaluer les activités suspectes et appliquer des remédiations via le blocage XDP au niveau noyau et les règles ipset/iptables. Un backend Go stocke et analyse les événements, tandis qu'un tableau de bord React offre la gestion des serveurs, le trafic en direct, les vues des menaces, les IP bloquées, la liste blanche, les rapports et les analyses.

Ce qu'il fait

• Surveillance du trafic Linux en temps réel avec eBPF.
• Suivi de bande passante avec des hooks TC.
• Score de menace à partir de la logique de scoring Go partagée dans shared/scoring.
• Analyse côté agent et remédiation automatique optionnelle.
• Blocage rapide de paquets via XDP et repli ipset/iptables.
• Workers d'analyse côté backend, gestion des blocages, conservation des données et rapports mensuels.
• Ingestion gRPC et diffusion de commandes de blocage entre agent et backend avec chiffrement TLS/mTLS et signature HMAC des commandes.
• Protection contre la relecture par nonce monotone et journalisation d'audit structurée pour toutes les actions de remédiation.
• Vérification périodique de l'intégrité des maps eBPF et rapports d'attestation d'état.
• Tableau de bord React avec mises à jour WebSocket, vues détaillées des serveurs, gestion des IP bloquées, liste blanche, rapports et analyses.
• Enrichissement GeoIP lorsque les bases MaxMind sont configurées.
• Support OAuth pour GitHub et Google (accès auto-hébergé à propriétaire unique).
• Collecte respectueuse de la vie privée : métadonnées uniquement, pas de charges utiles de paquets.

Architecture

Hôte Linux surveillé
  Sonde de trafic eBPF + hooks de bande passante TC
  Pare-feu XDP et remédiation ipset/iptables
  Agent Go (vérification des commandes HMAC, journal d'audit)
      |
      | gRPC (TLS/mTLS) + commandes de blocage signées HMAC
      v
API backend Go
  API HTTP Fiber
  Services gRPC d'ingestion/blocage (TLS/mTLS, signature de commandes)
  Worker d'analyse, gestionnaire de blocage, conservation, rapports
  Gestionnaire de rapports d'intégrité
      |
      v
PostgreSQL
      ^
      |
Tableau de bord React
  API REST + mises à jour en direct WebSocket

Composants clés

Agent

L'agent se trouve dans agent/ et est le processus hôte Linux.

• agent/main.go démarre l'enregistrement, le chargement eBPF, le suivi de bande passante, la remédiation, le scoring, l'agrégation et la diffusion de commandes de blocage.
• agent/ebpf/traffic_probe.c capture les métadonnées de trafic.
• agent/ebpf/xdp_firewall.c implémente le filtrage de paquets XDP.
• agent/tc.go configure le suivi de bande passante TC.
• agent/aggregator.go regroupe et vide les événements vers le backend.
• agent/history_store.go et agent/flush.go gèrent la persistance locale et le comportement de nouvelle tentative.
• agent/remediation/ contient l'analyseur, le blocage automatique, XDP, ipset et les remédiateurs hybrides.

L'agent nécessite Linux et des privilèges élevés pour les opérations eBPF/XDP.

Backend

Le backend se trouve dans backend/.

• backend/cmd/api/main.go démarre l'API HTTP Fiber et les services gRPC.
• backend/internal/api/ contient l'authentification, les gestionnaires du tableau de bord, les gestionnaires gRPC, les API de blocage, les API de liste blanche, la gestion WebSocket et la limitation de débit.
• backend/internal/analysis/ contient les workers de scoring, la gestion des blocages, la conservation des données et la logique des rapports mensuels.
• backend/internal/database/ contient le code d'accès à la base de données généré par sqlc.
• backend/internal/geoip/ gère l'enrichissement GeoIP.
• backend/internal/email/ envoie des e-mails via Mailtrap lorsqu'il est configuré.
• backend/migrations/ contient les migrations PostgreSQL.

HTTP écoute par défaut sur le port 8080 ; gRPC sur le port 9091.

Tableau de bord

Le tableau de bord se trouve dans dashboard/ et est une application React Vite.

• dashboard/src/pages/ inclut les pages d'aperçu, serveurs, détails du serveur, menaces, alertes, rapports, visualiseur, IP bloquées, liste blanche, connexion, profil et rappel OAuth.
• dashboard/src/components/ contient le trafic en direct, le flux de blocage, les graphiques, les listes de serveurs, les configurateurs et les composants de mise en page partagés.
• dashboard/src/api/client.ts définit le client API REST.
• dashboard/src/context/WebSocketContext.tsx gère les mises à jour d'événements en direct.

Le serveur de développement est configuré pour http://localhost:3000.

Page d'accueil

Le site marketing public se trouve dans kerneleye-landing-page/. L'image frontend de production construit à la fois la page d'accueil et le tableau de bord, puis les sert via nginx.

Code partagé et protocoles

• shared/scoring/ contient le module de scoring de menace partagé utilisé par l'agent et le backend.
• shared/cmdsigning/ contient le module de signature de commandes HMAC-SHA256 et de protection contre la relecture par nonce.
• proto/kerneleye/v1/ contient les définitions protobuf pour les services d'ingestion et de blocage.
• proto/gen/go/ contient le code Go généré pour protobuf.

Confidentialité

KernelEye n'inspecte pas les charges utiles des paquets ni le contenu des applications.

Les métadonnées collectées incluent :

• Adresses IP source et destination.
• Ports et protocoles.
• Drapeaux TCP et compteurs de connexions.
• Compteurs de paquets et d'octets.
• Direction du trafic.
• Horodatages.
• Enrichissement optionnel GeoIP/ASN.

Non collecté :

• Charges utiles des paquets.
• Corps ou en-têtes de requêtes HTTP.
• Identifiants utilisateur.
• Données d'application.

Score de menace

Le score de menace est implémenté dans shared/scoring/scorer.go. Le scoreur actuel est plus nuancé qu'une simple formule linéaire : il prend en compte le taux de SYN, l'accès à des ports uniques, les échecs de handshake, le comportement en rafale, l'abus de service, la direction, la confiance et la décroissance du score dans le temps.

Seuils de classification par défaut :

< 20   normal
20-39  suspect
>= 40  malveillant
>= 40  éligible au blocage automatique lorsque la remédiation est activée

Le worker d'analyse du backend utilise également des fenêtres de trafic accumulées et peut déclencher la gestion des blocages pour les sources à haut risque.

Remédiation

KernelEye prend en charge la remédiation active lorsqu'elle est activée sur l'agent.

Le tableau de bord expose également la gestion des IP bloquées et de la liste blanche.

Démarrage rapide

Prérequis

• Go 1.25.x pour les modules backend et agent actuels.
• Node.js/npm pour les applications React.
• PostgreSQL 14+ ou 15+.
• Pour l'agent : Linux avec support BTF, privilèges root, clang/LLVM, bpftool, en-têtes libbpf, ipset et iptables.

Configurer l'environnement

cp .env.example .env

Définissez au moins :

DATABASE_URL=postgres://kerneleye:<mot-de-passe>@localhost:5432/kerneleye?sslmode=disable
JWT_SECRET=<au-moins-32-caractères>
API_KEY_SECRET=<secret-fort>
CORS_ORIGINS=http://localhost:3000

Les intégrations optionnelles incluent la limitation de débit Redis, les e-mails Mailtrap, OAuth GitHub/Google et GeoIP MaxMind.

Démarrer le Backend

cd backend
go mod download
go run cmd/api/main.go

Le backend démarre :

• API HTTP sur http://localhost:8080
• gRPC sur localhost:9091

Démarrer le Tableau de Bord

cd dashboard
npm install
npm run dev

Ouvrez http://localhost:3000.

La connexion se fait uniquement par OAuth. Définissez AUTH_OWNER_EMAIL et configurez au moins un fournisseur OAuth (GitHub ou Google) pour l'accès au tableau de bord. Seul l'e-mail du propriétaire configuré est autorisé à se connecter.

Construire et Exécuter l'Agent

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=<clé-api-serveur> \
  KERNELEYE_SERVER=localhost:8080 \
  KERNELEYE_GRPC_URL=localhost:9091 \
  ./kerneleye-agent

Indicateurs utiles de l'agent :

-enable-remediation     active le blocage actif et le blocage automatique
-xdp                    active le blocage rapide via XDP
-interface <nom>        sélectionne l'interface réseau pour XDP
--read-only             surveille et rapporte uniquement, ne bloque jamais
--insecure              désactive TLS (développement uniquement)
--tls-ca-file <chemin>  certificat CA du backend pour la vérification TLS
--tls-cert-file <chemin>  certificat client de l'agent pour mTLS
--tls-key-file <chemin>   clé privée client de l'agent pour mTLS
-list-blocked           affiche l'état actuel d'ipset puis quitte
-flush-blocklists       vide les listes de blocage ipset et XDP puis quitte
-clear-data             supprime les stores SQLite locaux de l'agent puis quitte
-version                affiche la version de build

Lorsque --enable-remediation est défini, CMD_SIGNING_KEY doit être configuré à la fois sur l'agent et le backend. Générez avec openssl rand -base64 32.

Structure du projet

kerneleye/
├── agent/                     Agent de surveillance Go eBPF/XDP
│   ├── ebpf/                  Programmes C eBPF et objets compilés
│   ├── remediation/           Analyseur, remédiation XDP, ipset, hybride
│   ├── assets/                Actifs d'objets XDP embarqués
│   └── scripts/               Scripts d'aide ipset et fichiers de service
├── backend/                   API Go Fiber et backend gRPC
│   ├── cmd/api/               Point d'entrée du backend
│   ├── internal/api/          HTTP, authentification, WebSocket, gRPC, API de blocage
│   ├── internal/analysis/     Workers, blocage, conservation, rapports
│   ├── internal/database/     Requêtes générées par sqlc et aides
│   ├── internal/email/        Service e-mail Mailtrap
│   ├── internal/geoip/        Service GeoIP MaxMind
│   └── migrations/            Migrations PostgreSQL
├── dashboard/                 Application tableau de bord React
├── kerneleye-landing-page/    Application page d'accueil React
├── proto/                     Définitions protobuf et code Go généré
├── shared/
│   ├── scoring/            Module Go de scoring de menace partagé
│   └── cmdsigning/         Signature de commandes HMAC et suivi des nonces
├── docs/                     Documentation supplémentaire du projet
├── tests/                    Scripts shell de simulation de trafic
├── docker/                   Modèles de configuration nginx et scripts d'installation
├── Dockerfile.backend        Construction du conteneur backend
├── Dockerfile.frontend       Image d'accueil + tableau de bord + téléchargement agent
├── docker-compose.yml        Stack compose orienté production
└── Makefile                  Cibles de génération, construction et docker

Stack technique

Testé sur

L'agent KernelEye a été testé sur les configurations suivantes. Ce tableau est mis à jour à mesure que de nouveaux environnements sont validés.

Nous utilisons ebpf-go pour l'intégration eBPF en espace utilisateur.

Construction et génération

Cibles Make communes :

make gen-proto
make gen-sql
make gen-ebpf
make build-backend
make build-agent
make build
make docker-build

L'image Docker du frontend construit la page d'accueil, le tableau de bord et un binaire téléchargeable de l'agent Linux.

Documentation

• Démarrage
• Guide de développement
• Index du code base
• Architecture de sécurité
• Modèle de menace
• Modèle de confiance
• Analyse du système de scoring
• Architecture de l'agent
• Remédiation
• Migrations de base de données

Contact

• Site web : https://example.com
• E-mail : [email protected]

Licence

KernelEye est open source sous la Licence Apache, Version 2.0 (Apache-2.0). Voir LICENSE.

Copyright 2026 Abdeljalil Aitetaleb.

Le nom KernelEye, les logos et l'identité visuelle ne sont pas sous licence Apache. Voir TRADEMARKS.md pour les conditions d'utilisation de la marque.