System Overview — bee

What it does

Hardware audit LiveCD. Boots on a server via BMC virtual media or USB. Collects hardware inventory at OS level (not through BMC/Redfish). Produces HardwareIngestRequest JSON compatible with core/reanimator.

Why it exists

Fills gaps where Redfish/logpile is blind:

NVMe serials and SMART data
DIMM serials and slot layout
GPU serials and VBIOS versions
Physical disks behind RAID controllers
Full SMART wear telemetry
NIC firmware versions

In scope

Read-only hardware inventory: board, CPU, memory, storage, PCIe, PSU, GPU, NIC, RAID
Unattended operation — no user interaction required
NVIDIA proprietary driver loaded at boot for GPU enrichment via nvidia-smi
SSH access (OpenSSH) always available for inspection and debugging
Interactive Go TUI via bee tui for network setup, service management, and acceptance tests

Network isolation — CRITICAL

The live CD runs in an isolated network segment with no internet access.

All tools, drivers, and binaries MUST be pre-baked into the ISO at build time
No package installation at boot — packages are installed during ISO creation, not at runtime
No downloads at boot — NVIDIA modules, vendor tools, and all binaries come from the ISO overlay
DHCP is used only for LAN access (SSH from operator laptop); internet is NOT assumed
Any feature requiring network downloads cannot be added to the live CD

Out of scope

Any writes to the server being audited
Network configuration changes (persistent)
BMC/IPMI configuration
Anything requiring persistent storage on the audited machine
Windows support
Any functionality requiring internet access at boot

Tech stack

Component	Technology
Audit binary	Go, static, `CGO_ENABLED=0`
Live ISO	Debian 12 (bookworm), amd64 live-build image
ISO build	Debian `live-build` + overlay sync into `config/includes.chroot/`
Init system	`systemd`
SSH	OpenSSH server
NVIDIA driver	Proprietary `.run` installer, built against Debian kernel headers
NVIDIA modules	Loaded via `insmod` from `/usr/local/lib/nvidia/`
Builder	Debian 12 host/VM or Debian 12 container image

Runtime split

The main Go application must run both on a normal Linux host and inside the live ISO
Live-ISO-only responsibilities stay in iso/ integration code
Live ISO launches the Go CLI with --runtime livecd
Local/manual runs use --runtime auto or --runtime local

Key paths

Path	Purpose
`audit/cmd/bee/`	Main CLI entry point
`audit/internal/collector/`	Per-subsystem collectors
`audit/internal/schema/`	HardwareIngestRequest types
`iso/builder/`	ISO build scripts and `live-build` profile
`iso/overlay/`	Source overlay copied into a staged build overlay
`iso/vendor/`	Optional pre-built vendor binaries (storcli64, sas2ircu, sas3ircu, mstflint, …)
`iso/builder/VERSIONS`	Pinned versions: Debian, Go, NVIDIA driver, kernel ABI
`iso/builder/smoketest.sh`	Post-boot smoke test — run via SSH to verify live ISO
`dist/`	Build outputs (gitignored)
`iso/out/`	Downloaded ISO files (gitignored)

3.2 KiB Raw Blame History