From 80ae4d66673dfc9392dbdf4ba63599cf99817c8f Mon Sep 17 00:00:00 2001 From: Thales Maciel Date: Wed, 22 Apr 2026 13:01:11 -0300 Subject: [PATCH] docs: resync package docs, AGENTS, and kernel-catalog with current code MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Four drift fixes from a doc sweep. internal/daemon/doc.go Replace the capability-hook description that still said "Hook methods take *Daemon; VMService reaches them through a capabilityHooks seam." Current reality: every capability is a plain struct carrying its own service pointers (workDiskCapability{vm,ws,store}, dnsCapability{net}, natCapability{vm,net,logger}); wireServices builds the default list; no hook reaches *Daemon. internal/daemon/ARCHITECTURE.md The VMService field list still claimed guestWaitForSSH and guestDial were "per-instance fields." Those were deleted as refactor residue. Update the note to say the seams live on *Daemon (reached by WorkspaceService via closures wired at construction) and document the vsockHostDevice field that replaced the old package-global vsockHostDevicePath. AGENTS.md Drop the "experimental web UI" mention (removed) and the `session` subpackage (removed). Mention banger-vsock-agent as the third cmd/ binary while we're here — AGENTS hadn't listed it. docs/kernel-catalog.md The trust-model section still read as if upstream kernel sources were fetched by HTTPS alone. Add a paragraph covering the PGP verification make-generic-kernel.sh now does against the detached .tar.sign and the three kernel.org release signing keys. Co-Authored-By: Claude Opus 4.7 (1M context) --- AGENTS.md | 6 +++--- docs/kernel-catalog.md | 12 ++++++++++-- internal/daemon/ARCHITECTURE.md | 8 +++++++- internal/daemon/doc.go | 10 ++++++++-- 4 files changed, 28 insertions(+), 8 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3a7efae..a6fc770 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,9 +4,9 @@ Always run `make build` before commit. ## Project Structure -- `cmd/banger` and `cmd/bangerd` are the main user entrypoints. -- `internal/` contains the daemon, CLI, RPC, storage, Firecracker integration, guest helpers, and the experimental web UI. -- `internal/daemon/` is the composition root; pure helpers live in its subpackages (`opstate`, `dmsnap`, `fcproc`, `imagemgr`, `session`, `workspace`). See `internal/daemon/ARCHITECTURE.md`. +- `cmd/banger`, `cmd/bangerd`, and `cmd/banger-vsock-agent` are the three binaries. The first two are user-facing; the third is a companion that ships inside each guest VM. +- `internal/` contains the daemon, CLI, RPC, storage, Firecracker integration, and guest helpers. +- `internal/daemon/` is the composition root; pure helpers live in its subpackages (`opstate`, `dmsnap`, `fcproc`, `imagemgr`, `workspace`). See `internal/daemon/ARCHITECTURE.md`. - `internal/imagecat/` and `internal/kernelcat/` embed the image + kernel catalogs. - `images/golden/` is the Dockerfile for the `debian-bookworm` catalog entry. - `scripts/` contains manual helper workflows for rootfs, kernel, and bundle preparation. diff --git a/docs/kernel-catalog.md b/docs/kernel-catalog.md index 909f7a0..7bfea51 100644 --- a/docs/kernel-catalog.md +++ b/docs/kernel-catalog.md @@ -109,8 +109,16 @@ on R2 without also pushing a banger release. It does **not** protect against a compromise of the banger source repo itself — an attacker who can land a commit can change both the catalog -SHA256 and the tarball. GPG/sigstore signing is deferred until banger is -public and the threat model justifies the operational overhead. +SHA256 and the tarball. GPG/sigstore signing of the published catalog +tarballs is deferred until banger is public and the threat model +justifies the operational overhead. + +Upstream kernel sources *are* verified: `scripts/make-generic-kernel.sh` +fetches the detached PGP signature alongside the tarball from +kernel.org and rejects the build if gpg can't verify it against one +of the three known release signing keys (Greg KH / Linus / Sasha +Levin). So a compromised kernel.org mirror can't slip a backdoored +tarball past a maintainer rebuilding the kernel locally. ## Hosting diff --git a/internal/daemon/ARCHITECTURE.md b/internal/daemon/ARCHITECTURE.md index 709ad65..928c03b 100644 --- a/internal/daemon/ARCHITECTURE.md +++ b/internal/daemon/ARCHITECTURE.md @@ -107,7 +107,13 @@ idempotent and skips anything already set. process handles (PID, tap device, loop devices, DM target). Each VM directory holds a small `handles.json` scratch file so the cache can be rebuilt at daemon startup. -- Test seams `guestWaitForSSH`, `guestDial` are per-instance fields. +- `vsockHostDevice` — path to `/dev/vhost-vsock` the preflight and + doctor checks RequireFile against. Defaulted in wireServices; + tests point at a tempfile to make the check pass without the + kernel module loaded. Guest-SSH test seams live on `*Daemon` + (`d.guestWaitForSSH`, `d.guestDial`), not VMService — workspace + prepare is the only path that reaches guest SSH, and it gets + there through closures WorkspaceService captured at wiring time. ## Subpackages diff --git a/internal/daemon/doc.go b/internal/daemon/doc.go index 784c5c6..151f906 100644 --- a/internal/daemon/doc.go +++ b/internal/daemon/doc.go @@ -49,8 +49,14 @@ // cleanupRuntime / generateName (*VMService), // and small stateless utilities. // capabilities.go Pluggable capability hooks executed at VM -// start. Hook methods take *Daemon; VMService -// reaches them through a capabilityHooks seam. +// start. Each capability is a plain struct +// with explicit service-pointer fields +// (workDiskCapability carries vm+ws+store, +// dnsCapability carries net, natCapability +// carries vm+net+logger). wireServices builds +// the default list; VMService invokes hooks +// through a capabilityHooks seam. No hook +// reaches back to *Daemon. // vm_locks.go vmLockSet primitive. // guest_ssh.go guestSSHClient, dialGuest, waitForGuestSSH. // ssh_client_config.go Daemon-managed SSH client key material.