KernelEye

Inteligencia de tráfico a nivel de kernel y remediación de amenazas para servidores Linux.

KernelEye es una plataforma de monitorización de seguridad autoalojada para servidores Linux. Utiliza eBPF, TC y XDP en un agente Go para observar metadatos de red, puntuar actividades sospechosas y aplicar remediación mediante bloqueo a nivel de kernel con XDP y reglas ipset/iptables. Un backend Go almacena y analiza eventos, mientras que un panel de React proporciona gestión de servidores, tráfico en vivo, vistas de amenazas, IPs bloqueadas, listas blancas, informes y análisis.

Qué hace

• Monitorización de tráfico Linux en tiempo real con eBPF.
• Seguimiento de ancho de banda con hooks de TC.
• Puntuación de amenazas mediante la lógica de puntuación compartida en shared/scoring.
• Análisis del lado del agente y remediación automática opcional.
• Bloqueo de paquetes por ruta rápida XDP y respaldo ipset/iptables.
• Trabajadores de análisis del lado del backend, gestión de bloqueos, retención de datos e informes mensuales.
• Ingesta por gRPC y transmisión de comandos de bloqueo entre agente y backend con cifrado TLS/mTLS y firma HMAC para comandos.
• Protección contra repetición mediante nonce monotónico y registro de auditoría estructurado para todas las acciones de remediación.
• Verificación periódica de integridad de mapas eBPF e informes de atestación de estado.
• Panel React con actualizaciones vía WebSocket, vistas detalladas de servidores, gestión de IPs bloqueadas, listas blancas, informes y análisis.
• Enriquecimiento GeoIP cuando se configuran bases de datos MaxMind.
• Soporte OAuth para GitHub y Google (acceso autoalojado de un solo propietario).
• Recopilación centrada en la privacidad: solo metadatos, sin cargas útiles de paquetes.

Arquitectura

Host Linux monitorizado
  Sonda de tráfico eBPF + Hooks de ancho de banda TC
  Cortafuegos XDP y remediación ipset/iptables
  Agente Go (verificación de comandos HMAC, registro de auditoría)
      |
      | gRPC (TLS/mTLS) + comandos de bloqueo firmados con HMAC
      v
API Backend Go
  API HTTP Fiber
  Servicios gRPC de ingesta/bloqueo (TLS/mTLS, firma de comandos)
  trabajador de análisis, gestor de bloqueos, retención, informes
  manejador de informes de integridad
      |
      v
PostgreSQL
      ^
      |
Panel React
  API REST + actualizaciones en vivo vía WebSocket

Componentes Clave

Agente

El agente reside en agent/ y es el proceso del host Linux.

• agent/main.go inicia registro, carga de eBPF, seguimiento de ancho de banda, remediación, puntuación, agregación y transmisión de comandos de bloqueo.
• agent/ebpf/traffic_probe.c captura metadatos de tráfico.
• agent/ebpf/xdp_firewall.c implementa el filtrado de paquetes XDP.
• agent/tc.go configura el seguimiento de ancho de banda con TC.
• agent/aggregator.go agrupa y envía eventos al backend.
• agent/history_store.go y agent/flush.go manejan la persistencia local y el reintento.
• agent/remediation/ contiene analizador, bloqueo automático, XDP, ipset y remediadores híbridos.

El agente requiere Linux y privilegios elevados para operaciones eBPF/XDP.

Backend

El backend reside en backend/.

• backend/cmd/api/main.go inicia la API HTTP Fiber y los servicios gRPC.
• backend/internal/api/ contiene autenticación, manejadores del panel, manejadores gRPC, APIs de bloqueo, APIs de listas blancas, manejo de WebSocket y límite de tasa.
• backend/internal/analysis/ contiene trabajadores de puntuación, gestión de bloqueos, retención de datos y lógica de informes mensuales.
• backend/internal/database/ contiene código de acceso a base de datos generado por sqlc.
• backend/internal/geoip/ maneja el enriquecimiento GeoIP.
• backend/internal/email/ envía correos electrónicos respaldados por Mailtrap cuando está configurado.
• backend/migrations/ contiene migraciones de PostgreSQL.

HTTP por defecto en el puerto 8080; gRPC por defecto en el puerto 9091.

Panel

El panel reside en dashboard/ y es una aplicación React con Vite.

• dashboard/src/pages/ incluye páginas de resumen, servidores, detalle de servidor, amenazas, alertas, informes, visualizador, IPs bloqueadas, lista blanca, inicio de sesión, perfil y callback OAuth.
• dashboard/src/components/ contiene componentes de tráfico en vivo, feed de bloqueos, gráficos, listas de servidores, configuradores y diseño compartido.
• dashboard/src/api/client.ts define el cliente de la API REST.
• dashboard/src/context/WebSocketContext.tsx gestiona las actualizaciones de eventos en vivo.

El servidor de desarrollo está configurado para http://localhost:3000.

Página de Aterrizaje

El sitio de marketing público reside en kerneleye-landing-page/. La imagen de frontend de producción construye tanto la página de aterrizaje como el panel, y luego los sirve a través de nginx.

Código Compartido y Protocolos

• shared/scoring/ contiene el módulo de puntuación de amenazas compartido utilizado por el agente y el backend.
• shared/cmdsigning/ contiene el módulo de firma de comandos HMAC-SHA256 y protección contra repetición mediante nonce.
• proto/kerneleye/v1/ contiene definiciones protobuf para servicios de ingesta y bloqueo.
• proto/gen/go/ contiene código Go generado de protobuf.

