Black Sand Beacon

Un beacon C2 per Linux con un loader ELF BOF nativo in memoria, scritto in C senza runtime Go o Rust. Progettato per integrarsi nel framework LazyOwn RedTeam e ispirato ai Beacon Object Files di Cobalt Strike.

Questo repository contiene:

Beacon in beacons/v1/, beacons/v2/, beacons/v3/ Tre varianti dello stesso beacon HTTPS/CFB. v1 è il beacon canonico in modalità pull. v2 aggiunge il discovery mesh/p2p. v3 è un ramo sperimentale.
BOF in bof/<name>/bof.c Oggetti ELF position-independent che il beacon può recuperare ed eseguire in memoria. I cinque inclusi sono: whoami, is_sudo, cat, userenum, suid_enum.
Server C2 in c2/server.py Un piccolo server Python simile a Gopher che serve comandi, accetta risultati e ospita i BOF.
Libreria condivisa in include/ AES-256 standalone (aes.c/aes.h), cJSON, il loader della configurazione runtime (config.c/config.h più il mirror Python config_py.py), e i wrapper AES-256-CFB condivisi tra il beacon e i test.
Build in Makefile, CI in .github/workflows/ci.yml, test in tests/.

Per un'esecuzione end-to-end di 5 minuti, vedi QUICKSTART.md. Per la guida alla scrittura dei BOF, vedi docs/BOF_AUTHORING.md. Per il protocollo di rete C2, vedi docs/PROTOCOL.md.

Requisiti

Build (Debian/Ubuntu):

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

Runtime per il server C2:

pip install -r requirements.txt

Compilazione

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/

Dopo make beacon, il binario è pronto per l'esecuzione:

./build/beacon

Lo legge build/config.json (accanto a sé stesso) tramite il percorso di ricerca relativo al binario, quindi non sono necessari BSB_CONFIG o cd config/. Lo stesso binario copiato su un altro host funziona in modo identico purché un config.json si trovi accanto ad esso.

Se vuoi ricostruire solo un BOF:

make bof-whoami
make bof-suid_enum

Distribuzione su un altro host (opzionale)

Per il trasferimento su una destinazione, il Makefile dispone di un target install che prepara una directory autonoma:

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

Questo non è il flusso normale. Usalo solo quando devi raggruppare il binario + la configurazione + i BOF in un'unica directory che puoi copiare altrove.

Esegui il C2

python3 c2/server.py

Il server si associa a 0.0.0.0:7070 per impostazione predefinita e legge la sua chiave AES e l'URI C2 da config/config.json. Sovrascrivi il percorso della configurazione con BSB_CONFIG=/path/to/config.json.

Una volta che il server è attivo puoi iniettare comandi dalla REPL:

Client ID: linux
Command:   id

Esegui il beacon

./build/beacon

Il beacon legge config/config.json (relativo al binario, trovato tramite il percorso di ricerca relativo al binario), esegue il polling del C2 e stampa ciò che invia e riceve. Senza comandi in coda, si limita a dormire tra un polling e l'altro.

Per eseguire un BOF, il C2 restituisce un oggetto JSON con un campo bof che punta a /bof/<name>.x64.o. Il beacon recupera il file e lo carica nel proprio processo tramite il loader ELF in memoria (RunELF in beacons/v1/beacon.c).

Configurazione

Tutti i parametri operativi risiedono in config/config.json e vengono letti all'avvio. Nulla è incorporato nei binari.

Sezione	Chiave	Predefinito	Scopo
`c2`	`url`	`https://127.0.0.1:4444`	URL base del C2
`c2`	`uri`	`/api/poll/`	Percorso URI prima dell'id client
`c2`	`client_id`	`linux`	Identificatore del beacon
`crypto`	`aes_key_hex`	(segnaposto)	64 caratteri hex = 32 byte
`crypto`	`mode`	`cfb`	Modalità di cifratura
`timing`	`sleep_seconds`	`6`	Intervallo di polling base
`timing`	`jitter_percent`	`20`	Jitter +/- percentuale sul sonno
`timing`	`curl_timeout_seconds`	`10`	Timeout totale di libcurl
`timing`	`curl_connect_timeout_seconds`	`5`	Timeout di connessione di libcurl
`network`	`user_agents`	(4 stringhe)	Lista di rotazione
`network`	`verify_tls`	`false`	Verifica TLS del C2
`bof`	`download_chunk_size`	`4096`	Buffer di download dei BOF

La CI esegue un controllo che fa fallire la build se una chiave hex di 64 caratteri compare nel codice sorgente. Le chiavi reali appartengono a config/config.json, che è ignorato da git.

Scrivere un nuovo BOF

Un BOF è semplicemente un file sorgente C che esporta void go(char *args, int alen). Includi bof/include/beacon_api.h per l'API di callback e bof/include/syscalls.h per gli helper di syscall dirette. Compilalo position-independent e senza libc:

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

Il target make bof-<name> esegue questo processo. Copia il file .x64.o risultante in sessions/uploads/ sull'host C2 e attivalo restituendo un comando come bof:<name> dalla tua command injection.

Consulta docs/BOF_AUTHORING.md per il contratto completo.

Testing

make test

La suite di test è suddivisa in diversi file in tests/:

File	Cosa copre
`test_config.py`	Loader di configurazione JSON in C: valori predefiniti, override, errori
`test_crypto.py`	Roundtrip AES-256-CFB e interoperabilità Python/C
`test_bof_compile.py`	Ogni BOF viene compilato, esporta `go`, non presenta leak di libc
`test_beacon_build.py`	Il binario Beacon viene compilato, espone l'API BOF + RunELF
`test_c2_server.py`	Dispatcher C2: GET/POST/BOF, hardening contro path traversal
`test_c2_http_e2e.py`	Roundtrip reale su socket HTTP/1.1 con crittografia
`test_install_deploy.py`	Il flusso di lavoro `make` produce un albero eseguibile, `make clean` lo cancella

Struttura del repository

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

Licenza

GPL v3. Vedi LICENSE.

blacksandbeacon

Più Popolari