CISS.debian.installer/func/cdi_4000_debootstrap/README/README_4000.md

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