CISS.debian.live.builder/REPOSITORY.md

---
gitea: none
include_toc: true
---

# 1. CISS.debian.live.builder

**Centurion Intelligence Consulting Agency Information Security Standard**<br>
*Debian Live Build Generator for hardened live environment and CISS Debian Installer*<br>
**Master Version**: 8.13<br>
**Build**: V8.13.144.2025.10.16<br>

# 2.1. Repository Structure

**Project:** Centurion Intelligence Consulting Agency Information Security Standard (CISS) — Debian Live Builder  
**Branch:** `master`  
**Repository State:** Master Version **8.13**, Build **V8.13.144.2025.10.16** (as of 2025-10-11)

## 2.2. Top-Level Layout

````text
CISS.debian.live.builder/
├─ .archive/                                                                           # Archived artefacts or historical assets
├─ .gitea/ # Gitea CI/CD metadata (workflows, triggers, templates)
│ ├─ ISSUE_TEMPLATE/
│ ├─ properties/{json, lua}
│ ├─ TO DO/{dockerfile, render-md-to-html.yaml}
│ ├─ trigger/{t_generate_.yaml}
│ └─ workflows/{generate_.yaml, linter_char_scripts.yaml, render-.yaml}
├─ .pubkey/                                                                         # Public keys (e.g., for CI or verification)
├─ config/ # Live-build configuration (boot, hooks, includes, package lists)
│ ├─ bootloaders/{grub-efi, grub-pc, splash.png}
│ ├─ hooks/live/.chroot                                                                  # Ordered chroot hooks (0000_* … 99xx_)
│ ├─ includes.binary/boot/grub/config.cfg
│ ├─ includes.chroot/{etc, preseed, root}
│ └─ package-lists/{live.list.amd64.chroot, live.list.arm64.chroot, live.list.common.chroot}
├─ docs/                                                                  # Project documentation (audits, change log, policies)
│ ├─ AUDIT_.md, BOOTPARAMS.md, CHANGELOG.md, CODING_CONVENTION.md, ...
│ ├─ SECURITY/, LICENSES/, graphviz/, screenshots/
├─ lib/                                                                              # Shell library modules used by the builder
├─ scripts/ # Helper/orchestration scripts (e.g., network, live-boot)
├─ var/                                                                     # Variable sets and early/global defaults (*.var.sh)
├─ .editorconfig
├─ .gitignore
├─ .shellcheckrc
├─ .version.properties
├─ CISS.debian.live.builder.spdx                                                     # SPDX bill of materials / license manifest
├─ LICENSE
├─ SECURITY.md
├─ README.md
├─ config.mk.sample
├─ ciss_live_builder.sh                                                                              # Main entrypoint / wrapper
├─ makefile
├─ meta_sources_debug.sh
├─ LIVE_ISO_TRIXIE_0.private                                                                               # CI artefact markers
├─ LIVE_ISO_TRIXIE_1.private                                                                               # CI artefact markers
└─ LIVE_ISO.public                                                                                         # CI artefact markers
````

> **Note:** The ISO marker files (`LIVE_ISO.*`) are produced by CI workflows for convenient retrieval of generated images.

## 2.3. Directory Semantics

