CISS.debian.installer/docs/CODING_CONVENTION.md

Table of Contents

• 1. CISS.debian.installer
• 2. Purpose
• 3. Change discipline
• 4. Installer phase awareness
• 5. Bash baseline
• 6. Bash style
• 7. Variables and naming
• 8. Input validation, secrets, and files
• 9. Disk, partitioning, and cryptsetup safety
• 10. Chroot, target, and boot-chain safety
• 11. Dependencies and downloads
• 12. Documentation rules
• 13. Formatting
• 14. Narrow validation policy
• 15. Code review

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: 9.00
Build: V9.14.002.2026.06.08

2. Purpose

This document defines detailed coding conventions for CISS.debian.installer. AGENTS.md is the short operational guide for Codex. code_review.md is used for review tasks and final self-review.

The repository implements a Bash-first Debian installer for hardened, reproducible system installation workflows. Treat every change as security-sensitive, disk-destruction-sensitive, and boot-chain-sensitive, especially changes affecting partitioning, LUKS, Btrfs, initramfs, Dropbear remote unlock, GRUB, package sources, signatures, checksums, hardening settings, or logs.

3. Change discipline

• Keep changes small, local, and reviewable.
• Make one functional change per patch set.
• Preserve existing architecture, naming style, error handling, formatting, and security posture.
• Target Debian 13 Trixie unless the task or repository explicitly states otherwise.
• Do not introduce Ubuntu-specific assumptions.
• Do not invent Debian Installer, debootstrap, initramfs-tools, cryptsetup, GRUB, systemd, Btrfs, Debian package, or upstream tool behavior.
• Verify uncertain behavior against repository code or authoritative upstream documentation.
• Do not weaken cryptography, authentication, sandboxing, permission checks, TLS verification, signature verification, checksum verification, provenance verification, or input validation unless explicitly requested and documented.
• Do not perform unrelated cleanup or formatting churn.

4. Installer phase awareness

Identify the affected phase before changing behavior:

