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

Table of Contents

• 1. CISS.debian.installer
• 2. 4000_debootstrap.sh
• 2.1. Responsibilities
• 2.2. Inputs & Globals
• 2.3. Execution Flow
• 2.4. Design Paradigms
• 2.5. Security Considerations
• 2.6. Logging & Artifacts
• 2.7. Failure Modes & Exit Codes
• 2.8. Best Practices

1. CISS.debian.installer

Centurion Intelligence Consulting Agency Information Security Standard
The CISS Debian Installer provides a fully automated and hardened installation process.
Master Version: 8.00
Build: V8.00.000.2025.06.17

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