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

Table of Contents

• 1. CISS.debian.installer
• 2. Debugging and Tracing Infrastructure
• 2.1. Overview
• 2.2. Component Modules
• 2.2.1 0050_debug_pre_scan.sh
• 2.2.2. 0051_debug_var_dump.sh
• 2.2.3. 0052_debug_trace.sh
• 2.2.4. 0053_debug_trace_header.sh
• 2.2.5. 0054_debug_trap.sh
• initialize_debug_trap()
• debug_trap()
• 2.2.6. 0055_debug_trap_header.sh
• 2.3. Usage
• 2.4. Design Philosophy and Best Practices
• 2.5. Conclusion

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

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

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

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

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

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

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:

./setup.sh --debug trap
./setup.sh --debug xtrace
./setup.sh --debug trap xtrace

This generates the following artifacts under ${DIR_LOG}:

• ciss_debian_installer__var.log: Variable state diff.
• ciss_debian_installer__trace.log: set -x trace log.
• ciss_debian_installer__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