Bild

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

Bild

Was wird erfasst

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:

Bild

# 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

azazel/
├── main.go                          # Einstiegspunkt
├── cmd/root.go                      # CLI (cobra)
├── bpf/tracer.bpf.c                 # Alle eBPF-Programme (eine Datei)
├── internal/
│   ├── tracer/
│   │   ├── tracer.go                # Kern: laden, anhängen, Ringpuffer lesen
│   │   └── events.go                # Ereignistypen, Strukturen, Parsing
│   ├── container/
│   │   └── resolver.go              # cgroup → Container-ID-Auflösung
│   └── output/
│       └── writer.go                # JSON-Ausgabe + heuristische Warnungen
├── test/
│   ├── simulate_malware.sh          # Malware-Verhaltenssimulator
│   └── run_tests.sh                 # Automatisierte Testsuite
├── Dockerfile                       # Produktions-Multi-Stage-Build
├── Dockerfile.dev                   # Dev-Container mit Build-Abhängigkeiten
├── docker-compose.yml               # Vollständige Sandbox-Umgebung
├── analyze.sh                       # Automatisiertes Analysescript
└── Makefile                         # Build-System

Heuristische Warnungen

Azazel kennzeichnet verdächtiges Verhalten automatisch:

Entwickeln

Dev-Container

Alles baut und läuft innerhalb eines einzelnen Docker-Containers mit Go, clang, libbpf und bpftool:

make docker-dev          # Dev-Image bauen
make docker-dev-run      # Betreten (privilegiert + Host-Namespaces)

Build-Workflow

# Im Dev-Container:
make vmlinux             # vmlinux.h aus dem Host-Kernel-BTF generieren
make generate            # bpf2go: BPF C → Go-Bindings kompilieren
make build               # Go-Binärdatei bauen
make test                # Vollständiger Testzyklus

Kernel-Kompatibilität prüfen

make check-kernel

Fehlerbehebung

Technologie-Stack

Mitwirken

Beiträge sind willkommen. Bitte eröffne zuerst ein Issue, um zu besprechen, was du ändern möchtest.

# Fork, clone, then:
make docker-dev
make docker-dev-run
# hack hack hack
make test

Lizenz

GPL-2.0 — siehe LICENSE für Details.

BPF-Programme sind unter GPL-2.0 lizenziert (erforderlich für den Zugriff auf eBPF-Helfer). Der Userspace-Go-Code ist ebenfalls GPL-2.0.

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

Verdächtiger Ausführungspfad	Mittel	Ausführung von `/tmp/`, `/dev/shm/`, `/var/tmp/`
Verdächtiges Werkzeug	Mittel	`wget`, `curl`, `nc`, `python`, `base64`, `memfd:`
Zugriff auf sensible Dateien	Mittel	`/etc/passwd`, `/etc/shadow`, `/etc/sudoers`, `/etc/ssh/`, `/proc/self/maps`, `/proc/self/mem`, `/etc/ld.so.preload`
Ptrace	Hoch	Jeder `ptrace`-Syscall (Prozessinjektion / Debugging)
Kernelmodul laden	Hoch	Jeder `finit_module`-Syscall
W+X mmap	Kritisch	Speicher gleichzeitig als WRITE+EXEC zugeordnet (Code-Injektion, Entpacken)

`operation not permitted` beim Laden von BPF	Container muss mit `--privileged --pid=host --cgroupns=host` laufen
`vmlinux.h: No such file`	Führe `make vmlinux` aus (erfordert `/sys/kernel/btf/vmlinux`)
`kernel doesn't support BTF`	Host-Kernel benötigt `CONFIG_DEBUG_INFO_BTF=y` – prüfe `ls /sys/kernel/btf/vmlinux`
Ringbuffer-Map-Erstellung fehlgeschlagen	Kernel muss 5.8+ sein, prüfe mit `uname -r`
`failed to attach tracepoint`	Manche Tracepoints existieren nicht auf allen Kerneln – der Tracer loggt eine Warnung und fährt fort
Keine Ereignisse erfasst	Stelle sicher, dass der Tracer läuft (`ps aux

Sprache	Go 1.24+
eBPF-Bibliothek	cilium/ebpf v0.17+
BPF-Codegenerierung	`bpf2go` (CO-RE, BTF-basiert)
BPF-Programme	C, kompiliert mit clang, unter Verwendung von `vmlinux.h`
CLI	cobra
Ausgabe	NDJSON (ein JSON-Objekt pro Zeile)
Container	Docker, mit docker-compose für die Sandbox-Orchestrierung

azazel

Beliebteste

Azazel

CLI-Referenz

Architektur

Was wird erfasst

Warum Azazel?

Schnellstart

Voraussetzungen

Mit Docker bauen (empfohlen)

Ausführen

Testsuite ausführen

Ausgabeformat

Sandbox-Einrichtung mit Docker Compose

Automatisierte Analyse

CLI-Referenz

Projektstruktur

Heuristische Warnungen

Entwickeln

Dev-Container

Build-Workflow

Kernel-Kompatibilität prüfen

Fehlerbehebung

Technologie-Stack

Mitwirken

Lizenz