msw/CISS.debian.installer

SHA256

Fork 0

Files

T

msw 261d770e42

🛡️ Shell Script Linting / 🛡️ Shell Script Linting (push) Has been cancelled

Details

🛡️ Retrieve DNSSEC status of coresecret.dev. / 🛡️ Retrieve DNSSEC status of coresecret.dev. (push) Has been cancelled

Details

V9.14.000.2026.06.07

Signed-off-by: Marc S. Weidner <msw@coresecret.dev>

2026-06-07 15:46:30 +01:00

8.8 KiB

Raw Blame History

AGENTS.md

Purpose

This repository builds and maintains CISS.debian.installer, a script-driven Debian installer for hardened and reproducible system installation workflows.

Treat every change as security-sensitive, disk-destruction-sensitive, and boot-chain-sensitive. Persistent coding details live in docs/CODING_CONVENTION.md. Review-only instructions live in code_review.md.

Instruction precedence for this repository

Use this order when instructions differ:

The current task prompt defines the immediate objective and task-specific acceptance criteria.
This AGENTS.md defines repository-wide constraints and routing guidance.
docs/CODING_CONVENTION.md defines detailed coding conventions.
code_review.md applies when performing a review or final self-review.
Personal/global Codex instructions apply only where they do not conflict with repository rules.

When instructions conflict, prefer the safer, smaller, more easily reviewable change and explain the conflict.

Non-negotiable constraints

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 existing repository code or authoritative upstream documentation.
Preserve encrypted-root and boot-chain security assumptions unless the task explicitly changes them.
Preserve existing module source guards, especially guard_sourcing, source_guard, and readonly -f conventions.
Do not overwrite existing ERR, EXIT, INT, or TERM traps from modules or runtime scripts.
Prefer simple, explicit, inspectable Bash over clever abstraction.
Do not use eval.
Do not print secrets, passphrases, private keys, tokens, or sensitive environment values.
Do not perform destructive disk operations in validation unless explicitly requested and safely isolated.

Repository map

Common areas:

