Black Sand Beacon

Um beacon C2 para Linux com um carregador BOF ELF nativo em memória, escrito em C sem runtime Go ou Rust. Projetado para se integrar ao framework LazyOwn RedTeam e inspirado nos Beacon Object Files do Cobalt Strike.

Este repositório contém:

• Beacons em beacons/v1/, beacons/v2/, beacons/v3/ Três variantes do mesmo beacon HTTPS/CFB. A v1 é o beacon canônico em modo pull. A v2 adiciona descoberta mesh/p2p. A v3 é um branch experimental.
• BOFs em bof/<name>/bof.c Objetos ELF independentes de posição que o beacon pode buscar e executar em memória. Os cinco incluídos são: whoami, is_sudo, cat, userenum, suid_enum.
• Servidor C2 em c2/server.py Um pequeno servidor Python do tipo Gopher que serve comandos, aceita resultados e hospeda BOFs.
• Biblioteca compartilhada em include/ AES-256 standalone (aes.c/aes.h), cJSON, o carregador de configuração em runtime (config.c/config.h mais o espelho em Python config_py.py), e os wrappers AES-256-CFB compartilhados pelo beacon e pelos testes.
• Build em Makefile, CI em .github/workflows/ci.yml, testes em tests/.

Para uma execução ponta a ponta de 5 minutos, consulte QUICKSTART.md. Para o guia de autoria de BOFs, consulte docs/BOF_AUTHORING.md. Para o protocolo de comunicação do C2, consulte docs/PROTOCOL.md.

Requisitos

Build (Debian/Ubuntu):

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

Runtime para o servidor C2:

pip install -r requirements.txt

Compilação

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/

Após make beacon, o binário está pronto para ser executado:

./build/beacon

Ele lê build/config.json (ao lado de si mesmo) através do caminho de busca relativo ao binário, portanto não é necessário BSB_CONFIG nem cd config/. O mesmo binário copiado para outro host funciona de forma idêntica desde que um config.json esteja ao seu lado.

Se você quiser apenas reconstruir um único BOF:

make bof-whoami
make bof-suid_enum

Implantar em outro host (opcional)

Para enviar para um destino, o Makefile tem um alvo install que prepara um diretório autocontido:

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

Este não é o fluxo normal. Use-o apenas quando precisar empacotar o binário + config + BOFs em um único diretório que você possa copiar para algum lugar.

Executar o C2

python3 c2/server.py

O servidor escuta em 0.0.0.0:7070 por padrão e lê sua chave AES e URI de C2 a partir de config/config.json. Substitua o caminho da configuração com BSB_CONFIG=/path/to/config.json.

Assim que o servidor estiver ativo, você pode injetar comandos a partir do REPL:

Client ID: linux
Command:   id

Execute o beacon

./build/beacon

O beacon lê config/config.json (relativo ao binário, encontrado através do caminho de busca relativo ao binário), consulta o C2 e imprime o que envia e recebe. Sem comandos na fila, ele apenas dorme entre as consultas.

Para executar um BOF, o C2 retorna um objeto JSON com um campo bof apontando para /bof/<name>.x64.o. O beacon busca o arquivo e o carrega em seu próprio processo através do carregador ELF em memória (RunELF em beacons/v1/beacon.c).

Configuração

Todos os parâmetros operacionais ficam em config/config.json e são lidos na inicialização. Nada é embutido nos binários.

Seção	Chave	Padrão	Finalidade
c2	url	https://127.0.0.1:4444	URL base do C2
c2	uri	/api/poll/	Caminho URI antes do id do cliente
c2	client_id	linux	Identificador do beacon
crypto	aes_key_hex	(placeholder)	64 caracteres hex = 32 bytes
crypto	mode	cfb	Modo de criptografia
timing	sleep_seconds	6	Intervalo base de consulta
timing	jitter_percent	20	Jitter de +/- porcento no sleep
timing	curl_timeout_seconds	10	Timeout total do libcurl
timing	curl_connect_timeout_seconds	5	Timeout de conexão do libcurl
network	user_agents	(4 strings)	Lista de rotação
network	verify_tls	false	Verificação TLS do C2
bof	download_chunk_size	4096	Buffer de download de BOF

A CI executa uma verificação que falha a build se uma chave hex de 64 caracteres aparecer no código-fonte. Chaves reais pertencem a config/config.json, que é ignorado pelo git.

Escrevendo um novo BOF

Um BOF é apenas um arquivo-fonte C que exporta void go(char *args, int alen). Inclua bof/include/beacon_api.h para a API de callback e bof/include/syscalls.h para auxiliares de syscall direta. Compile-o independente de posição e sem libc:

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

O alvo make bof-<name> encapsula isso. Coloque o .x64.o resultante em sessions/uploads/ no host C2 e acione-o retornando um comando como bof:<name> a partir da sua injeção de comando.

Consulte docs/BOF_AUTHORING.md para o contrato completo.

Testes

make test

A suíte de testes está dividida em vários arquivos em tests/:

Arquivo	O que cobre
test_config.py	Carregador de configuração JSON em C: padrões, substituições, erros
test_crypto.py	Roundtrip AES-256-CFB e interoperabilidade Python/C
test_bof_compile.py	Todo BOF compila, exporta go, não possui vazamento de libc
test_beacon_build.py	O binário Beacon compila, expõe a API BOF + RunELF
test_c2_server.py	Despachante C2: GET/POST/BOF, endurecimento contra path-traversal
test_c2_http_e2e.py	Roundtrip real de socket HTTP/1.1 com criptografia
test_install_deploy.py	O fluxo de trabalho make produz uma árvore executável, make clean a apaga

Estrutura do repositório

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

Licença

GPL v3. Consulte LICENSE.

Base de Conhecimento