Black Sand Beacon

一个 Linux C2 beacon，带有原生内存内 ELF BOF 加载器，使用 C 编写，不依赖 Go 或 Rust 运行时。设计用于接入 LazyOwn RedTeam 框架，灵感来自 Cobalt Strike 的 Beacon Object Files。

本仓库包含：

• Beacons 位于 beacons/v1/、beacons/v2/、beacons/v3/ 同一 HTTPS/CFB beacon 的三个变体。v1 是标准的拉取模式 beacon。v2 增加了 mesh/p2p 发现功能。v3 是实验性分支。
• BOFs 位于 bof/<name>/bof.c 位置无关的 ELF 对象，beacon 可以获取并在内存中执行。包含的五个为：whoami、is_sudo、cat、userenum、suid_enum。
• C2 服务器 位于 c2/server.py 一个小型 Python Gopher 风格服务器，用于下发命令、接收结果并托管 BOF。
• 共享库 位于 include/ 独立的 AES-256（aes.c/aes.h）、cJSON、运行时配置加载器（config.c/config.h 以及 Python 镜像 config_py.py），以及 beacon 和测试共用的 AES-256-CFB 封装。
• 构建 位于 Makefile，CI 位于 .github/workflows/ci.yml，测试 位于 tests/。

如需 5 分钟端到端运行，请参阅 QUICKSTART.md。 如需 BOF 编写指南，请参阅 docs/BOF_AUTHORING.md。 如需 C2 通信协议，请参阅 docs/PROTOCOL.md。

环境要求

构建（Debian/Ubuntu）：

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

C2 服务器的运行时：

pip install -r requirements.txt

构建

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/

执行 make beacon 后，二进制文件即可运行：

./build/beacon

它通过相对于二进制的搜索路径读取 build/config.json（位于其自身旁边），因此不需要 BSB_CONFIG 或 cd config/。只要 config.json 位于其旁边，将同一个二进制文件复制到另一台主机上也能以相同方式工作。

如果你只想重新构建一个 BOF：

make bof-whoami
make bof-suid_enum

部署到另一台主机（可选）

为了将程序投递到目标主机，Makefile 提供了一个 install 目标，用于 暂存一个自包含的目录：

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

这不是正常流程。仅当你需要将二进制文件 + 配置 + BOF 打包到一个可以复制到别处的单一目录时，才使用它。

运行 C2

python3 c2/server.py

服务器默认绑定 0.0.0.0:7070，并从 config/config.json 读取其 AES 密钥和 C2 URI。可通过 BSB_CONFIG=/path/to/config.json 覆盖配置路径。

服务器启动后，你可以从 REPL 注入命令：

Client ID: linux
Command:   id

运行信标

./build/beacon

beacon 读取 config/config.json（相对于二进制文件，通过二进制相对搜索路径找到），轮询 C2，并打印它发送和接收的内容。在没有排队命令时，它只是在轮询之间休眠。

要运行 BOF，C2 返回一个 JSON 对象，其中 bof 字段指向 /bof/<name>.x64.o。beacon 获取该文件，并通过内存中的 ELF 加载器（beacons/v1/beacon.c 中的 RunELF）将其加载到自己的进程中。

配置

所有操作参数都位于 config/config.json 中，并在启动时读取。没有任何内容被硬编码到二进制文件中。

部分	键	默认值	用途
c2	url	https://127.0.0.1:4444	C2 基础 URL
c2	uri	/api/poll/	客户端 ID 之前的 URI 路径
c2	client_id	linux	Beacon 标识符
crypto	aes_key_hex	（占位符）	64 个十六进制字符 = 32 字节
crypto	mode	cfb	加密模式
timing	sleep_seconds	6	基础轮询间隔
timing	jitter_percent	20	休眠时间的 +/- 百分比抖动
timing	curl_timeout_seconds	10	libcurl 总超时
timing	curl_connect_timeout_seconds	5	libcurl 连接超时
network	user_agents	（4 个字符串）	轮换列表
network	verify_tls	false	C2 TLS 验证
bof	download_chunk_size	4096	BOF 下载缓冲区

CI 运行一项防护检查，如果源代码中出现 64 字符的十六进制密钥，则构建失败。真实密钥应放在 config/config.json 中，该文件已被 git 忽略。

编写新的 BOF

BOF 只是一个导出 void go(char *args, int alen) 的 C 源文件。包含 bof/include/beacon_api.h 以使用回调 API，包含 bof/include/syscalls.h 以使用直接系统调用辅助函数。以位置无关方式编译，并且不使用 libc：

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

make bof-<name> 目标封装了这一过程。将生成的 .x64.o 放入 C2 主机上的 sessions/uploads/，并通过从命令 注入中返回类似 bof:<name> 的命令来触发它。

完整约定请参见 docs/BOF_AUTHORING.md。

测试

make test

测试套件在 tests/ 目录下拆分为多个文件：

文件	覆盖内容
test_config.py	C JSON 配置加载器：默认值、覆盖、错误
test_crypto.py	AES-256-CFB 往返测试及 Python/C 互操作
test_bof_compile.py	每个 BOF 均可编译、导出 go、无 libc 泄漏
test_beacon_build.py	Beacon 二进制构建、暴露 BOF API + RunELF
test_c2_server.py	C2 调度器：GET/POST/BOF、路径遍历加固
test_c2_http_e2e.py	带加密的真实 HTTP/1.1 socket 往返测试
test_install_deploy.py	make 工作流生成可运行目录树，make clean 将其清除

仓库布局

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

许可证

GPL v3。参见 LICENSE。

知识库

本项目已由 ReadMenator 分析， 这是一个零 token 的多语言静态分析工具。可使用 pip install readmenator && readmenator . --rebuild 重新生成。分析输出：