Zero-token knowledge base

blacksandbeacon | System Maps

Architecture maps, an overview video, and the full documentation set, generated offline from the source code. Nothing here was written by an LLM.

25communities
179files
976imports
4languages
1,590symbols

Interactive maps

Physics-driven diagrams: drag nodes, click one for its documentation, trace upstream or downstream reach. Maps load their engine from a CDN.

Overview video

Cinematic synthwave overview rendered from real scan data: layers, god nodes, dependency tree, communities, import graph, and code DNA. Open/download readmenator.mp4.

Documentation 54 files

Wiki 20

Concept pages per code community: start with index.md.

legacy

readmenator-wiki/community_0_legacy.md

Community 0 | 20 files | cohesion 0.89

130 lines~2302 tokens
Open raw markdown

mutants/src: bof_streaming_(large_outputs)

readmenator-wiki/community_10_mutants_src_bof_streaming_large_outputs.md

Community 10 | 3 files | cohesion 1.00

47 lines~533 tokens
Open raw markdown

mutants/src: c2_rest_api

readmenator-wiki/community_11_mutants_src_c2_rest_api.md

Community 11 | 3 files | cohesion 1.00

47 lines~442 tokens
Open raw markdown

mutants/src: certificate_pinning___tofu

readmenator-wiki/community_12_mutants_src_certificate_pinning_tofu.md

Community 12 | 3 files | cohesion 1.00

47 lines~544 tokens
Open raw markdown

mutants/src: command_execution_via_execve

readmenator-wiki/community_13_mutants_src_command_execution_via_execve.md

Community 13 | 3 files | cohesion 1.00

51 lines~699 tokens
Open raw markdown

mutants/src: containerized_build_+_sbom

readmenator-wiki/community_14_mutants_src_containerized_build_sbom.md

Community 14 | 3 files | cohesion 1.00

44 lines~424 tokens
Open raw markdown

mutants/src: hkdf_key_derivation

readmenator-wiki/community_15_mutants_src_hkdf_key_derivation.md

Community 15 | 3 files | cohesion 1.00

47 lines~497 tokens
Open raw markdown

mutants/src: iv_generation_with_entropy_verification

readmenator-wiki/community_16_mutants_src_iv_generation_with_entropy_verification.md

Community 16 | 3 files | cohesion 1.00

47 lines~632 tokens
Open raw markdown

mutants/src: mutation_testing_integration

readmenator-wiki/community_17_mutants_src_mutation_testing_integration.md

Community 17 | 3 files | cohesion 1.00

47 lines~553 tokens
Open raw markdown

mutants/src: pre-commit_+_ci_hardening

readmenator-wiki/community_18_mutants_src_pre_commit_ci_hardening.md

Community 18 | 3 files | cohesion 1.00

44 lines~407 tokens
Open raw markdown

mutants/src: replay_protection

readmenator-wiki/community_19_mutants_src_replay_protection.md

Community 19 | 3 files | cohesion 1.00

47 lines~484 tokens
Open raw markdown

c2

readmenator-wiki/community_1_c2.md

Community 1 | 17 files | cohesion 1.00

108 lines~1947 tokens
Open raw markdown

mutants/src: socks5___http_proxy_support

readmenator-wiki/community_20_mutants_src_socks5_http_proxy_support.md

Community 20 | 3 files | cohesion 1.00

47 lines~550 tokens
Open raw markdown

mutants/src: structured_jsonl_logging

readmenator-wiki/community_21_mutants_src_structured_jsonl_logging.md

Community 21 | 3 files | cohesion 1.00

47 lines~498 tokens
Open raw markdown

mutants/src: tls_client_certificate_authentication

readmenator-wiki/community_22_mutants_src_tls_client_certificate_authentication.md

Community 22 | 3 files | cohesion 1.00

47 lines~583 tokens
Open raw markdown

mutants/src: unified_config_schema

readmenator-wiki/community_23_mutants_src_unified_config_schema.md

Community 23 | 3 files | cohesion 1.00

47 lines~479 tokens
Open raw markdown

include: config_autogen

