--- gitea: none include_toc: true --- # 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. 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. 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 ` for Bash scripts, and `shellcheck ` when ShellCheck is available. * POSIX shell files: `sh -n ` 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](https://coresecret.eu/)**