V9.14.022.2026.06.11: document and test audit safeguards

V9.14.022.2026.06.11: enforce secret and cleanup safeguards
V9.14.022.2026.06.11: add path security helpers
2026-06-11 05:08:18 +02:00 · 2026-06-11 05:08:01 +02:00 · 2026-06-11 05:07:33 +02:00
18 changed files with 1247 additions and 175 deletions
@@ -60,12 +60,15 @@ and spoofing surfaces.
 Internally, the builder employs a dedicated secret-handling pipeline backed by a tmpfs-only secrets directory
 (`/dev/shm/cdlb_secrets`). Sensitive material such as root passwords, SSH keys, and signing keys never appears on the command
-line, is guarded by strict `0400 root:root` permissions, and any symlink inside the secret path is treated as a hard failure
+line, is guarded by a `0700 root:root` secret root and single-link regular `0400` or `0600` root-owned files, and any symlink
-that aborts the run. Critical code paths temporarily disable Bash xtrace so that credentials never leak into debug logs, and
+inside the secret path is treated as a hard failure that aborts the run. Filename-only secret arguments reject slashes and
-transient secret files are shredded (`shred -fzu`) as soon as they are no longer needed. GNUPG homes used for signing are
+traversal.
-wiped, unencrypted chroot artifacts and includes are removed after `lb build`, and the final artifact is reduced to the
+Critical code paths temporarily disable Bash xtrace, and a final exact-value debug-log sanitisation pass provides additional
-encrypted SquashFS inside the LUKS2 container. At runtime, LUKS passphrases in the live ISO and installer are transported via
+defence in depth. Transient secret files are shredded (`shred -fzu`) as soon as they are no longer needed, but this is only a
-named pipes inside the initramfs instead of process arguments, further minimizing exposure in process listings.
+best-effort cleanup on SSD, NVMe, copy-on-write, journaled, and virtualised storage. Use tmpfs for secrets and encrypted storage
 for build workspaces. Destructive build cleanup is restricted to the exact canonical directory carrying the
 `.ciss-live-builder-owned` marker. This private operator workflow still requires strict local path validation; it does not
 define public ISO release policy.
 Check out more leading world-class services powered by Centurion Intelligence Consulting Agency:
 * [CenturionDNS Resolver](https://eddns.eu/)
@@ -493,10 +496,14 @@ To use **``CISS.debian.live.builder``** as intended, the following baseline is e
 2. Preparation:
   1. Ensure you are root.
-   2. Create the build directory `mkdir /opt/cdlb` and the tmpfs secrets directory `mkdir /dev/shm/cdlb_secrets`.
+   2. Create the empty build directory with `install -d -m 0700 -o root -g root /opt/cdlb`.
-   3. Place your desired SSH public key in the `authorized_keys` file, for example, in the `/dev/shm/cdlb_secrets` directory.
+   3. Create the tmpfs secret root with `install -d -m 0700 -o root -g root /dev/shm/cdlb_secrets`.
-   4. Place your desired Password in the `password.txt` file, for example, in the `/dev/shm/cdlb_secrets` directory.
+   4. Place required secret files in the secret root as single-link regular, non-symlink, root-owned files with mode `0400`
-   5. Make any other changes you need to.
+      or `0600`.
   5. Place your desired SSH public key in `/dev/shm/cdlb_secrets/authorized_keys`.
   6. Place your desired root password in `/dev/shm/cdlb_secrets/password.txt`.
   7. Use filename-only values without slashes, `.` or `..` for `--key_age`, `--key_luks`, and signing-file arguments.
   8. Make any other changes you need to.
 3. Run the config builder script `./ciss_live_builder.sh` and the integrated `lb build` command (example):
@@ -538,6 +545,10 @@ To use **``CISS.debian.live.builder``** as intended, the following baseline is e
   both the newer Sigstore bundle asset, and the legacy-split certificate/signature assets before checking the downloaded
   SOPS binary with `sha256sum -c --ignore-missing`.
   On the first run, the builder creates `.ciss-live-builder-owned` in a new or empty build directory whose canonical parent
   already exists. A populated directory without that marker is rejected and is never adopted automatically. Cleanup remains
   intentionally destructive inside the exact validated marker-owned directory.
 4. Locate your ISO in the `--build-directory`.
 5. Boot from the ISO and login to the live image via the console, or the multi-layer secured **coresecret** SSH tunnel.
 6. Type `sysp` for the final kernel hardening features.
@@ -559,7 +570,8 @@ preview it or run it.
 2. Preparation:
   1. Ensure you are root.
-   2. Create the build directory `mkdir /opt/cdlb` and the tmpfs secrets directory `mkdir /dev/shm/cdlb_secrets`.
+   2. Create the empty build directory and tmpfs secret root with restrictive ownership and permissions:
      `install -d -m 0700 -o root -g root /opt/cdlb /dev/shm/cdlb_secrets`.
   3. Place your desired SSH public key in the `authorized_keys` file, for example, in the `/dev/shm/cdlb_secrets` directory.
   4. Place your desired Password in the `password.txt` file, for example, in the `/dev/shm/cdlb_secrets` directory.
   5. Copy and edit the sample and set your options (no spaces around commas in lists): 
@@ -656,10 +668,10 @@ The private directory is ignored by Git. The hooks fail if the CISS EFI image si
  #...
        - name: Preparing the build environment.
          run: |
-            mkdir -p /opt/config
+            install -d -m 0700 -o root -g root /opt/livebuild /dev/shm/cdlb_secrets
-            mkdir -p /opt/livebuild
+            umask 0077
-            echo "${{ secrets.CHANGE_ME }}" >| /opt/config/password.txt
+            printf '%s\n' "${{ secrets.CHANGE_ME }}" >| /dev/shm/cdlb_secrets/password.txt
-            echo "${{ secrets.CHANGE_ME }}" >| /opt/config/authorized_keys
+            printf '%s\n' "${{ secrets.CHANGE_ME }}" >| /dev/shm/cdlb_secrets/authorized_keys
  #...
        - name: Starting CISS.debian.live.builder. This may take a while ...
          run: |
@@ -672,9 +684,9 @@ The private directory is ignored by Git. The hooks fail if the CISS EFI image si
              --build-directory /opt/livebuild \
              --control "${timestamp}" \
              --jump-host "${{ secrets.CHANGE_ME }}" \
-              --root-password-file /opt/config/password.txt \
+              --root-password-file /dev/shm/cdlb_secrets/password.txt \
              --ssh-port CHANGE_ME \
-              --ssh-pubkey /opt/config
+              --ssh-pubkey /dev/shm/cdlb_secrets
  #...
        ### SKIP OR CHANGE ALL REMAINING STEPS
  ```
@@ -124,22 +124,28 @@ sleep 4
 printf "\e[95m🧪 %s starting ... \e[0m\n" "${BASH_SOURCE[0]}"
 declare -grx VAR_SETUP="true"
 ### SECURING SECRETS ARTIFACTS.
 test ! -L "${VAR_TMP_SECRET}" || {
  . ./var/global.var.sh
  printf "\e[91m❌ Refusing symlink: '%s'! Bye... \e[0m\n" "${VAR_TMP_SECRET}" >&2
  exit "${ERR_SECRETSSYM}"
 }
 find "${VAR_TMP_SECRET}" -type f -exec chmod 0400 {} +
 find "${VAR_TMP_SECRET}" -type f -exec chown root:root {} +
 ### SOURCING VARIABLES.
 [[ "${VAR_SETUP}" == true ]] && {
  source_guard "./var/color.var.sh"
  source_guard "./var/global.var.sh"
 }
-### SOURCING LIBRARIES.
+### SOURCE THE MINIMUM REQUIRED FOR EARLY EXIT CLEANUP COVERAGE.
 [[ "${VAR_SETUP}" == true ]] && {
  source_guard "./lib/lib_secret_validation.sh"
  source_guard "./lib/lib_build_directory.sh"
  source_guard "./lib/lib_debug_sanitizer.sh"
  source_guard "./lib/lib_clean_up.sh"
  source_guard "./lib/lib_trap_on_err.sh"
  source_guard "./lib/lib_trap_on_exit.sh"
 }
 trap 'trap_on_exit "$?" "${BASH_SOURCE[0]}" "${LINENO}" "${FUNCNAME[0]:-main}" "${BASH_COMMAND}"' EXIT
 ### Validate the fixed tmpfs secret staging area without modifying operator-provided files.
 validate_secret_staging_area
 ### SOURCING REMAINING LIBRARIES.
 [[ "${VAR_SETUP}" == true ]] && {
  source_guard "./lib/lib_arg_parser.sh"
  source_guard "./lib/lib_arg_priority_check.sh"
@@ -158,7 +164,6 @@ find "${VAR_TMP_SECRET}" -type f -exec chown root:root {} +
  source_guard "./lib/lib_ciss_upgrades_boot.sh"
  source_guard "./lib/lib_ciss_upgrades_build.sh"
  source_guard "./lib/lib_clean_screen.sh"
  source_guard "./lib/lib_clean_up.sh"
  source_guard "./lib/lib_copy_integrity.sh"
  source_guard "./lib/lib_gnupg.sh"
  source_guard "./lib/lib_hardening_root_pw.sh"
@@ -174,12 +179,13 @@ find "${VAR_TMP_SECRET}" -type f -exec chown root:root {} +
  source_guard "./lib/lib_run_analysis.sh"
  source_guard "./lib/lib_sanitizer.sh"
  source_guard "./lib/lib_secureboot_profile.sh"
  source_guard "./lib/lib_trap_on_err.sh"
  source_guard "./lib/lib_trap_on_exit.sh"
  source_guard "./lib/lib_update_microcode.sh"
  source_guard "./lib/lib_usage.sh"
 }
 ### Add ERR handling after all remaining libraries are available.
 trap 'trap_on_err  "$?" "${BASH_SOURCE[0]}" "${LINENO}" "${FUNCNAME[0]:-main}" "${BASH_COMMAND}"' ERR
 ### PRE-SCAN SECURE BOOT PROFILE FOR BUILD-HOST PACKAGE CHECKS.
 ### Formal validation still happens in arg_parser().
 for ((idx=0; idx<${#ARY_PARAM_ARRAY[@]}; idx++)); do
@@ -223,10 +229,6 @@ if ! ${VAR_HANDLER_AUTOBUILD}; then printf "XXX\nInitialization done ... \nXXX\n
 ### Updating Status of Dialog Gauge Bar.
 if ! ${VAR_HANDLER_AUTOBUILD}; then printf "XXX\nActivate traps ... \nXXX\n50\n" >&3; fi
 ### Following the CISS Bash naming and ordering scheme:
 trap 'trap_on_exit "$?" "${BASH_SOURCE[0]}" "${LINENO}" "${FUNCNAME[0]:-main}" "${BASH_COMMAND}"' EXIT
 trap 'trap_on_err  "$?" "${BASH_SOURCE[0]}" "${LINENO}" "${FUNCNAME[0]:-main}" "${BASH_COMMAND}"' ERR
 ### Updating Status of Dialog Gauge Bar.
 if ! ${VAR_HANDLER_AUTOBUILD}; then printf "XXX\nSanitizing Arguments ... \nXXX\n75\n" >&3; fi
 arg_check "$@"
@@ -66,6 +66,49 @@ readonly -f preallocate
 declare ROOTFS="${VAR_HANDLER_BUILD_DIR}/binary/live/filesystem.squashfs"
 declare LUKSFS="${VAR_HANDLER_BUILD_DIR}/binary/live/ciss_rootfs.crypt"
 declare KEYFD=""
 declare LUKS_KEY_FILE=""
 declare LUKS_KEY_FILENAME="${VAR_LUKS_KEY:-luks.txt}"
 declare LUKS_KEY_LINK_COUNT=""
 declare LUKS_KEY_MODE=""
 declare LUKS_KEY_OWNER=""
 declare SECRET_ROOT_FS=""
 declare SECRET_ROOT_MODE=""
 declare SECRET_ROOT_OWNER=""
 if [[ -L "${VAR_TMP_SECRET}" || ! -d "${VAR_TMP_SECRET}" ]]; then
  printf "\e[91m❌ Unsafe secret root rejected. \e[0m\n" >&2
  exit 42
 fi
 SECRET_ROOT_OWNER="$(stat -c '%u' "${VAR_TMP_SECRET}")"
 SECRET_ROOT_MODE="$(stat -c '%a' "${VAR_TMP_SECRET}")"
 SECRET_ROOT_FS="$(stat -f -c '%T' "${VAR_TMP_SECRET}")"
 if [[ "${SECRET_ROOT_OWNER}" != "${EUID}" || "${SECRET_ROOT_MODE}" != "700" \
  || ( "${SECRET_ROOT_FS}" != "tmpfs" && "${SECRET_ROOT_FS}" != "ramfs" ) ]]; then
  printf "\e[91m❌ Unsafe secret-root ownership, permissions, or filesystem rejected. \e[0m\n" >&2
  exit 42
 fi
 if [[ -z "${LUKS_KEY_FILENAME}" || "${LUKS_KEY_FILENAME}" == "." || "${LUKS_KEY_FILENAME}" == ".." \
  || "${LUKS_KEY_FILENAME}" == */* || ! "${LUKS_KEY_FILENAME}" =~ ^[A-Za-z0-9._@%+=:,~-]+$ ]]; then
  printf "\e[91m❌ Unsafe LUKS key filename rejected. \e[0m\n" >&2
  exit 42
 fi
 LUKS_KEY_FILE="${VAR_TMP_SECRET}/${LUKS_KEY_FILENAME}"
 if [[ -L "${LUKS_KEY_FILE}" || ! -f "${LUKS_KEY_FILE}" ]]; then
  printf "\e[91m❌ Unsafe LUKS key file rejected. \e[0m\n" >&2
  exit 42
 fi
 LUKS_KEY_OWNER="$(stat -c '%u' "${LUKS_KEY_FILE}")"
 LUKS_KEY_MODE="$(stat -c '%a' "${LUKS_KEY_FILE}")"
 LUKS_KEY_LINK_COUNT="$(stat -c '%h' "${LUKS_KEY_FILE}")"
 if [[ "${LUKS_KEY_OWNER}" != "${EUID}" || "${LUKS_KEY_LINK_COUNT}" != "1" \
  || ( "${LUKS_KEY_MODE}" != "400" && "${LUKS_KEY_MODE}" != "600" ) ]]; then
  printf "\e[91m❌ Unsafe LUKS key ownership, permissions, or link count rejected. \e[0m\n" >&2
  exit 42
 fi
 # shellcheck disable=SC2155
 declare -i VAR_ROOTFS_SIZE=$(stat -c%s -- "${ROOTFS}")
@@ -82,7 +125,7 @@ declare -i VAR_LUKSFS_SIZE=$(( ( (BASE_SIZE + ALIGN_BYTES - 1) / ALIGN_BYTES ) *
 preallocate "${LUKSFS}" "${VAR_LUKSFS_SIZE}"
-exec {KEYFD}<"${VAR_TMP_SECRET}/luks.txt"
+exec {KEYFD}<"${LUKS_KEY_FILE}"
 if [[ "${VAR_CDLB_INSIDE_RUNNER}" == "false" ]]; then
@@ -146,7 +189,7 @@ cryptsetup close crypt_liveiso
 exec {KEYFD}<&-
-shred -fzu -n 5 -- "${VAR_TMP_SECRET}/luks.txt"
+shred -fzu -n 5 -- "${LUKS_KEY_FILE}"
 rm -f -- "${ROOTFS}"
@@ -37,6 +37,10 @@ A lightweight Shell Wrapper for building a hardened Debian Live ISO Image.
  --build-directory </path/to/build_directory>
    Where the Debian Live Build Image should be generated. RECOMMENDED path: </opt/cdlb>
    The path MUST be canonical and dedicated to the builder; a new directory's canonical parent MUST already exist.
    New or empty directories receive the
    '.ciss-live-builder-owned' marker; populated unmarked directories are rejected. Cleanup is intentionally destructive
    only inside the exact validated marker-owned directory.
    MUST be provided.
  --change-splash <STRING> one of <club | hexagon>
@@ -57,6 +61,7 @@ A lightweight Shell Wrapper for building a hardened Debian Live ISO Image.
  --debug, -d
    Enables debug logging for the main program routine. Detailed logging information are written to:
    </tmp/ciss_live_builder_1801049.log>
    A final exact-value sanitisation pass is defence in depth and does not replace careful tracing discipline.
  --dhcp-centurion
    If a DHCP lease is provided, the provider's name server will be overridden and the hardened, privacy-focused
@@ -86,11 +91,13 @@ A lightweight Shell Wrapper for building a hardened Debian Live ISO Image.
  --key_age=*
    The SOPS AGE private keyring for decryption operations. Change '*' to your desired SOPS AGE key file.
    '*' MUST be a filename only without slashes, '.' or '..' traversal.
    File MUST be placed in:
    </dev/shm/cdlb_secrets>
  --key_luks=*
    The LUKS encryption / decryption passphrase for '/'-fs-encryption. Change '*' to your desired passphrase file.
    '*' MUST be a filename only without slashes, '.' or '..' traversal.
    File MUST be placed in:
    </dev/shm/cdlb_secrets>
@@ -140,7 +147,7 @@ A lightweight Shell Wrapper for building a hardened Debian Live ISO Image.
  --root-password-file </dev/shm/cdlb_secrets/password.txt>>
    Password file for 'root', if given, MUST be a string of 42 to 64 characters.
    If the argument is omitted, no further login authentication is required for the local console.
-    MUST be placed in:
+    Safe absolute paths remain supported and are validated separately. RECOMMENDED path:
    </dev/shm/cdlb_secrets/password.txt>
  --secure-boot-profile <STRING> one of <debian-shim | ciss-uki>
@@ -156,7 +163,8 @@ A lightweight Shell Wrapper for building a hardened Debian Live ISO Image.
    specified via '--signing_key=*'. If the keyring is protected, then provide the passphrase in its own file.
    Specify the fingerprint of the key to use via '--signing_key_fpr=*'.
    Optionally import an offline GPG CA signing public key via: '--signing_ca=*'.
-    Change '*' to your desired files / fingerprint. Files MUST be placed in:
+    Change '*' to your desired filename-only files / fingerprint. Filename-only values MUST NOT contain slashes or traversal.
    Files MUST be placed in:
    </dev/shm/cdlb_secrets>
  --sshfp
@@ -182,6 +190,9 @@ A lightweight Shell Wrapper for building a hardened Debian Live ISO Image.
 💡 Notes:
 🔵 You MUST be 'root' to run this script.
 🔵 Private operator control does not remove the requirement for strict local secret path validation.
 🔵 '/dev/shm/cdlb_secrets' MUST be tmpfs-backed, root-owned, mode 0700, and contain only single-link regular non-symlink files
   with mode 0400 or 0600. Secure deletion with shred is best-effort only on modern storage.
 💷 Please consider donating to my work at:
 🌐 https://coresecret.eu/spenden/
@@ -57,20 +57,17 @@ guard_sourcing || return "${ERR_GUARD_SRCE}"
 #   None
 # Returns:
 #   ERR_ARG_MSMTCH: on failure
-#   ERR_ARG_MSMTCH: on failure
+#   ERR_BUILD_PATH: on failure
 #   ERR_CONTROL_CT: on failure
 #   ERR_DROPBEAR_V: on failure
 #   ERR_MISS_PWD_F: on failure
 #   ERR_MISS_PWD_P: on failure
 #   ERR_NOTABSPATH: on failure
 #   ERR_OWNS_PWD_F: on failure
 #   ERR_PASS_LENGH: on failure
 #   ERR_PASS_PLICY: on failure
 #   ERR_REIONICE_P: on failure
 #   ERR_REIO_C_VAL: on failure
 #   ERR_REIO_P_VAL: on failure
 #   ERR_RENICE_PRI: on failure
-#   ERR_RGHT_PWD_F: on failure
+#   ERR_SECRET_PATH: on failure
 #   ERR_SPLASH_PNG: on failure
 #   ERR__SOPS__VER: on failure
 #   ERR__SSH__PORT: on failure
@@ -134,12 +131,9 @@ arg_parser() {
          ;;
        --build-directory)
-          declare -gx VAR_HANDLER_BUILD_DIR="${2}"
+          declare build_directory="${2-}"
-          if [[ ! "${VAR_HANDLER_BUILD_DIR}" =~ ^/ ]]; then
+          validate_build_directory_path "${build_directory}" build_directory || exit "${ERR_BUILD_PATH}"
-            if ! ${VAR_HANDLER_AUTOBUILD}; then boot_screen_cleaner; fi
+          declare -gx VAR_HANDLER_BUILD_DIR="${build_directory}"
            printf "\e[91m❌ Error: --build-directory MUST be an absolute path. Got: '%s'\n" "${VAR_HANDLER_BUILD_DIR}" >&2
            exit "${ERR_NOTABSPATH}"
          fi
          declare -gx VAR_BUILD_LOG="${VAR_HANDLER_BUILD_DIR}/cdlb_${VAR_ISO8601}_build.log"
          shift 2
          ;;
@@ -266,18 +260,22 @@ arg_parser() {
          ;;
        --key_age=*)
          declare age_key="${1#*=}"
          validate_secret_file_in_root "${age_key}" "SOPS Age key" || exit "${ERR_SECRET_PATH}"
          # shellcheck disable=SC2034
          declare -gx VAR_AGE="true"
          # shellcheck disable=SC2034
-          declare -gx VAR_AGE_KEY="${1#*=}"
+          declare -gx VAR_AGE_KEY="${age_key}"
          shift 1
          ;;
        --key_luks=*)
          declare luks_key="${1#*=}"
          validate_secret_file_in_root "${luks_key}" "LUKS key file" || exit "${ERR_SECRET_PATH}"
          # shellcheck disable=SC2034
          declare -gx VAR_LUKS="true"
          # shellcheck disable=SC2034
-          declare -gx VAR_LUKS_KEY="${1#*=}"
+          declare -gx VAR_LUKS_KEY="${luks_key}"
          shift 1
          ;;
@@ -473,39 +471,7 @@ arg_parser() {
          fi
-          if [[ ! -f "${pw_file}" ]]; then
+          validate_secret_absolute_file "${pw_file}" "root password file" || exit "${ERR_SECRET_PATH}"
            if ! ${VAR_HANDLER_AUTOBUILD}; then boot_screen_cleaner; fi
            printf "\e[91m❌ Error: --root-password-file password file '%s' does not exist.\e[0m\n" "${pw_file}" >&2
            # shellcheck disable=SC2162
            read -p  $'\e[92m✅ Press \'ENTER\' to exit the script ... \e[0m'
            exit "${ERR_MISS_PWD_F}"
          fi
          declare owner
          owner=$(stat -c '%U:%G' "${pw_file}")
          if [[ "${owner}" != "root:root" ]]; then
            chown root:root "${pw_file}" || {
              if ! ${VAR_HANDLER_AUTOBUILD}; then boot_screen_cleaner; fi
              printf "\e[91m❌ Error: --root-password-file failed to set owner root:root on '%s'.\e[0m\n" "${pw_file}" >&2
              # shellcheck disable=SC2162
              read -p  $'\e[92m✅ Press \'ENTER\' to exit the script ... \e[0m'
              exit "${ERR_OWNS_PWD_F}"
            }
          fi
          declare perms
          perms=$(stat -c '%a' "${pw_file}")
          if [[ "${perms}" -ne 400 ]]; then
            chmod 0400 "${pw_file}" || {
              if ! ${VAR_HANDLER_AUTOBUILD}; then boot_screen_cleaner; fi
              printf "\e[91m❌ Error: --root-password-file failed to set permissions 0400 on '%s'.\e[0m\n" "${pw_file}" >&2
              # shellcheck disable=SC2162
              read -p  $'\e[92m✅ Press \'ENTER\' to exit the script ... \e[0m'
              exit "${ERR_RGHT_PWD_F}"
            }
          fi
          declare plaintext_pw
          ### No tracing for security reasons ----------------------------------------------------------------------------------
@@ -558,6 +524,7 @@ arg_parser() {
          [[ "${VAR_EARLY_DEBUG}" == "true" ]] && set +x
          hash_temp=$(mkpasswd --method=sha-512 --salt="${salt}" --rounds=8388608 "${plaintext_pw}")
          register_secret_value "${hash_temp}"
          ### Turn on tracing again --------------------------------------------------------------------------------------------
          [[ "${VAR_EARLY_DEBUG}" == "true" ]] && set -x
@@ -606,16 +573,20 @@ arg_parser() {
          ;;
        --signing_ca=*)
          declare signing_ca="${1#*=}"
          validate_secret_file_in_root "${signing_ca}" "signing CA file" || exit "${ERR_SECRET_PATH}"
          # shellcheck disable=SC2034
-          declare -gx VAR_SIGNING_CA="${1#*=}"
+          declare -gx VAR_SIGNING_CA="${signing_ca}"
          shift 1
          ;;
        --signing_key=*)
          declare signing_key="${1#*=}"
          validate_secret_file_in_root "${signing_key}" "signing key file" || exit "${ERR_SECRET_PATH}"
          # shellcheck disable=SC2034
          declare -gx VAR_SIGNER="true"
          # shellcheck disable=SC2034
-          declare -gx VAR_SIGNING_KEY="${1#*=}"
+          declare -gx VAR_SIGNING_KEY="${signing_key}"
          shift 1
          ;;
@@ -626,8 +597,10 @@ arg_parser() {
          ;;
        --signing_key_pass=*)
          declare signing_key_pass="${1#*=}"
          validate_secret_file_in_root "${signing_key_pass}" "signing passphrase file" || exit "${ERR_SECRET_PATH}"
          # shellcheck disable=SC2034
-          declare -gx VAR_SIGNING_KEY_PASS="${1#*=}"
+          declare -gx VAR_SIGNING_KEY_PASS="${signing_key_pass}"
          shift 1
          ;;
@@ -694,8 +667,11 @@ arg_parser() {
          ;;
        --ssh-pubkey)
          declare ssh_pubkey_dir="${2-}"
          validate_secret_absolute_directory "${ssh_pubkey_dir}" "SSH public-key directory" || exit "${ERR_SECRET_PATH}"
          validate_secret_file "${ssh_pubkey_dir}/authorized_keys" "SSH authorized_keys file" || exit "${ERR_SECRET_PATH}"
          # shellcheck disable=SC2034
-          declare -gx VAR_SSHPUBKEY="${2}"
+          declare -gx VAR_SSHPUBKEY="${ssh_pubkey_dir}"
          shift 2
          ;;
@@ -0,0 +1,340 @@
 #!/bin/bash
 # SPDX-Version: 3.0
 # SPDX-CreationInfo: 2026-06-11; WEIDNER, Marc S.; <msw@coresecret.dev>
 # SPDX-ExternalRef: GIT https://git.coresecret.dev/msw/CISS.debian.live.builder.git
 # SPDX-FileContributor: WEIDNER, Marc S.; Centurion Intelligence Consulting Agency
 # SPDX-FileCopyrightText: 2024-2026; WEIDNER, Marc S.; <msw@coresecret.dev>
 # SPDX-FileType: SOURCE
 # SPDX-License-Identifier: LicenseRef-CNCL-1.1 OR LicenseRef-CCLA-1.1
 # SPDX-LicenseComment: This file is part of the CISS.debian.installer.secure framework.
 # SPDX-PackageName: CISS.debian.live.builder
 # SPDX-Security-Contact: security@coresecret.eu
 guard_sourcing || return "${ERR_GUARD_SRCE}"
 #######################################
 # Prints a generic build-directory validation error without disclosing a path.
 # Arguments:
 #   1: unsafe input class
 #   2: quiet flag
 # Returns:
 #   ERR_BUILD_PATH
 #######################################
 build_directory_validation_error() {
  declare error_class="$1" quiet="${2:-false}"
  if [[ "${quiet}" != "true" ]]; then
    printf "\e[91m❌ Unsafe build-directory input rejected: %s. \e[0m\n" "${error_class}" >&2
  fi
  return "${ERR_BUILD_PATH:-217}"
 }
 ### Prevents accidental 'unset -f'.
 # shellcheck disable=SC2034
 readonly -f build_directory_validation_error
 #######################################
 # Canonicalises an existing path or a path whose parent exists.
 # Arguments:
 #   1: candidate path
 #   2: output variable name
 # Returns:
 #   0: on success
 #   ERR_BUILD_PATH: on failure
 #######################################
 canonicalize_build_directory() {
  declare candidate="$1" output_variable="$2" basename="" parent="" resolved_path=""
  [[ -n "${candidate}" && "${candidate}" == /* ]] || return "${ERR_BUILD_PATH:-217}"
  [[ "${candidate}" == "/" ]] || candidate="${candidate%/}"
  [[ ! -L "${candidate}" ]] || return "${ERR_BUILD_PATH:-217}"
  if [[ -e "${candidate}" ]]; then
    resolved_path="$(realpath "${candidate}" 2>/dev/null)" || return "${ERR_BUILD_PATH:-217}"
  else
    basename="${candidate##*/}"
    parent="${candidate%/*}"
    [[ -n "${parent}" ]] || parent="/"
    [[ -n "${basename}" && "${basename}" != "." && "${basename}" != ".." && -d "${parent}" ]] || return "${ERR_BUILD_PATH:-217}"
    resolved_path="$(realpath "${parent}" 2>/dev/null)" || return "${ERR_BUILD_PATH:-217}"
    resolved_path="${resolved_path%/}/${basename}"
  fi
  [[ "${candidate}" == "${resolved_path}" ]] || return "${ERR_BUILD_PATH:-217}"
  printf -v "${output_variable}" '%s' "${resolved_path}"
  return 0
 }
 ### Prevents accidental 'unset -f'.
 # shellcheck disable=SC2034
 readonly -f canonicalize_build_directory
 #######################################
 # Validates a build directory against the repository cleanup policy.
 # Globals:
 #   VAR_TMP_SECRET
 #   VAR_WORKDIR
 # Arguments:
 #   1: candidate path
 #   2: output variable name
 #   3: quiet flag
 # Returns:
 #   0: on success
 #   ERR_BUILD_PATH: on failure
 #######################################
 validate_build_directory_path() {
  declare candidate="$1" output_variable="${2:-}" quiet="${3:-false}" secret_root="" validated_path="" workdir=""
  declare -a rejected_paths=(
    "/" "/bin" "/boot" "/dev" "/etc" "/home" "/lib" "/lib64" "/media" "/mnt" "/opt" "/proc" "/root" "/run" "/sbin" "/srv"
    "/sys" "/tmp" "/usr" "/usr/local" "/var" "/var/lib" "/var/tmp"
  )
  declare rejected_path=""
  canonicalize_build_directory "${candidate}" validated_path || {
    build_directory_validation_error \
      "path is empty, non-absolute, non-canonical, missing its parent, or is a symlink" "${quiet}"
    return "${ERR_BUILD_PATH:-217}"
  }
  for rejected_path in "${rejected_paths[@]}"; do
    if [[ "${validated_path}" == "${rejected_path}" ]]; then
      build_directory_validation_error "broad or system parent directory" "${quiet}"
      return "${ERR_BUILD_PATH:-217}"
    fi
  done
  workdir="$(realpath "${VAR_WORKDIR}" 2>/dev/null)" || {
    build_directory_validation_error "repository work directory cannot be resolved" "${quiet}"
    return "${ERR_BUILD_PATH:-217}"
  }
  secret_root="$(realpath "${VAR_TMP_SECRET}" 2>/dev/null)" || {
    build_directory_validation_error "secret root cannot be resolved" "${quiet}"
    return "${ERR_BUILD_PATH:-217}"
  }
  if [[ "${workdir}" == "${validated_path}" || "${workdir}" == "${validated_path}/"* || "${validated_path}" == "${workdir}/"* \
    || "${validated_path}" == "${secret_root}" || "${validated_path}" == "${secret_root}/"* ]]; then
    build_directory_validation_error "path is outside the dedicated build-directory policy" "${quiet}"
    return "${ERR_BUILD_PATH:-217}"
  fi
  if [[ -n "${output_variable}" ]]; then
    printf -v "${output_variable}" '%s' "${validated_path}"
  fi
  return 0
 }
 ### Prevents accidental 'unset -f'.
 # shellcheck disable=SC2034
 readonly -f validate_build_directory_path
 #######################################
 # Validates the builder-owned marker for an exact build directory.
 # Globals:
 #   EUID
 # Arguments:
 #   1: candidate path
 #   2: quiet flag
 # Returns:
 #   0: on success
 #   ERR_BUILD_PATH: on failure
 #######################################
 validate_build_directory_marker() {
  declare candidate="$1" quiet="${2:-false}" directory_mode="" directory_owner="" marker="" marker_build_dir=""
  declare expected_marker_value="" marker_link_count="" marker_value="" mode="" owner=""
  validate_build_directory_path "${candidate}" marker_build_dir "${quiet}" || return "${ERR_BUILD_PATH:-217}"
  [[ -d "${marker_build_dir}" ]] || {
    build_directory_validation_error "build directory does not exist" "${quiet}"
    return "${ERR_BUILD_PATH:-217}"
  }
  directory_owner="$(secure_stat -c '%u' "${marker_build_dir}" 2>/dev/null)" || return "${ERR_BUILD_PATH:-217}"
  directory_mode="$(secure_stat -c '%a' "${marker_build_dir}" 2>/dev/null)" || return "${ERR_BUILD_PATH:-217}"
  if [[ "${directory_owner}" != "${EUID}" ]] || (( (8#${directory_mode} & 022) != 0 )); then
    build_directory_validation_error "build directory ownership or permissions are unsafe" "${quiet}"
    return "${ERR_BUILD_PATH:-217}"
  fi
  marker="${marker_build_dir}/.ciss-live-builder-owned"
  if [[ -L "${marker}" || ! -f "${marker}" ]]; then
    build_directory_validation_error "builder-owned marker is missing or unsafe" "${quiet}"
    return "${ERR_BUILD_PATH:-217}"
  fi
  owner="$(secure_stat -c '%u' "${marker}" 2>/dev/null)" || return "${ERR_BUILD_PATH:-217}"
  mode="$(secure_stat -c '%a' "${marker}" 2>/dev/null)" || return "${ERR_BUILD_PATH:-217}"
  marker_link_count="$(secure_stat -c '%h' "${marker}" 2>/dev/null)" || return "${ERR_BUILD_PATH:-217}"
  marker_value="$(cat "${marker}" || exit $?; printf '.')" || return "${ERR_BUILD_PATH:-217}"
  marker_value="${marker_value%.}"
  expected_marker_value="${marker_build_dir}"$'\n'
  if [[ "${owner}" != "${EUID}" || "${mode}" != "400" || "${marker_link_count}" != "1" \
    || "${marker_value}" != "${expected_marker_value}" ]]; then
    build_directory_validation_error "builder-owned marker does not match the exact directory" "${quiet}"
    return "${ERR_BUILD_PATH:-217}"
  fi
  return 0
 }
 ### Prevents accidental 'unset -f'.
 # shellcheck disable=SC2034
 readonly -f validate_build_directory_marker
 #######################################
 # Validates an existing exact subpath below a marker-owned build directory.
 # Arguments:
 #   1: build directory
 #   2: relative subpath
 #   3: output variable name
 #   4: quiet flag
 # Returns:
 #   0: on success
 #   ERR_BUILD_PATH: on failure
 #######################################
 validate_build_directory_subpath() {
  declare build_directory="$1" relative_path="$2" output_variable="$3" quiet="${4:-false}"
  declare candidate_subpath="" resolved_subpath=""
  validate_build_directory_marker "${build_directory}" "${quiet}" || return "${ERR_BUILD_PATH:-217}"
  if [[ -z "${relative_path}" || "${relative_path}" == /* || "${relative_path}" == "." || "${relative_path}" == ".." \
    || "${relative_path}" == ../* || "${relative_path}" == */../* || "${relative_path}" == */.. \
    || "${relative_path}" == ./* || "${relative_path}" == */./* || "${relative_path}" == */. ]]; then
    build_directory_validation_error "unsafe relative cleanup subpath" "${quiet}"
    return "${ERR_BUILD_PATH:-217}"
  fi
  candidate_subpath="${build_directory}/${relative_path}"
  if [[ -L "${candidate_subpath}" || ! -e "${candidate_subpath}" ]]; then
    build_directory_validation_error "cleanup subpath is missing or is a symlink" "${quiet}"
    return "${ERR_BUILD_PATH:-217}"
  fi
  resolved_subpath="$(realpath "${candidate_subpath}" 2>/dev/null)" || return "${ERR_BUILD_PATH:-217}"
  if [[ "${resolved_subpath}" != "${candidate_subpath}" || "${resolved_subpath}" != "${build_directory}/"* ]]; then
    build_directory_validation_error "cleanup subpath escapes the exact build directory" "${quiet}"
    return "${ERR_BUILD_PATH:-217}"
  fi
  printf -v "${output_variable}" '%s' "${resolved_subpath}"
  return 0
 }
 ### Prevents accidental 'unset -f'.
 # shellcheck disable=SC2034
 readonly -f validate_build_directory_subpath
 #######################################
 # Initialises a new or empty build directory and its ownership marker.
 # Arguments:
 #   1: candidate path
 #   2: output variable name
 # Returns:
 #   0: on success
 #   ERR_BUILD_PATH: on failure
 #######################################
 initialize_build_directory() {
  declare candidate="$1" output_variable="$2" directory_mode="" directory_owner="" existing_entry=""
  declare initialized_build_dir="" marker=""
  validate_build_directory_path "${candidate}" initialized_build_dir || return "${ERR_BUILD_PATH:-217}"
  if [[ ! -e "${initialized_build_dir}" ]]; then
    mkdir -m 0700 "${initialized_build_dir}" || return "${ERR_BUILD_PATH:-217}"
  fi
  validate_build_directory_path "${initialized_build_dir}" initialized_build_dir || return "${ERR_BUILD_PATH:-217}"
  [[ -d "${initialized_build_dir}" && ! -L "${initialized_build_dir}" ]] || return "${ERR_BUILD_PATH:-217}"
  directory_owner="$(secure_stat -c '%u' "${initialized_build_dir}" 2>/dev/null)" || return "${ERR_BUILD_PATH:-217}"
  directory_mode="$(secure_stat -c '%a' "${initialized_build_dir}" 2>/dev/null)" || return "${ERR_BUILD_PATH:-217}"
  if [[ "${directory_owner}" != "${EUID}" ]] || (( (8#${directory_mode} & 022) != 0 )); then
    build_directory_validation_error "build directory ownership or permissions are unsafe"
    return "${ERR_BUILD_PATH:-217}"
  fi
  marker="${initialized_build_dir}/.ciss-live-builder-owned"
  if [[ -e "${marker}" || -L "${marker}" ]]; then
    validate_build_directory_marker "${initialized_build_dir}" || return "${ERR_BUILD_PATH:-217}"
  else
    existing_entry="$(find "${initialized_build_dir}" -mindepth 1 -maxdepth 1 -print -quit)" || return "${ERR_BUILD_PATH:-217}"
    if [[ -n "${existing_entry}" ]]; then
      build_directory_validation_error "non-empty directory has no builder-owned marker"
      return "${ERR_BUILD_PATH:-217}"
    fi
    (umask 077; printf '%s\n' "${initialized_build_dir}" >| "${marker}") || return "${ERR_BUILD_PATH:-217}"
    chmod 0400 "${marker}" || return "${ERR_BUILD_PATH:-217}"
    validate_build_directory_marker "${initialized_build_dir}" || return "${ERR_BUILD_PATH:-217}"
  fi
  printf -v "${output_variable}" '%s' "${initialized_build_dir}"
  return 0
 }
 ### Prevents accidental 'unset -f'.
 # shellcheck disable=SC2034
 readonly -f initialize_build_directory
 #######################################
 # Removes paths with a one-filesystem boundary where supported.
 # Arguments:
 #   paths to remove
 # Returns:
 #   rm exit status
 #######################################
 remove_build_paths() {
  # shellcheck disable=SC2312
  if rm --help 2>&1 | grep -q -- '--one-file-system'; then
    rm -rf --one-file-system -- "$@"
  else
    rm -rf -- "$@"
  fi
 }
 ### Prevents accidental 'unset -f'.
 # shellcheck disable=SC2034
 readonly -f remove_build_paths
 #######################################
 # Deletes all content except the ownership marker from an exact build directory.
 # Arguments:
 #   1: candidate path
 # Returns:
 #   0: on success
 #   ERR_BUILD_PATH: on failure
 #######################################
 clean_build_directory_contents() {
  declare candidate="$1" build_entry=""
  declare -a build_entries=()
  declare -i old_dotglob=0 old_failglob=0 old_nullglob=0
  validate_build_directory_marker "${candidate}" || return "${ERR_BUILD_PATH:-217}"
  shopt -q dotglob  && old_dotglob=1
  shopt -q failglob && old_failglob=1
  shopt -q nullglob && old_nullglob=1
  shopt -s dotglob nullglob
  shopt -u failglob
  build_entries=("${candidate}"/*)
  for build_entry in "${build_entries[@]}"; do
    [[ "${build_entry}" == "${candidate}/.ciss-live-builder-owned" ]] && continue
    remove_build_paths "${build_entry}" || {
      if (( old_dotglob )); then shopt -s dotglob; else shopt -u dotglob; fi
      if (( old_failglob )); then shopt -s failglob; else shopt -u failglob; fi
      if (( old_nullglob )); then shopt -s nullglob; else shopt -u nullglob; fi
      return "${ERR_BUILD_PATH:-217}"
    }
  done
  if (( old_dotglob )); then shopt -s dotglob; else shopt -u dotglob; fi
  if (( old_failglob )); then shopt -s failglob; else shopt -u failglob; fi
  if (( old_nullglob )); then shopt -s nullglob; else shopt -u nullglob; fi
  validate_build_directory_marker "${candidate}" || return "${ERR_BUILD_PATH:-217}"
  return 0
 }
 ### Prevents accidental 'unset -f'.
 # shellcheck disable=SC2034
 readonly -f clean_build_directory_contents
 # vim: number et ts=2 sw=2 sts=2 ai tw=128 ft=sh
@@ -23,36 +23,26 @@ guard_sourcing || return "${ERR_GUARD_SRCE}"
 #   0: on success
 #######################################
 x_remove() {
  declare luks_key_filename="${VAR_LUKS_KEY:-luks.txt}" luks_key_path="" signing_pass_path=""
  declare -a find_args=("${VAR_TMP_SECRET}" -xdev -type f)
  printf "\e[95m🧪 %s starting ... \e[0m\n" "${BASH_SOURCE[0]}"
-  declare _old_nullglob="" _old_dotglob=""
+  validate_secret_staging_area || return "${ERR_SECRET_PATH}"
  ### Enable nullglob/dotglob, disable failglob for safe globbing.
  _old_nullglob="$(shopt -p nullglob || true)"
  _old_dotglob="$( shopt -p dotglob  || true)"
  shopt -s nullglob dotglob
  if [[ "${VAR_SIGNER}" == "true" ]]; then
-
+    validate_secret_file_in_root "${VAR_SIGNING_KEY_PASS}" "signing passphrase file" || return "${ERR_SECRET_PATH}"
-    # shellcheck disable=SC2312
+    signing_pass_path="${VAR_TMP_SECRET}/${VAR_SIGNING_KEY_PASS}"
-    find "${VAR_TMP_SECRET}" -xdev -type f \
+    find_args+=(! -path "${signing_pass_path}")
      ! -path "${VAR_TMP_SECRET}/signing_key_pass.txt" \
      ! -path "${VAR_TMP_SECRET}/luks.txt" \
      -print0 \
      | xargs -0 --no-run-if-empty shred -fzu -n 5 --
  else
    ### Removes secrets securely.
    # shellcheck disable=SC2312
    find "${VAR_TMP_SECRET}" -xdev -type f -print0 | xargs -0 --no-run-if-empty shred -fzu -n 5 --
    find "${VAR_TMP_SECRET}" -xdev -depth -type d -empty -delete
  fi
-  eval "${_old_nullglob}" 2>/dev/null || true
+  validate_secret_file_in_root "${luks_key_filename}" "LUKS key file" || return "${ERR_SECRET_PATH}"
-  eval "${_old_dotglob}"  2>/dev/null || true
+  luks_key_path="${VAR_TMP_SECRET}/${luks_key_filename}"
  find_args+=(! -path "${luks_key_path}")
  # shellcheck disable=SC2312
  find "${find_args[@]}" -print0 | xargs -0 --no-run-if-empty shred -fzu -n 5 --
  find "${VAR_TMP_SECRET}" -xdev -depth -type d -empty -delete
  printf "\e[92m✅ %s successfully applied. \e[0m\n" "${BASH_SOURCE[0]}"
@@ -32,15 +32,7 @@ guard_sourcing || return "${ERR_GUARD_SRCE}"
 #   0: on success
 #######################################
 clean_up() {
-  declare clean_exit_code="$1" fs_type="" _old_nullglob="" _old_dotglob="" _old_failglob=""
+  declare chroot_directory="" clean_exit_code="$1" fs_type="" includes_directory=""
  ### Enable nullglob/dotglob, disable failglob for safe globbing.
  _old_nullglob="$(shopt -p nullglob || true)"
  _old_dotglob="$( shopt -p dotglob  || true)"
  _old_failglob="$(shopt -p failglob || true)"
  shopt -s nullglob dotglob
  shopt -u failglob
  if [[ -e /dev/mapper/crypt_liveiso ]]; then
    cryptsetup close crypt_liveiso || true
@@ -52,10 +44,10 @@ clean_up() {
  rm -f -- "${VAR_NOTES}"
  ### Release advisory lock on FD 127.
-  flock -u 127
+  flock -u 127 2>/dev/null || true
  ### Close file descriptor 127.
-  exec 127>&-
+  exec 127>&- 2>/dev/null || true
  ### Remove the lockfile artifact.
  rm -f /run/lock/ciss_live_builder.lock
@@ -100,36 +92,41 @@ clean_up() {
  ### No tracing for security reasons ------------------------------------------------------------------------------------------
  [[ "${VAR_EARLY_DEBUG}" == "true" ]] && set +x
-  ### Removes secrets securely.
+  ### Removes secrets securely only after re-validating the fixed tmpfs staging area.
  if validate_secret_staging_area "true"; then
    # shellcheck disable=SC2312
-  find "${VAR_TMP_SECRET}" -xdev -type f -print0 | xargs -0 --no-run-if-empty shred -fzu -n 5 --
+    find "${VAR_TMP_SECRET}" -xdev -type f -print0 | xargs -0 --no-run-if-empty shred -fzu -n 5 -- || true
-  find "${VAR_TMP_SECRET}" -xdev -depth -type d -empty -delete
+    find "${VAR_TMP_SECRET}" -xdev -depth -type d -empty -delete || true
-
+  else
-  ### Securely shred all regular files below ./includes.chroot, then remove empty dirs.
+    printf "\e[93m⚠ Secret cleanup skipped because the staging area failed validation. \e[0m\n" >&2
  if [[ -d "${VAR_HANDLER_BUILD_DIR}/config/includes.chroot" ]]; then
    # shellcheck disable=SC2312
    find "${VAR_HANDLER_BUILD_DIR}/config/includes.chroot" -xdev -type f -print0 | xargs -0 --no-run-if-empty shred -fzu -n 5 --
    ### Remove empty directories (bottom-up).
    find "${VAR_HANDLER_BUILD_DIR}/config/includes.chroot" -depth -xdev -type d -empty -delete
  fi
-  ### Delete all files and directories below ./chroot.
+  ### Destructive build cleanup requires the exact builder-owned directory marker.
-  if [[ -d "${VAR_HANDLER_BUILD_DIR}/chroot" ]]; then
+  if [[ -n "${VAR_HANDLER_BUILD_DIR}" ]] && validate_build_directory_marker "${VAR_HANDLER_BUILD_DIR}" "true"; then
-
+    if [[ -e "${VAR_HANDLER_BUILD_DIR}/config/includes.chroot" || -L "${VAR_HANDLER_BUILD_DIR}/config/includes.chroot" ]]; then
-    rm -rf "${VAR_HANDLER_BUILD_DIR}/chroot"
+      if validate_build_directory_subpath "${VAR_HANDLER_BUILD_DIR}" "config/includes.chroot" includes_directory "true"; then
        # shellcheck disable=SC2312
        find "${includes_directory}" -xdev -type f -print0 | xargs -0 --no-run-if-empty shred -fzu -n 5 -- || true
        find "${includes_directory}" -depth -xdev -type d -empty -delete || true
      else
        printf "\e[93m⚠ Build includes cleanup skipped because the exact subpath failed validation. \e[0m\n" >&2
      fi
    fi
    if [[ -e "${VAR_HANDLER_BUILD_DIR}/chroot" || -L "${VAR_HANDLER_BUILD_DIR}/chroot" ]]; then
      if validate_build_directory_subpath "${VAR_HANDLER_BUILD_DIR}" "chroot" chroot_directory "true"; then
        remove_build_paths "${chroot_directory}" || true
      else
        printf "\e[93m⚠ Build chroot cleanup skipped because the exact subpath failed validation. \e[0m\n" >&2
      fi
    fi
  elif [[ -n "${VAR_HANDLER_BUILD_DIR}" ]]; then
    printf "\e[93m⚠ Build-directory cleanup skipped because the exact builder-owned marker failed validation. \e[0m\n" >&2
  fi
  ### Turn on tracing again ----------------------------------------------------------------------------------------------------
  [[ "${VAR_EARLY_DEBUG}" == "true" ]] && set -x
  eval "${_old_nullglob}" 2>/dev/null || true
  eval "${_old_dotglob}"  2>/dev/null || true
  eval "${_old_failglob}" 2>/dev/null || true
  return 0
 }
 ### Prevents accidental 'unset -f'.
@@ -0,0 +1,92 @@
 #!/bin/bash
 # SPDX-Version: 3.0
 # SPDX-CreationInfo: 2026-06-11; WEIDNER, Marc S.; <msw@coresecret.dev>
 # SPDX-ExternalRef: GIT https://git.coresecret.dev/msw/CISS.debian.live.builder.git
 # SPDX-FileContributor: WEIDNER, Marc S.; Centurion Intelligence Consulting Agency
 # SPDX-FileCopyrightText: 2024-2026; WEIDNER, Marc S.; <msw@coresecret.dev>
 # SPDX-FileType: SOURCE
 # SPDX-License-Identifier: LicenseRef-CNCL-1.1 OR LicenseRef-CCLA-1.1
 # SPDX-LicenseComment: This file is part of the CISS.debian.installer.secure framework.
 # SPDX-PackageName: CISS.debian.live.builder
 # SPDX-Security-Contact: security@coresecret.eu
 guard_sourcing || return "${ERR_GUARD_SRCE}"
 #######################################
 # Replaces exact registered secret values in one controlled log file.
 # Globals:
 #   _ARY_SECRET_REDACTION_VALUES
 # Arguments:
 #   1: log file
 # Returns:
 #   0: on success or missing log
 #   ERR_SANITIZING: on failure
 #######################################
 sanitize_debug_log() {
  declare log_file="$1" log_text="" replacement="" secret_value="" tmp_file=""
  [[ -n "${log_file}" && -f "${log_file}" ]] || return 0
  [[ ! -L "${log_file}" ]] || return "${ERR_SANITIZING:-133}"
  log_text="$(cat "${log_file}" || exit $?; printf '.')" || return "${ERR_SANITIZING:-133}"
  log_text="${log_text%.}"
  for secret_value in "${_ARY_SECRET_REDACTION_VALUES[@]}"; do
    [[ -n "${secret_value}" ]] || continue
    printf -v replacement '%*s' "${#secret_value}" ''
    replacement="${replacement// /*}"
    log_text="${log_text//"${secret_value}"/"${replacement}"}"
  done
  tmp_file="$(mktemp "${log_file}.sanitize.XXXXXX")" || return "${ERR_SANITIZING:-133}"
  chmod 0600 "${tmp_file}" || {
    rm -f "${tmp_file}"
    return "${ERR_SANITIZING:-133}"
  }
  printf '%s' "${log_text}" >| "${tmp_file}" || {
    rm -f "${tmp_file}"
    return "${ERR_SANITIZING:-133}"
  }
  mv -f "${tmp_file}" "${log_file}" || {
    rm -f "${tmp_file}"
    return "${ERR_SANITIZING:-133}"
  }
  return 0
 }
 ### Prevents accidental 'unset -f'.
 # shellcheck disable=SC2034
 readonly -f sanitize_debug_log
 #######################################
 # Runs the final exact-value sanitisation pass for controlled logs.
 # Globals:
 #   LOG_DEBUG
 #   LOG_ERROR
 #   LOG_VAR
 # Arguments:
 #   None
 # Returns:
 #   0: on success
 #   ERR_SANITIZING: on failure
 #######################################
 sanitize_debug_logs() {
  declare log_file=""
  declare -a log_files=("${LOG_DEBUG:-}" "${LOG_VAR:-}" "${LOG_ERROR:-}")
  set +x
  if [[ -e "/proc/$$/fd/42" || -e "/dev/fd/42" ]]; then
    exec 42>&-
  fi
  for log_file in "${log_files[@]}"; do
    sanitize_debug_log "${log_file}" || return "${ERR_SANITIZING:-133}"
  done
  return 0
 }
 ### Prevents accidental 'unset -f'.
 # shellcheck disable=SC2034
 readonly -f sanitize_debug_logs
 # vim: number et ts=2 sw=2 sts=2 ai tw=128 ft=sh
@@ -41,6 +41,12 @@ init_gnupg() {
  if [[ "${VAR_SIGNER}" == "true" ]]; then
    validate_secret_file_in_root "${VAR_SIGNING_KEY}" "signing key file" || return "${ERR_SECRET_PATH}"
    validate_secret_file_in_root "${VAR_SIGNING_KEY_PASS}" "signing passphrase file" || return "${ERR_SECRET_PATH}"
    if [[ -n "${VAR_SIGNING_CA}" ]]; then
      validate_secret_file_in_root "${VAR_SIGNING_CA}" "signing CA file" || return "${ERR_SECRET_PATH}"
    fi
    __umask=$(umask)
    umask 0077
@@ -82,6 +88,7 @@ EOF
    declare __pw=""
    __pw="$(<"${VAR_SIGNING_KEY_PASSFILE}")"; __pw="${__pw%$'\r'}"; printf '%s' "${__pw}" >| "${VAR_SIGNING_KEY_PASSFILE}"
    register_secret_value "${__pw}"
    __pw="" && unset __pw
    ### Turn on tracing again ----------------------------------------------------------------------------------------------------
@@ -182,6 +182,8 @@ hardening_ultra() {
  printf "\e[95m🧪 Updating SSH Keys, Ports ... \e[0m\n"
  ### ./config/includes.chroot/root/.ssh ---------------------------------------------------------------------------------------
  validate_secret_absolute_directory "${VAR_SSHPUBKEY}" "SSH public-key directory" || return "${ERR_SECRET_PATH}"
  validate_secret_file "${VAR_SSHPUBKEY}/authorized_keys" "SSH authorized_keys file" || return "${ERR_SECRET_PATH}"
  install -d -m 0700 "${VAR_HANDLER_BUILD_DIR}/config/includes.chroot/root/.ssh"
  install -m 0600 -o root -g root "${VAR_SSHPUBKEY}/authorized_keys" "${VAR_HANDLER_BUILD_DIR}/config/includes.chroot/root/.ssh/"
@@ -23,36 +23,22 @@ guard_sourcing || return "${ERR_GUARD_SRCE}"
 #   0: on success
 #######################################
 lb_config_start() {
  declare canonical_build_dir=""
  printf "\e[95m🧪 %s starting ... \e[0m\n" "${BASH_SOURCE[0]}"
-  if [[ ! -d ${VAR_HANDLER_BUILD_DIR} ]]; then
+  initialize_build_directory "${VAR_HANDLER_BUILD_DIR}" canonical_build_dir || return "${ERR_BUILD_PATH}"
-
+  VAR_HANDLER_BUILD_DIR="${canonical_build_dir}"
-    mkdir -p "${VAR_HANDLER_BUILD_DIR}"
+  cd "${VAR_HANDLER_BUILD_DIR}" || return "${ERR_BUILD_PATH}"
    # shellcheck disable=SC2164
    cd "${VAR_HANDLER_BUILD_DIR}"
    printf "\e[92m✅ '%s' created. \e[0m\n" "${VAR_HANDLER_BUILD_DIR}"
  else
    # shellcheck disable=SC2164
    cd "${VAR_HANDLER_BUILD_DIR}"
  fi
  if [[ -d "${VAR_HANDLER_BUILD_DIR}/.build" ]]; then
-    # shellcheck disable=SC2164
+    validate_build_directory_marker "${VAR_HANDLER_BUILD_DIR}" || return "${ERR_BUILD_PATH}"
    cd "${VAR_HANDLER_BUILD_DIR}"
    printf "\e[95m🧪 Deleting former config, binary and cache ... \e[0m\n"
    lb clean --binary --cache --purge --source
-
+    clean_build_directory_contents "${VAR_HANDLER_BUILD_DIR}" || return "${ERR_BUILD_PATH}"
    if [[ "${PWD}" == "${VAR_HANDLER_BUILD_DIR}" && "${PWD}" != "/" && -n "${PWD}" ]]; then
      rm -rf -- ./* ./.??*
    fi
    printf "\e[92m✅ Deleting former config, binary and cache done.\e[0m\n"
@@ -84,6 +84,7 @@ init_primordial() {
  ### Check for SOPS AGE key integration ---------------------------------------------------------------------------------------
  if [[ "${VAR_AGE,,}" == "true" ]]; then
    validate_secret_file_in_root "${VAR_AGE_KEY}" "SOPS Age key" || return "${ERR_SECRET_PATH}"
    install -d -m 0700                                 "${VAR_HANDLER_BUILD_DIR}/config/includes.chroot/root/.config/sops/age"
    install -m 0400 "${VAR_TMP_SECRET}/${VAR_AGE_KEY}" "${VAR_HANDLER_BUILD_DIR}/config/includes.chroot/root/.config/sops/age/keys.txt"
    shred -fzu -n 5 -- "${VAR_TMP_SECRET}/${VAR_AGE_KEY}" 2>/dev/null || rm -f "${VAR_TMP_SECRET}/${VAR_AGE_KEY}"
@@ -92,16 +93,35 @@ init_primordial() {
  ### Check for SSH CISS and PhysNet Primordial-Workflow™ integration -------------------------------------------------------
  if [[ "${VAR_SSHFP,,}" == "true" ]]; then
    declare secret_key_file=""
    declare -a identity_files=() host_key_files=()
    validate_secret_directory "${VAR_TMP_SECRET}" "secret root" "true" || return "${ERR_SECRET_PATH}"
    while IFS= read -r -d '' secret_key_file; do
      validate_secret_file "${secret_key_file}" "primordial SSH identity file" || return "${ERR_SECRET_PATH}"
      identity_files+=("${secret_key_file}")
    done < <(find "${VAR_TMP_SECRET}" -maxdepth 1 -type f -name 'id*' -print0)
    while IFS= read -r -d '' secret_key_file; do
      validate_secret_file "${secret_key_file}" "primordial SSH host-key file" || return "${ERR_SECRET_PATH}"
      host_key_files+=("${secret_key_file}")
    done < <(find "${VAR_TMP_SECRET}" -maxdepth 1 -type f -name 'ssh_host_*' -print0)
    (( ${#identity_files[@]} > 0 && ${#host_key_files[@]} > 0 )) || {
      secret_validation_error "required primordial SSH key files are missing"
      return "${ERR_SECRET_PATH}"
    }
    install -d -m 0700                      "${VAR_HANDLER_BUILD_DIR}/config/includes.chroot/root/.ssh"
-    install -m 0600 "${VAR_TMP_SECRET}/id"* "${VAR_HANDLER_BUILD_DIR}/config/includes.chroot/root/.ssh/"
+    install -m 0600 "${identity_files[@]}"  "${VAR_HANDLER_BUILD_DIR}/config/includes.chroot/root/.ssh/"
    normalize_ssh_keys_in_dir               "${VAR_HANDLER_BUILD_DIR}/config/includes.chroot/root/.ssh"
-    shred -fzu -n 5 -- "${VAR_TMP_SECRET}/id"* 2>/dev/null || rm -f "${VAR_TMP_SECRET}/id"*
+    shred -fzu -n 5 -- "${identity_files[@]}" 2>/dev/null || rm -f "${identity_files[@]}"
    install -d -m 0700                             "${VAR_HANDLER_BUILD_DIR}/config/includes.chroot/root/ssh"
-    install -m 0600 "${VAR_TMP_SECRET}/ssh_host_"* "${VAR_HANDLER_BUILD_DIR}/config/includes.chroot/root/ssh/"
+    install -m 0600 "${host_key_files[@]}"         "${VAR_HANDLER_BUILD_DIR}/config/includes.chroot/root/ssh/"
    normalize_ssh_keys_in_dir                      "${VAR_HANDLER_BUILD_DIR}/config/includes.chroot/root/ssh/"
-    shred -fzu -n 5 -- "${VAR_TMP_SECRET}/ssh_host_"* 2>/dev/null || rm -f "${VAR_TMP_SECRET}/ssh_host_"*
+    shred -fzu -n 5 -- "${host_key_files[@]}" 2>/dev/null || rm -f "${host_key_files[@]}"
  fi
@@ -0,0 +1,384 @@
 #!/bin/bash
 # SPDX-Version: 3.0
 # SPDX-CreationInfo: 2026-06-11; WEIDNER, Marc S.; <msw@coresecret.dev>
 # SPDX-ExternalRef: GIT https://git.coresecret.dev/msw/CISS.debian.live.builder.git
 # SPDX-FileContributor: WEIDNER, Marc S.; Centurion Intelligence Consulting Agency
 # SPDX-FileCopyrightText: 2024-2026; WEIDNER, Marc S.; <msw@coresecret.dev>
 # SPDX-FileType: SOURCE
 # SPDX-License-Identifier: LicenseRef-CNCL-1.1 OR LicenseRef-CCLA-1.1
 # SPDX-LicenseComment: This file is part of the CISS.debian.installer.secure framework.
 # SPDX-PackageName: CISS.debian.live.builder
 # SPDX-Security-Contact: security@coresecret.eu
 guard_sourcing || return "${ERR_GUARD_SRCE}"
 if ! declare -p _ARY_SECRET_REDACTION_VALUES >/dev/null 2>&1; then
  declare -ga _ARY_SECRET_REDACTION_VALUES=()
 fi
 #######################################
 # Runs GNU stat on Debian and gstat on macOS development hosts.
 # Arguments:
 #   stat arguments
 # Returns:
 #   stat exit status
 #######################################
 secure_stat() {
  if command -v gstat >/dev/null 2>&1; then
    gstat "$@"
  else
    stat "$@"
  fi
 }
 ### Prevents accidental 'unset -f'.
 # shellcheck disable=SC2034
 readonly -f secure_stat
 #######################################
 # Prints a generic secret validation error without disclosing a path or value.
 # Arguments:
 #   1: unsafe input class
 #   2: quiet flag
 # Returns:
 #   ERR_SECRET_PATH
 #######################################
 secret_validation_error() {
  declare error_class="$1" quiet="${2:-false}"
  if [[ "${quiet}" != "true" ]]; then
    printf "\e[91m❌ Unsafe secret input rejected: %s. \e[0m\n" "${error_class}" >&2
  fi
  return "${ERR_SECRET_PATH:-216}"
 }
 ### Prevents accidental 'unset -f'.
 # shellcheck disable=SC2034
 readonly -f secret_validation_error
 #######################################
 # Registers an exact known secret value for final log redaction.
 # Globals:
 #   _ARY_SECRET_REDACTION_VALUES
 # Arguments:
 #   1: secret value
 # Returns:
 #   0: on success
 #######################################
 register_secret_value() {
  declare secret_value="$1" registered_value="" was_traced="false"
  [[ $- == *x* ]] && was_traced="true"
  set +x
  if [[ -n "${secret_value}" ]]; then
    for registered_value in "${_ARY_SECRET_REDACTION_VALUES[@]}"; do
      if [[ "${registered_value}" == "${secret_value}" ]]; then
        [[ "${was_traced}" == "true" ]] && set -x
        return 0
      fi
    done
    _ARY_SECRET_REDACTION_VALUES+=("${secret_value}")
  fi
  [[ "${was_traced}" == "true" ]] && set -x
  return 0
 }
 ### Prevents accidental 'unset -f'.
 # shellcheck disable=SC2034
 readonly -f register_secret_value
 #######################################
 # Registers exact text values from a controlled secret file.
 # Globals:
 #   _ARY_SECRET_REDACTION_VALUES
 # Arguments:
 #   1: secret file
 # Returns:
 #   0: on success
 #######################################
 register_secret_file_for_redaction() {
  declare secret_file="$1" secret_line="" secret_text="" was_traced="false"
  [[ $- == *x* ]] && was_traced="true"
  set +x
  secret_text="$(cat "${secret_file}" || exit $?; printf '.')" || {
    [[ "${was_traced}" == "true" ]] && set -x
    return "${ERR_SANITIZING:-133}"
  }
  secret_text="${secret_text%.}"
  register_secret_value "${secret_text}"
  while IFS= read -r secret_line || [[ -n "${secret_line}" ]]; do
    register_secret_value "${secret_line}"
  done < "${secret_file}"
  [[ "${was_traced}" == "true" ]] && set -x
  return 0
 }
 ### Prevents accidental 'unset -f'.
 # shellcheck disable=SC2034
 readonly -f register_secret_file_for_redaction
 #######################################
 # Validates a filename-only secret argument.
 # Arguments:
 #   1: filename
 #   2: input class
 # Returns:
 #   0: on success
 #   ERR_SECRET_PATH: on failure
 #######################################
 validate_secret_filename() {
  declare filename="$1" input_class="${2:-filename-only secret argument}"
  declare filename_regex='^[A-Za-z0-9._@%+=:,~-]+$'
  if [[ -z "${filename}" || "${filename}" == "." || "${filename}" == ".." || "${filename}" == */* \
    || ! "${filename}" =~ ${filename_regex} ]]; then
    secret_validation_error "${input_class}"
    return "${ERR_SECRET_PATH:-216}"
  fi
  return 0
 }
 ### Prevents accidental 'unset -f'.
 # shellcheck disable=SC2034
 readonly -f validate_secret_filename
 #######################################
 # Validates a restrictively permissioned secret directory.
 # Arguments:
 #   1: directory path
 #   2: input class
 #   3: require tmpfs
 #   4: quiet flag
 # Returns:
 #   0: on success
 #   ERR_SECRET_PATH: on failure
 #######################################
 validate_secret_directory() {
  declare directory="$1" input_class="${2:-secret directory}" require_tmpfs="${3:-false}" quiet="${4:-false}"
  declare fs_type="" mode="" owner=""
  if [[ -z "${directory}" || -L "${directory}" || ! -d "${directory}" ]]; then
    secret_validation_error "${input_class}" "${quiet}"
    return "${ERR_SECRET_PATH:-216}"
  fi
  owner="$(secure_stat -c '%u' "${directory}" 2>/dev/null)" || {
    secret_validation_error "${input_class} ownership" "${quiet}"
    return "${ERR_SECRET_PATH:-216}"
  }
  mode="$(secure_stat -c '%a' "${directory}" 2>/dev/null)" || {
    secret_validation_error "${input_class} permissions" "${quiet}"
    return "${ERR_SECRET_PATH:-216}"
  }
  if [[ "${owner}" != "${EUID}" || "${mode}" != "700" ]]; then
    secret_validation_error "${input_class} ownership or permissions" "${quiet}"
    return "${ERR_SECRET_PATH:-216}"
  fi
  if [[ "${require_tmpfs}" == "true" ]]; then
    fs_type="$(secure_stat -f -c '%T' "${directory}" 2>/dev/null)" || {
      secret_validation_error "${input_class} filesystem" "${quiet}"
      return "${ERR_SECRET_PATH:-216}"
    }
    if [[ "${fs_type}" != "tmpfs" && "${fs_type}" != "ramfs" ]]; then
      secret_validation_error "${input_class} is not tmpfs-backed" "${quiet}"
      return "${ERR_SECRET_PATH:-216}"
    fi
  fi
  return 0
 }
 ### Prevents accidental 'unset -f'.
 # shellcheck disable=SC2034
 readonly -f validate_secret_directory
 #######################################
 # Validates and registers a secret file.
 # Arguments:
 #   1: file path
 #   2: input class
 #   3: register for redaction
 #   4: quiet flag
 # Returns:
 #   0: on success
 #   ERR_SECRET_PATH: on failure
 #######################################
 validate_secret_file() {
  declare secret_file="$1" input_class="${2:-secret file}" register_value="${3:-true}" quiet="${4:-false}"
  declare link_count="" mode="" owner=""
  if [[ -z "${secret_file}" || -L "${secret_file}" || ! -f "${secret_file}" ]]; then
    secret_validation_error "${input_class}" "${quiet}"
    return "${ERR_SECRET_PATH:-216}"
  fi
  owner="$(secure_stat -c '%u' "${secret_file}" 2>/dev/null)" || {
    secret_validation_error "${input_class} ownership" "${quiet}"
    return "${ERR_SECRET_PATH:-216}"
  }
  mode="$(secure_stat -c '%a' "${secret_file}" 2>/dev/null)" || {
    secret_validation_error "${input_class} permissions" "${quiet}"
    return "${ERR_SECRET_PATH:-216}"
  }
  link_count="$(secure_stat -c '%h' "${secret_file}" 2>/dev/null)" || {
    secret_validation_error "${input_class} link count" "${quiet}"
    return "${ERR_SECRET_PATH:-216}"
  }
  if [[ "${owner}" != "${EUID}" || "${link_count}" != "1" || ( "${mode}" != "400" && "${mode}" != "600" ) ]]; then
    secret_validation_error "${input_class} ownership, permissions, or link count" "${quiet}"
    return "${ERR_SECRET_PATH:-216}"
  fi
  if [[ "${register_value}" == "true" ]]; then
    register_secret_file_for_redaction "${secret_file}"
  fi
  return 0
 }
 ### Prevents accidental 'unset -f'.
 # shellcheck disable=SC2034
 readonly -f validate_secret_file
 #######################################
 # Validates an explicitly supported absolute secret file path.
 # Arguments:
 #   1: file path
 #   2: input class
 # Returns:
 #   0: on success
 #   ERR_SECRET_PATH: on failure
 #######################################
 validate_secret_absolute_file() {
  declare secret_file="$1" input_class="${2:-absolute secret file}" resolved_file=""
  if [[ -z "${secret_file}" || "${secret_file}" != /* ]]; then
    secret_validation_error "${input_class} must be an absolute path"
    return "${ERR_SECRET_PATH:-216}"
  fi
  resolved_file="$(realpath "${secret_file}" 2>/dev/null)" || {
    secret_validation_error "${input_class} cannot be resolved"
    return "${ERR_SECRET_PATH:-216}"
  }
  if [[ "${resolved_file}" != "${secret_file}" ]]; then
    secret_validation_error "${input_class} must be canonical and must not traverse symlinked parents"
    return "${ERR_SECRET_PATH:-216}"
  fi
  validate_secret_file "${secret_file}" "${input_class}" || return "${ERR_SECRET_PATH:-216}"
  return 0
 }
 ### Prevents accidental 'unset -f'.
 # shellcheck disable=SC2034
 readonly -f validate_secret_absolute_file
 #######################################
 # Validates an explicitly supported absolute secret directory path.
 # Arguments:
 #   1: directory path
 #   2: input class
 # Returns:
 #   0: on success
 #   ERR_SECRET_PATH: on failure
 #######################################
 validate_secret_absolute_directory() {
  declare directory="$1" input_class="${2:-absolute secret directory}" resolved_directory=""
  if [[ -z "${directory}" || "${directory}" != /* ]]; then
    secret_validation_error "${input_class} must be an absolute path"
    return "${ERR_SECRET_PATH:-216}"
  fi
  resolved_directory="$(realpath "${directory}" 2>/dev/null)" || {
    secret_validation_error "${input_class} cannot be resolved"
    return "${ERR_SECRET_PATH:-216}"
  }
  if [[ "${resolved_directory}" != "${directory}" ]]; then
    secret_validation_error "${input_class} must be canonical and must not traverse symlinked parents"
    return "${ERR_SECRET_PATH:-216}"
  fi
  validate_secret_directory "${directory}" "${input_class}" || return "${ERR_SECRET_PATH:-216}"
  return 0
 }
 ### Prevents accidental 'unset -f'.
 # shellcheck disable=SC2034
 readonly -f validate_secret_absolute_directory
 #######################################
 # Validates a filename-only secret file below the fixed secret root.
 # Globals:
 #   VAR_TMP_SECRET
 # Arguments:
 #   1: filename
 #   2: input class
 #   3: register for redaction
 # Returns:
 #   0: on success
 #   ERR_SECRET_PATH: on failure
 #######################################
 validate_secret_file_in_root() {
  declare filename="$1" input_class="${2:-secret file}" register_value="${3:-true}"
  validate_secret_directory "${VAR_TMP_SECRET}" "secret root" "true" || return "${ERR_SECRET_PATH:-216}"
  validate_secret_filename "${filename}" "${input_class} filename" || return "${ERR_SECRET_PATH:-216}"
  validate_secret_file "${VAR_TMP_SECRET}/${filename}" "${input_class}" "${register_value}" || return "${ERR_SECRET_PATH:-216}"
  return 0
 }
 ### Prevents accidental 'unset -f'.
 # shellcheck disable=SC2034
 readonly -f validate_secret_file_in_root
 #######################################
 # Validates the fixed tmpfs secret staging area and all entries below it.
 # Globals:
 #   VAR_TMP_SECRET
 # Arguments:
 #   1: quiet flag
 # Returns:
 #   0: on success
 #   ERR_SECRET_PATH: on failure
 #######################################
 validate_secret_staging_area() {
  declare quiet="${1:-false}" secret_entries_file="" secret_entry=""
  declare -a secret_entries=()
  validate_secret_directory "${VAR_TMP_SECRET}" "secret root" "true" "${quiet}" || return "${ERR_SECRET_PATH:-216}"
  secret_entries_file="$(mktemp)" || return "${ERR_SECRET_PATH:-216}"
  if ! find "${VAR_TMP_SECRET}" -xdev -mindepth 1 -print0 >| "${secret_entries_file}"; then
    rm -f "${secret_entries_file}"
    secret_validation_error "secret-root enumeration failed" "${quiet}"
    return "${ERR_SECRET_PATH:-216}"
  fi
  mapfile -d '' -t secret_entries < "${secret_entries_file}"
  rm -f "${secret_entries_file}"
  for secret_entry in "${secret_entries[@]}"; do
    if [[ -L "${secret_entry}" ]]; then
      secret_validation_error "symlink below secret root" "${quiet}"
      return "${ERR_SECRET_PATH:-216}"
    elif [[ -d "${secret_entry}" ]]; then
      validate_secret_directory "${secret_entry}" "directory below secret root" "false" "${quiet}" \
        || return "${ERR_SECRET_PATH:-216}"
    elif [[ -f "${secret_entry}" ]]; then
      validate_secret_file "${secret_entry}" "file below secret root" "true" "${quiet}" || return "${ERR_SECRET_PATH:-216}"
    else
      secret_validation_error "non-regular entry below secret root" "${quiet}"
      return "${ERR_SECRET_PATH:-216}"
    fi
  done
  return 0
 }
 ### Prevents accidental 'unset -f'.
 # shellcheck disable=SC2034
 readonly -f validate_secret_staging_area
 # vim: number et ts=2 sw=2 sts=2 ai tw=128 ft=sh
@@ -49,8 +49,6 @@ trap_on_exit() {
    print_scr_exit "${errcode}"
    exit "${errcode}"
  else
    if [[ "${ERRTRAP}" != "true" ]]; then
@@ -63,9 +61,16 @@ trap_on_exit() {
    fi
    exit "${errcode}"
  fi
  if ! sanitize_debug_logs; then
    printf "\e[93m⚠ Final debug-log sanitisation failed; preserving original exit status %s. \e[0m\n" "${errcode}" >&2
    if [[ -n "${LOG_ERROR:-}" && -f "${LOG_ERROR}" && ! -L "${LOG_ERROR}" ]]; then
      printf "⚠ Final debug-log sanitisation failed; original exit status: %s.\n" "${errcode}" >> "${LOG_ERROR}" || true
    fi
  fi
  exit "${errcode}"
 }
 ### Prevents accidental 'unset -f'.
 # shellcheck disable=SC2034
@@ -67,6 +67,10 @@ usage() {
    echo
    echo -e "\e[97m  --build-directory </path/to/build_directory> \e[0m"
    echo "    Where the Debian Live Build Image should be generated. RECOMMENDED path: </opt/cdlb>"
    echo "    The path MUST be canonical and dedicated to the builder; a new directory's canonical parent MUST already exist."
    echo "    New or empty directories receive the"
    echo "    '.ciss-live-builder-owned' marker; populated unmarked directories are rejected. Cleanup is intentionally"
    echo "    destructive only inside the exact validated marker-owned directory."
    echo "    MUST be provided."
    echo
    echo -e "\e[97m  --change-splash <STRING> one of <club | hexagon> \e[0m"
@@ -87,6 +91,7 @@ usage() {
    echo -e "\e[97m  --debug, -d \e[0m"
    echo "    Enables debug logging for the main program routine. Detailed logging information are written to:"
    echo "    </tmp/ciss_live_builder_$$.log>"
    echo "    A final exact-value sanitisation pass is defence in depth and does not replace careful tracing discipline."
    echo
    echo -e "\e[97m  --dhcp-centurion \e[0m"
    echo "    If a DHCP lease is provided, the provider's name server will be overridden and the hardened, privacy-focused "
@@ -108,11 +113,13 @@ usage() {
    echo
    echo -e "\e[97m  --key_age=* \e[0m"
    echo "    The SOPS AGE private keyring for decryption operations. Change '*' to your desired SOPS AGE key file."
    echo "    '*' MUST be a filename only without slashes, '.' or '..' traversal."
    echo "    File MUST be placed in:"
    echo "    </dev/shm/cdlb_secrets>"
    echo
    echo -e "\e[97m  --key_luks=* \e[0m"
    echo "    The LUKS encryption / decryption passphrase for '/'-fs-encryption. Change '*' to your desired passphrase file."
    echo "    '*' MUST be a filename only without slashes, '.' or '..' traversal."
    echo "    File MUST be placed in:"
    echo "    </dev/shm/cdlb_secrets>"
    echo
@@ -162,7 +169,7 @@ usage() {
    echo -e "\e[97m  --root-password-file </dev/shm/cdlb_secrets/password.txt>> \e[0m"
    echo "    Password file for 'root', if given, MUST be a string of 42 to 64 characters."
    echo "    If the argument is omitted, no further login authentication is required for the local console."
-    echo "    MUST be placed in:"
+    echo "    Safe absolute paths remain supported and are validated separately. RECOMMENDED path:"
    echo "    </dev/shm/cdlb_secrets/password.txt>"
    echo
    echo -e "\e[97m  --secure-boot-profile <STRING> one of <debian-shim | ciss-uki> \e[0m"
@@ -178,7 +185,8 @@ usage() {
    echo "    specified via '--signing_key=*'. If the keyring is protected, then provide the passphrase in its own file."
    echo "    Specify the fingerprint of the key to use via '--signing_key_fpr=*'."
    echo "    Optionally import an offline GPG CA signing public key via: '--signing_ca=*'."
-    echo "    Change '*' to your desired files / fingerprint. Files MUST be placed in:"
+    echo "    Change '*' to your desired filename-only files / fingerprint. Filename-only values MUST NOT contain slashes"
    echo "    or traversal. Files MUST be placed in:"
    echo "    </dev/shm/cdlb_secrets>"
    echo
    echo -e "\e[97m  --sops-version <STRING> \e[0m"
@@ -212,6 +220,9 @@ usage() {
    echo
    echo -e "\e[93m💡 Notes: \e[0m"
    echo -e "\e[93m🔵 You MUST be 'root' to run this script. \e[0m"
    echo -e "\e[93m🔵 Private operator control does not remove the requirement for strict local secret path validation. \e[0m"
    echo -e "\e[93m🔵 '/dev/shm/cdlb_secrets' MUST be tmpfs-backed, root-owned, mode 0700, and contain only \e[0m"
    echo -e "\e[93m   single-link regular secret files with mode 0400 or 0600. Secure deletion with shred is best-effort only. \e[0m"
    echo
    echo -e "\e[95m💷 Please consider donating to my work at: \e[0m"
    echo -e "\e[95m🌐 https://coresecret.eu/spenden/ \e[0m"
@@ -0,0 +1,191 @@
 #!/bin/bash
 # SPDX-Version: 3.0
 # SPDX-CreationInfo: 2026-06-11; WEIDNER, Marc S.; <msw@coresecret.dev>
 # SPDX-ExternalRef: GIT https://git.coresecret.dev/msw/CISS.debian.live.builder.git
 # SPDX-FileContributor: WEIDNER, Marc S.; Centurion Intelligence Consulting Agency
 # SPDX-FileCopyrightText: 2024-2026; WEIDNER, Marc S.; <msw@coresecret.dev>
 # SPDX-FileType: SOURCE
 # SPDX-License-Identifier: LicenseRef-CNCL-1.1 OR LicenseRef-CCLA-1.1
 # SPDX-LicenseComment: This file is part of the CISS.debian.installer.secure framework.
 # SPDX-PackageName: CISS.debian.live.builder
 # SPDX-Security-Contact: security@coresecret.eu
 set -Ceuo pipefail
 # shellcheck disable=SC1091,SC2034
 declare TEST_ROOT=""
 declare TEST_TMP=""
 TEST_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 TEST_TMP="$(realpath "$(mktemp -d)")"
 readonly TEST_ROOT TEST_TMP
 declare -r ERR_BUILD_PATH=217
 declare -r ERR_GUARD_SRCE=131
 declare -r ERR_SANITIZING=133
 declare -r ERR_SECRET_PATH=216
 declare -r VAR_WORKDIR="${TEST_ROOT}"
 declare VAR_TMP_SECRET="${TEST_TMP}/secret-root"
 declare LOG_DEBUG=""
 declare LOG_ERROR=""
 declare LOG_VAR=""
 declare VAR_EARLY_DEBUG="false"
 declare ERRTRAP="true"
 cleanup_test() {
  chmod -R u+rwX "${TEST_TMP}" 2>/dev/null || true
  rm -rf "${TEST_TMP}"
 }
 trap cleanup_test EXIT
 guard_sourcing() {
  return 0
 }
 # shellcheck source=../lib/lib_secret_validation.sh
 . "${TEST_ROOT}/lib/lib_secret_validation.sh"
 # shellcheck source=../lib/lib_build_directory.sh
 . "${TEST_ROOT}/lib/lib_build_directory.sh"
 # shellcheck source=../lib/lib_debug_sanitizer.sh
 . "${TEST_ROOT}/lib/lib_debug_sanitizer.sh"
 # shellcheck source=../lib/lib_trap_on_exit.sh
 . "${TEST_ROOT}/lib/lib_trap_on_exit.sh"
 fail() {
  printf 'FAIL: %s\n' "$1" >&2
  exit 1
 }
 expect_failure() {
  declare description="$1"
  shift
  if "$@" >/dev/null 2>&1; then
    fail "${description}"
  fi
 }
 mkdir -m 0700 "${VAR_TMP_SECRET}"
 printf 'safe-private-value\n' > "${VAR_TMP_SECRET}/safe.txt"
 chmod 0400 "${VAR_TMP_SECRET}/safe.txt"
 validate_secret_directory "${VAR_TMP_SECRET}" "test secret root" "false" || fail "safe secret root rejected"
 validate_secret_filename "safe.txt" "test secret filename" || fail "safe secret filename rejected"
 validate_secret_file "${VAR_TMP_SECRET}/safe.txt" "test secret file" || fail "safe secret file rejected"
 validate_secret_absolute_file "${VAR_TMP_SECRET}/safe.txt" "test absolute secret file" \
  || fail "safe absolute secret file rejected"
 expect_failure "relative external secret path accepted" \
  validate_secret_absolute_file "secret-root/safe.txt" "test absolute secret file"
 mkdir -m 0700 "${TEST_TMP}/external-secret-dir"
 printf 'external-private-value\n' > "${TEST_TMP}/external-secret-dir/external.txt"
 chmod 0400 "${TEST_TMP}/external-secret-dir/external.txt"
 ln -s "${TEST_TMP}/external-secret-dir" "${TEST_TMP}/external-secret-dir-link"
 expect_failure "external secret file through a symlinked parent accepted" \
  validate_secret_absolute_file "${TEST_TMP}/external-secret-dir-link/external.txt" "test absolute secret file"
 expect_failure "external secret directory through a symlinked parent accepted" \
  validate_secret_absolute_directory "${TEST_TMP}/external-secret-dir-link" "test absolute secret directory"
 declare secret_root_fs=""
 secret_root_fs="$(secure_stat -f -c '%T' "${VAR_TMP_SECRET}")"
 if [[ "${secret_root_fs}" != "tmpfs" && "${secret_root_fs}" != "ramfs" ]]; then
  expect_failure "persistent secret staging area accepted" validate_secret_staging_area
 fi
 expect_failure "secret filename traversal accepted" validate_secret_filename "../safe.txt" "test secret filename"
 expect_failure "absolute filename-only secret accepted" validate_secret_filename "/tmp/safe.txt" "test secret filename"
 expect_failure "slash in filename-only secret accepted" validate_secret_filename "subdir/safe.txt" "test secret filename"
 ln -s "${VAR_TMP_SECRET}" "${TEST_TMP}/secret-root-link"
 expect_failure "secret-root symlink accepted" \
  validate_secret_directory "${TEST_TMP}/secret-root-link" "test secret root" "false"
 mkdir -m 0700 "${TEST_TMP}/unsafe-secret-root-mode"
 chmod 0755 "${TEST_TMP}/unsafe-secret-root-mode"
 expect_failure "broad secret-root permissions accepted" \
  validate_secret_directory "${TEST_TMP}/unsafe-secret-root-mode" "test secret root" "false"
 ln -s "${VAR_TMP_SECRET}/safe.txt" "${VAR_TMP_SECRET}/unsafe-link"
 expect_failure "secret-file symlink accepted" validate_secret_file "${VAR_TMP_SECRET}/unsafe-link" "test secret file"
 rm "${VAR_TMP_SECRET}/unsafe-link"
 ln "${VAR_TMP_SECRET}/safe.txt" "${VAR_TMP_SECRET}/unsafe-hardlink"
 expect_failure "hardlinked secret file accepted" validate_secret_file "${VAR_TMP_SECRET}/safe.txt" "test secret file"
 rm "${VAR_TMP_SECRET}/unsafe-hardlink"
 declare fake_secret='CISS-CANARY-[exact]-value'
 declare expected_redaction=""
 declare sanitisation_status=0
 printf -v expected_redaction '%*s' "${#fake_secret}" ''
 expected_redaction="${expected_redaction// /*}"
 register_secret_value "${fake_secret}"
 LOG_DEBUG="${TEST_TMP}/debug.log"
 LOG_VAR="${TEST_TMP}/var.log"
 LOG_ERROR="${TEST_TMP}/error.log"
 printf 'before %s after\nunrelated line\n' "${fake_secret}" > "${LOG_DEBUG}"
 printf 'unrelated vars\n' > "${LOG_VAR}"
 printf 'unrelated error\n' > "${LOG_ERROR}"
 chmod 0600 "${LOG_DEBUG}" "${LOG_VAR}" "${LOG_ERROR}"
 sanitize_debug_logs || fail "debug-log sanitisation failed"
 grep -Fq "${fake_secret}" "${LOG_DEBUG}" && fail "debug-log canary remained"
 grep -Fq "${expected_redaction}" "${LOG_DEBUG}" || fail "expected exact-value redaction missing"
 grep -Fq 'unrelated line' "${LOG_DEBUG}" || fail "unrelated debug content changed"
 ln -s "${LOG_DEBUG}" "${TEST_TMP}/unsafe-debug-link"
 (
  LOG_DEBUG="${TEST_TMP}/unsafe-debug-link"
  trap_on_exit 73 "test" 1 "test" "false"
 ) 2>/dev/null || sanitisation_status=$?
 [[ ${sanitisation_status} -eq 73 ]] || fail "sanitisation failure masked the original exit status"
 expect_failure "empty build-directory path accepted" validate_build_directory_path ""
 expect_failure "root build-directory path accepted" validate_build_directory_path "/"
 expect_failure "broad parent build-directory path accepted" validate_build_directory_path "/tmp"
 expect_failure "secret root accepted as build directory" validate_build_directory_path "${VAR_TMP_SECRET}"
 mkdir -m 0700 "${VAR_TMP_SECRET}/unsafe-build-child"
 expect_failure "secret-root descendant accepted as build directory" \
  validate_build_directory_path "${VAR_TMP_SECRET}/unsafe-build-child"
 mkdir -m 0700 "${TEST_TMP}/unmarked"
 expect_failure "build directory without marker accepted" validate_build_directory_marker "${TEST_TMP}/unmarked"
 printf 'do-not-adopt\n' > "${TEST_TMP}/unmarked/content"
 expect_failure "non-empty unmarked build directory adopted" initialize_build_directory "${TEST_TMP}/unmarked" unsafe_result
 mkdir -m 0700 "${TEST_TMP}/unsafe-build-mode"
 chmod 0777 "${TEST_TMP}/unsafe-build-mode"
 expect_failure "unsafe build-directory permissions accepted" \
  initialize_build_directory "${TEST_TMP}/unsafe-build-mode" unsafe_result
 mkdir -m 0700 "${TEST_TMP}/marker-link-dir"
 printf '%s\n' "${TEST_TMP}/marker-link-dir" > "${TEST_TMP}/marker-target"
 chmod 0400 "${TEST_TMP}/marker-target"
 ln -s "${TEST_TMP}/marker-target" "${TEST_TMP}/marker-link-dir/.ciss-live-builder-owned"
 expect_failure "symlinked builder-owned marker accepted" validate_build_directory_marker "${TEST_TMP}/marker-link-dir"
 mkdir -m 0700 "${TEST_TMP}/marker-hardlink-dir"
 printf '%s\n' "${TEST_TMP}/marker-hardlink-dir" > "${TEST_TMP}/marker-hardlink-target"
 chmod 0400 "${TEST_TMP}/marker-hardlink-target"
 ln "${TEST_TMP}/marker-hardlink-target" "${TEST_TMP}/marker-hardlink-dir/.ciss-live-builder-owned"
 expect_failure "hardlinked builder-owned marker accepted" validate_build_directory_marker "${TEST_TMP}/marker-hardlink-dir"
 mkdir -m 0700 "${TEST_TMP}/marker-extra-content-dir"
 printf '%s\nunexpected\n' "${TEST_TMP}/marker-extra-content-dir" \
  > "${TEST_TMP}/marker-extra-content-dir/.ciss-live-builder-owned"
 chmod 0400 "${TEST_TMP}/marker-extra-content-dir/.ciss-live-builder-owned"
 expect_failure "builder-owned marker with extra content accepted" \
  validate_build_directory_marker "${TEST_TMP}/marker-extra-content-dir"
 ln -s "${TEST_TMP}/unmarked" "${TEST_TMP}/build-link"
 expect_failure "build-directory symlink accepted" validate_build_directory_path "${TEST_TMP}/build-link"
 declare validated_build_dir=""
 initialize_build_directory "${TEST_TMP}/owned-build" validated_build_dir || fail "safe builder-owned directory rejected"
 validate_build_directory_marker "${validated_build_dir}" || fail "builder marker rejected"
 mkdir "${validated_build_dir}/subdir"
 printf 'remove me\n' > "${validated_build_dir}/artifact"
 printf 'remove me too\n' > "${validated_build_dir}/.hidden-artifact"
 printf 'nested\n' > "${validated_build_dir}/subdir/nested"
 clean_build_directory_contents "${validated_build_dir}" || fail "safe builder-owned cleanup failed"
 validate_build_directory_marker "${validated_build_dir}" || fail "builder marker removed by cleanup"
 [[ -z "$(find "${validated_build_dir}" -mindepth 1 ! -name '.ciss-live-builder-owned' -print -quit)" ]] \
  || fail "builder-owned cleanup left unexpected content"
 mkdir -m 0700 "${TEST_TMP}/outside-build"
 mkdir "${TEST_TMP}/outside-build/includes.chroot"
 ln -s "${TEST_TMP}/outside-build" "${validated_build_dir}/config"
 expect_failure "cleanup subpath through a symlinked parent accepted" \
  validate_build_directory_subpath "${validated_build_dir}" "config/includes.chroot" unsafe_subpath
 printf 'PASS: secret validation, debug sanitisation, and build cleanup guards\n'
@@ -28,6 +28,7 @@ touch "${LOG_ERROR}" && chmod 0600 "${LOG_ERROR}"
 declare -g  __umask=""
 declare -g  VAR_ARCHITECTURE=""
 declare -g  VAR_ARG_SANITIZED=""
 declare -g  VAR_DROPBEAR_VERSION="2026.91"
 declare -g  VAR_HANDLER_BUILD_DIR=""
 declare -g  VAR_HANDLER_CDI="false"
@@ -91,6 +92,8 @@ declare -gir ERR__SSH__PORT=212 # --ssh-port MUST be an integer between '1' and
 declare -gir ERR_ARG_MSMTCH=213 # Wrong Number of optional Arguments provided
 declare -gir ERR_DROPBEAR_V=214 # --dropbear-version MUST match the bundled Dropbear tarball version format
 declare -gir ERR__SOPS__VER=215 # --sops-version MUST match the upstream SOPS semantic version format
 declare -gir ERR_SECRET_PATH=216 # Unsafe secret root, filename, or file.
 declare -gir ERR_BUILD_PATH=217 # Unsafe build-directory path or marker.
 declare -gir ERR_SECRETSSYM=251 # VAR_TMP_SECRET is a symlink.
 declare -gir ERR_NOTABSPATH=252 # Not an absolute path
 declare -gir ERR_INVLD_CHAR=253 # Invalid Character
Author	SHA256	Message	Date
ahz	85ff080b40	V9.14.022.2026.06.11: document and test audit safeguards	2026-06-11 05:08:18 +02:00
ahz	9d3f283297	V9.14.022.2026.06.11: enforce secret and cleanup safeguards	2026-06-11 05:08:01 +02:00
ahz	74897d85b1	V9.14.022.2026.06.11: add path security helpers	2026-06-11 05:07:33 +02:00