154 lines
8.8 KiB
Markdown
154 lines
8.8 KiB
Markdown
# 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:
|
|
|
|
1. The current task prompt defines the immediate objective and task-specific acceptance criteria.
|
|
2. This `AGENTS.md` defines repository-wide constraints and routing guidance.
|
|
3. `docs/CODING_CONVENTION.md` defines detailed coding conventions.
|
|
4. `code_review.md` applies when performing a review or final self-review.
|
|
5. 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:
|
|
|
|
1. Inspect the relevant scripts, configuration files, documentation, workflows, and naming conventions.
|
|
2. 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.
|
|
3. Check existing source guards, trap behavior, logging, secret handling, and helper APIs before changing code.
|
|
4. 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.
|
|
|
|
## Final response
|
|
|
|
Return a concise implementation report:
|
|
|
|
- changed files
|
|
- what changed
|
|
- checks run and result
|
|
- real remaining risks or follow-up steps
|
|
|
|
Do not claim success for checks that were not run.
|
|
|
|
---
|
|
**[no tracking | no logging | no advertising | no profiling | no bullshit](https://coresecret.eu/)**
|
|
<!-- vim: set number et ts=2 sw=2 sts=2 ai tw=128 ft=markdown -->
|