CISS.debian.installer/func/cdi_1000_helper/README/README_1080.md

Table of Contents

• 1. CISS.debian.installer
• 2. 1080_helper_chroot.sh
• 2.1. When to use what
• 2.2. Design rationale
• 2.2.1. chroot_exec() — argv purity, preflight, the least overhead
• 2.2.2. chroot_script() — controlled shell, explicit -c
• 2.2.3 chroot_stdin() — robust multi-line scripts via bash -s
• 2.3. Common foundation across all helpers
• 2.4. Decision guide
• 2.5. Subtleties and gotchas (and how the helpers address them)
• 2.6. Antipatterns (what to avoid)
• 3. Appendix — Helper signatures & guarantees

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. 1080_helper_chroot.sh

Scope: This note explains what to use when among

• chroot_exec(),
• chroot_script(), and
• chroot_stdin().

2.1. When to use what

• chroot_exec (target, argv...) — Simple, argv-style commands.
  Use it whenever you type a short command with discrete arguments (no shell features).
  Examples from the updated user provisioning flow: getent, groupadd, useradd, usermod, chsh.

• chroot_script (target, "shell pipeline | redir && control-flow") — Anything that needs a shell.
  Use it for pipelines, redirections, variable expansions, conditionals/loops, or tools that expect to run under a shell (e.g., visudo with EDITOR=..., logrotate -d ... >> logfile).

• chroot_stdin (target) <<'EOF' ... EOF — Long, multi-line payloads without argv/ARG_MAX pain.
  Use it to stream robust, quoting-safe scripts via stdin (bash -s). Ideal for multi-line awk/sed edits, or any content that would otherwise suffer from nested quoting or size limits if passed via -c. The helper sets up bash -s with strict shell options; ones provide the payload on stdin.

All three helpers run with a minimal, deterministic environment via env -i, reintroducing only:

• HOME,
• PATH,
• TERM,
• LANG/LC_ALL, and
• noninteractive APT settings. This ensures reproducibility and reduces the risk of ambient-environment leakage.

2.2. Design rationale

2.2.1. chroot_exec() — argv purity, preflight, the least overhead

Best for: idempotent system administration commands that do not require shell parsing.

Key traits

• Preflight binary presence with which inside the chroot before running the command — early, clear failure if a package was not installed yet.
• Sanitized environment (env -i with a strict default PATH and essential variables) for deterministic behavior.
• Straight argv execution — no shell interpretation; no quoting games.

When not to use
If you need a pipe, a redirect, variable expansion, or inline control flow — switch to chroot_script (or chroot_stdin for long fragments).

2.2.2. chroot_script() — controlled shell, explicit -c

Best for: single-line pipelines and short shell snippets.

Key traits

• Launches /bin/bash with strict options: errexit, errtrace, functrace, nounset, pipefail, plus Bash options inherit_errexit, failglob, lastpipe. This makes subtle failures visible and prevents masked errors in pipelines.
• Same minimal environment as chroot_exec().
• Debug path: on failure and if debugging flags are enabled, it drops into an interactive shell in the chroot for immediate triage.

Trade-offs

• The entire snippet becomes one long argument to bash -c. Very long or quote-dense payloads hit argv+env limits and are harder to lint. Prefer chroot_stdin for larger edits.

2.2.3 chroot_stdin() — robust multi-line scripts via bash -s

Best for: complex, multi-line payloads (Heredoc), quoting-heavy awk/sed programs, or anything beyond a small snippet.

Key traits

• Uses bash -s under the same strict shell options as chroot_script, but reads the script from stdin.
• Avoids argv size and 'ARG_MAX' constraints entirely; ideal for longer program fragments.
• Greatly simplifies quoting: with a single-quoted heredoc (<<'EOF') in the caller, you eliminate shell expansion surprises and keep editors/IDEs happy.

2.3. Common foundation across all helpers

• Minimal, controlled environment via env -i, whitelisting only the necessities (HOME, PATH, TERM, LANG/LC_ALL, noninteractive APT vars). This blocks noisy caller environments from leaking into the chroot and keeps behavior reproducible across systems.
• Strict Bash modes in the shell-based helpers — the effective default for the installer — to fail fast and surface latent errors.
• Structured logging for both success and failure paths, and an interactive debug shell when requested by the debug flags.

2.4. Decision guide

• Is it a single command with clean argv? → chroot_exec.
• Is it a short shell line with redirection/pipe/env assignment? → chroot_script.
• Is it long, quote-heavy, or multi-line logic? → chroot_stdin with a single-quoted heredoc.

If in doubt, start with chroot_exec. The moment you need a shell feature, jump to chroot_script. If your -c string grows past comfort (readability, quoting, or length), upgrade to chroot_stdin.

2.5. Subtleties and gotchas (and how the helpers address them)

• ARG_MAX and long -c strings: bash -c places the entire script in argv. On typical Linux systems you effectively have ≈2 MiB for argv+env; very long strings or large environments hit E2BIG. bash -s (stdin) avoids this entirely.

• Quoting pitfalls: Nested single quotes within single-quoted strings become painful; Heredoc's with <<'EOF' (stdin) eliminate accidental expansions and simplify review.

• Locale-sensitive regex: Always set LC_ALL=C for tools like awk to get predictable [[:class:]] semantics and bytewise collation in system config edits.

• Partially writes / truncated files: When editing files, write to a *.new and then mv -f only after test -s (non-empty) to guard against empty outputs in case of earlier errors.

• Debug ergonomics: The helpers integrate a conditional drop-in shell on failures when VAR_CHROOT_DEBUG (and related flags) is enabled, enabling immediate forensics inside the target environment.

2.6. Antipatterns (what to avoid)

• Using chroot_exec for anything involving the shell. That defeats the argv-only contract and will either fail or behave unexpectedly.
• Packing large scripts into -c strings. Hard to quote, hits argv limits, and clutters process lists. Prefer stdin.
• Relying on the caller’s ambient environment. The helpers intentionally use env -i to avoid such a leakage; do not reintroduce it unless you must.

3. Appendix — Helper signatures & guarantees

• chroot_exec(target, argv...)

  • Preflights the binary using which inside the chroot; fails early if missing.
  • Runs with a minimal, deterministic environment.

• chroot_script(target, "code", [loglevel])

  • Executes bash -c "code" under strict bash options; minimal environment; rich failure logging and optional interactive debug.

• chroot_stdin(target, "marker", [loglevel]) <<'EOF' ... EOF

  • Executes bash -s under strict bash options; minimal environment; same debug path; payload read from stdin, avoiding argv/ARG_MAX issues.

---

no tracking | no logging | no advertising | no profiling | no bullshit