Marc S. Weidner
2e50dd9535
Signed-off-by: Marc S. Weidner <msw@coresecret.dev>
10 KiB
Table of Contents
1. CISS.debian.live.builder
Centurion Intelligence Consulting Agency Information Security Standard
Debian Live Build Generator for hardened live environment and CISS Debian Installer
Master Version: 8.13
Build: V8.13.768.2025.12.06
2. ciss_live_builder.sh
This module implements the primary orchestration entry point for the CISS.debian.live.builder toolchain and drives the
complete lifecycle of a hardened Debian live ISO build in a single, linear control flow. It is responsible for validating the
execution environment, enforcing strict process invariants, loading all required library components, and then delegating the
actual configuration and build steps to the specialized helper libraries in a defined order.
The script assumes a modern Bash runtime and treats any other shell as a hard error. It refuses to run under ash, dash,
ksh, generic sh, or zsh, and verifies that it is executed, not sourced, by checking BASH_SOURCE versus $0
and by probing signal handling to detect accidental invocation through sh. It further enforces an effective user id of 0
and requires Bash 5.1 or newer; lower versions or older minor releases result in immediate termination with explicit
diagnostics. These checks rely on error codes and constants provided by a shared global variable file that is sourced only when
the precondition fails, which keeps the fast path minimal while still centralizing return codes and messages.
At startup the module captures positional parameters into a dedicated array and records several pieces of invocation metadata,
such as the raw argument string, the program name, the absolute path to the script location, and a fixed path in tmpfs for
secret build artifacts. This secret area, mapped to /dev/shm, is hardened early in the control flow: any symlink at that
location is treated as a fatal integrity violation, and existing files below that directory are forced to mode 0400 and
ownership root:root in order to prevent privilege erosion or leakage of keys and sensitive configuration. The script also
establishes a canonical working directory rooted at the script location and exposes it via VAR_WORKDIR for downstream
components.
Before any complex logic runs, a minimal early-variable configuration and the guard infrastructure are loaded. The module uses a
source_guard() abstraction to pull in environment and option hardening bash.var.sh and later the broader variable sets
color.var.sh and global.var.sh. This guard layer encapsulates defensive sourcing: it ensures that required files exist,
are regular files, and can be safely imported, and it centralizes error handling for missing or malformed dependencies. On top
of this, the script interprets a narrow set of meta-arguments that short-circuit the normal control flow. Options for contact
information, help text, version output, and a debug mode are resolved in small one-line loops that normalize the argument case,
source the corresponding library and call a single function, then exit cleanly. The debug mode delegates to a separate
debug wrapper that is expected to toggle xtrace facilities without polluting non-debug runs.
Once the basic environment is secured, the script marks setup completion through a VAR_SETUP flag and proceeds to load the
full set of library modules that provide the actual functionality of the builder. These range from argument parsing, priority
checks and on-screen dialog handling to live-build configuration, hardening routines, SSH and root password security tweaks,
provider-specific integration for Netcup, microcode updates, GnuPG initialization and signature handling, as well as a family of
trap and sanitization helpers. The module does not itself implement these behaviors; instead, it acts as a strict dispatcher that
sequences the library calls, which keeps the main script relatively compact while enforcing one centralized control graph.
A mandatory dependency check is performed via check_pkgs(), which is expected to verify the presence of all external tools
that later library calls depend on, including live-build, dialog, cryptographic tools, and network utilities. Only after
this succeeds does the module attempt to acquire an advisory lock on /var/lock/ciss_live_builder.lock. It assigns file
descriptor 127 to the lock file and uses flock in nonblocking exclusive mode. If the lock cannot be acquired, the script
assumes that another builder instance is running and aborts with a collision error code, thereby ensuring that concurrent runs
cannot corrupt the shared build directory or interfere with secret handling.
Command line semantics distinguish between interactive and autobuild modes. The module scans the argument list for -a= or
--autobuild= options and, when present, toggles a VAR_HANDLER_AUTOBUILD flag and records the specified kernel identifier.
In autobuild mode, intended for CI pipelines, the dialog-based user interface is suppressed, and the script runs purely
non-interactively. Independently of the mode, the script ensures that /usr/local/sbin and /usr/sbin are present in PATH,
which is relevant when live-build or other administrative tools are installed in non-standard locations.
For interactive runs, the module uses a dialog-based boot screen abstraction with a gauge that is updated through writes to file
descriptor 3. It announces successive phases of initialization, including trap activation, argument sanitization, parsing,
and final checks, incrementally advancing the progress indicator until initialization reaches 100 percent. Sanitization is
applied through arg_check(), which rejects malformed or unsupported options and normalizes the argument vector, and the
result is captured in both an array, and a flattened string for later logging and diagnostics. The dedicated arg_parser()
then interprets the cleaned arguments into internal configuration variables that govern the behavior of the subsequent build
steps. A clean_ip() routine is invoked as part of final checks, indicating that IP address parameters or environment-derived
network settings are normalized and scrubbed before being used to contact external resources.
Once initialization completes, the dialog wrapper is dismantled via boot_screen_cleaner() and the script transitions into
the main program. When not in autobuild mode, provider and kernel are verified explicitly; check_provider() ensures that the
selected hosting or deployment provider is supported and properly configured, and check_kernel() validates the target kernel
flavor or version, matching it against what is available on the build host.
The build preparation sequence starts with ciss_upgrades_build(), which enforces a specific upgrade policy on the build host
ISO generation, followed by hardening_ssh_tcp(), which introduces transport-level SSH and TCP hardening settings required
for the resulting live system. The live-build tooling is then initialized. The lb_config_start() helper prepares the
build environment, by creating or cleaning the live-build configuration directory and populating baseline files. Immediately
afterward lb_config_write_trixie() writes a fully specified configuration for a Debian Trixie based system, which anchors
the release and package universe of the live medium.
Before any cryptographic operations or remote integrations occur, init_gnupg() provisions a dedicated GNUPGHOME for this
build, including keyring directories and trust anchors, to isolate GnuPG state. The following init_primordial() step
integrates an initial SSH identity set into the build context, which designates as "primordial" identities, used for early
remote access into the private primordial git repo environment. From that point on, all modifications that touch the future ISO
are applied inside the live-build directory referenced by VAR_HANDLER_BUILD_DIR rather than the repository itself. The
hardening_ultra() library is invoked to apply an extended hardening profile across configuration files, sysctl parameters to
achieve the stringent security posture expected from the CISS standard.
Integration with the CISS.debian.installer is performed by the cdi() helper, which is responsible for embedding
autostart logic into the live image so that the installer can be launched in a controlled way directly from the live medium.
Subsequent calls tweak the visual and operational characteristics of the image: change_splash() adjusts boot splash assets,
check_dhcp() verifies that DHCP behavior and network defaults are consistent with the target environment, ciss_signatures()
applies cryptographic signatures to artifacts and configuration checkpoints, and ciss_upgrades_boot() prepares the boot-time
upgrade mechanism. hardening_root_pw() finalises the root password policy in the resulting system, note_target() records
build metadata about the deployment target, provider_netcup() executes provider-specific adjustments for Netcup environments,
and update_microcode() brings CPU microcode handling to a defined state inside the image.
Before the actual image build begins, x_hooks() and x_remove() are called to integrate additional live-build hooks and to
remove transient or development-only components from the build tree. The script then temporarily disables error trace propagation
with set +o errtrace, runs lb_build_start() to invoke the live-build engine and generate the ISO, and re-enables
errtrace afterwards so that subsequent failures are again intercepted by the error trap. Post-build analysis is performed by
run_analysis(), which inspects the build logs, artifact hashes, and runtime, and ISO artifacts. Finally, the script marks
VAR_SCRIPT_SUCCESS as true to document a clean run and exits with a zero status code; any earlier failure would be caught by
the ERR or EXIT traps and processed by the trap_on_err() or trap_on_exit() handlers defined in the corresponding
libraries, ensuring consistent diagnostic output and cleanup for both expected and unexpected error conditions.
no tracking | no logging | no advertising | no profiling | no bullshit