From 6125165833791ef0d93f2d4e4508c7148a4fd860 Mon Sep 17 00:00:00 2001 From: Tibo De Peuter Date: Tue, 17 Mar 2026 21:50:58 +0100 Subject: [PATCH] docs: add deployment and security documentation --- README.md | 64 ++++++++++++++++++++++++++++++++++++ SECURITY.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 157 insertions(+) create mode 100644 README.md create mode 100644 SECURITY.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..19f9892 --- /dev/null +++ b/README.md @@ -0,0 +1,64 @@ +# Bos55 NixOS Config + +Automated CI/CD deployment for NixOS homelab using `deploy-rs`. + +## Repository Structure + +- `hosts/`: Host-specific configurations. +- `modules/`: Shared NixOS modules. +- `users/`: User definitions (including the `deploy` user). +- `secrets/`: Encrypted secrets via `sops-nix`. + +## Deployment Workflow + +### Prerequisites +- SSH access to the `deploy` user on target hosts. +- `deploy-rs` installed locally (`nix profile install github:serokell/deploy-rs`). + +### Deployment Modes + +1. **Production Deployment (main branch):** + Triggered on push to `main`. Automatically builds and switches all hosts. bootloader is updated. + Manual: `deploy .` + +2. **Test Deployment (test- branch):** + Triggered on push to `test-`. Builds and activates the configuration on the specific host **without** updating the bootloader. Reboots will revert to the previous generation. + Manual: `deploy .#.test` + +3. **Kernel Upgrades / Maintenance:** + Use `deploy .#.system --boot` to update the bootloader without immediate activation, followed by a manual reboot. + +## Local Development + +### 1. Developer Shell +This repository includes a standardized development environment containing all necessary tools (`deploy-rs`, `sops`, `age`, etc.). +```bash +nix develop +# or if using direnv +direnv allow +``` + +### 2. Build a host VM +You can build a QEMU VM for any host configuration to test changes locally: +```bash +nix build .#nixosConfigurations..config.system.build.vm +./result/bin/run--vm +``` + +> [!WARNING] +> **Network Conflict**: Default VMs use user-mode networking (NAT) which is safe. However, if you configure the VM to use bridge networking, it will attempt to use the static IP defined in `hostIp`. Ensure you do not have a physical host with that IP active on the same bridge to avoid network interference. + +### 3. Run Integration Tests +Run the automated test suite: +```bash +nix-build test/vm-test.nix +``` + +### 3. Test CI Workflows Locally +Use `act` to test the GitHub Actions workflows: +```bash +act -W .github/workflows/check.yml +``` + +## Security +See [SECURITY.md](SECURITY.md) for details on the trust model and secret management. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..ca1c208 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,93 @@ +# Security and Trust Model + +This document outlines the security architecture, trust boundaries, and assumptions of the Bos55 NixOS deployment pipeline. This model is designed to support a multi-member infrastructure team and remains secure even if the repository is published publicly. + +## Trust Zones + +The system is partitioned into three distinct trust zones, each with specific controls to prevent lateral movement and privilege escalation. + +### 🔴 Zone 1: Trusted Maintainers (Source of Truth) +* **Actors:** Infrastructure Team / Maintainers. +* **Capabilities:** + * Full access to the Git repository. + * Ownership of `sops-nix` master keys (GPG or Age). + * Direct root access to NixOS hosts via personal SSH keys for emergency maintenance. +* **Trust:** Root of trust. All changes must originate from or be approved by a Trusted Maintainer. +* **Security Controls:** + * **Signed Commits:** All contributions must be cryptographically signed by a trusted GPG/SSH key to be eligible for deployment. + - **MFA:** Hardware-based multi-factor authentication for repository access. + - **Metadata Redaction:** Sensitive identifiers like SSH `authorizedKeys` are stored in `sops-nix`. This prevents **infrastructure fingerprinting**, where an attacker could link your public keys to your personal identities or other projects. + +### 🟡 Zone 2: CI/CD Pipeline (Automation Layer) +* **Actor:** GitHub Actions / Forgejo Runners. +* **Capabilities:** + * Builds Nix derivations from the repository. + * Access to the `DEPLOY_SSH_KEY` (allowing SSH access to the `deploy` user on target hosts). + * **Trusted Signers:** The public keys for verifying signatures are stored as a **Runner Secret** (`TRUSTED_SIGNERS`). This hides the identities of the infrastructure team even in a public repository. + * **NO ACCESS** to `sops-nix` decryption keys. Secrets remain encrypted during the build. +* **Security Controls:** + * **Signature Enforcement:** The `deploy.yml` workflow verifies the cryptographic signature of every maintainer commit. Deployment is aborted if the signature is missing or untrusted. + * **Sandboxing:** Runners execute in ephemeral, isolated containers. + * **Branch Protection:** Deployments to production (`main`) require approved Pull Requests. + * **Fork Protection:** CI workflows (and secrets) are explicitly disabled for forks. + +### 🟢 Zone 3: Target NixOS Hosts (Runtime) +* **Actor:** Production, Testing, and Service nodes. +* **Capabilities:** Decrypt secrets locally using host-specific `age` keys. +* **Trust:** Consumers of builds. They trust Zone 2 only for the pushing of store paths and triggering activation scripts. +* **Security Controls:** + * **Restricted `deploy` User:** The SSH user for automation is non-root. Sudo access is strictly policed via `sudoers` rules to allow only `nix-env` and `switch-to-configuration`. + * **Immutable Store:** Building on Nix ensures that the system state is derived from a cryptographically hashed store, preventing unauthorized local modifications from persisting across reboots. + +--- + +## Security Assumptions & Policies + +### 1. Public Repository Safety +The repository is designed to be safe for public viewing. No unencrypted secrets should ever be committed. The deployment pipeline is protected against "malicious contributors" via: +- **Mandatory PR Reviews:** No code can reach the `main` branch without peer review. +- **Secret Scoping:** Deployment keys are only available to authorized runs on protected branches. + +### 2. Supply Chain & Dependencies +- **Flake Lockfiles:** All dependencies (Nixpkgs, `deploy-rs`, etc.) are pinned to specific git revisions. +- **Renovate Bot:** Automated version upgrades allow for consistent tracking of upstream changes, though they require manual review or successful status checks for minor/patch versions. + +### 3. Signed Commit Enforcement +To prevent "force-push" attacks or runner compromises from injecting malicious code into the history, the pipeline should be configured to only deploy commits signed by a known "Trusted Maintainer" key. This ensures that even if a git account is compromised, the attacker cannot deploy code without the physical/cryptographic signing key. + +--- + +## Trust Boundary Diagram + +```mermaid +graph TD + subgraph "Zone 1: Trusted Workstations" + DEV["Maintainers (Team)"] + SOPS_KEYS["Master SOPS Keys"] + SIGN_KEYS["Signing Keys (GPG/SSH)"] + end + + subgraph "Zone 2: CI/CD Runner (Sandboxed)" + CI["Automated Runner"] + SSH_KEY["Deploy SSH Key"] + end + + subgraph "Zone 3: NixOS Target Hosts" + HOST["Target Host"] + HOST_AGE["Host Age Key"] + end + + DEV -- "Signed Push / PR" --> CI + CI -- "Push Store Paths & Activate" --> HOST + HOST_AGE -- "Local Decrypt" --> HOST + + style DEV fill:#f96,stroke:#333 + style CI fill:#ff9,stroke:#333 + style HOST fill:#9f9,stroke:#333 +``` + +## Security Best Practices for Maintainers + +1. **Keep Master Keys Offline:** Never store `sops-nix` master keys on the CI runner or public servers. +2. **Audit Runner Logs:** Periodically review CI execution logs for unexpected behavior. +3. **Rotate Deployment Keys:** Rotate the `DEPLOY_SSH_KEY` if maintainer membership changes significantly.