Observabilidad Semántica para Sistemas UNIX - Una sonda de sistema ligera basada en C con análisis impulsado por IA
Observabilidad Semántica para Sistemas UNIX
Un probe de sistema ligero y portátil escrito en C que captura "huellas del sistema" para análisis asistido por IA de riesgos no obvios. Incluye integración con auditd, puntuación de riesgos explicable y un panel web en vivo con autenticación multiusuario de nivel empresarial.
Demo en vivo: sentinel.speytech.com
| Configuración | Inicio de sesión |
|---|---|
 |  |
v0.5.x: Resumen de postura de seguridad, minigráfico de tendencia de riesgos, indicador de aprendizaje, factores de riesgo explicables, alertas por correo electrónico, historial de eventos
v0.4.0: Integración con auditd, detección de fuerza bruta, hash de nombres de usuario que preserva la privacidad, atribución de procesos, puntuación de riesgos
v0.3.0: Panel web, sumas de verificación SHA256, servicio systemd, aprendizaje de línea base, sonda de red, modo de vigilancia
Las herramientas modernas de observabilidad como Dynatrace, Datadog y Prometheus son excelentes para la recolección de métricas y alertas basadas en umbrales. Pero responden una pregunta limitada: "¿Está esta métrica fuera de su rango esperado?"
Tienen dificultades con:
C-Sentinel adopta un enfoque diferente: capturar una huella completa del sistema, incluidos los eventos de seguridad, y utilizar el razonamiento de LLM para identificar los "fantasmas en la máquina".
git clone https://github.com/williamofai/c-sentinel.git cd c-sentinel make
./bin/sentinel --quick --network
sudo ./bin/sentinel --quick --network --audit
./bin/sentinel --learn --network
sudo ./bin/sentinel --watch --interval 300 --network --audit
## Características del Panel
El panel web proporciona monitoreo de seguridad en tiempo real en toda su infraestructura.
### Autenticación Multiusuario
Control de acceso de nivel empresarial con tres roles:
| Rol | Permisos |
|------|-------------|
| **Administrador** | Acceso completo: gestionar usuarios, ver registros de auditoría, todas las operaciones |
| **Operador** | Reconocer eventos, restablecer contadores, ver todos los datos |
| **Espectador** | Acceso de solo lectura a paneles y datos |
### Autenticación de Dos Factores (TOTP)
Asegure su cuenta con TOTP estándar de la industria:
- Funciona con Google Authenticator, Authy, Microsoft Authenticator
- Configuración mediante código QR para fácil configuración
- Requerido en cada inicio de sesión cuando está habilitado
- Notificaciones por correo electrónico al habilitar/deshabilitar
### Claves API Personales
Cada usuario puede crear sus propias claves API para automatización:
- Claves con nombre (p. ej., "CI/CD Pipeline", "Script de Monitoreo")
- Fechas de vencimiento opcionales
- Habilitar/deshabilitar sin eliminar
- Seguimiento de último uso
- Las claves heredan los permisos del rol del usuario```bash
# Use your personal API key
curl -X POST https://sentinel.example.com/api/ingest \
-H "Content-Type: application/json" \
-H "X-API-Key: sk_your_personal_key" \
-d @fingerprint.json
Rastrea todas las acciones de los usuarios para cumplimiento y seguridad:
Visibilidad completa de las sesiones activas:
Explicación en lenguaje sencillo del estado de seguridad de tu sistema:
"Este sistema no muestra problemas de seguridad. Los patrones de autenticación son normales sin fallos detectados. No se ha detectado actividad de escalada de privilegios. Postura general: SALUDABLE."
Cada puntuación de riesgo incluye factores que explican por qué:
| Factor | Peso |
|---|---|
| 10 fallos de autenticación (200% por encima de la línea base - alto) | +30 |
| Patrón de ataque de fuerza bruta detectado | +10 |
| 2 archivo(s) sensible(s) accedido(s) | +4 |
| Total | 44 |
El sistema aprende lo que es "normal" para tu entorno:
| Muestras | Estado | Significado |
|---|---|---|
| < 10 | 🧠 Aprendiendo | Construyendo línea base inicial |
| 10-50 | 🧠 Calibrando | Refinando patrones normales |
| > 50 | (oculto) |
Un minigráfico que muestra el historial de puntuación de riesgo de 24 horas: ve al instante si las cosas están mejorando o empeorando.
Notificaciones automáticas por correo electrónico y/o Slack cuando:
Las alertas de Slack incluyen formato enriquecido con gravedad codificada por colores, enlaces de panel de control en los que se puede hacer clic y detalles estructurados de factores de riesgo.
C-Sentinel resume los registros de auditd para un análisis semántico de seguridad.
Hostname: axioma-validator Uptime: 14.5 days Load: 0.02 0.04 0.00 Memory: 49.2% used Processes: 120 total
Potential Issues: Zombie processes: 0 High FD processes: 1 Long-running (>7d): 95 Config permission issues: 0
Network: Listening ports: 26 Established connections: 14 Unusual ports: 12 ⚠
Security (audit): Auth failures: 6 ⚠ BRUTE FORCE PATTERN DETECTED Sudo commands: 81 Sensitive file access: 2 - /etc/passwd by touch - /etc/shadow by touch ⚠
Risk: high (score: 25)
### Salida JSON```json
{
"audit_summary": {
"enabled": true,
"period_seconds": 300,
"authentication": {
"failures": 6,
"failure_users_hashed": ["user_c4c5", "user_b91b"],
"brute_force_detected": true
},
"privilege_escalation": {
"sudo_count": 81,
"sudo_baseline_avg": 12.5,
"sudo_deviation_pct": 548.0,
"su_count": 5
},
"file_integrity": {
"sensitive_file_access": [
{
"path": "/etc/shadow",
"access": "write",
"count": 2,
"process": "touch",
"process_chain": ["touch", "bash", "sshd"],
"suspicious": true
}
]
},
"learning": {
"sample_count": 42,
"confidence": "medium"
},
"risk_factors": [
{"reason": "6 auth failures (200% above baseline - high)", "weight": 18},
{"reason": "Brute force attack pattern detected", "weight": 10}
],
"risk_score": 25,
"risk_level": "high"
}
}
Para obtener mejores resultados, agregue reglas de auditoría para archivos sensibles:```bash
sudo auditctl -w /etc/passwd -p wa -k identity sudo auditctl -w /etc/shadow -p wa -k identity sudo auditctl -w /etc/sudoers -p wa -k priv_esc sudo auditctl -w /var/log/lastlog -p wa -k auth
### Funciones de Privacidad
- **Hash de nombres de usuario**: Los nombres de usuario de inicios de sesión fallidos se hashean (por ejemplo, `user_c4c5`) preservando la detección de patrones sin exponer identidades
- **Sin contraseñas**: Los argumentos de comandos y datos sensibles nunca se capturan
- **Solo nombres de procesos**: Rutas completas sanitizadas por privacidad
## Panel Web
C-Sentinel incluye un panel web para monitorear múltiples hosts en tiempo real.
### Características
- **Autenticación Multi-Usuario** - Control de acceso basado en roles
- **Autenticación de Dos Factores** - Configuración TOTP con código QR
- **Claves API Personales** - Claves de automatización por usuario
- **Registro de Auditoría de Administrador** - Historial completo de acciones
- **Gestión de Sesiones** - Control de sesiones activas
- **Resumen de Postura de Seguridad** - Estado del sistema en lenguaje sencillo
- **Gráfico de Tendencia de Riesgo** - Historial visual de 24 horas
- **Factores de Riesgo Explicables** - Sepa *por qué* la puntuación es lo que es
- **Indicador de Aprendizaje** - Progreso de calibración de línea base
- **Historial de Eventos** - Línea de tiempo con confirmación
- **Alertas por Correo Electrónico** - Notificaciones proactivas
- **Monitoreo en Tiempo Real** - Todos los hosts de un vistazo
- **Gráficos Históricos** - Memoria y carga durante 24 horas
- **Vista de Red** - Todos los puertos y conexiones en escucha
- **Seguimiento de Configuración** - Sumas SHA256 de archivos monitoreados
### Configuración Rápida```bash
# Install dashboard
cd dashboard
sudo ./install-dashboard.sh
# Run database migration
sudo -u postgres psql -d sentinel -f migrate.sql
# Install 2FA dependencies (optional)
sudo /opt/sentinel-dashboard/venv/bin/pip install pyotp qrcode pillow
# Configure agent to report (with audit)
*/5 * * * * sudo /usr/local/bin/sentinel --json --network --audit | curl -s -X POST \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d @- https://your-dashboard.com/api/ingest
Añade a tu servicio systemd o entorno:```bash ALERT_EMAIL_ENABLED=true ALERT_SMTP_HOST=smtp.gmail.com ALERT_SMTP_PORT=587 ALERT_SMTP_USER=[email protected] ALERT_SMTP_PASS=your-app-password ALERT_FROM=[email protected] ALERT_TO=[email protected] ALERT_COOLDOWN_MINS=60
### Configuración del Webhook de Slack```bash
ALERT_SLACK_ENABLED=true
ALERT_SLACK_WEBHOOK=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
ALERT_SLACK_CHANNEL=#security-alerts # Optional - override default webhook channel
ALERT_SLACK_USERNAME=C-Sentinel # Optional - bot display name
Para obtener una URL de webhook:
Consulta dashboard/README.md para obtener instrucciones completas de configuración.
Habilita el acceso público de solo lectura para mostrar tu panel:```bash Environment="DEMO_MODE=true"
En modo demo:
- No se requiere inicio de sesión: los visitantes van directamente al panel
- Acceso de solo lectura (rol de visor)
- Funciones de administración ocultas
- Enlaces de perfil/cierre de sesión reemplazados por enlace a GitHub
- Banner amarillo indica modo demo
Ideal para publicaciones de LinkedIn, artículos de blog o para que los prospectos exploren antes de implementar.
## Systemd Service
Para implementación en producción:```bash
# Install
sudo ./install.sh
# Enable and start
sudo systemctl enable sentinel
sudo systemctl start sentinel
# Check status
sudo journalctl -u sentinel -f
La salida de color se detecta automáticamente (TTY) y respeta el estándar NO_COLOR.
| Código | Significado |
|---|---|
| 0 | Sin problemas detectados |
| 1 | Advertencias (problemas menores) |
| 2 | Crítico (zombies, problemas de permisos, puertos inusuales, eventos de seguridad de alto riesgo) |
| 3 |
┌─────────────────────────────────────────────────────────────────┐ │ Web Dashboard │ │ • Multi-user auth (RBAC) • Two-factor authentication │ │ • Personal API keys • Session management │ │ • Admin audit log • Email & Slack alerts │ │ • Security posture summary • Risk trend sparkline │ │ • Explainable risk factors • Event history timeline │ │ • Multi-host view • Historical charts │ └─────────────────────────────────────────────────────────────────┘ ▲ │ JSON via HTTP POST │ ┌─────────────────────────────────────────────────────────────────┐ │ C Foundation (99KB) │ │ • /proc parsing • SHA256 checksums │ │ • Process analysis • Drift detection │ │ • Network probing • Baseline learning │ │ • Auditd parsing • Risk scoring │ │ • Process chains • Anomaly detection │ └─────────────────────────────────────────────────────────────────┘
### ¿Por qué C?
| Factor | Python | C |
|---------|--------|---|
| **Dependencias** | Requiere el intérprete de Python (~100MB) | Binario estático (~99KB) |
| **Tiempo de inicio** | ~500ms de inicio del intérprete | ~1ms |
| **Memoria** | ~30MB de base | <2MB |
| **Portabilidad** | Requiere una versión de Python compatible | Se ejecuta en cualquier sistema POSIX |
## Construcción```bash
make # Release build
make DEBUG=1 # Debug build with symbols
make test # Run all tests (unit + integration)
make install # Install to /usr/local/bin
C-Sentinel incluye un conjunto completo de pruebas con más de 128 pruebas unitarias que utilizan el marco de pruebas cmocka.
Debian/Ubuntu:```bash sudo apt-get install libcmocka-dev
**Fedora/RHEL/CentOS:**```bash
sudo dnf install libcmocka-devel
macOS (Homebrew):```bash brew install cmocka
**FreeBSD:**```bash
sudo pkg install cmocka
OpenBSD:```bash doas pkg_add cmocka
### Ejecución de pruebas```bash
make test # Run all tests (unit + integration)
make unit-test # Run unit tests only (requires cmocka)
make integration-test # Run integration/smoke tests only
make coverage # Run tests with gcov coverage report
make check-cmocka # Verify cmocka is installed correctly
Las pruebas unitarias cubren:
Las pruebas se encuentran en tests/src/ y utilizan las convenciones de cmocka:```c
#include <stdarg.h>
#include <stddef.h>
#include <setjmp.h>
#include <cmocka.h>
#include "test_helpers.h"
static void test_example(void **state) { (void)state; assert_int_equal(1 + 1, 2); }
int main(void) { const struct CMUnitTest tests[] = { cmocka_unit_test(test_example), }; return cmocka_run_group_tests(tests, NULL, NULL); }
Agregar nuevos archivos de prueba a la variable `TEST_SOURCES` del Makefile.
## Soporte de Plataforma
| Plataforma | Compilación | Sonda de Procesos | Sonda de Red | Auditoría |
|----------|-------|---------------|---------------|-------|
| Linux | ✅ | ✅ /proc | ✅ /proc/net | ✅ auditd |
| macOS | ✅ | ✅ libproc | ✅ netstat | ❌ N/A |
| FreeBSD | ✅ | ✅ libkvm | ✅ netstat | ❌ N/A |
| OpenBSD | ✅ | ✅ libkvm | ✅ netstat | ❌ N/A |
| NetBSD | ✅ | ✅ libkvm | ✅ netstat | ❌ N/A |
| DragonFlyBSD | ✅ | ✅ libkvm | ✅ netstat | ❌ N/A |
### Requisitos
- GCC o Clang con soporte C99
- GNU Make (gmake en BSD)
- Plataformas compatibles:
- Linux (kernel 3.x+)
- macOS (10.12+)
- FreeBSD (12+)
- OpenBSD (7.x)
- NetBSD (9.x)
- DragonFlyBSD (6.x)
- auditd (opcional, solo Linux para la opción `--audit`)
## Estructura del Proyecto```
c-sentinel/
├── include/
│ ├── sentinel.h # Core data structures
│ └── audit.h # Audit integration types
├── src/
│ ├── main.c # CLI entry point
│ ├── prober.c # System probing (/proc)
│ ├── net_probe.c # Network probing
│ ├── audit.c # Auditd log parsing
│ ├── audit_json.c # Audit JSON serialisation
│ ├── process_chain.c # Process ancestry walking
│ ├── baseline.c # Baseline learning
│ ├── sha256.c # Pure C SHA256
│ └── ...
├── dashboard/ # Flask web dashboard
├── deploy/ # Systemd service files
└── docs/
├── AUDIT_SPEC.md # Audit integration design
└── DESIGN_DECISIONS.md
Licencia MIT - consulte LICENSE para más detalles.
William Murray - 30 años de ingeniería de sistemas UNIX
"El objetivo no es reemplazar las herramientas de monitoreo, sino agregar sabiduría a sus datos."
| Totalmente calibrado |
| Característica | Comando | Descripción |
|---|
| Análisis rápido | --quick | Resumen legible |
| Sonda de red | --network | Puertos y conexiones en escucha |
| Sonda de auditoría | --audit | Eventos de seguridad (requiere root) |
| Modo vigilancia | --watch --interval 60 | Monitoreo continuo |
| Aprendizaje de línea base | --learn | Guardar estado actual como "normal" |
| Línea base de auditoría | --audit-learn | Aprender patrones de seguridad normales |
| Comparar línea base | --baseline | Detectar desviaciones |
| Salida JSON | --json | Huella completa para LLM/panel |
| Salida de color | --color | Salida de terminal coloreada |
| Config | --config | Mostrar configuración actual |
| Error (falló la sonda) |
| Categoría | Datos | Propósito |
|---|
| Sistema | Nombre de host, kernel, tiempo de actividad, carga, memoria | Contexto básico de salud |
| Procesos | Procesos notables con metadatos | Detección de zombies, fugas, atascados |
| Configuraciones | Metadatos de archivo + sumas de verificación SHA256 | Detección de deriva criptográfica |
| Red | Escuchas, conexiones, puertos | Monitoreo de servicios |
| Seguridad | Fallos de autenticación, uso de sudo, acceso a archivos | Detección de amenazas |
| Módulo | Pruebas | Cobertura |
|---|
| SHA256 | 10 | Vectores de prueba NIST, casos límite |
| Sanitize | 30 | Validación de entrada, prevención de inyección |
| Policy | 36 | Reglas de permitir/denegar comandos/rutas |
| JSON Serialize | 11 | Formateo de salida, escape |
| Baseline | 11 | Modo de aprendizaje, detección de desviaciones |
| Config | 9 | Análisis de configuración |
| Audit | 21 | Puntuación de riesgo, análisis de eventos |