readmenator-wiki/community_24_include_config_autogen.md

Community 24 | 2 files | cohesion 1.00

71 lines~1341 tokens
Open raw markdown

orphans

readmenator-wiki/community_25_orphans.md

Community 25 | 64 files | cohesion 0.00

174 lines~2005 tokens
Open raw markdown

bof/include

readmenator-wiki/community_2_bof_include.md

Community 2 | 7 files | cohesion 1.00

81 lines~1087 tokens
Open raw markdown

Audit Report

readmenator-wiki/REPORT.md

Project: blacksandbeacon | 2026-11-13 | offline, deterministic

43 lines~363 tokens
Open raw markdown

GraphRAG 1

Community report hierarchy for agents. Query it with: readmenator . ask "question" (or MCP readmenator.graphrag).

GraphRAG Community Reports

readmenator-graphrag/REPORTS.md

Entities: 1901 | Relationships: 4313 | Communities: 26 | Themes: 24 | Text units: 1698

586 lines~13932 tokens
Open raw markdown

Project docs 8

Knowledge base, README, and policies.

Polyglot Codebase Knowledge Graph

KNOWLEDGE_BASE.md

Start here: Statistics Dashboard for scope, God Nodes for blast radius, Architecture Reference for per-file API. Agents: prefer readmenator-agent/INDEX.md +...

5497 lines~205844 tokens
Open raw markdown

Black Sand Beacon

README.md

A Linux C2 beacon with a native in-memory ELF BOF loader, written in

302 lines~2946 tokens
Open raw markdown

c2

readmenator-diagrams/c2.md

c2 groups 17 files (py) around derivekeys, deepmerge, loadconfig, randomfreeport, ensurestagetls. Black Sand Beacon C2 Server Gopher-style command and control...

52 lines~483 tokens
Open raw markdown

include: aes

readmenator-diagrams/include_aes.md

