---
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. Global Environment and Error Handling in CISS.debian.installer

## 2.1. Overview

This document outlines the core mechanisms responsible for global Bash environment configuration, error trapping, signal 
handling, and structured diagnostics in the `CISS.debian.installer`. These foundational components ensure that the installer 
operates in a predictable, robust, and audit-friendly manner, even under adverse conditions.

## 2.2. [bash.var.sh](../../var/bash.var.sh)

### 2.2.1. Purpose

Defines the global shell behavior and enforces rigorous execution semantics. This file is sourced early in the setup pipeline 
and governs how the shell reacts to unexpected states, variable misuses, and subshell propagation.

### 2.2.2. Execution Settings

The following Bash options are set to enforce secure and fail-fast behavior:

#### 2.2.2.1. `set` Options

| Option             | Purpose                                                                                                      |
|--------------------|--------------------------------------------------------------------------------------------------------------|
| `errexit` (`-e`)   | Immediately exits the script if any command returns a non-zero status. Prevents silent failure continuation. |
| `errtrace` (`-E`)  | Ensures that `ERR` traps are inherited by functions and subshells, maintaining error-handling consistency.   |
| `functrace` (`-T`) | Ensures that `DEBUG` and `RETURN` traps are inherited, enabling full-stack debug tracing.                    |
| `ignoreeof`        | Prevents accidental shell termination from a stray `EOF` (Ctrl-D) in interactive sessions.                   |
| `noclobber` (`-C`) | Prohibits overwriting existing files via output redirection, mitigating destructive accidents.               |
| `nounset` (`-u`)   | Treats use of undefined variables as fatal errors, preventing unpredictable logic paths.                     |
| `pipefail`         | Returns the exit status of the first failed command in a pipeline, avoiding false-positive success states.   |

#### 2.2.2.2. `shopt` Options

| Option            | State | Purpose                                                                                                                    |
|-------------------|-------|----------------------------------------------------------------------------------------------------------------------------|
| `failglob`        | `on`  | Causes filename expansion to fail if no matches are found, avoiding unintended literal pattern usage.                      |
| `inherit_errexit` | `on`  | Preserves `errexit` behaviour inside command substitutions, ensuring subshells do not mask failures.                       |
| `lastpipe`        | `on`  | Runs the last command in a pipeline in the current shell (non-job-control mode), preserving variables set in that command. |
| `expand_aliases`  | `off` | Disables alias expansion in non-interactive mode to maintain predictable parsing and avoid hidden behaviours.              |
| `dotglob`         | `off` | Prevents inclusion of dotfiles in filename expansion unless explicitly requested, avoiding unintentional file processing.  |
| `extglob`         | `off` | Disables extended pattern matching by default, reducing syntactic ambiguity unless explicitly enabled.                     |
| `nullglob`        | `off` | Prevents non-matching globs from expanding to empty strings, preserving error signalling.                                  |

#### 2.2.2.3. Environment Variables

* **`PATH`** Explicitly set to a minimal, trusted search path: ``/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin``
  This minimizes the risk of executing binaries from untrusted directories.
* **`IFS`** Reset to the canonical safe value for whitespace splitting. This mitigates word-splitting injection vulnerabilities.
* **`umask 0022`** Ensures newly created files are world-readable but only writable by their owner. This is a conservative 
  default that prevents accidental creation of files with overly permissive access rights.

### 2.2.3 Security Considerations

- **Fail-fast principle**: By combining `set -Ceuo pipefail` with strict `shopt` rules, unexpected runtime states result in 
  immediate termination and diagnostic reporting.
- **Predictability**: Disabled features (such as `extglob`, `expand_aliases`) prevent accidental reliance on non-portable or 
  side-effect-prone shell behavior.
- **Isolation**: A fixed `PATH` ensures that only known system binaries are invoked, neutralizing the risk of executing 
  malicious binaries from user-writable directories.
- **Consistency across contexts**: `inherit_errexit` ensures subshell and function calls do not silently bypass global error policy.

### 2.2.4. Paradigm

All scripts and modules in the **CISS.debian.installer** framework operate under the principle of deterministic failure and 
exhaustive state introspection. The defined options anticipate and actively prevent common scripting failures due to overlooked 
conditions or shell misbehavior.

## 2.3. [0060_trap_err.sh](../../lib/cdi_0060_traps/0060_trap_err.sh)

### 2.3.1. Purpose

