120 lines
8.0 KiB
Markdown
120 lines
8.0 KiB
Markdown
---
|
||
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.432.2025.11.18<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.432.2025.11.18** (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_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](https://coresecret.eu/)**
|
||
<!-- vim: set number et ts=2 sw=2 sts=2 ai tw=128 ft=markdown -->
|