CISS.debian.installer/docs/CODING_CONVENTION.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**: 9.00<br>
**Build**: V9.14.000.2026.06.07<br>

# 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](https://coresecret.eu/)**
<!-- vim: set number et ts=2 sw=2 sts=2 ai tw=128 ft=markdown -->