Azazel

---

Ein leichtgewichtiger, eBPF-basierter Laufzeit-Sicherheitstracer, der speziell für Malware-Analyse-Sandboxes entwickelt wurde. Gib eine Probe in einen isolierten Container, und Azazel erfasst jeden Syscall, jeden Dateizugriff, jede Netzwerkverbindung und jedes verdächtige Verhalten und liefert dir einen sauberen JSON-Stream von allem, was passiert ist.

Ob du nun eine automatisierte Malware-Analyse-Sandbox baust oder eine 24/7-Laufzeitüberwachung für autonome KI-Agenten benötigst – Azazel liefert chirurgische, unsichtbare und KI-bereite JSON-Telemetrie.

---

CLI-Referenz

Usage:
  azazel [flags]
  azazel [command]

Commands:
  run-sandbox       Run a malware sample in an isolated Docker sandbox and trace it
  list-containers   List running containers
  version           Print version

Global Flags:
  -c, --container strings   Container ID(s) to filter (can specify multiple)
  -o, --output string       Output file path (default: stdout)
      --pretty              Pretty-print JSON output
      --stdout              Also print to stdout when --output is set
  -v, --verbose             Verbose logging
      --no-summary          Disable summary on exit
  -h, --help                Help

Architektur

Was wird erfasst

Kategorie	Ereignisse	Details
Prozess	process_exec, process_exit, process_clone	Vollständiger Prozessbaum: Dateiname, argv, Exit-Codes, Clone-Flags, Eltern-PID
Datei	file_open, file_write, file_read, file_unlink, file_rename	Pfadnamen, Flags, Byte-Anzahlen
Netzwerk	net_connect, net_bind, net_listen, net_accept, net_sendto, net_dns	IPv4/IPv6-Adressen, Ports, DNS-Erkennung via kprobe auf udp_sendmsg
Sicherheit	mmap_exec, ptrace, module_load	W+X-Speicherzuordnungen, Prozess-Injektionsversuche, Laden von Kernelmodulen

19 Hook-Punkte insgesamt – Tracepoints beim Syscall-Eintritt + ein kprobe für DNS-Erkennung.

---

Warum Azazel?

• Sandbox-zentriert – entwickelt, um isolierte Container zu tracen, mit cgroup-basiertem Filtern, um nur die untersuchte Malware zu erfassen
• Keine Laufzeitabhängigkeiten – einzelne statische Go-Binärdatei, keine Agents oder Dienste
• CO-RE – Compile Once, Run Everywhere via BTF und vmlinux.h, funktioniert über Kernelversionen hinweg ohne Neukompilierung
• JSON-nativ – NDJSON-Ausgabe (ein Ereignis pro Zeile), bereit für jq, Elasticsearch, Splunk oder deine eigene Pipeline
• Integrierte Heuristiken – automatische Warnungen für Ausführung aus /tmp, Zugriff auf sensible Dateien (/etc/shadow, /proc/self/mem), ptrace, W+X mmap und Laden von Kernelmodulen

---

Schnellstart

Voraussetzungen

• Linux-Kernel 5.8+ mit CONFIG_DEBUG_INFO_BTF=y
• Docker (für den Dev-Container und die Sandbox)
• Das war's

Überprüfe deinen Kernel:

# BTF-Unterstützung (erforderlich)
ls /sys/kernel/btf/vmlinux

# Kernel-Version
uname -r

Mit Docker bauen (empfohlen)

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

# Dev-Container bauen
make docker-dev

# Betreten (privilegiert, mit Host-PID-/Cgroup-Namespace)
make docker-dev-run

# Im Container:
make vmlinux    # Kernel-Typdefinitionen generieren
make generate   # BPF C → Go-Bindings kompilieren
make build      # Binärdatei bauen

Ausführen

# Alles tracen, Ausgabe auf stdout
sudo ./bin/azazel

# Alles tracen, in Datei speichern mit hübschem JSON
sudo ./bin/azazel --output events.json --pretty

# Nur einen bestimmten Container tracen
sudo ./bin/azazel --container <container_id> --output events.json

# Laufende Container auflisten
sudo ./bin/azazel list-containers

Testsuite ausführen

# Im Dev-Container
make test

Dies baut die Binärdatei, startet den Tracer, führt einen Malware-Verhaltenssimulator aus und validiert anschließend, dass alle erwarteten Ereignistypen erfasst wurden.

---

Ausgabeformat

Jedes Ereignis ist eine einzelne JSON-Zeile (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
}

Wenn der Tracer herunterfährt (Strg+C oder SIGTERM), gibt er eine Zusammenfassung auf stderr aus:

========================================
 Azazel Summary
========================================
 Total events: 1847

 Event counts:
   file_open             892
   file_write            312
   process_exec           47
   net_connect            23
   ...

 Security Alerts (3):
   [MEDIUM] execution from suspicious path: /tmp/suspicious_binary (pid=12345 comm=bash)
   [MEDIUM] sensitive file access: /etc/shadow (pid=12346 comm=cat)
   [CRITICAL] memory mapped as WRITE+EXEC (possible code injection/unpacking) (pid=12347 comm=malware)
========================================

---

Sandbox-Einrichtung mit Docker Compose

Das enthaltene docker-compose.yml richtet eine vollständige Analyseumgebung ein:

# Sandbox starten
docker compose up -d

# Eine Probe in die Sandbox kopieren
docker cp ./samples/malware.elf sandbox:/tmp/sample

# Ausführen
docker exec sandbox /tmp/sample

# Ereignisse werden nach ./output/events.json geschrieben
cat output/events.json | jq .

Automatisierte Analyse

# Eine Probe von Ende zu Ende analysieren: Hash → Trace → Bericht
sudo ./analyze.sh ./samples/malware.elf 30

Dies erzeugt:

• output/events_<timestamp>.json — roher Ereignisstrom
• output/report_<timestamp>.md — Markdown-Bericht mit Hashes, Ereignisübersicht, Netzwerkverbindungen und Sicherheitswarnungen

---

CLI-Referenz

Usage:
  azazel [flags]
  azazel [command]

Commands:
  list-containers   List running containers
  version           Print version

Flags:
  -c, --container strings   Container ID(s) to filter (can specify multiple)
  -o, --output string       Output file path (default: stdout)
      --pretty              Pretty-print JSON output
      --stdout              Also print to stdout when --output is set
  -v, --verbose             Verbose logging
      --no-summary          Disable summary on exit
  -h, --help                Help

---

Projektstruktur