CISS.debian.live.builder/REPOSITORY.md

Table of Contents

• 1. CISS.debian.live.builder
• 2.1. Repository Structure
• 2.2. Top-Level Layout
• 2.3. Directory Semantics
• 2.3.1. .gitea/ — CI/CD Orchestration
• 2.3.2. config/ — Live-Build Configuration
• 2.3.3. docs/ — Documentation Corpus
• 2.3.4. lib/ — Shell Library Modules
• 2.3.5. scripts/ — Operational Helpers
• 2.3.6. var/ — Variables & Defaults
• 2.4. Key Files
• 2.5. Conventions & Build Logic
• 2.6. Cross-References (Documentation)
• 2.7. Licensing & Compliance

1. CISS.debian.live.builder

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

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.400.2025.11.08 (as of 2025-10-11)

2.2. Top-Level Layout

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_hardening_fail2ban.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