diff --git a/README.md b/README.md index 952ac33..b94fc90 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ include_toc: true [![Static Badge](https://badges.coresecret.dev/badge/shellformat-passed-white?style=plastic&logo=google&logoColor=white&logoSize=auto&label=shellformat&color=%234285F4)](https://github.com/mvdan/sh)   [![Static Badge](https://badges.coresecret.dev/badge/Shellstyle-Google-white?style=plastic&logo=google&logoColor=white&logoSize=auto&label=Shellstyle&color=%234285F4)](https://google.github.io/styleguide/shellguide.html)   -[![Static Badge](https://badges.coresecret.dev/badge/Gitea-1.24.2-white?style=plastic&logo=gitea&logoColor=white&logoSize=auto&label=gitea&color=%23609926)](https://docs.gitea.com/)   +[![Static Badge](https://badges.coresecret.dev/badge/Gitea-1.24.5-white?style=plastic&logo=gitea&logoColor=white&logoSize=auto&label=gitea&color=%23609926)](https://docs.gitea.com/)   [![Static Badge](https://badges.coresecret.dev/badge/IntelliJ-2025.2-white?style=plastic&logo=intellijidea&logoColor=white&logoSize=auto&label=IntelliJ&color=%23000000)](https://www.jetbrains.com/store/?section=personal&billing=yearly)   [![Static Badge](https://badges.coresecret.dev/badge/keepassxc-2.7.10-white?style=plastic&logo=keepassxc&logoColor=white&logoSize=auto&label=KeePassXC&color=%236CAC4D)](https://keepassxc.org/)   [![Static Badge](https://badges.coresecret.dev/badge/netcup-Netcup-white?style=plastic&logo=netcup&logoColor=white&logoSize=auto&label=powered&color=%23056473)](https://www.netcup.com/de)   @@ -70,7 +70,16 @@ separate directory tree, employs `DynamicUser` features, and adheres to strict s rating of **``2.6``**). Docker containers used by runners do not run in privileged mode. Security is further enhanced through the use of both UFW software firewalls and dedicated hardware firewall appliances. -## 1.2. Immutable Source-of-Truth System +## 1.2. Match Host and Target Versions + +Build, for example, a Debian Trixie live image only on a Debian Trixie host. The build toolchain and boot artifacts are +release-specific: ``live-build``, ``live-boot``, ``live-config``, ``debootstrap``, ``kernel/initramfs`` tools, ``mksquashfs``, +``GRUB/ISOLINUX``, and even ``dpkg/apt`` often change defaults and formats between releases (e.g., compression modes, SquashFS +options, hook ordering, systemd/udev behavior). Building on a different host release commonly yields non-reproducible or even +unbootable ISOs (missing modules/firmware, ABI mismatches, divergent paths). Keeping host and target on the same version ensures +reproducible builds, matching dependencies, and compatible boot artifacts. + +## 1.3. Immutable Source-of-Truth System This live ISO establishes a secure, fully deterministic, integrity self-verifying boot environment based entirely on static source-code definitions. All configurations, system components, and installation routines are embedded during build time and @@ -103,11 +112,11 @@ After build and configuration, the following audit reports can be generated: * **SSH Audit Report**: Verifies SSH daemon configuration against the latest best-practice cipher, KEX, and MAC recommendations. Type `ssh-audit :`. See example report: **[SSH Audit Report](/docs/AUDIT_SSH.md)** -## 1.3. Preview +## 1.4. Preview ![CISS.debian.live.builder](/docs/screenshots/CISS.debian.live.builder_preview.jpeg) -## 1.4. Caution. Significant information for those considering using D-I. +## 1.5. Caution. Significant information for those considering using D-I. **The Debian Installer (d-i) will ALWAYS boot a new system.**
@@ -138,7 +147,7 @@ This means function status of the **CISS.2025.debian.live.builder** ISO after d- * Logging (rsyslog, journald) ✘ not active, * preseed control over the network is possible (but without any protection). -## 1.5. Versioning Schema +## 1.6. Versioning Schema This project adheres strictly to a structured versioning scheme following the pattern x.y.z-Date. @@ -149,7 +158,7 @@ Example: `V8.13.008.2025.08.22` Date (YYYY.MM.DD) denotes the build or release date, facilitating clear tracking of incremental changes and ensuring reproducibility and traceability. -## 1.6. Keywords +## 1.7. Keywords The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this Repo are to be interpreted as described in [[BCP 14](https://www.rfc-editor.org/info/bcp14)], @@ -420,20 +429,21 @@ predictable script behavior. # 5. Installation & Usage -# 5.1. Interactive CLI / Dialog Wrapper +## 5.1. Interactive CLI / Dialog Wrapper 1. Clone the repository: - ```bash git clone https://git.coresecret.dev/msw/CISS.debian.live.builder.git cd CISS.debian.live.builder ``` + 2. Preparation: 1. Ensure you are root. 2. Create the build directory `mkdir /opt/livebuild`. 3. Place your desired SSH public key in the `authorized_keys` file, for example, in the `/opt/gitea/CISS.debian.live.builder` directory. 4. Place your desired Password in the `password.txt` file, for example, in the `/opt/gitea/CISS.debian.live.builder` directory. 5. Make any other changes you need to. + 3. Run the config builder script `./ciss_live_builder.sh` and the integrated `lb build` command (example): ````bash @@ -454,6 +464,7 @@ predictable script behavior. --ssh-pubkey /opt/gitea/CISS.debian.live.builder \ --trixie ```` + 4. Locate your ISO in the `--build-directory`. 5. Boot from the ISO and login to the live image via the console, or the multi-layer secured **coresecret** SSH tunnel. 6. Type `sysp` for the final kernel hardening features. @@ -461,7 +472,45 @@ predictable script behavior. 8. Finally, audit your environment with `lsadt` for a comprehensive Lynis audit. 9. Type `celp` for some shortcuts. -# 5.2. CI/CD Gitea Runner Workflow Example +## 5.2. Make Wrapper, Quick Usage + +This repo ships a thin make wrapper around ``./ciss_live_builder.sh``, so you can compose a correctly quoted command and either +preview it or run it. + +1. Clone the repository: + + ```bash + git clone https://git.coresecret.dev/msw/CISS.debian.live.builder.git + cd CISS.debian.live.builder + ``` + +2. Preparation: + 1. Ensure you are root. + 2. Create the build directory `mkdir /opt/livebuild`. + 3. Place your desired SSH public key in the `authorized_keys` file, for example, in the `/opt/gitea/CISS.debian.live.builder` directory. + 4. Place your desired Password in the `password.txt` file, for example, in the `/opt/gitea/CISS.debian.live.builder` directory. + 5. Copy and edit the sample and set your options (no spaces around commas in lists): + + ````bash + cp config.mk.sample config.mk + ```` + + ````bash + BUILD_DIR=/opt/livebuild + ROOT_PASSWORD_FILE=/opt/gitea/CISS.debian.live.builder/password.txt + SSH_PORT=4242 + SSH_PUBKEY=/root/.ssh + + # Optional + PROVIDER_NETCUP_IPV6=2001:cdb::1 + JUMP_HOSTS=[2001:db8::1],[2001:db8::2] # comma-separated; IPv6 in [] is fine + ```` + +3. Dry-run first (prints the exact command): ````bash make dry-run```` + +4. Execute the build: ````bash make live```` + +## 5.3. CI/CD Gitea Runner Workflow Example 1. Clone the repository: