V8.00.000.2025.06.17

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

docs/man/DEBUG_HANDLING.md

@@ -0,0 +1,147 @@
+---
+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. Debugging and Tracing Infrastructure
+
+## 2.1. Overview
+
+This document provides a detailed exposition of the debug and tracing modules of the `CISS.debian.installer`. These facilities
+offer a comprehensive introspection framework designed to assist developers and integrators in identifying defects, verifying 
+execution paths, and auditing variable state transitions. Debugging may be enabled via `--debug [xtrace|trap]`, and generates 
+structured logs with full environmental metadata and deterministic command evaluation snapshots.
+
+
+## 2.2. Component Modules
+
+### 2.2.1 [0050_debug_pre_scan.sh](../../lib/0050_debug_pre_scan.sh)
+
+**Purpose**: Parses the script's argument vector (`$@`) to detect and initialize debug mode before the main installer logic 
+executes.
+
+- Accepts flags:
+  - `-d xtrace` → Enables `set -x` tracing to a file.
+  - `-d trap`   → Enables `trap DEBUG` command evaluation logging.
+- Initializes `LOG_VAR`, secures it (`chmod 0600`) and triggers the initial variable dump via `dump_vars_initial()`.
+- Performs strict validation on the argument format (at most two debug flags; none may be empty).
+- Explicitly sets the necessary global flags: `VAR_DEBUG_TRACE` and/or `VAR_DEBUG_TRAP`.
+
+
+### 2.2.2. [0051_debug_var_dump.sh](../../lib/0051_debug_var_dump.sh)
+
+**Functions**:
+- `dump_vars_initial()`: Captures the initial state of all non-internal variables.
+- `dump_vars_exiting()`: Captures the final state and performs a differential comparison.
+
+**Purpose**:
+- Stores snapshots of the Bash environment at entry and exit points.
+- Filters out shell internals via regex (`^(BASH|_).*`).
+- Produces a normalized `comm`-based diff showing added and removed variables.
+- Appends structured logs to `LOG_VAR`.
+
+**Security Considerations**:
+- Operates with `set +x` to avoid leaking secrets to stdout.
+- Temporary files are created with `mktemp` and removed after usage.
+
+### 2.2.3. [0052_debug_trace.sh](../../lib/0052_debug_trace.sh)
+
+**Purpose**: Initializes Bash's `xtrace` (`set -x`) with rich metadata formatting and redirects output to `LOG_TRC`.
+
+**Features**:
+- Sets `PS4` to a custom format including:
+  - UTC timestamp
+  - Source filename and line number
+  - Exit status of the preceding command
+  - Calling function context
+- Opens file descriptor `42` as an isolated stream for trace output.
+- Utilizes `BASH_XTRACEFD` to redirect debug output cleanly.
+- Appends a structured log header via `debug_trace_header()`.
+
+**Best Practice**:
+- Serves as a non-interfering, shell-native audit mechanism.
+- Avoid collision with terminal output or stderr logging.
+
+### 2.2.4. [0053_debug_trace_header.sh](../../lib/0053_debug_trace_header.sh)
+
+**Purpose**: Prints an extensive contextual header to `LOG_TRC`, including:
+
+- Script version, Git commit, timestamp (`EPOCHREALTIME`)
+- Bash version matrix (MAJ, MIN, PATCH, RELEASE)
+- Host metadata (hostname, UID/EUID, system info)
+- Shell environment (`BASHOPTS`, `SHELLOPTS`, `$-`)
+- Full command-line argument string and process IDs
+
+This header facilitates offline analysis and correlates script execution to external events or CI/CD timelines.
+
+### 2.2.5. [0054_debug_trap.sh](../../lib/0054_debug_trap.sh)
+
+**Purpose**: Implements runtime-level command introspection using the `DEBUG` trap.
+
+#### `initialize_debug_trap()`
+- Sets up `LOG_DBG` and its metadata header via `debug_trap_header()`.
+- Defines redaction patterns in a `MASK_PATTERNS` associative array:
+  - Keywords like `password`, `token`, `API_KEY`, etc., are obfuscated.
+
+#### `debug_trap()`
+- Captures and logs every evaluated command via `VAR_LAST_CMD`.
+- Applies masking rules to commands that contain sensitive data.
+- Skips `set -x/+x` shell internals to avoid log pollution.
+- Delegates logging to `debug_trap_logger()` once the command has executed.
+
+**Security Paradigm**:
+- Designed to be safely enabled in production with obfuscation of credentials and secrets.
+- Provides a temporal correlation of command execution and exit codes.
+
+### 2.2.6. [0055_debug_trap_header.sh](../../lib/0055_debug_trap_header.sh)
+
+**Purpose**: Similar to `debug_trace_header()`, this module prints an elaborate preamble into the `LOG_DBG` file.
+
+- All environmental metadata is captured at script entry.
+- Enables forensic traceability by recording:
+  - User context
+  - Runtime invocation parameters
+  - Script identity and parent PID
+  - Directory of execution and active shell options
+
+## 2.3. Usage
+
+To enable debugging, invoke the script as follows:
+
+```bash
+./setup.sh --debug trap
+./setup.sh --debug xtrace
+./setup.sh --debug trap xtrace
+````
+
+This generates the following artifacts under ${DIR_LOG}:
+
+- ciss_debian_installer_<PID>_var.log: Variable state diff.
+- ciss_debian_installer_<PID>_trace.log: set -x trace log.
+- ciss_debian_installer_<PID>_debug.log: trap DEBUG log.
+
+## 2.4. Design Philosophy and Best Practices
+
+- **Orthogonality**: Debugging mechanisms do not interfere with normal I/O or runtime behavior.
+- **Determinism**: Logs are timestamped, redacted, and structured to facilitate automation and review.
+- **Security-First Logging**: Masking of credentials is strictly enforced to prevent secret leakage.
+- **Granularity**: Users can enable trap-level tracing, shell-level tracing, or both.
+- **Idempotence**: Initialization routines are guarded to prevent multiple activations or log clobbering.
+
+## 2.5. Conclusion
+
+The debug and tracing subsystem of the **CISS.debian.installer** is a high-fidelity introspection facility tailored to secure 
+automation. It enables precise, controlled observability without compromising operational integrity or leaking sensitive 
+information. As such, it is ideally suited to both development and hardened deployment scenarios.
+
+---
+**[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 -->