include: aes groups 6 files (c, h) around BSBAESCFBH, aes256cfbencrypt, aes256cfbdecrypt, AESH, CBC. tiny-AES-c (https://github.com/kokke/tiny-AES-c)

33 lines~200 tokens
Open raw markdown

include: config

readmenator-diagrams/include_config.md

include: config groups 6 files (c, h) around BSBCONFIGH, BSBCONFIGPATHDEFAULT, BSBCONFIGPATHENV, BSBMAXURL, BSBMAXURI. slurp: declared in the schema.

33 lines~268 tokens
Open raw markdown

legacy

readmenator-diagrams/legacy.md

legacy groups 20 files (c, h) around BEACONCOMMONH, GNUSOURCE, BSBOUTPUTBUFFERDEFAULT, BSBOUTPUTTRUNCATIONMARKER, httpresponset. tiny-AES-c...

62 lines~481 tokens
Open raw markdown

overview.md

readmenator-diagrams/overview.md

Static architecture map of 179 files (c, h, py, sh) in 25 components: legacy, c2, bof/include, include: aes, include: config, mutants/src: asyncioforbeacon...

330 lines~5716 tokens
Open raw markdown

Security Policy

SECURITY.md

Black Sand Beacon is actively developed. Only the latest release receives security updates.

48 lines~538 tokens
Open raw markdown

Agent docs 20

Grep-friendly indexes for AI agents (also useful for humans).

API

readmenator-agent/API.md

getSBoxValue (function) aes.c:11 static uint8t getSBoxValue(uint8t num)

1068 lines~27412 tokens
Open raw markdown

Architecture

readmenator-agent/ARCHITECTURE.md

beacons/v1/beacon.c -> include/beaconcommon.h

241 lines~4942 tokens
Open raw markdown

Concepts

readmenator-agent/CONCEPTS.md

Nouns map atomically to file sets (EXTRACTED); verbs aggregate structural edges (INFERRED).

120 lines~5172 tokens
Open raw markdown

Gotchas

readmenator-agent/GOTCHAS.md

These files have the most connections. Changes here have high blast radius.

57 lines~880 tokens
Open raw markdown

Subsystem: bof_include

readmenator-agent/KB_bof_include.md

Doc: datap: Argument parser.

67 lines~1033 tokens
Open raw markdown

Subsystem: c2

readmenator-agent/KB_c2.md

Imported by: mutants/tests/testc2httpe2e.py, tests/testc2httpe2e.py

61 lines~933 tokens
Open raw markdown

Subsystem: cat

readmenator-agent/KB_cat.md

go (function, line 15) void go(char args, int alen)

26 lines~287 tokens
Open raw markdown

Subsystem: include

readmenator-agent/KB_include.md

Doc: tiny-AES-c (https://github.com/kokke/tiny-AES-c)

715 lines~12541 tokens
Open raw markdown

Subsystem: is_sudo

readmenator-agent/KB_is_sudo.md

useringroup (function, line 15) static int useringroup(const char group, const char username, char filebuf, long filesize)

32 lines~428 tokens
Open raw markdown

Subsystem: legacy

readmenator-agent/KB_legacy.md

Doc: MemoryStruct: === ESTRUCTURAS ===

277 lines~4698 tokens
Open raw markdown

Subsystem: misc

readmenator-agent/KB_misc.md

reportresult (function, line 24) static void reportresult(const bsbconfigt cfg, const char command, const char output)

90 lines~1139 tokens
Open raw markdown

Subsystem: root

readmenator-agent/KB_root.md

Doc: tiny-AES-c (https://github.com/kokke/tiny-AES-c)

374 lines~6712 tokens
Open raw markdown

Subsystem: src

readmenator-agent/KB_src.md

Doc: Auto-generated implementation for contract: Async I/O for Beacon

147 lines~1418 tokens
Open raw markdown

Subsystem: tests

readmenator-agent/KB_tests.md

main (function, line 24) int main(void)

399 lines~7278 tokens
Open raw markdown

Subsystem: userenum

readmenator-agent/KB_userenum.md

userinmemberlist (function, line 67) static int userinmemberlist(const char username, const char members)

28 lines~345 tokens
Open raw markdown

Subsystem: whoami

readmenator-agent/KB_whoami.md

go (function, line 19) void go(char args, int alen)

28 lines~311 tokens
Open raw markdown

Project Memory

readmenator-agent/MEMORY.md

Generated from 179 files at commit e9feea6269c6. Read this first, then readmenator-wiki/index.md, then readmenator . ask "<question>" for anything specific.

97 lines~2024 tokens
Open raw markdown

Security Findings

readmenator-agent/SECURITY.md

3 lines~10 tokens
Open raw markdown

Symbols

readmenator-agent/SYMBOLS.md

1617 lines~44432 tokens
Open raw markdown

Recipes 5

Step-by-step tasks grounded in this codebase.

Recipe: Add a Function

readmenator-agent/recipes/add-function.md

Find the target file by purpose: grep -in '<topic>' readmenator-agent/INDEX.md

9 lines~99 tokens
Open raw markdown

Recipe: Change a File Safely

readmenator-agent/recipes/change-impact.md

Riskiest file: include/configpy.py (14 dependents)

9 lines~108 tokens
Open raw markdown

Recipe: Fix a Dependency Cycle

readmenator-agent/recipes/fix-cycle.md

Read cycles: grep -A5 'Dependency Cycles' readmenator-agent/GOTCHAS.md

6 lines~65 tokens
Open raw markdown

Recipe: Fix a Security Finding

readmenator-agent/recipes/fix-security.md

Read findings: grep -n '<file>' readmenator-agent/SECURITY.md

6 lines~69 tokens
Open raw markdown

Recipe: Reduce File Complexity

readmenator-agent/recipes/reduce-complexity.md

Target hotspot: c2/server.py

9 lines~73 tokens
Open raw markdown

How to read these maps

Open any map, then: drag nodes freely while physics settles the rest, search (/) to filter, click a node to focus it with full file documentation, Upstream and Downstream to trace authored reach, Path to probe the exact route between two ids, Lens to compare semantic roles, Play to walk the guided chapters, Stabilize to re-run physics, Theme for dark and light, Export for PNG or typed JSON. Deep links such as #route=a~b restore any reading.