### 2.3.1. `.gitea/` — CI/CD Orchestration
- **`workflows/`**: Declarative Gitea Actions to lint shell scripts, render Graphviz/DNSSEC status, and generate **PUBLIC**/**PRIVATE (TRIXIE)** ISOs reproducibly.
- **`trigger/`**: Manual/auxiliary trigger manifests (`t_generate_PUBLIC.yaml`, `t_generate_PRIVATE_trixie_{0,1}.yaml`, `t_generate_dns.yaml`) to drive pipeline variants.
- **`ISSUE_TEMPLATE/`**: Issue and pull request templates to standardize change management.
- **`properties/`** and **`TODO/`**: Auxiliary config fragments (JSON/Lua) and maintenance utilities (e.g., `render-md-to-html.yaml`).

### 2.3.2. `config/` — Live-Build Configuration
- **`bootloaders/`**: Boot assets for GRUB in EFI and PC modes, incl. a branded splash image.
- **`hooks/live/`**: **Ordered** `*.chroot` hooks implementing system configuration and hardening during image creation; the numeric prefixes dictate execution (e.g., `0000_basic_chroot_setup.chroot`, `0810_chrony_setup.chroot`, `0900_ufw_setup.chroot`, `9930_hardening_ssh.chroot`, `9950_fail2ban_hardening.chroot`).
- **`includes.binary/boot/grub/`**: Static GRUB configuration embedded in the binary image (`config.cfg`).
- **`includes.chroot/`**: Files copied into the live system’s root:
  - `etc/` (APT configuration, `live/`, `modprobe.d/`, network, SSH, `sysctl.d/`, systemd drop-ins, banners),
  - `preseed/` (installer preseeding and supporting artifacts),
  - `root/` (administrator dotfiles and keys).
- **`package-lists/`**: Architecture-specific and common package manifests (`amd64`, `arm64`, `common`) used by `live-build`.

### 2.3.3. `docs/` — Documentation Corpus
Audit reports (DNSSEC, Lynis, SSH, TLS, Haveged), **BOOTPARAMS**, **CHANGELOG**, **CODING_CONVENTION**, **CONTRIBUTING**, **REFERENCES**; plus `SECURITY/`, `LICENSES/`, architecture diagrams under `graphviz/`, and illustrative `screenshots/`.

### 2.3.4. `lib/` — Shell Library Modules
Composable, single-purpose modules used by the wrapper and CI steps (argument parsing and validation, kernel/CPU mitigation checks, provider support, `lb config/build` scaffolding, usage/version banners, sanitization and traps, SSH/root-password hardening, ultra-hardening profile, etc.).

### 2.3.5. `scripts/` — Operational Helpers
Ancillary scripts for DHCP supersedes, resolver bootstrapping, and live-boot verification; targeted paths such as `scripts/etc/network/` and `scripts/live-boot/` encapsulate deploy-time adjustments and integrity checks.

### 2.3.6. `var/` — Variables & Defaults
Layered variable sets (`early.var.sh`, `global.var.sh`, `bash.var.sh`, `color.var.sh`) providing early-boot defaults, global tuning, and TTY/UI niceties.

## 2.4. Key Files

- **`ciss_live_builder.sh`** — Primary entrypoint; orchestrates argument parsing, environment preparation, `lb config`/`lb build` execution and post-processing.
- **`makefile`** & **`config.mk.sample`** — Make-based convenience wrapper and a sample configuration surface.
- **`README.md`, `SECURITY.md`, `LICENSE`, `CISS.debian.live.builder.spdx`** — Project overview, security policy, licensing, and SPDX manifest for compliance.
- **ISO markers**: `LIVE_ISO.public`, `LIVE_ISO_TRIXIE_{0,1}.private` reflect CI pipeline outputs.

## 2.5. Conventions & Build Logic

- **Hook Ordering**: Numeric prefixes (`0000_…` → `99xx_…`) strictly determine execution sequencing within `config/hooks/live/`. Early hooks establish base state (initramfs modules, checksums), mid-range hooks integrate security services (AppArmor, Chrony/NTPsec, Lynis, UFW, Fail2Ban, SSH auditing), late hooks enforce hardening and cleanup (SSH tightening, memory-dump policies, service disablement).
- **Binary vs. Chroot Includes**: Assets under `includes.binary/` affect the ISO’s bootloader stage; `includes.chroot/` become part of the runtime filesystem.
- **Architecture Scoping**: Package lists are split into `*amd64*`, `*arm64*`, and `*common*` to keep images minimal and deterministic.
- **CI/CD**: Reproducible ISO builds are executed via Gitea workflows; dedicated `trigger/` manifests parameterize public vs. private images and auxiliary rendering jobs (e.g., DNSSEC status, Graphviz diagrams).

## 2.6. Cross-References (Documentation)

- **Boot Parameters**: see `docs/BOOTPARAMS.md`.
- **Audits**: `docs/AUDIT_*.md` (DNSSEC, Lynis, SSH, TLS, Haveged).
- **Coding & Contribution**: `docs/CODING_CONVENTION.md`, `docs/CONTRIBUTING.md`.
- **Change Log & References**: `docs/CHANGELOG.md`, `docs/REFERENCES.md`.

## 2.7. Licensing & Compliance

The repository is **SPDX-compliant**; source files carry SPDX identifiers. See `CISS.debian.live.builder.spdx` and `LICENSE` for details.

---
**[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 -->