V8.00.000.2025.06.17

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

func/cdi_4000_debootstrap/README/README_4000.md

@@ -0,0 +1,101 @@
+---
+gitea: none
+include_toc: true
+---
+
+# 1. CISS.debian.installer
+
+**Centurion Intelligence Consulting Agency Information Security Standard**<br>
+*The CISS Debian Installer provides a fully automated and hardened installation process.*<br>
+**Master Version**: 8.00<br>
+**Build**: V8.00.000.2025.06.17<br>
+
+# 2. [4000_debootstrap.sh](../4000_debootstrap.sh)
+This module provisions a minimal Debian userspace into the installers target root (`$TARGET`) using `debootstrap`.
+It encapsulates argument construction, execution, logging, and the controlled hand-off of the `/debootstrap` working tree into a
+private, permissions-hardened folder under `root/.ciss/cdi/`.
+
+## 2.1. Responsibilities
+- Resolve architecture, distribution codename, mirror, and optionally include-set from the global environment.
+- Execute `debootstrap` with deterministic flags (`--keep-debootstrap-dir`, `--log-extra-deps`, `--merged-usr`) and optional `--include=`.
+- Stream all `debootstrap` output to a dedicated log (`$LOG_DBS`) for reproducibility and forensics.
+- Post-provisioning: create a sealed directory hierarchy beneath `$TARGET/root/.ciss/cdi/` and relocate the working directory 
+  from `$TARGET/debootstrap` to `$TARGET/root/.ciss/cdi/debootstrap`.
+- Emit structured progress diagnostics via the common logging facility.
+- Return a specific non-zero error code on failure to enable consistent trap-level handling.
+
+## 2.2. Inputs & Globals
+- **`$VAR_ARCHITECTURE`** — target architecture (e.g., `amd64`, `arm64`).
+- **`$VAR_CODENAME`** — Debian release codename (e.g., `trixie`).
+- **`$debootstrap_mirror`** — HTTP/HTTPS mirror base URL.
+- **`$debootstrap_includes`** — comma-separated package list to seed into the base system (optional).
+- **`$TARGET`** — absolute mount path of the target root filesystem.
+- **`$LOG_DBS`** — file path to receive `debootstrap` combined output via `tee`.
+- **`ERR_DEBOOTSTRAP`** — module-specific error code for uniform failure signaling.
+
+> All variables are expected to be pre-validated and exported by the installer setup/bootstrap chain.
+
+## 2.3. Execution Flow
+* **Command assembly**
+  - Build `ary_cmd` as:
+    ```
+    debootstrap \
+      --arch="${VAR_ARCHITECTURE}" \
+      --keep-debootstrap-dir \
+      --log-extra-deps \
+      --merged-usr \
+      [--include="${debootstrap_includes}"] \
+      "${VAR_CODENAME}" "${TARGET}" "${debootstrap_mirror}"
+    ```
+  - Emit a debug log line with the fully materialized command.
+
+* **Run & log**
+  - Execute the array-form command; pipe stdout/stderr to `$LOG_DBS` using `tee`.
+  - On success, emit an informational log entry; on failure, emit an emergency log and `return ${ERR_DEBOOTSTRAP}`.
+
+* **Post-provisioning layout (on success)**
+  - Create (mode `0700`, owned by `root:root`) under `$TARGET/root/.ciss/cdi/`:
+    - `backup/`, `debootstrap/`, `hooks/`, `keys/`, `log/`
+  - Move the working directory:
+    - `mv -T "$TARGET/debootstrap" "$TARGET/root/.ciss/cdi/debootstrap"`
+  - Reassert restrictive permissions on `.ciss/`, `.ciss/cdi/`, and `.ciss/cdi/debootstrap/`.
+  - Invoke `guard_dir` (module guard) and return `0`.
+
+## 2.4. Design Paradigms
+- **Array-based invocation**: Prevents word-splitting and globbing pitfalls; arguments are passed verbatim to `execve`.
+- **Deterministic defaults**:
+  - `--merged-usr`: aligns the base system with usrmerge conventions (Debian ≥ 12).
+  - `--keep-debootstrap-dir`: preserves provenance and the exact state of the bootstrap transaction.
+  - `--log-extra-deps`: surfaces additional dependency resolution in logs for auditability.
+- **Fail-fast and traceable**: Execution is meant to run under global hardening (`set -Ceuo pipefail`, `inherit_errexit`) and 
+  integrates with the installer trap/debug framework; logs are persisted for triage.
+
+## 2.5. Security Considerations
+- **Least exposure of artifacts**: The bootstrap working directory is relocated into a sealed, root-only area (`0700`).
+  This avoids exposing transient metadata under world-readable paths.
+- **No shell expansion in command string**: Array execution and explicit variables reduce injection risk and ambiguity.
+- **Privilege hygiene**: Directory creation and moves are executed with explicit ownership/mode; no reliance on ambient umask.
+- **Provenance retention**: Keeping the original `debootstrap` directory (under a protected path) allows later verification of
+  package selection, scripts, and logs.
+
+## 2.6. Logging & Artifacts
+- **Primary log**: `${LOG_DBS}` receives the raw `debootstrap` stream (via `tee`).
+- **Provenance**: `${TARGET}/root/.ciss/cdi/debootstrap/` contains the retained working directory after a successful run.
+- **Installer meta-folders**: `${TARGET}/root/.ciss/cdi/{backup,debootstrap,hooks,keys,log}/` (all `0700`).
+
+These artifacts integrate with the global debug facilities when enabled.
+
+## 2.7. Failure Modes & Exit Codes
+- **Network or mirror failure** → non-zero `debootstrap` exit → module returns `ERR_DEBOOTSTRAP`.
+- **Invalid codename/arch** → early `debootstrap` abort → `ERR_DEBOOTSTRAP`.
+- **Insufficient permissions or target not writable** → directory creation/move fails → `ERR_DEBOOTSTRAP`.
+
+Errors are surfaced to the installers `ERR`/`EXIT` traps, which will record environment, stack, and runtime context.
+
+## 2.8. Best Practices
+- Use `--include` judiciously; keep the base system minimal and defer optional packages to dedicated post-bootstrap tasks.
+- Treat `${TARGET}/root/.ciss/cdi/` as sensitive metadata: back it up or snapshot it if you require later audits.
+
+---
+**[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 -->