V8.13.536.2025.12.04

Signed-off-by: Marc S. Weidner <msw@coresecret.dev>

docs/CHANGELOG.md

@@ -13,8 +13,14 @@ include_toc: true
 # 2. Changelog
 
 ## V8.13.536.2025.12.04
-* **Bugfixes**: [unlock_wrapper.sh](../config/includes.chroot/etc/initramfs-tools/files/unlock_wrapper.sh)
+* **Added**: [ciss_live_builder.sh.md](documentation/ciss_live_builder.sh.md)
 * **Bugfixes**: Unified network management via ``systemd-networkd``
+* **Bugfixes**: [0822_ssh_restart_hook.chroot](../config/hooks/live/0822_ssh_restart_hook.chroot) + ssh restart cron job replaced by systemd override
+* **Bugfixes**: [unlock_wrapper.sh](../config/includes.chroot/etc/initramfs-tools/files/unlock_wrapper.sh) + ``: > /var/log/wtmp``
+* **Bugfixes**: [1000_ciss_fixpath.sh](../config/includes.chroot/etc/initramfs-tools/scripts/init-premount/1000_ciss_fixpath.sh) + ``: > /var/log/wtmp``
+* **Bugfixes**: [0000_ciss_fixpath.sh](../config/includes.chroot/etc/initramfs-tools/scripts/init-top/0000_ciss_fixpath.sh) + ``: > /var/log/wtmp``
+* **Bugfixes**: [30-ciss-hardening.conf](../config/includes.chroot/etc/modprobe.d/30-ciss-hardening.conf) + UAS blacklisting
+* **Bugfixes**: [0024-ciss-crypt-squash](../config/includes.chroot/usr/lib/live/boot/0024-ciss-crypt-squash) + unified ``kill`` & ``wait`` handling for ``BROKER`` & ``PROMPT`` PIDs
 * **Removed** [0100_ciss_mem_wipe.chroot](../.archive/0100_ciss_mem_wipe.chroot)
 
 ## V8.13.528.2025.12.03

docs/documentation/ciss_live_builder.sh.md

@@ -0,0 +1,113 @@
+---
+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 -->