Black Sand Beacon

Ein Linux-C2-Beacon mit einem nativen In-Memory-ELF-BOF-Loader, geschrieben in C ohne Go- oder Rust-Runtime. Entwickelt, um in das LazyOwn RedTeam-Framework integriert zu werden, und inspiriert von Cobalt Strike's Beacon Object Files.

Dieses Repository enthält:

• Beacons in beacons/v1/, beacons/v2/, beacons/v3/ Drei Varianten desselben HTTPS/CFB-Beacons. v1 ist der kanonische Pull-Mode-Beacon. v2 fügt Mesh-/P2P-Discovery hinzu. v3 ist ein experimenteller Branch.
• BOFs in bof/<name>/bof.c Positionsunabhängige ELF-Objekte, die der Beacon abrufen und im Speicher ausführen kann. Die fünf enthaltenen sind: whoami, is_sudo, cat, userenum, suid_enum.
• C2-Server in c2/server.py Ein kleiner Python-Gopher-ähnlicher Server, der Befehle bereitstellt, Ergebnisse entgegennimmt und BOFs hostet.
• Gemeinsame Bibliothek in include/ AES-256 standalone (aes.c/aes.h), cJSON, der Runtime- Konfigurationslader (config.c/config.h plus das Python- Pendant config_py.py) und die AES-256-CFB-Wrapper, die vom Beacon und den Tests gemeinsam genutzt werden.
• Build in Makefile, CI in .github/workflows/ci.yml, Tests in tests/.

Für einen 5-minütigen End-to-End-Durchlauf siehe QUICKSTART.md. Für die BOF-Autorenanleitung siehe docs/BOF_AUTHORING.md. Für das C2-Wire-Protokoll siehe docs/PROTOCOL.md.

Voraussetzungen

Build (Debian/Ubuntu):

sudo apt-get install gcc libcurl4-openssl-dev libssl-dev make

Laufzeitumgebung für den C2-Server:

pip install -r requirements.txt

Build

make config        # one-time: copies config.example.json -> config.json
make beacon        # builds build/beacon (runnable, with build/config.json staged next to it)
make bofs          # builds all BOFs into build/bof/*.x64.o
make all-beacons   # builds v1, v2, v3
make test          # runs the full test suite
make clean         # removes build/

Nach make beacon ist die Binärdatei bereit zur Ausführung:

./build/beacon

Es liest build/config.json (neben sich selbst) über den binärrelativen Suchpfad, sodass weder BSB_CONFIG noch cd config/ erforderlich ist. Dieselbe Binärdatei, die auf einen anderen Host kopiert wird, funktioniert identisch, solange eine config.json daneben liegt.

Wenn Sie nur ein BOF neu bauen möchten:

make bof-whoami
make bof-suid_enum

Auf einen anderen Host bereitstellen (optional)

Für die Auslieferung an ein Ziel enthält das Makefile ein install-Target, das ein eigenständiges Verzeichnis bereitstellt:

