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