Azazel

---

Un tracer di sicurezza runtime leggero basato su eBPF, progettato specificamente per sandbox di analisi malware. Inserisci un campione in un contenitore isolato e Azazel cattura ogni syscall, accesso a file, connessione di rete e comportamento sospetto, fornendoti un flusso JSON pulito di tutto ciò che è accaduto.

Che tu stia costruendo una Sandbox per l'Analisi Malware automatizzata o necessiti di Monitoraggio Runtime 24/7 per Agenti AI autonomi, Azazel fornisce una telemetria JSON chirurgica, invisibile e pronta per l'AI.

---

Riferimento CLI

Usage:
  azazel [flags]
  azazel [command]

Commands:
  run-sandbox       Esegui un campione malware in una sandbox Docker isolata e traccialo
  list-containers   Elenca i contenitori in esecuzione
  version           Stampa la versione

Global Flags:
  -c, --container strings   ID del contenitore da filtrare (è possibile specificarne più di uno)
  -o, --output string       Percorso del file di output (default: stdout)
      --pretty              Stampa JSON indentato
      --stdout              Stampa anche su stdout quando --output è impostato
  -v, --verbose             Logging verboso
      --no-summary          Disabilita il riepilogo all'uscita
  -h, --help                Aiuto

Architettura

Cosa cattura

Categoria	Eventi	Dettagli
Processo	process_exec, process_exit, process_clone	Albero completo dei processi: nome file, argv, codici di uscita, flag di clone, PID padre
File	file_open, file_write, file_read, file_unlink, file_rename	Percorsi, flag, conteggi di byte
Rete	net_connect, net_bind, net_listen, net_accept, net_sendto, net_dns	Indirizzi IPv4/IPv6, porte, rilevamento DNS tramite kprobe su udp_sendmsg
Sicurezza	mmap_exec, ptrace, module_load	Mappature di memoria W+X, tentativi di iniezione di processo, caricamento di moduli del kernel

19 punti di hook in totale — tracepoint all'ingresso delle syscall + un kprobe per il rilevamento DNS.

---

Perché Azazel?

• Priorità alla sandbox — costruito per tracciare contenitori isolati, con filtraggio basato su cgroup per catturare solo il malware che stai analizzando
• Zero dipendenze a runtime — singolo binario Go statico, niente agenti o demone
• CO-RE — Compila Una Volta, Esegui Ovunque grazie a BTF e vmlinux.h, funziona su diverse versioni del kernel senza ricompilazione
• Nativo JSON — output NDJSON (un evento per riga) pronto per jq, Elasticsearch, Splunk o la tua pipeline
• Euristiche integrate — avvisi automatici per esecuzioni da /tmp, accesso a file sensibili (/etc/shadow, /proc/self/mem), ptrace, mmap W+X e caricamento di moduli del kernel

---

Avvio rapido

Prerequisiti

• Kernel Linux 5.8+ con CONFIG_DEBUG_INFO_BTF=y
• Docker (per il contenitore di sviluppo e la sandbox)
• Tutto qui

Verifica il tuo kernel:

# Supporto BTF (richiesto)
ls /sys/kernel/btf/vmlinux

# Versione del kernel
uname -r

Compilazione con Docker (consigliata)

# Clona
git clone https://github.com/beelzebub-labs/azazel.git
cd azazel

# Compila il contenitore di sviluppo
make docker-dev

# Entra (privilegiato, con namespace PID/cgroup dell'host)
make docker-dev-run

# All'interno del contenitore:
make vmlinux    # Genera le definizioni dei tipi del kernel
make generate   # Compila BPF C → bindings Go
make build      # Compila il binario

Esecuzione

# Traccia tutto, output su stdout
sudo ./bin/azazel

# Traccia tutto, salva su file con JSON indentato
sudo ./bin/azazel --output events.json --pretty

# Traccia solo un contenitore specifico
sudo ./bin/azazel --container <container_id> --output events.json

# Elenca i contenitori in esecuzione
sudo ./bin/azazel list-containers

Esegui la suite di test

# All'interno del contenitore di sviluppo
make test

Questo compila il binario, avvia il tracer, esegue un simulatore di comportamento malware, quindi verifica che tutti i tipi di evento attesi siano stati catturati.

---

Formato dell'output

Ogni evento è una singola riga JSON (NDJSON):

{
  "timestamp": "2025-01-15T14:30:22.123456789Z",
  "event_type": "process_exec",
  "pid": 12345,
  "tgid": 12345,
  "ppid": 12300,
  "uid": 0,
  "gid": 0,
  "comm": "bash",
  "cgroup_id": 6789,
  "container_id": "a1b2c3d4e5f6",
  "filename": "/tmp/suspicious_binary",
  "args": "/tmp/suspicious_binary"
}

{
  "timestamp": "2025-01-15T14:30:22.234567890Z",
  "event_type": "net_connect",
  "pid": 12345,
  "tgid": 12345,
  "ppid": 12300,
  "uid": 0,
  "gid": 0,
  "comm": "curl",
  "cgroup_id": 6789,
  "container_id": "a1b2c3d4e5f6",
  "sa_family": "AF_INET",
  "dst_addr": "93.184.216.34",
  "dst_port": 443
}

Quando il tracer viene arrestato (Ctrl+C o SIGTERM), stampa un riepilogo su stderr:

========================================
 Riepilogo Azazel
========================================
 Eventi totali: 1847

 Conteggi eventi:
   file_open             892
   file_write            312
   process_exec           47
   net_connect            23
   ...

 Avvisi di Sicurezza (3):
   [MEDIO] esecuzione da percorso sospetto: /tmp/suspicious_binary (pid=12345 comm=bash)
   [MEDIO] accesso a file sensibile: /etc/shadow (pid=12346 comm=cat)
   [CRITICO] memoria mappata come SCRITTURA+ESECUZIONE (possibile iniezione di codice/unpacking) (pid=12347 comm=malware)
========================================

---

Configurazione della sandbox con Docker Compose

Il file docker-compose.yml incluso configura un ambiente di analisi completo:

# Avvia la sandbox
docker compose up -d

# Copia un campione nella sandbox
docker cp ./samples/malware.elf sandbox:/tmp/sample

# Eseguilo
docker exec sandbox /tmp/sample

# Gli eventi vengono scritti in ./output/events.json
cat output/events.json | jq .

Analisi automatizzata

# Analizza un campione end-to-end: hash → traccia → report
sudo ./analyze.sh ./samples/malware.elf 30

Questo produce:

• output/events_<timestamp>.json — flusso grezzo di eventi
• output/report_<timestamp>.md — report Markdown con hash, riepilogo eventi, connessioni di rete e avvisi di sicurezza

---

Riferimento CLI

Usage:
  azazel [flags]
  azazel [command]

Commands:
  list-containers   Elenca i contenitori in esecuzione
  version           Stampa la versione

Flags:
  -c, --container strings   ID del contenitore da filtrare (è possibile specificarne più di uno)
  -o, --output string       Percorso del file di output (default: stdout)
      --pretty              Stampa JSON indentato
      --stdout              Stampa anche su stdout quando --output è impostato
  -v, --verbose             Logging verboso
      --no-summary          Disabilita il riepilogo all'uscita
  -h, --help                Aiuto

---

Struttura del progetto