• ciss_debian_installer.sh: host-side entrypoint, root/Bash checks, lock handling, trap activation, and phase order.
• meta_loader_*.sh: ordered sourcing of variables, functions, and libraries via source_guard.
• .preseed/preseed.yaml, .preseed/partitioning.yaml, .preseed/SECRETS.yaml: installer settings, partition recipes, and secret material.
• lib/cdi_0100_arg/*: CLI argument sanitation, parsing, priority handling, and passphrase-module argument support.
• func/cdi_1200_validation/* and func/cdi_1250_yaml/*: element, IP, preseed, YAML, and secret validation.
• func/cdi_3200_partitioning/*: destructive disk wiping, partition creation, LUKS setup, formatting, mount ordering, and UUID logging.
• func/cdi_4000_debootstrap/*: debootstrap, target mount preparation, base target setup, hostname, resolver, timezone, and locale setup.
• func/cdi_4100_base/*: APT source generation, updates, kernel/initramfs installation, toolset, systemd, machine-id, firmware, microcode, Chrony, and base packages.
• func/cdi_4200_boot/*: fstab, crypttab, cryptsetup-initramfs, GRUB installation, GRUB password, and boot parameters.
• func/cdi_4300_network/*: target networking, network security, Dropbear build/initramfs/setup, initramfs update, and SSH.
• func/cdi_4400_hardening/*: kernel modules, sysctl, fail2ban, filesystem permissions, entropy, memory, OpenSSL, UFW, USB, and malware-auditing hardening.
• func/cdi_4500_user/*: account preparation, password policy, user setup, SSH keys, privileges, and timing fields.
• func/cdi_4600_packages/*: package installation, security profile installation, verification, and auditing packages.
• func/cdi_4900_xtended/*: final commands, logrotate setup, and target chroot exit.
• func/cdi_5000_recovery/*: recovery target debootstrap and finalization when recovery is enabled.
• includes/target/*: files installed into the target system, including initramfs-tools hooks/scripts/files and service configuration.
• includes/chroot/hooks/*: chroot hook payloads.
• upgrades/*: vendored upgrade/build material for Dropbear, Linux image options, and Secure Boot work.
• py/*: Python configurator support.

Keep host-side behavior, target chroot behavior, initramfs behavior, and bootloader behavior separate.

5. Bash baseline

• Use Bash for installer logic and orchestration.
• Use POSIX shell only where an existing Debian interface file requires it, such as an initramfs hook or script that already declares #!/bin/sh.
• The main installer requires Bash 5.1 or newer; do not add compatibility code for older Bash versions unless explicitly requested.
• Prefer set -Ceuo pipefail for executable Bash scripts where feasible. In sourced modules, preserve the caller's shell option and trap model unless the surrounding code already changes it intentionally.
• Preserve guard_sourcing || return "${ERR_GUARD_SOURCE}" in sourced modules that use it.
• Preserve source_guard-based module loading.
• Preserve readonly -f on functions where surrounding files use it.
• Do not overwrite existing ERR, EXIT, INT, or TERM traps. Coordinate any trap change with lib/cdi_0060_traps/* and initramfs runtime scripts.

6. Bash style

• Quote expansions unless word splitting or globbing is explicitly required.
• Prefer arrays for commands and options.
• Use [[ ... ]] for Bash conditionals.
• Use case for option dispatch and multi-branch string handling.
• Use $(...) command substitution, not backticks.
• Do not use eval.
• Avoid parsing ls.
• Prefer command -v over which.
• Check command results explicitly when failure needs custom logging or cleanup.
• Keep functions small enough to review.
• End functions explicitly with return 0 where consistent with surrounding code.
• Use English comments. Comment non-obvious security, disk, cryptographic, initramfs, or boot-chain decisions.

7. Variables and naming

Follow the existing repository naming style:

• Global variables are uppercased and initialized before use.
• Global arrays and maps use established prefixes such as ARY_, HMP_, C_, ERR_, LOG_, PID_, PIPE_, and VAR_.
• Local variables are lowercase and initialized before use.
• Local arrays and helper variables use established prefixes such as ary_, hmp_, c_, err_, log_, and var_.
• Use declare consistently with surrounding files.
• Function names use lowercase words separated by underscores.
• Avoid new global variables when an argument, local variable, or existing helper is sufficient.
• Keep Boolean-like values normalized where existing code expects lowercase strings.

8. Input validation, secrets, and files

• Treat CLI arguments, YAML values, environment variables, generated paths, network data, package metadata, and user-provided files as untrusted until validated.
• Validate disk names, partition numbers, mount paths, filesystem names, Debian suites, architecture names, ports, IP addresses, package names, URLs, feature flags, and file paths before use.
• Fail closed when validation cannot prove that continuing is safe.
• Do not print secrets, passphrases, private keys, tokens, decrypted SOPS values, or sensitive environment values.
• Keep debug tracing disabled around secret handling unless the local guard explicitly protects sensitive values.
• Use restrictive permissions for generated key material, passphrase files, LUKS header backups, SSH material, and root-only configuration.
• Prefer mktemp for temporary files and clean them up with existing cleanup or trap helpers.
• Preserve existing secure deletion helpers where used for passphrase or key material.
• Do not add a persistent state unless the behavior is intentional, scoped, and documented.

9. Disk, partitioning, and cryptsetup safety

• Treat changes under func/cdi_3200_partitioning/* as destructive by default.
• Never run partitioning, formatting, LUKS, blkdiscard, sgdisk --zap-all, or dd validation on a real device unless the task explicitly requests it, and the target is safely isolated.
• Preserve explicit device scoping from .preseed/partitioning.yaml.
• Preserve udev settling and UUID/PARTUUID collection where disk identity is needed by later phases.
• Preserve LUKS2 defaults and stronger cryptographic settings unless the task explicitly changes them.
• Do not weaken PBKDF, cipher, hash, key size, integrity, discard, or keyslot behavior without documenting the risk.
• Preserve the special handling for encrypted /boot, root, recovery, ephemeral SWAP, and ephemeral /tmp.
• Keep LUKS header backups encrypted when backup behavior is enabled and remove plaintext backup material after encryption.
• Keep /etc/fstab and /etc/crypttab generation consistent with mapper names, UUIDs, PARTUUIDs, filesystem types, and mount options.
• Preserve Btrfs subvolume and snapshot semantics when changing Btrfs mount or formatting logic.

10. Chroot, target, and boot-chain safety

• Use chroot_exec for simple command execution in the target.
• Use chroot_script or chroot_stdin for shell constructs, redirection, pipelines, loops, or larger payloads.
• Preserve the sanitized env -i target environment unless a task explicitly requires a new variable.
• Do not leak host paths or host environment assumptions into the target system.
• Preserve target mount setup and teardown behavior.
• Keep initramfs-tools hooks and scripts in their expected directories; do not add ad-hoc phase arguments.
• Preserve Dropbear initramfs forced-command, unlock-wrapper integrity checks, signature verification, and nuke behavior.
• Preserve GRUB support for encrypted boot paths, and the repository's UEFI/BIOS handling unless explicitly changed.
• Do not change UEFI NVRAM behavior or fallback boot paths without documenting the boot-chain impact.

11. Dependencies and downloads

• Do not add new runtime dependencies unless the task requires them.
• Prefer standard Debian tooling or existing project helpers.
• When a dependency is needed, document why the existing toolchain, or a standard alternative is insufficient.
• Do not add remote downloads, auto-update behavior, telemetry, or network callbacks without explicit justification.
• For required downloads, use HTTPS where applicable and preserve or add signature, checksum, or provenance verification.
• Do not use curl | sh, wget | sh, or equivalent execution of unaudited remote content.
• Preserve package authentication and APT source integrity checks.

12. Documentation rules

• Update documentation together with behavior changes.
• New or changed CLI options must update usage() and relevant documentation.
• New or changed YAML/preseed keys must update the relevant .preseed example or project documentation.
• Boot parameter changes must update docs/man/BOOTPARAMS.md when applicable.
• Security-sensitive behavior changes must update the relevant manual, audit, or security documentation when applicable.
• Generated examples must stay valid for Debian 13 Trixie unless the task explicitly targets another release.
• Code comments, embedded prompts, commit messages, and repository documentation should normally be written in English.

13. Formatting

• Preserve SPDX headers and existing file headers where present.
• New source or configuration files should include the project SPDX header when comparable files already use one.
• Follow .editorconfig: LF line endings, UTF-8, two-space indentation for most repository files, four-space indentation for Python, and readable line lengths.
• Preserve the local Vim modeline style in source/config files where neighboring files use it.
• Keep Markdown concise and structured. Avoid decorative text that does not define repository behavior.
• Do not churn formatting unrelated to the task.

14. Narrow validation policy

Run only the narrowest checks that prove the change:

• Bash files: bash -n <file> and shellcheck <file> when ShellCheck is available.
• POSIX shell files: sh -n <file>.
• CLI or parser changes: the safest available help/parser check, if the environment permits it without performing installer actions.
• YAML/preseed changes: parse or validate the changed file with repository tooling if a cheap parser or validator is present.
• Python files: run the relevant checks configured under py/, such as Ruff, mypy, or pytest, when applicable.
• Documentation-only changes: confirm the target files exist, check the final diff, and run Markdown linting only when the repository has a cheap configured Markdown lint command.

Do not run full installer builds, debootstrap, destructive disk tests, broad repository audits, or network-heavy validation unless explicitly requested or technically required to validate the change.

If a relevant check cannot be run, state the exact reason, and the command that should be run locally.

15. Code review

Reviews follow code_review.md.

---

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