Privacidad

KernelEye no inspecciona cargas útiles de paquetes ni contenido de aplicaciones.

Los metadatos recopilados incluyen:

• Direcciones IP de origen y destino.
• Puertos y protocolos.
• Banderas TCP y contadores de conexión.
• Conteos de paquetes y bytes.
• Dirección del tráfico.
• Marcas de tiempo.
• Enriquecimiento opcional de GeoIP/ASN.

No se recopila:

• Cargas útiles de paquetes.
• Cuerpos o cabeceras de solicitudes HTTP.
• Credenciales de usuario.
• Datos de aplicaciones.

Puntuación de Amenazas

La puntuación de amenazas se implementa en shared/scoring/scorer.go. El puntuador actual es más matizado que una única fórmula lineal: considera la tasa de SYN, acceso a puertos únicos, handshakes fallidos, comportamiento de ráfagas, abuso de servicios, dirección, confianza y disminución de la puntuación con el tiempo.

Umbrales de clasificación predeterminados:

< 20   normal
20-39  sospechoso
>= 40  malicioso
>= 40  elegible para bloqueo automático cuando la remediación está habilitada

El trabajador de análisis del backend también utiliza ventanas de tráfico acumulado y puede activar la gestión de bloqueos para fuentes de alto riesgo.

Remediación

KernelEye admite remediación activa cuando está habilitada en el agente.

El panel también expone gestión de IPs bloqueadas y listas blancas.

Inicio Rápido

Requisitos Previos

• Go 1.25.x para los módulos actuales del backend y agente.
• Node.js/npm para las aplicaciones React.
• PostgreSQL 14+ o 15+.
• Para el agente: Linux con soporte BTF, privilegios root, clang/LLVM, bpftool, cabeceras libbpf, ipset e iptables.

Configurar el Entorno

cp .env.example .env

Establecer al menos:

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

Las integraciones opcionales incluyen limitación de tasa con Redis, correo Mailtrap, OAuth de GitHub/Google y GeoIP de MaxMind.

Iniciar Backend

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

El backend inicia:

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

Iniciar Panel

cd dashboard
npm install
npm run dev

Abrir http://localhost:3000.

El inicio de sesión es solo OAuth. Establecer AUTH_OWNER_EMAIL y configurar al menos un proveedor OAuth (GitHub o Google) para acceder al panel. Solo se permite iniciar sesión al correo del propietario configurado.

Compilar y Ejecutar Agente

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

Flags útiles del 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

Cuando se activa --enable-remediation, se debe configurar CMD_SIGNING_KEY tanto en el agente como en el backend. Generar con openssl rand -base64 32.

Estructura del Proyecto

kerneleye/
├── agent/                     Agente de monitorización Go eBPF/XDP
│   ├── ebpf/                  Programas C eBPF y objetos compilados
│   ├── remediation/           Analizador, XDP, ipset, remediación híbrida
│   ├── assets/                Activos de objetos XDP embebidos
│   └── scripts/               Scripts auxiliares ipset y archivos de servicio
├── backend/                   Backend API Go Fiber y gRPC
│   ├── cmd/api/               Punto de entrada del backend
│   ├── internal/api/          APIs HTTP, auth, WebSocket, gRPC, bloqueo
│   ├── internal/analysis/     Trabajadores, bloqueo, retención, informes
│   ├── internal/database/     Consultas y ayudantes generados por sqlc
│   ├── internal/email/        Servicio de correo Mailtrap
│   ├── internal/geoip/        Servicio GeoIP MaxMind
│   └── migrations/            Migraciones PostgreSQL
├── dashboard/                 Aplicación panel React
├── kerneleye-landing-page/    Aplicación página de aterrizaje React
├── proto/                     Definiciones protobuf y código Go generado
├── shared/
│   ├── scoring/            Módulo Go de puntuación de amenazas compartido
│   └── cmdsigning/         Firma de comandos HMAC y seguimiento de nonce
├── docs/                      Documentación adicional del proyecto
├── tests/                     Scripts shell de simulación de tráfico
├── docker/                    Plantillas nginx de frontend y script de instalación
├── Dockerfile.backend         Construcción del contenedor backend
├── Dockerfile.frontend        Imagen de página de aterrizaje + panel + descarga del agente
├── docker-compose.yml         Pila compose orientada a producción
└── Makefile                   Objetivos de generación, compilación y docker

Pila Tecnológica

Probado En

El agente KernelEye ha sido probado en las siguientes configuraciones. Esta tabla se actualiza a medida que se validan nuevos entornos.

Usamos ebpf-go para la integración del espacio de usuario de eBPF.

Compilación y Generación

Objetivos Make comunes:

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

La imagen Docker del frontend compila la página de aterrizaje, el panel y un binario descargable del agente Linux.

Documentación

• Primeros pasos
• Guía de desarrollo
• Índice del código base
• Arquitectura de seguridad
• Modelo de amenazas
• Modelo de confianza
• Análisis del sistema de puntuación
• Arquitectura del agente
• Remediación
• Migraciones de base de datos

Contacto

• Sitio web: https://example.com
• Correo electrónico: [email protected]

Licencia

KernelEye es código abierto bajo la Licencia Apache, Versión 2.0 (Apache-2.0). Consulte LICENSE.

Copyright 2026 Abdeljalil Aitetaleb.

El nombre de KernelEye, sus logotipos e identidad visual no están licenciados bajo la Licencia Apache. Consulte TRADEMARKS.md para conocer los términos de uso de la marca.