CISS.debian.installer/docs/man/ERROR_HANDLING.md

Table of Contents

• 1. CISS.debian.installer
• 2. Global Environment and Error Handling in CISS.debian.installer
• 2.1. Overview
• 2.2. bash.var.sh
• 2.2.1. Purpose
• 2.2.2. Execution Settings
• 2.2.2.1. set Options
• 2.2.2.2. shopt Options
• 2.2.2.3. Environment Variables
• 2.2.3 Security Considerations
• 2.2.4. Paradigm
• 2.3. 0060_trap_err.sh
• 2.3.1. Purpose
• 2.3.2. Key Functionalities
• 2.3.3. Design Considerations
• 2.4. 0070_trap_exit.sh
• 2.4.1. Purpose
• 2.4.2. Behavior Summary
• 2.4.2.1. trap_exit_zero()
• 2.4.2.2. trap_exit_non_zero()
• 2.4.3 Integration Notes
• 2.5. 0080_trap_int.sh
• 2.5.1. Purpose
• 2.5.2. Core Mechanism
• 2.5.2.1. trap_int()
• 2.5.2.2. restart_dialog()
• 2.5.3. Security and UX Considerations
• 2.6. Security and Best Practices
• 2.7. Summary

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

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

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

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

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