CISS.debian.live.builder/docs/CODING_CONVENTION.md

Table of Contents

• 1. CISS.debian.live.builder
• 2. Purpose
• 3. Change discipline
• 4. Boot and build phases
• 5. Bash style
• 6. Variables and functions
• 7. Input, secrets, and files
• 8. Dependencies and downloads
• 9. Documentation
• 10. Formatting
• 11. Checks
• 12. Code review

1. CISS.debian.live.builder

Centurion Intelligence Consulting Agency Information Security Standard
Debian Live Build Generator for hardened live environment and CISS Debian Installer

2. Purpose

This document defines the coding and review conventions for this repository.

The project builds Debian-based live and installer infrastructure. Treat every change as security-sensitive and boot-chain-sensitive, especially changes that affect initramfs behavior, encrypted SquashFS handling, LUKS, Dropbear, GRUB, checksums, signatures, package sources, hardening settings, or network exposure.

3. Change discipline

• Keep changes small, local, and reviewable.
• Make one functional change per pull request or patch set.
• Preserve existing architecture, naming style, error handling, formatting, and security posture.
• Do not introduce Ubuntu-specific assumptions. The default target distribution is Debian 13 Trixie.
• Do not invent live-build, live-boot, initramfs, cryptsetup, GRUB, systemd, or Debian package behavior. Verify against existing code or authoritative Debian/upstream documentation.
• Do not weaken cryptography, authentication, sandboxing, permission checks, TLS verification, signature verification, checksum verification, or input validation unless the task explicitly requires it and the risk is documented.
• Prefer simple, inspectable Bash over clever abstractions.

4. Boot and build phases

Identify the affected phase before changing behavior:

• ciss_live_builder.sh and lib/*.sh: host-side orchestration and argument handling.
• makefile: local wrapper for composing and executing builder invocations.
• config/hooks/live/*.chroot: live-build chroot hooks.
• config/hooks/live/*.binary: live-build binary-image hooks.
• config/includes.chroot/etc/initramfs-tools/hooks/*: initramfs build hooks.
• config/includes.chroot/etc/initramfs-tools/scripts/*: initramfs boot scripts.
• config/includes.chroot/usr/lib/live/boot/*: live-boot runtime scripts.
• scripts/*: source files copied into the generated image or used by build helpers.

Do not add ad-hoc phase arguments to live-boot or initramfs scripts. Execution phase must be controlled by the directory and hook placement expected by Debian tooling.

5. Bash style

• Use Bash for builder scripts and live-build hooks when the existing file uses Bash.
• Use POSIX sh only where Debian hook interfaces or neighboring files require it. Keep such files POSIX-compatible.
• Prefer set -Ceuo pipefail for Bash scripts where feasible. If a script cannot use strict mode safely, keep the exception local and make the reason clear.
• Quote expansions unless word splitting or globbing is explicitly required.
• Prefer arrays where arguments or file names may contain whitespace.
• Use [[ ... ]] for Bash conditionals. For regular-expression matches with =~, do not quote the right-hand regex.
• Use $(...) command substitution, not backticks.
• Avoid eval.
• Avoid parsing ls.
• Prefer command -v over which.
• Check command results explicitly when failure needs custom handling.
• Use case for option dispatch and multi-branch string handling.
• Keep functions small and readable.
• Use English comments. Add comments for non-obvious security or boot-chain decisions, not for obvious assignments.

6. Variables and functions

Follow the existing repository naming style:

• Global variables are uppercase and initialized before use.
• Global arrays use the ARY_ prefix where this convention already applies.
• Other established global prefixes include C_, ERR_, HMP_, LOG_, PID_, PIPE_, and VAR_.
• Local variables are lowercase and initialized before use.
• Local array and helper prefixes include ary_, c_, err_, hmp_, log_, and var_.
• Function names use lowercase words separated by underscores.
• Prefer declare or local consistently with the surrounding file.

7. Input, secrets, and files

• Treat CLI arguments, environment variables, generated file paths, network data, package metadata, and user-provided files as untrusted until validated.
• Validate ports, IP addresses, kernel version strings, paths, package names, and feature flags before use.
• Fail closed when validation cannot prove that continuing is safe.
• Do not print secrets, private keys, passphrases, tokens, or sensitive environment values.
• Use restrictive permissions for generated secret material.
• Prefer mktemp for temporary files and clean them up with traps when appropriate.
• Do not create persistent state unless the behavior is intentional and documented.

8. 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 an existing or standard-library 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 verification.
• Do not use curl | sh, wget | sh, or equivalent execution of unaudited remote content.

9. Documentation

Update documentation together with behavior:

• New or changed CLI options must update usage() and relevant README or documentation sections.
• Boot parameter changes must update docs/BOOTPARAMS.md where applicable.
• Security-sensitive behavior changes must update the relevant audit, manual, or security documentation.
• 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.

10. 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 where configured, two-space Markdown indentation, and tabs for makefile recipes.
• Keep line lengths readable and consistent with neighboring files.
• Do not churn formatting unrelated to the task.

11. Checks

Run the narrowest checks that prove the change:

• Shell files: bash -n <file> for Bash scripts, and shellcheck <file> when ShellCheck is available.
• POSIX shell files: sh -n <file> where Bash syntax is not expected.
• Make wrapper or argument-composition changes: make dry-run.
• Python files, if introduced or changed: ruff check, mypy, and pytest when tests exist.
• Live-build, initramfs, or ISO behavior changes: document the required Debian Trixie build validation command, normally make live or the equivalent ./ciss_live_builder.sh ... invocation.

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

12. Code review

Reviews follow code_review.md.

---

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