msw
c80b45417f
🔐 Generating a Private Live ISO TRIXIE. / 🔐 Generating a Private Live ISO TRIXIE. (push) Has been cancelled
💙 Generating a PUBLIC Live ISO. / 💙 Generating a PUBLIC Live ISO. (push) Has been cancelled
🛡️ Shell Script Linting / 🛡️ Shell Script Linting (push) Has been cancelled
🛡️ Retrieve DNSSEC status of coresecret.dev. / 🛡️ Retrieve DNSSEC status of coresecret.dev. (push) Has been cancelled
Signed-off-by: Marc S. Weidner <msw@coresecret.dev>
87 lines
3.2 KiB
Markdown
87 lines
3.2 KiB
Markdown
# AGENTS.md
|
|
|
|
## Repository purpose
|
|
|
|
This repository builds and maintains Debian-based live/installer infrastructure.
|
|
Treat changes as security-sensitive and boot-chain-sensitive.
|
|
Follow `docs/CODING_CONVENTION.md` for coding style and `code_review.md` for reviews.
|
|
|
|
## Non-negotiable constraints
|
|
|
|
- Target distribution: Debian 13 Trixie unless explicitly stated otherwise.
|
|
- Do not introduce Ubuntu-specific assumptions.
|
|
- Do not invent live-build, initramfs, cryptsetup, systemd, GRUB, or Debian package behavior. Verify against existing files or
|
|
official documentation.
|
|
- Do not add phase-argument gates to live-boot/initramfs scripts. Script execution is controlled by Debian hook placement.
|
|
- Preserve encrypted-root / encrypted-SquashFS architecture unless the task explicitly changes it.
|
|
- Prefer simple, inspectable Bash over clever abstractions.
|
|
|
|
## Repository workflow
|
|
|
|
Before editing:
|
|
- Inspect the relevant scripts, hooks, config files, README files, and existing naming conventions.
|
|
- Identify the exact boot/build phase affected by the change.
|
|
- Explain the minimal intended change.
|
|
|
|
Boot/build phases:
|
|
- host-side orchestration: `ciss_live_builder.sh`, `lib/*.sh`, `makefile`
|
|
- live-build hooks: `config/hooks/live/*.chroot` and `config/hooks/live/*.binary`
|
|
- initramfs hooks/scripts: `config/includes.chroot/etc/initramfs-tools/*`
|
|
- live-boot runtime scripts: `config/includes.chroot/usr/lib/live/boot/*`
|
|
|
|
After editing:
|
|
- Run the most relevant available checks.
|
|
- At minimum, run syntax checks for changed shell scripts:
|
|
- `bash -n <file>`
|
|
- `shellcheck <file>` if available
|
|
- If POSIX shell scripts are changed, run `sh -n <file>` where Bash syntax is not expected.
|
|
- If the make wrapper or builder argument composition changes, run `make dry-run`.
|
|
- If Python files are introduced or changed:
|
|
- `ruff check`
|
|
- `mypy`
|
|
- `pytest` if tests exist
|
|
- If CLI options or user-facing behavior change, update `usage()` and the relevant README/docs.
|
|
- If live-build, initramfs, or ISO behavior changes, describe the required Debian Trixie live-build or ISO validation command.
|
|
|
|
## Bash conventions
|
|
|
|
- Use explicit error handling.
|
|
- Quote expansions.
|
|
- Prefer arrays where word splitting matters.
|
|
- Avoid `eval`.
|
|
- Avoid parsing `ls`.
|
|
- Keep functions small and readable.
|
|
- Use English comments.
|
|
- Explain security-sensitive fallbacks.
|
|
- Fail closed where possible.
|
|
|
|
## Python conventions
|
|
|
|
- Use Python 3.14-compatible code unless the project states otherwise.
|
|
- Use pathlib.
|
|
- Add type hints.
|
|
- Keep ruff and mypy compatibility.
|
|
- Avoid broad `except Exception` unless justified and logged.
|
|
- Prefer explicit models/config objects over unstructured dictionaries for durable interfaces.
|
|
|
|
## Security review checklist
|
|
|
|
Before finalizing a change, check whether it affects:
|
|
- boot trust
|
|
- initramfs behavior
|
|
- cryptsetup/LUKS handling
|
|
- key material
|
|
- remote unlock
|
|
- TLS/mTLS verification
|
|
- signature/hash verification
|
|
- network exposure
|
|
- file permissions
|
|
- persistence
|
|
- logging of sensitive values
|
|
|
|
If affected, document the risk and mitigation in the final response.
|
|
|
|
---
|
|
**[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 -->
|