C-Sentinel

Observabilidade Semântica para Sistemas UNIX

Uma sonda de sistema leve e portátil escrita em C que captura 'impressões digitais do sistema' para análise assistida por IA de riscos não óbvios. Inclui integração com auditd, pontuação de risco explicável e um painel web ao vivo com autenticação multiusuário de nível empresarial.

Demonstração ao Vivo: sentinel.speytech.com

Capturas de Tela

Painel de Segurança

Visão Geral de Múltiplos Hosts

Perfil do Usuário e Configurações de Segurança

Autenticação de Dois Fatores

Configuração	Login

Chaves de API Pessoais

Recursos de Administrador

Gerenciamento de Sessões

Registro de Auditoria

Login Seguro

Novidades na v0.6.0

• 👥 Autenticação Multiusuário - Controle de acesso baseado em funções (Admin/Operador/Visualizador)
• 🔐 Autenticação de Dois Fatores - Suporte a TOTP com Google Authenticator, Authy, etc.
• 🔑 Chaves de API Pessoais - Chaves de API por usuário para automação e CI/CD
• 📋 Registro de Auditoria do Admin - Rastreie todas as ações do usuário com filtragem
• 💻 Gerenciamento de Sessões - Visualize sessões ativas, revogue acesso, force logout
• 📧 Alertas por Email e Slack - Notificações proativas com formatação rica
• 🎨 Notificações Toast Modernas - Chega de alerts JavaScript dos anos 90!
• 👁️ Modo de Demonstração Pública - Acesso somente leitura para exibir seu painel
• 📱 Responsivo para Dispositivos Móveis - Funcionalidade completa em celulares e tablets

Versões Anteriores

v0.5.x: Resumo da postura de segurança, sparkline de tendência de risco, indicador de aprendizado, fatores de risco explicáveis, alertas por email, histórico de eventos

v0.4.0: Integração com auditd, detecção de força bruta, hash de nomes de usuário preservando privacidade, atribuição de processos, pontuação de risco

v0.3.0: Painel Web, checksums SHA256, serviço systemd, aprendizado de linha de base, sonda de rede, modo de observação

O Problema

Ferramentas modernas de observabilidade como Dynatrace, Datadog e Prometheus são excelentes na coleta de métricas e alertas de limite. Mas elas respondem a uma pergunta restrita: "Esta métrica está fora do intervalo esperado?"

Elas têm dificuldade com:

• Raciocínio causal: Por que algo falhou?
• Síntese de contexto: Conectar uma mudança de configuração da semana passada ao pico de latência de hoje
• Degradação não óbvia: Coisas que não estão 'quebradas' mas estão se afastando em direção à falha
• Contexto de segurança: Entender quem acessou o quê e por que isso importa

C-Sentinel adota uma abordagem diferente: capturar uma impressão digital abrangente do sistema — incluindo eventos de segurança — e usar raciocínio de LLM para identificar os 'fantasmas na máquina.'

Início Rápido```bash

Clone and build

git clone https://github.com/williamofai/c-sentinel.git cd c-sentinel make

Quick analysis

./bin/sentinel --quick --network

Quick analysis with security events (requires root for audit logs)

sudo ./bin/sentinel --quick --network --audit

Learn baselines (automatic with --audit flag)

./bin/sentinel --learn --network

Continuous monitoring with full context

sudo ./bin/sentinel --watch --interval 300 --network --audit

## Funcionalidades do Painel

O painel web fornece monitoramento de segurança em tempo real em toda a sua infraestrutura.

### Autenticação Multiusuário

Controle de acesso de nível empresarial com três funções:

| Função | Permissões |
|--------|------------|
| **Administrador** | Acesso total: gerenciar usuários, visualizar logs de auditoria, todas as operações |
| **Operador** | Confirmar eventos, redefinir contadores, visualizar todos os dados |
| **Visualizador** | Acesso somente leitura aos painéis e dados |

### Autenticação de Dois Fatores (TOTP)

Proteja sua conta com TOTP padrão do setor:
- Funciona com Google Authenticator, Authy, Microsoft Authenticator
- Configuração por QR code para fácil configuração
- Exigido em todo login quando ativado
- Notificações por e-mail ao ativar/desativar

### Chaves de API Pessoais

Cada usuário pode criar suas próprias chaves de API para automação:
- Chaves nomeadas (ex.: "Pipeline CI/CD", "Script de Monitoramento")
- Datas de expiração opcionais
- Ativar/desativar sem excluir
- Rastreamento do último uso
- As chaves herdam as permissões da função do usuário```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

