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

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

azazel/
├── main.go                          # Punto di ingresso
├── cmd/root.go                      # CLI (cobra)
├── bpf/tracer.bpf.c                 # Tutti i programmi eBPF (singolo file)
├── internal/
│   ├── tracer/
│   │   ├── tracer.go                # Core: carica, attacca, legge il ring buffer
│   │   └── events.go                # Tipi di evento, struct, parsing
│   ├── container/
│   │   └── resolver.go              # Risoluzione cgroup → ID contenitore
│   └── output/
│       └── writer.go                # Output JSON + avvisi euristici
├── test/
│   ├── simulate_malware.sh          # Simulatore di comportamento malware
│   └── run_tests.sh                 # Suite di test automatizzata
├── Dockerfile                       # Compilazione multi-stage di produzione
├── Dockerfile.dev                   # Contenitore di sviluppo con dipendenze di build
├── docker-compose.yml               # Ambiente sandbox completo
├── analyze.sh                       # Script di analisi automatizzata
└── Makefile                         # Sistema di build

Avvisi euristici

Azazel segnala automaticamente i comportamenti sospetti:

Sviluppo

Contenitore di sviluppo

Tutto viene compilato ed eseguito all'interno di un singolo contenitore Docker con Go, clang, libbpf e bpftool:

make docker-dev          # Compila l'immagine di sviluppo
make docker-dev-run      # Entra (privilegiato + namespace host)

Flusso di lavoro di compilazione

# All'interno del contenitore di sviluppo:
make vmlinux             # Genera vmlinux.h dal BTF del kernel host
make generate            # bpf2go: compila BPF C → bindings Go
make build               # Compila il binario Go
make test                # Ciclo di test completo

Verifica compatibilità kernel

make check-kernel

Risoluzione dei problemi

Stack tecnologico

Contribuire

I contributi sono benvenuti. Apri prima una issue per discutere cosa vorresti cambiare.

# Fork, clona, poi:
make docker-dev
make docker-dev-run
# hack hack hack
make test

Licenza

GPL-2.0 — vedi LICENSE per i dettagli.

I programmi BPF sono concessi in licenza GPL-2.0 (richiesto per l'accesso agli helper eBPF). Anche il codice Go nello spazio utente è GPL-2.0.

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

Percorso esecuzione sospetto	Medio	Esecuzione da `/tmp/`, `/dev/shm/`, `/var/tmp/`
Strumento sospetto	Medio	`wget`, `curl`, `nc`, `python`, `base64`, `memfd:`
Accesso a file sensibile	Medio	`/etc/passwd`, `/etc/shadow`, `/etc/sudoers`, `/etc/ssh/`, `/proc/self/maps`, `/proc/self/mem`, `/etc/ld.so.preload`
Ptrace	Alto	Qualsiasi syscall `ptrace` (iniezione di processo / debugging)
Caricamento modulo kernel	Alto	Qualsiasi syscall `finit_module`
mmap W+X	Critico	Memoria mappata contemporaneamente come SCRITTURA+ESECUZIONE (iniezione di codice, unpacking)

`operation not permitted` durante il caricamento di BPF	Il contenitore deve essere eseguito con `--privileged --pid=host --cgroupns=host`
`vmlinux.h: No such file`	Esegui `make vmlinux` (richiede `/sys/kernel/btf/vmlinux`)
`kernel doesn't support BTF`	Il kernel host necessita di `CONFIG_DEBUG_INFO_BTF=y` — verifica con `ls /sys/kernel/btf/vmlinux`
La creazione della mappa del ring buffer fallisce	Il kernel deve essere 5.8+, verifica con `uname -r`
`failed to attach tracepoint`	Alcuni tracepoint non esistono su tutti i kernel — il tracer registra un avviso e continua
Nessun evento catturato	Verifica che il tracer sia in esecuzione (`ps aux

Linguaggio	Go 1.24+
Libreria eBPF	cilium/ebpf v0.17+
Generazione codice BPF	`bpf2go` (CO-RE, basato su BTF)
Programmi BPF	C, compilati con clang, usando `vmlinux.h`
CLI	cobra
Output	NDJSON (un oggetto JSON per riga)
Contenitore	Docker, con docker-compose per l'orchestrazione della sandbox

azazel

Più Popolari

Azazel

Riferimento CLI

Architettura

Cosa cattura

Perché Azazel?

Avvio rapido

Prerequisiti

Compilazione con Docker (consigliata)

Esecuzione

Esegui la suite di test

Formato dell'output

Configurazione della sandbox con Docker Compose

Analisi automatizzata

Riferimento CLI

Struttura del progetto

Avvisi euristici

Sviluppo

Contenitore di sviluppo

Flusso di lavoro di compilazione

Verifica compatibilità kernel

Risoluzione dei problemi

Stack tecnologico

Contribuire

Licenza