make install-all DESTDIR=/tmp/deploy
scp -r /tmp/deploy/* user@target:/opt/bsb/
ssh user@target /opt/bsb/beacon

Dies ist nicht der normale Ablauf. Verwende ihn nur, wenn du die Binärdatei + Konfiguration + BOFs in einem einzigen Verzeichnis bündeln musst, das du an einen anderen Ort kopieren kannst.

Starte das C2

python3 c2/server.py

Der Server bindet standardmäßig an 0.0.0.0:7070 und liest seinen AES-Schlüssel sowie die C2-URI aus config/config.json. Der Konfigurationspfad kann mit BSB_CONFIG=/path/to/config.json überschrieben werden.

Sobald der Server läuft, können Befehle aus der REPL injiziert werden:

Client ID: linux
Command:   id

Den Beacon ausführen

./build/beacon

Der Beacon liest config/config.json (relativ zur Binary, gefunden über den binary-relativen Suchpfad), pollt das C2 und gibt aus, was er sendet und empfängt. Wenn keine Befehle in der Warteschlange stehen, schläft er einfach zwischen den Polls.

Um ein BOF auszuführen, gibt das C2 ein JSON-Objekt mit einem bof-Feld zurück, das auf /bof/<name>.x64.o verweist. Der Beacon ruft die Datei ab und lädt sie über den In-Memory-ELF-Loader (RunELF in beacons/v1/beacon.c) in seinen eigenen Prozess.

Konfiguration

Alle operativen Parameter befinden sich in config/config.json und werden beim Start gelesen. Nichts ist in die Binaries eingebrannt.

Abschnitt	Schlüssel	Standard	Zweck
c2	url	https://127.0.0.1:4444	C2-Basis-URL
c2	uri	/api/poll/	URI-Pfad vor der Client-ID
c2	client_id	linux	Beacon-Bezeichner
crypto	aes_key_hex	(Platzhalter)	64 Hex-Zeichen = 32 Bytes
crypto	mode	cfb	Verschlüsselungsmodus
timing	sleep_seconds	6	Basis-Poll-Intervall
timing	jitter_percent	20	+/- Prozent Jitter beim Schlafen
timing	curl_timeout_seconds	10	libcurl-Gesamt-Timeout
timing	curl_connect_timeout_seconds	5	libcurl-Verbindungs-Timeout
network	user_agents	(4 Strings)	Rotationsliste
network	verify_tls	false	C2-TLS-Verifikation
bof	download_chunk_size	4096	BOF-Download-Puffer

Die CI führt eine Schutzprüfung aus, die den Build fehlschlagen lässt, wenn ein 64-Zeichen-Hex-Schlüssel im Quellcode erscheint. Echte Schlüssel gehören in config/config.json, die von Git ignoriert wird.

Ein neues BOF schreiben

Ein BOF ist einfach eine C-Quelldatei, die void go(char *args, int alen) exportiert. Binde bof/include/beacon_api.h für die Callback-API und bof/include/syscalls.h für Direct-Syscall-Helfer ein. Kompiliere es positionsunabhängig und ohne libc:

gcc -c -fPIC -nostdlib -m64 -O2 -I bof/include bof/<name>/bof.c -o build/bof/<name>.x64.o

Das Ziel make bof-<name> kapselt dies ein. Legen Sie die resultierende .x64.o in sessions/uploads/ auf dem C2-Host ab und lösen Sie sie aus, indem Sie einen Befehl wie bof:<name> aus Ihrer Befehls- injektion zurückgeben.

Siehe docs/BOF_AUTHORING.md für den vollständigen Vertrag.

Testen

make test

Die Testsuite ist in mehrere Dateien in tests/ aufgeteilt:

Datei	Was sie abdeckt
test_config.py	C-JSON-Konfigurationslader: Standardwerte, Überschreibungen, Fehler
test_crypto.py	AES-256-CFB-Roundtrip und Python/C-Interop
test_bof_compile.py	Jedes BOF kompiliert, exportiert go, hat kein libc-Leak
test_beacon_build.py	Beacon-Binary wird gebaut, stellt BOF-API + RunELF bereit
test_c2_server.py	C2-Dispatcher: GET/POST/BOF, Path-Traversal-Härtung
test_c2_http_e2e.py	Echter HTTP/1.1-Socket-Roundtrip mit Krypto
test_install_deploy.py	make-Workflow erzeugt einen lauffähigen Baum, make clean löscht ihn

Repository-Layout

beacons/
  v1/beacon.c        canonical beacon
  v2/beacon.c        mesh/p2p variant
  v3/beacon.c        experimental variant
bof/
  include/           shared BOF headers (beacon_api.h, syscalls.h)
  whoami/bof.c       sample: print effective UID
  is_sudo/bof.c      sample: check sudo/wheel membership
  cat/bof.c          sample: read a file
  userenum/bof.c     sample: list /etc/passwd users and privileges
  suid_enum/bof.c    privesc recon: walk FS, list SUID/SGID binaries
c2/
  server.py          Gopher-style C2 server
config/
  config.example.json  template (copy to config.json)
include/
  config.h, config.c  runtime config loader
  config_py.py        Python mirror for the C2
  aes.h, aes.c        standalone AES (ECB/CTR/CBC)
  aes_cfb.h, aes_cfb.c  AES-256-CFB the beacon actually uses
  cJSON.h, cJSON.c     vendored JSON parser
  beacon.h            BOF API the beacon implements
tests/
  test_*.py           Python test suite
  *_harness.c         C test harnesses
docs/
  PROTOCOL.md         wire protocol
  BOF_AUTHORING.md    BOF contract and gotchas
.github/workflows/
  ci.yml              build + test + key-leak guard
Makefile
requirements.txt      C2 server runtime deps

Lizenz

GPL v3. Siehe LICENSE.