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
Master Version: 9.14
Build: V9.14.026.2026.06.12

2. Purpose

This document defines the coding and review conventions for this repository. This file is the detailed engineering convention.

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.

AGENTS.md is the short operational guide for Codex. code_review.md is used for review tasks and final self-review.

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.
• Do not introduce Ubuntu-specific assumptions.
• Target Debian 13 Trixie unless explicitly instructed otherwise.
• Do not invent live-build, live-boot, initramfs, cryptsetup, GRUB, systemd, 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.
• Prefer simple, inspectable Bash over clever abstractions.
• Do not perform unrelated cleanup or formatting churn.

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. The 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 uppercased 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 a 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