CISS.debian.live.builder/docs/documentation/ciss_live_builder.sh.md

---
gitea: none
include_toc: true
-----------------

# 1. CISS.debian.live.builder

**Centurion Intelligence Consulting Agency Information Security Standard**<br>
*Debian Live Build Generator for hardened live environment and CISS Debian Installer*<br>
**Master Version**: 8.13<br>
**Build**: V8.13.536.2025.12.04<br>

# 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.<br>

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.<br>

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.<br>

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.<br>

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.<br>

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.<br>

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.<br>

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.<br>

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.<br>

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.<br>

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.<br>

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](https://coresecret.eu/)**
<!-- vim: set number et ts=2 sw=2 sts=2 ai tw=128 ft=markdown -->