Black Sand Beacon

Un beacon C2 para Linux con un cargador BOF ELF nativo en memoria, escrito en C sin runtime de Go ni Rust. Diseñado para integrarse en el framework LazyOwn RedTeam e inspirado en los Beacon Object Files de Cobalt Strike.

Este repositorio contiene:

• Beacons en beacons/v1/, beacons/v2/, beacons/v3/ Tres variantes del mismo beacon HTTPS/CFB. v1 es el beacon canónico en modo pull. v2 añade descubrimiento mesh/p2p. v3 es una rama experimental.
• BOFs en bof/<name>/bof.c Objetos ELF independientes de posición que el beacon puede descargar y ejecutar en memoria. Los cinco incluidos son: whoami, is_sudo, cat, userenum, suid_enum.
• Servidor C2 en c2/server.py Un pequeño servidor Python tipo Gopher que sirve comandos, acepta resultados y aloja BOFs.
• Biblioteca compartida en include/ AES-256 autónomo (aes.c/aes.h), cJSON, el cargador de configuración en tiempo de ejecución (config.c/config.h más el espejo en Python config_py.py), y los wrappers AES-256-CFB compartidos por el beacon y las pruebas.
• Compilación en Makefile, CI en .github/workflows/ci.yml, pruebas en tests/.

Para una ejecución completa de 5 minutos, consulta QUICKSTART.md. Para la guía de creación de BOFs, consulta docs/BOF_AUTHORING.md. Para el protocolo de comunicación del C2, consulta docs/PROTOCOL.md.

Requisitos

Compilación (Debian/Ubuntu):

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

Entorno de ejecución para el servidor C2:

pip install -r requirements.txt

Compilación

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/

Después de make beacon, el binario está listo para ejecutarse:

./build/beacon

Lo lee build/config.json (junto a sí mismo) a través de la ruta de búsqueda relativa al binario, por lo que no se necesita BSB_CONFIG ni cd config/. El mismo binario copiado a otro host funciona de forma idéntica siempre que un config.json se encuentre junto a él.

Si solo quieres reconstruir un BOF:

make bof-whoami
make bof-suid_enum

Desplegar en otro host (opcional)

Para enviar a un destino, el Makefile tiene un objetivo install que prepara un directorio autocontenido:

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

Este no es el flujo normal. Úsalo solo cuando necesites empaquetar el binario + la configuración + los BOFs en un único directorio que puedas copiar a otro lugar.

Ejecutar el C2

python3 c2/server.py

El servidor se enlaza a 0.0.0.0:7070 por defecto y lee su clave AES y la URI de C2 desde config/config.json. Sobrescribe la ruta de configuración con BSB_CONFIG=/path/to/config.json.

Una vez que el servidor está en marcha, puedes inyectar comandos desde el REPL:

Client ID: linux
Command:   id

Ejecutar el beacon

./build/beacon

El beacon lee config/config.json (relativo al binario, encontrado mediante la ruta de búsqueda relativa al binario), consulta el C2 e imprime lo que envía y recibe. Sin comandos en cola, simplemente duerme entre consultas.

Para ejecutar un BOF, el C2 devuelve un objeto JSON con un campo bof que apunta a /bof/<name>.x64.o. El beacon obtiene el archivo y lo carga en su propio proceso mediante el cargador ELF en memoria (RunELF en beacons/v1/beacon.c).

Configuración

Todos los parámetros operativos residen en config/config.json y se leen al inicio. Nada está integrado en los binarios.

Sección	Clave	Predeterminado	Propósito
c2	url	https://127.0.0.1:4444	URL base del C2
c2	uri	/api/poll/	Ruta URI antes del id de cliente
c2	client_id	linux	Identificador del beacon
crypto	aes_key_hex	(marcador de posición)	64 caracteres hex = 32 bytes
crypto	mode	cfb	Modo de cifrado
timing	sleep_seconds	6	Intervalo base de consulta
timing	jitter_percent	20	Porcentaje +/- de jitter en el sueño
timing	curl_timeout_seconds	10	Tiempo de espera total de libcurl
timing	curl_connect_timeout_seconds	5	Tiempo de espera de conexión de libcurl
network	user_agents	(4 cadenas)	Lista de rotación
network	verify_tls	false	Verificación TLS del C2
bof	download_chunk_size	4096	Búfer de descarga de BOF

La CI ejecuta una comprobación de seguridad que hace fallar la compilación si una clave hex de 64 caracteres aparece en el código fuente. Las claves reales pertenecen a config/config.json, que está ignorado por git.

Escribir un nuevo BOF

Un BOF es simplemente un archivo fuente C que exporta void go(char *args, int alen). Incluye bof/include/beacon_api.h para la API de callback y bof/include/syscalls.h para los ayudantes de llamadas directas al sistema. Compílalo independiente de la posición y sin libc:

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

El objetivo make bof-<name> envuelve esto. Coloca el archivo .x64.o resultante en sessions/uploads/ en el host C2 y actívalo devolviendo un comando como bof:<name> desde tu inyección de comandos.

Consulta docs/BOF_AUTHORING.md para ver el contrato completo.

Pruebas

make test

El conjunto de pruebas está dividido en varios archivos en tests/:

Archivo	Qué cubre
test_config.py	Cargador de configuración JSON en C: valores predeterminados, sobrescrituras, errores
test_crypto.py	Ida y vuelta de AES-256-CFB e interoperabilidad entre Python y C
test_bof_compile.py	Cada BOF compila, exporta go, no tiene fuga de libc
test_beacon_build.py	El binario Beacon compila, expone la API de BOF + RunELF
test_c2_server.py	Despachador C2: GET/POST/BOF, endurecimiento contra path traversal
test_c2_http_e2e.py	Ida y vuelta real de socket HTTP/1.1 con cifrado
test_install_deploy.py	El flujo de trabajo make produce un árbol ejecutable, make clean lo borra

Estructura del repositorio

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

Licencia