Registro de Auditoria de Administração

Rastreie todas as ações dos usuários para conformidade e segurança:

• Eventos de login/logout com endereços IP
• Ações de gerenciamento de usuários (criar, atualizar, excluir)
• Alterações de senha
• Revogações de sessão
• Filtrável por usuário, tipo de ação e intervalo de tempo

Gerenciamento de Sessão

Visibilidade completa das sessões ativas:

• Veja quem está logado e de onde
• Detecção de dispositivo e navegador
• Revogar sessões individuais
• "Sair de todos os outros" para incidentes de segurança
• Limpeza automática de sessões expiradas

Resumo da Postura de Segurança

Explicação em linguagem simples do status de segurança do seu sistema:

"Este sistema não apresenta preocupações de segurança. Os padrões de autenticação estão normais, sem falhas detectadas. Nenhuma atividade de escalonamento de privilégio detectada. Postura geral: SAUDÁVEL."

Pontuação de Risco Explicável

Cada pontuação de risco inclui fatores que explicam por quê:

Indicador de Aprendizado/Calibração

O sistema aprende o que é 'normal' para o seu ambiente:

Minigráfico de Tendência de Risco

Um minigráfico mostrando o histórico de pontuação de risco de 24 horas - veja instantaneamente se as coisas estão melhorando ou piorando.

Alertas por Email e Slack

Notificações automáticas por email e/ou Slack quando:

• Pontuação de risco ≥ 16 (alto/crítico)
• Ataque de força bruta detectado
• Execuções de /tmp ou /dev/shm
• Login de usuário de novo IP
• Alterações de senha ou 2FA

Os alertas do Slack incluem formatação rica com gravidade codificada por cores, links clicáveis para o painel e detalhes estruturados dos fatores de risco.

Integração com Auditd

O C-Sentinel resume os logs do auditd para análise semântica de segurança.

Exemplo de Saída```

C-Sentinel Quick Analysis

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)

### Saída 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"
  }
}

Configurar Regras de Auditoria

Para melhores resultados, adicione regras de auditoria para arquivos sensíveis:```bash

Add audit rules

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

Make permanent (add to /etc/audit/rules.d/sentinel.rules)

### Funcionalidades de Privacidade

- **Hash de nomes de utilizador**: Nomes de utilizador de login falhados são hashados (ex.: `user_c4c5`) preservando a deteção de padrões sem expor identidades
- **Sem senhas**: Argumentos de comandos e dados sensíveis nunca são capturados
- **Apenas nomes de processos**: Caminhos completos são sanitizados para privacidade

## Painel de Controlo Web

### Funcionalidades

- **Autenticação Multi-Utilizador** - Controlo de acesso baseado em funções
- **Autenticação de Dois Fatores** - TOTP com configuração por código QR
- **Chaves de API Pessoais** - Chaves de automação por utilizador
- **Registo de Auditoria de Admin** - Histórico completo de ações
- **Gestão de Sessões** - Controlo de sessões ativas
- **Resumo da Postura de Segurança** - Estado do sistema em linguagem clara
- **Gráfico de Tendência de Risco** - Histórico visual de 24 horas
- **Fatores de Risco Explicáveis** - Saiba *porquê* a pontuação é o que é
- **Indicador de Aprendizagem** - Progresso da calibração da linha de base
- **Histórico de Eventos** - Linha temporal com reconhecimento
- **Alertas de Email** - Notificações proativas
- **Monitorização em Tempo Real** - Todos os hosts à vista
- **Gráficos Históricos** - Memória e carga ao longo de 24 horas
- **Vista de Rede** - Todas as portas e conexões à escuta
- **Monitorização de Configuração** - Checksums SHA256 de ficheiros monitorizados

### Configuração 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

Configuração de Alerta de Email

Adicione ao seu serviço systemd ou ambiente:```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

### Configuração de Webhook do 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 obter uma URL de webhook:

1. Acesse api.slack.com/apps
2. Crie um novo app → "Do zero"
3. Ative "Webhooks de Entrada"
4. Clique em "Adicionar Novo Webhook ao Workspace"
5. Selecione um canal e copie a URL do webhook

Consulte dashboard/README.md para instruções completas de configuração.

Modo de Demonstração Pública

Ative o acesso público somente leitura para exibir seu painel:```bash Environment="DEMO_MODE=true"

