beelzebub-labs/azazeleBPF 기반의 무음 관찰자로, 컨테이너화된 런타임을 대상으로 하며, 악성코드 분석 샌드박스 및 에이전틱 AI 모니터링을 위해 설계되었습니다.
악성코드 분석 샌드박스를 위해 특별히 제작된 가벼운 eBPF 기반 런타임 보안 트레이서입니다. 격리된 컨테이너에 샘플을 넣으면 Azazel이 모든 시스템 호출, 파일 접근, 네트워크 연결 및 의심스러운 행동을 캡처하여 발생한 모든 사항에 대한 깔끔한 JSON 스트림을 제공합니다.
자동화된 악성코드 분석 샌드박스를 구축하든, 자율 AI 에이전트를 위한 24/7 런타임 모니터링이 필요하든, Azazel은 정밀하고 투명하며 AI에 최적화된 JSON 텔레메트리를 제공합니다.
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
총 19개의 후크 포인트 — syscall 항목의 tracepoint + DNS 탐지를 위한 kprobe.
vmlinux.h를 통해 한 번 컴파일하면 모든 곳에서 실행 가능, 커널 재컴파일 없이 다양한 커널 버전에서 작동jq, Elasticsearch, Splunk 또는 자체 파이프라인에 바로 사용 가능/tmp에서의 실행, 민감 파일 접근(/etc/shadow, /proc/self/mem), ptrace, W+X mmap, 커널 모듈 로딩에 대한 자동 경고CONFIG_DEBUG_INFO_BTF=y 필요)커널 확인:
# BTF 지원 (필수)
ls /sys/kernel/btf/vmlinux
# 커널 버전
uname -r
# 클론
git clone https://github.com/beelzebub-labs/azazel.git
cd azazel
# 개발 컨테이너 빌드
make docker-dev
# 실행 (프리빌리지드, 호스트 PID/cgroup 네임스페이스)
make docker-dev-run
# 컨테이너 내부에서:
make vmlinux # 커널 타입 정의 생성
make generate # BPF C → Go 바인딩 컴파일
make build # 바이너리 빌드
# 모든 것을 추적, stdout으로 출력
sudo ./bin/azazel
# 모든 것을 추적, 파일로 저장 (예쁜 JSON)
sudo ./bin/azazel --output events.json --pretty
# 특정 컨테이너만 추적
sudo ./bin/azazel --container <container_id> --output events.json
# 실행 중인 컨테이너 목록
sudo ./bin/azazel list-containers
# 개발 컨테이너 내부에서
make test
이 명령은 바이너리를 빌드하고, 트레이서를 시작하며, 악성코드 행동 시뮬레이터를 실행한 후, 모든 예상 이벤트 유형이 캡처되었는지 검증합니다.
모든 이벤트는 단일 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
}
트레이서가 종료될 때(Ctrl+C 또는 SIGTERM) stderr에 요약을 출력합니다:
========================================
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)
========================================
포함된 docker-compose.yml은 완전한 분석 환경을 설정합니다:
# 샌드박스 시작
docker compose up -d
# 샘플을 샌드박스로 복사
docker cp ./samples/malware.elf sandbox:/tmp/sample
# 실행
docker exec sandbox /tmp/sample
# 이벤트는 ./output/events.json에 기록됨
cat output/events.json | jq .
# 샘플을 전체적으로 분석: 해시 → 추적 → 보고서
sudo ./analyze.sh ./samples/malware.elf 30
이 명령은 다음을 생성합니다:
output/events_<timestamp>.json — 원시 이벤트 스트림output/report_<timestamp>.md — 해시, 이벤트 요약, 네트워크 연결, 보안 경고를 포함한 Markdown 보고서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
azazel/
├── main.go # Entry point
├── cmd/root.go # CLI (cobra)
├── bpf/tracer.bpf.c # All eBPF programs (single file)
├── internal/
│ ├── tracer/
│ │ ├── tracer.go # Core: load, attach, read ring buffer
│ │ └── events.go # Event types, structs, parsing
│ ├── container/
│ │ └── resolver.go # cgroup → container ID resolution
│ └── output/
│ └── writer.go # JSON output + heuristic alerts
├── test/
│ ├── simulate_malware.sh # Malware behavior simulator
│ └── run_tests.sh # Automated test suite
├── Dockerfile # Production multi-stage build
├── Dockerfile.dev # Dev container with build deps
├── docker-compose.yml # Full sandbox environment
├── analyze.sh # Automated analysis script
└── Makefile # Build system
Azazel은 의심스러운 행동을 자동으로 플래그 지정합니다:
모든 빌드와 실행은 Go, clang, libbpf, bpftool이 포함된 단일 Docker 컨테이너 내에서 이루어집니다:
make docker-dev # 개발 이미지 빌드
make docker-dev-run # 실행 (프리빌리지드 + 호스트 네임스페이스)
# 개발 컨테이너 내부에서:
make vmlinux # 호스트 커널 BTF에서 vmlinux.h 생성
make generate # bpf2go: BPF C → Go 바인딩 컴파일
make build # Go 바이너리 빌드
make test # 전체 테스트 사이클
make check-kernel
기여는 환영합니다. 변경하고 싶은 사항에 대해 먼저 이슈를 열어 논의해 주세요.
# Fork, clone, then:
make docker-dev
make docker-dev-run
# hack hack hack
make test
GPL-2.0 — 자세한 내용은 LICENSE를 참조하세요.
BPF 프로그램은 GPL-2.0에 따라 라이선스가 부여됩니다(eBPF 헬퍼 액세스에 필요). 사용자 공간 Go 코드도 GPL-2.0입니다.
| 분류 | 이벤트 | 상세 |
|---|
| 프로세스 | process_exec, process_exit, process_clone | 전체 프로세스 트리: 파일명, argv, 종료 코드, clone 플래그, 부모 PID |
| 파일 | file_open, file_write, file_read, file_unlink, file_rename | 경로명, 플래그, 바이트 수 |
| 네트워크 | net_connect, net_bind, net_listen, net_accept, net_sendto, net_dns | IPv4/IPv6 주소, 포트, udp_sendmsg kprobe를 통한 DNS 탐지 |
| 보안 | mmap_exec, ptrace, module_load | W+X 메모리 매핑, 프로세스 인젝션 시도, 커널 모듈 로딩 |
| 알림 | 심각도 | 트리거 |
|---|
| 의심스러운 실행 경로 | 중간 | /tmp/, /dev/shm/, /var/tmp/에서 실행 |
| 의심스러운 도구 | 중간 | wget, curl, nc, python, base64, memfd: |
| 민감 파일 접근 | 중간 | /etc/passwd, /etc/shadow, /etc/sudoers, /etc/ssh/, /proc/self/maps, /proc/self/mem, /etc/ld.so.preload |
| Ptrace | 높음 | 모든 ptrace 시스템 호출 (프로세스 인젝션/디버깅) |
| 커널 모듈 로드 | 높음 | 모든 finit_module 시스템 호출 |
| W+X mmap | 심각 | 메모리가 WRITE+EXEC로 동시에 매핑됨 (코드 인젝션, 언패킹) |
| 문제 | 해결 방법 |
|---|
BPF 로딩 시 operation not permitted | 컨테이너는 --privileged --pid=host --cgroupns=host 플래그로 실행해야 함 |
vmlinux.h: No such file | make vmlinux 실행 (필요 조건: /sys/kernel/btf/vmlinux) |
kernel doesn't support BTF | 호스트 커널에 CONFIG_DEBUG_INFO_BTF=y 필요 — ls /sys/kernel/btf/vmlinux 확인 |
| 링 버퍼 맵 생성 실패 | 커널 5.8+ 필요, uname -r로 확인 |
failed to attach tracepoint | 일부 tracepoint는 모든 커널에 존재하지 않음 — 트레이서가 경고를 기록하고 계속 진행 |
| 이벤트가 캡처되지 않음 | 트레이서가 실행 중인지 확인(ps aux | grep azazel), 테스트 활동이 트레이서 시작 후에 발생하는지 확인 |
| 구성 요소 | 기술 |
|---|
| 언어 | Go 1.24+ |
| eBPF 라이브러리 | cilium/ebpf v0.17+ |
| BPF 코드 생성 | bpf2go (CO-RE, BTF 기반) |
| BPF 프로그램 | C, clang으로 컴파일, vmlinux.h 사용 |
| CLI | cobra |
| 출력 | NDJSON (한 줄에 하나의 JSON 객체) |
| 컨테이너 | Docker, docker-compose로 샌드박스 오케스트레이션 |