CISS.debian.installer/var/README/README_BASH_VAR.md

---
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. [bash.var.sh](../bash.var.sh)
This module establishes the global execution profile for all modules of the `CISS.debian.installer`. It is sourced at the very 
beginning of the installer lifecycle to impose strict, deterministic shell semantics, to minimize ambiguity in expansions, and 
to reduce the attack surface inherent to shell scripting. The profile complements the project-wide trap and debugging
infrastructure and applies uniformly to subshells and functions.

## 2.1. Scope and Guarantees
- Enforces fail-fast error semantics across functions and subshells.
- Normalizes filename expansion and word-splitting to safe defaults.
- Constrains the effective runtime search path (`PATH`) to trusted system locations.
- Establishes a conservative file creation policy (`umask 0022`).
- Avoids reliance on interactive shell artifacts (aliases, dotglob, nullglob).
- Ensures consistent behaviour for pipelines and command substitutions.

## 2.2. Execution Settings (`set -o ...`)

| Option      | Effect (Rationale)                                                                                     |
|-------------|--------------------------------------------------------------------------------------------------------|
| `errexit`   | Abort on any non-zero exit status. Prevents silent continuation after failed steps.                    |
| `errtrace`  | Inherit `ERR` traps in functions/subshells. Ensures uniform error handling depth-wise.                 |
| `functrace` | Inherit `DEBUG`/`RETURN` traps. Enables deep stack and step tracing when debug facilities are enabled. |
| `ignoreeof` | Suppress accidental exit on `EOF` (Ctrl-D) in interactive contexts.                                    |
| `noclobber` | Disallow redirections from overwriting existing files. Reduces risk of destructive writes.             |
| `nounset`   | Treat use of unset variables as fatal. Surfaces programming defects immediately.                       |
| `pipefail`  | Pipeline returns the first non-zero exit code. Eliminates false positives in multi-stage pipelines.    |

> These options are intended to run in concert; changing one (e.g., disabling `nounset`) undermines the overall guarantee set.

## 2.3. Bash Operational Settings (`shopt ...`)

| Option            | State | Effect (Rationale)                                                                                                 |
|-------------------|-------|--------------------------------------------------------------------------------------------------------------------|
| `failglob`        | `on`  | Globs that match nothing raise an error instead of passing a literal. Prevents unintended mass operations.         |
| `inherit_errexit` | `on`  | Preserves `errexit` in command substitutions. Prevents subshells from masking failures.                            |
| `lastpipe`        | `on`  | When job control is off, the last pipeline command runs in the current shell. Allows variable assignment in place. |
| `expand_aliases`  | `off` | Disables alias expansion in non-interactive execution. Ensures parse-time predictability.                          |
| `dotglob`         | `off` | Excludes dotfiles from globbing unless explicitly requested. Reduces accidental inclusion of hidden state.         |
| `extglob`         | `off` | Disables extended pattern operators by default. Avoids syntactic ambiguity; enable locally if strictly required.   |
| `nullglob`        | `off` | Non-matching globs do not vanish to empty strings. Preserves error signalling pathways.                            |


## 2.4. Environment Normalisation

- **`PATH`** `/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin` Restricts execution to canonical system directories 
  and avoids user-writable or ephemeral locations.
- **`IFS`**  `space, tab, newline` Resets the internal field separator to the safe triplet, mitigating word-splitting injections
  and parsing anomalies.
- **`umask`** `0022` Files are world-readable by default but only owner-writable; directories are owner-writable/executable.
  This aligns with conservative system defaults while avoiding accidental over-permission.

## 2.5. Design Paradigms
- **Deterministic failure**: The profile is built around immediate error surfacing and uniform propagation into traps and 
  subshells.
- **Minimal ambient state**: Aliases and risky globbing behaviors are disabled to reduce hidden semantics and side effects.
- **Explicitness first**: Module code is expected to prefer explicit redirections, explicit globbing, and explicit function 
  variable declarations (`declare`, `declare -g` for globals).
- **Composability**: Settings are chosen to interoperate cleanly with the installers `ERR`, `EXIT`, `INT`, and optional
  `DEBUG` `XTRACE` subsystems.

## 2.6. Interaction with TRAP/DEBUG Subsystem (Brief)

- `errtrace` and `functrace` ensure that `ERR` and `DEBUG` handlers fire consistently in nested contexts, enabling accurate 
  stack and command logging.
- `nounset` guarantees that unbound variable faults propagate as hard failures, which are then recorded by the `EXIT` trap 
  (covering cases not seen by `ERR`).
- `pipefail` produces truthful failure points for `ERR` to capture in multi-stage pipelines.

## 2.7. Security Considerations

- **Search path integrity**: A reduced, fixed `PATH` avoids resolving executables from untrusted paths (e.g., pwd, temp).
- **Write-safety**: `noclobber` and a conservative `umask` reduce both accidental and adversarial overwrites.
- **Predictable expansion**: `failglob`, `dotglob`, and `nullglob` settings ensure globs behave loudly on errors and never 
  silently widen or narrow scope.
- **Secret hygiene**: In combination with the debug modules, sensitive data is not exposed through uncontrolled expansions or
  unset variables.

## 2.8. Best Practices
- **Scope deviations locally**: If a module must enable `extglob` or relax an option, do so in the narrowest possible lexical 
  scope and restore the default immediately afterward.
- **Avoid reliance on aliases**: Prefer explicit functions or scripts with fully qualified paths.
- **Validate assumptions**: When using pipelines or command substitutions, assume `pipefail`/`inherit_errexit` semantics and 
  handle errors accordingly.
- **Pair with traps**: Always run under the project trap handlers to obtain structured diagnostics on failure.

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