|
|
|
@@ -7,84 +7,200 @@ include_toc: true
|
|
|
|
|
|
|
|
|
|
**Centurion Intelligence Consulting Agency Information Security Standard**<br>
|
|
|
|
|
*The CISS Debian Installer provides a fully automated and hardened installation process.*<br>
|
|
|
|
|
**Master Version**: 8.00<br>
|
|
|
|
|
**Build**: V8.00.000.2025.06.17<br>
|
|
|
|
|
**Master Version**: 9.00<br>
|
|
|
|
|
**Build**: V9.14.000.2026.06.07<br>
|
|
|
|
|
|
|
|
|
|
# 2. Coding Style
|
|
|
|
|
# 2. Purpose
|
|
|
|
|
|
|
|
|
|
## 2.1. PR
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
You'd make the life of the maintainers easier if you submit only _one_ patch with _one_ functional change per PR.
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
## 2.2 Documentation
|
|
|
|
|
# 3. Change discipline
|
|
|
|
|
|
|
|
|
|
Some people really read that ! New features would need to be documented in the appropriate section in `usage()` and in
|
|
|
|
|
`~/docs/DOCUMENTATION.md`.
|
|
|
|
|
- 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.
|
|
|
|
|
|
|
|
|
|
## 2.3. Coding
|
|
|
|
|
# 4. Installer phase awareness
|
|
|
|
|
|
|
|
|
|
### 2.3.1. Shell / bash
|
|
|
|
|
Identify the affected phase before changing behavior:
|
|
|
|
|
|
|
|
|
|
Bash is actually quite powerful—not only with respect to sockets. It's not as mighty as perl or python, but there are a lot of
|
|
|
|
|
neat features. Here's how you make use of them. Besides those short hints here, there's a wealth of information there.
|
|
|
|
|
- `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.
|
|
|
|
|
|
|
|
|
|
* Don't use backticks anymore, use `$(..)` instead
|
|
|
|
|
* Use double square `[[]]` brackets (_conditional expressions)_ instead of single square `[]` brackets
|
|
|
|
|
* In double square brackets, avoid quoting at the right-hand side if not necessary. For regex matching (`=~`) you shouldn't
|
|
|
|
|
quote at all.
|
|
|
|
|
* The [BashPitfalls](http://mywiki.wooledge.org/BashPitfalls) is a good read!
|
|
|
|
|
* Whenever possible try to avoid `tr` `sed` `awk` and use bash internal functions instead, see
|
|
|
|
|
e.g., [bash shell parameter substitution](http://www.cyberciti.biz/tips/bash-shell-parameter-substitution-2.html). It is
|
|
|
|
|
slower as it forks, fopens and pipes back the result.
|
|
|
|
|
* `read` often can replace `awk`: `IFS=, read -ra a b c <<< "$line_with_comma"`
|
|
|
|
|
* Bash can also deal perfectly with regular expressions, see
|
|
|
|
|
e.g., [here](https://www.networkworld.com/article/2693361/unix-tip-using-bash-s-regular-expressions.html)
|
|
|
|
|
and [here](https://unix.stackexchange.com/questions/421460/bash-regex-and-https-regex101-com).
|
|
|
|
|
* If you still need to use any of `tr`, `sed` and `awk`: try to avoid a mix of several external binaries e.g., if you can
|
|
|
|
|
achieve the same with e.g. `awk`.
|
|
|
|
|
* Be careful with very advanced bash features. Mac OS X is still using bash version 3 ([differences](http://tldp.org/LDP/abs/html/bashver4.html)).
|
|
|
|
|
* Always use a return value for a function/method. 0 means all is fine.
|
|
|
|
|
* Make use of [shellcheck](https://github.com/koalaman/shellcheck) if possible.
|
|
|
|
|
* Follow the [shellformat](https://google.github.io/styleguide/shellguide.html) Shell-Style Guide.
|
|
|
|
|
Keep host-side behavior, target chroot behavior, initramfs behavior, and bootloader behavior separate.
|
|
|
|
|
|
|
|
|
|
### 2.3.2. Shell specific
|
|
|
|
|
# 5. Bash baseline
|
|
|
|
|
|
|
|
|
|
* Security:
|
|
|
|
|
* Watch out for any input especially (but not only) supplied from the server. Input should never be trusted.
|
|
|
|
|
* Unless you're really sure where the values come from, variables need to be put in quotes.
|
|
|
|
|
- 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.
|
|
|
|
|
|
|
|
|
|
### 2.3.3. Variables
|
|
|
|
|
# 6. Bash style
|
|
|
|
|
|
|
|
|
|
* Use **"speaking variables"** but don't overdo it with the length.
|
|
|
|
|
* No _camelCase_, please. We distinguish between lowercase and uppercase only.
|
|
|
|
|
* Global variables:
|
|
|
|
|
* use them only when really necessary,
|
|
|
|
|
* in CAPS,
|
|
|
|
|
* initialize them (`declare -g VAR_EXAMPLE=""`),
|
|
|
|
|
* SHOULD start with:
|
|
|
|
|
* `ARY_` for Arrays,
|
|
|
|
|
* `C_` for Variables defining colored outputs,
|
|
|
|
|
* `ERR_` for Error Codes Variables,
|
|
|
|
|
* `HMP_` for HashMap Arrays,
|
|
|
|
|
* `LOG_` for Logfile Variables,
|
|
|
|
|
* `PID_` for PID Variables,
|
|
|
|
|
* `PIPE_` for PIPE Variables,
|
|
|
|
|
* `VAR_` for Variables
|
|
|
|
|
* Local variables:
|
|
|
|
|
* are lower case,
|
|
|
|
|
* declare them before usage (`declare` eq `local`),
|
|
|
|
|
* initialize them (`declare var_example=""`),
|
|
|
|
|
* SHOULD start with:
|
|
|
|
|
* `ary_` for Arrays,
|
|
|
|
|
* `c_` for Variables defining colored outputs,
|
|
|
|
|
* `err_` for Error Codes Variables,
|
|
|
|
|
* `hmp_` for HashMap Arrays,
|
|
|
|
|
* `log_` for Logfile Variables,
|
|
|
|
|
* `var_` for Variables.
|
|
|
|
|
- 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.
|
|
|
|
|
|
|
|
|
|
# 3. Misc
|
|
|
|
|
# 7. Variables and naming
|
|
|
|
|
|
|
|
|
|
* Test before doing a PR! Best if you check with two bad and two good examples, which should then work as expected.
|
|
|
|
|
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/)**
|
|
|
|
|