Implements the `trap_err()` handler invoked automatically upon any uncaught error (`ERR`). It is designed to distinguish runtime
anomalies precisely, log them comprehensively, and expose them to the console and log system.

### 2.3.2. Key Functionalities

- Captures the failing command, line number, function, and script context.
- Records full environmental metadata: UID, EUID, hostname, Git commit, resource state, and Bash version information.
- Generates separate diagnostic artifacts:
  - `LOG_ERR` for the error summary,
  - `LOG_DBG` and `LOG_TRC` for verbose debug/trace logs (conditionally),
  - `LOG_VAR` for the differential variable dump (if debugging is enabled).
- Provides structured output both to file and to `stderr`, with color coding for visual inspection.
- Outputs a stack trace via `print_stacktrace()` for post-mortem debugging.

### 2.3.3. Design Considerations

- The function uses `trap - DEBUG ERR INT TERM` to prevent a reentrant trap firing during the error handler itself.
- Integrates gracefully with dialog-driven user interfaces (e.g., `dialog_box_cleaner`, `dialog_gauge_cleaner`).
- Evaluates `VAR_DEBUG_TRACE` and `VAR_DEBUG_TRAP` to determine the scope of runtime introspection.

## 2.4. [0070_trap_exit.sh](../../lib/cdi_0060_traps/0070_trap_exit.sh)

### 2.4.1. Purpose

Defines `trap_exit()`, a comprehensive exit handler for any script termination—whether normal (`exit 0`) or due to a fatal 
error. Notably, it complements `trap_err()` by catching unbound variable errors that bypass `ERR`.

### 2.4.2. Behavior Summary

#### 2.4.2.1. `trap_exit_zero()`
- Triggered upon a successful script exit.
- Logs positive confirmation including runtime and debug log paths if available.
- Initiate cleanup routines.
- Outputs user guidance and donation links (non-critical aesthetic footer).

#### 2.4.2.2. `trap_exit_non_zero()`
- Triggered upon abnormal termination where `ERRTRAP` is not set, e.g., due to an unbound variable.
- Captures a broad spectrum of diagnostic data similar to `trap_err()`.
- Ensures that the cause (such as an unset variable) is clearly hinted.
- Invokes final cleanup and prints the complete diagnostic suite with full metadata.

### 2.4.3 Integration Notes

- Cleans up dialog UIs on abnormal exit.
- Isolates early trap context via local read-only declarations to avoid overwriting.
- Ensures that debug logs and variable states are flushed before exit.

## 2.5. [0080_trap_int.sh](../../lib/cdi_0060_traps/0080_trap_int.sh)

### 2.5.1. Purpose

Provides signal handling for `SIGINT` (Ctrl+C), with a dialog-safe mechanism that prevents unintended termination. This is 
crucial for headless or semi-automated deployments with interactive components.

### 2.5.2. Core Mechanism

#### 2.5.2.1. `trap_int()`
- Captures `INT` signals.
- Pauses for user confirmation (timeout after 16 seconds).
- Either gracefully aborts or resumes the script, depending on user input or timeout.
- Integrates with the dialog subsystem, cleaning UI artifacts prior to action.

#### 2.5.2.2. `restart_dialog()`
- Reinitialized the dialog interface after an interrupted run if the user chooses to continue.
- Restores traps post-resumption to ensure robustness.

### 2.5.3. Security and UX Considerations

- Prevents accidental termination of long-running installations.
- Avoids data corruption due to mid-script interrupts.
- Enhances user control without compromising automation logic.

## 2.6. Security and Best Practices

- **Immutable trap guards:** Traps are explicitly unset before being reassigned to ensure deterministic behavior and prevent recursive invocation.
- **Subshell inheritance:** Use of `errtrace` and `functrace` ensures traceability even in nested scripts or background processes.
- **Fail-fast philosophy:** The combination of `set -Ceuo pipefail` with trap integration guarantees that misconfigurations or runtime anomalies are never silently ignored.
- **Interactive safety net:** Signal handling introduces it a user-verifiable fail-safe for recovery or re-entry.

## 2.7. Summary

These core components of the `CISS.debian.installer` provide a robust, secure, and transparent execution environment. The Bash 
environment is tightly constrained to fail predictably and verbosely, while the trap handlers furnish a rich diagnostic 
infrastructure, indispensable for debugging and secure automation. Signal interception and dialog integration round off a 
cohesive control architecture, ensuring resilience in interactive and automated deployments alike.

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