ciss_debian_installer.sh: primary installer entrypoint and phase orchestration.
meta_loader_*.sh: ordered module, library, and variable sourcing.
.preseed/preseed.yaml, .preseed/partitioning.yaml, .preseed/SECRETS.yaml: installer configuration, partition recipes, and secret input material.
var/*.sh: global variables, colors, terminal settings, and error codes.
lib/cdi_0000_preliminary/*: contact, usage, and version helpers.
lib/cdi_0005_guard/*: sourcing, source-guard, safe-execution, directory, and variable guards.
lib/cdi_0010_basic/*, lib/cdi_0025_logging/*, lib/cdi_0030_checks/*, lib/cdi_0050_debug/*, lib/cdi_0060_traps/*: basic helpers, logging, package/git checks, debug support, and traps.
lib/cdi_0100_arg/*, lib/cdi_0110_interactive/*, lib/cdi_0200_dialog/*: argument handling and interactive dialogs.
func/cdi_1000_helper/*: chroot helpers, GRUB helpers, module helpers, sanitizers, secure downloads, and YAML helpers.
func/cdi_1200_validation/*, func/cdi_1250_yaml/*: validation and preseed/YAML processing.
func/cdi_3200_partitioning/*: destructive partitioning, LUKS setup, formatting, mounting, and UUID logging.
func/cdi_4000_debootstrap/*: debootstrap, target mount preparation, and base target setup.
func/cdi_4100_base/*: APT sources, kernel, initramfs, systemd, firmware, and base package setup.
func/cdi_4200_boot/*: fstab, crypttab, cryptsetup, GRUB, GRUB password, and boot parameter handling.
func/cdi_4300_network/*: network setup, Dropbear initramfs remote unlock, initramfs updates, and SSH setup.
func/cdi_4400_hardening/*, func/cdi_4500_user/*, func/cdi_4600_packages/*: hardening, account setup, package installation, security verification, and auditing packages.
func/cdi_4900_xtended/*, func/cdi_5000_recovery/*: final commands, logrotate, chroot exit, and recovery target handling.
includes/target/*: files installed into the target system, including initramfs-tools hooks, scripts, Dropbear unlock files, GRUB assets, SSH, OpenSSL, sysctl, modprobe, PAM, and profile configuration.
includes/chroot/hooks/*: hook payloads copied into or executed inside the target environment.
upgrades/*: vendored or upgrade-related materials for Dropbear, Linux image options, and Secure Boot work.
py/*: Python-based configurator support.
docs/*, .gitea/workflows/*: project documentation and repository automation.

Working method

Before editing:

Inspect the relevant scripts, configuration files, documentation, workflows, and naming conventions.
Identify the affected installer phase: host orchestration, YAML/preseed handling, destructive disk setup, target chroot, initramfs, bootloader, network/Dropbear, hardening, user setup, package installation, finalization, or recovery.
Check existing source guards, trap behavior, logging, secret handling, and helper APIs before changing code.
Give a concise implementation plan and list likely files to touch unless the change is trivial.

While editing:

Keep changes minimal and local to the task.
Preserve existing architecture, naming style, error handling, formatting, and security posture.
Do not perform unrelated cleanup or formatting churn.
Reuse existing helpers for logging, fatal errors, validation, source guards, chroot execution, secure downloads, temporary files, and secret cleanup where available.
Prefer arrays for command argument composition.
Do not introduce new runtime dependencies unless technically necessary and justified.

After editing:

Run only the narrowest checks that prove the change.
Changed Bash files: run bash -n <file> and shellcheck <file> if ShellCheck is available.
Changed POSIX shell files: run sh -n <file>.
Changed CLI behavior: update usage() and relevant documentation, then run the safest available parser/help check if the environment permits it.
Changed Python files: run the relevant checks configured under py/ when applicable.
Changed installer, disk, initramfs, cryptsetup, GRUB, or Dropbear behavior: state the required Debian 13 Trixie validation command or isolated test, but do not run destructive or full installer validation unless explicitly requested.
For documentation-only changes, confirm the target files exist and review the final diff.

Bash conventions summary

See docs/CODING_CONVENTION.md for details.

Use Bash for installer logic unless an existing Debian interface file must remain POSIX shell.
Preserve module source guards and readonly -f usage where surrounding files use them.
Prefer strict Bash mode where feasible and consistent with the file's execution context.
Use declare for variables inside functions.
Quote expansions unless word splitting or globbing is explicitly required.
Prefer arrays where argument boundaries matter.
Use [[ ... ]], case, and $(...).
Avoid parsing ls; prefer structured tool output or existing helpers.
Prefer command -v over which.
Code comments must be in English.

Security-sensitive areas

Before finalizing a change, check whether it affects:

disk wiping, partition table creation, partition type codes, or filesystem formatting
cryptsetup/LUKS2 parameters, passphrases, key files, key slots, LUKS header backups, or nuke behavior
Btrfs subvolumes, mount ordering, mount options, snapshots, or labels
/etc/fstab, /etc/crypttab, UUIDs, PARTUUIDs, or mapper names
initramfs-tools hooks, scripts, included binaries, or early boot behavior
Dropbear initramfs remote unlock, forced commands, firewalling, host keys, unlock wrapper signatures, or hashes
GRUB installation, GRUB modules, encrypted /boot, UEFI/BIOS paths, NVRAM handling, or Secure Boot material
chroot command execution, mount propagation, target/root separation, or environment sanitization
APT sources, package authentication, TLS, signatures, checksums, or remote downloads
account setup, SSH policy, PAM, sudo, permissions, hardening files, or network exposure
logging, debug tracing, traps, cleanup paths, or exposure of sensitive values

If affected, document the concrete risk and mitigation in the final response.

Validation policy

Use the narrowest validation that proves the requested change. Do not run full installer builds, debootstrap runs, live disk tests, destructive partitioning, broad repository audits, or network-heavy validation unless the task explicitly asks for them or the change cannot be validated responsibly without them.

8.8 KiB Raw Blame History