No modo de demonstração:
- Nenhum login necessário - visitantes vão direto ao painel
- Acesso somente leitura (função de visualizador)
- Funcionalidades de administrador ocultas
- Links de perfil/sair substituídos por link do GitHub
- Faixa amarela indica modo de demonstração

Ótimo para postagens no LinkedIn, artigos de blog ou permitir que clientes em potencial explorem antes de implantar.

## Serviço Systemd

Para implantação em produção:```bash
# Install
sudo ./install.sh

# Enable and start
sudo systemctl enable sentinel
sudo systemctl start sentinel

# Check status
sudo journalctl -u sentinel -f

Todos os Recursos

A saída colorida é detectada automaticamente (TTY) e respeita o padrão NO_COLOR.

Códigos de Saída (para CI/CD)

O Que Captura

O Que Sinaliza

Problemas do Sistema

• 🧟 Processos zumbi: Sempre um problema
• 📂 Contagem alta de FD: Possíveis vazamentos de descritores (>100 abertos)
• ⏰ Processos de longa duração: >7 dias sem reinicialização
• 🔓 Problemas de permissão: Configurações graváveis por todos

Problemas de Rede

• 🌐 Portas incomuns: Serviços não listados na lista de portas comuns
• 📡 Novos ouvintes: Portas que não estavam na linha de base
• ❌ Serviços ausentes: Portas esperadas que pararam de ouvir

Problemas de Segurança (com --audit)

• 🔐 Força bruta: Picos de falhas de autenticação (>5 na janela)
• 📊 Desvio da linha de base: Atividade significativamente acima do normal
• 📝 Acesso a arquivos sensíveis: Modificações em /etc/shadow, /etc/sudoers
• ⚠️ Processos suspeitos: Processo incomum acessando arquivos sensíveis
• 💀 Indicadores de malware: Execuções a partir de /tmp ou /dev/shm

Arquitetura```

┌─────────────────────────────────────────────────────────────────┐ │ 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 │ └─────────────────────────────────────────────────────────────────┘

### Porquê C?

| Preocupação | Python | C |
|---------|--------|---|
| **Dependências** | Requer runtime Python (~100MB) | Binário estático (~99KB) |
| **Tempo de inicialização** | ~500ms para inicializar o interpretador | ~1ms |
| **Memória** | ~30MB de base | <2MB |
| **Portabilidade** | Requer versão específica do Python | Funciona em qualquer sistema POSIX |

## Construção```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

Testes

O C-Sentinel inclui uma suíte de testes abrangente com mais de 128 testes unitários usando o framework de testes cmocka.

Instalando o 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

### Executando Testes```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

Cobertura de Testes

Os testes unitários cobrem:

Escrevendo Novos Testes

Os testes estão localizados em tests/src/ e usam convenções do 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); }

Adicione novos arquivos de teste à variável `TEST_SOURCES` do Makefile.

## Suporte de Plataforma

| Plataforma | Compilação | Sonda de Processo | Sonda de Rede | Auditoria |
|----------|-------|---------------|---------------|-------|
| 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 ou Clang com suporte a C99
- GNU Make (gmake no BSD)
- Plataformas suportadas:
  - Linux (kernel 3.x+)
  - macOS (10.12+)
  - FreeBSD (12+)
  - OpenBSD (7.x)
  - NetBSD (9.x)
  - DragonFlyBSD (6.x)
- auditd (opcional, apenas no Linux para a flag `--audit`)

## Estrutura do Projeto```
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

Roadmap

Concluído ✅

• Sonda central do sistema
• Serialização JSON
• Sondagem de rede
• Modo de monitorização e aprendizagem de base
• Checksums SHA256
• Serviço systemd
• Painel web
• Integração com auditd
• Pontuação de risco com análise de desvios
• Atribuição de processos
• Autenticação do painel
• Linha temporal do histórico de eventos
• Fatores de risco explicáveis
• Resumo da postura de segurança
• Sparkline de tendência de risco
• Indicador de aprendizagem/calibração

Planeado 📋

• Alertas via webhook do Microsoft Teams
• Regras de alerta personalizadas
• Relatórios de segurança em PDF
• Permissões a nível do host

Licença

Licença MIT - consulte LICENSE para mais detalhes.

Autor

William Murray - 30 anos de engenharia de sistemas UNIX

• GitHub: @williamofai
• LinkedIn: William Murray
• Site: speytech.com

"O objetivo não é substituir ferramentas de monitorização—é acrescentar sabedoria aos seus dados."