From 0e131e31626029560d18592c99e4495a069578a5 Mon Sep 17 00:00:00 2001 From: Miguel Lozano Date: Mon, 16 Nov 2026 18:11:56 -0500 Subject: [PATCH] docs: align validation scope, supported systems and wording - Replace Production Ready with scoped production status and validation scope - Restrict supported systems to Debian 12 and Ubuntu 22.04 - Map to NIST 800-53 and CIS instead of claiming compliance - Describe Tailscale as a private mesh; cite NIST SP 800-207 by its official title - Document SOPS + age as the secrets mechanism - Reorder README closing sections and fix contact role - Updated GLOSSARY.md to clarify terminology and definitions, including changes to Zero Trust and Private Mesh. - Revised README.md to specify the framework's alignment with NIST 800-53 for Debian 12 and Ubuntu 22.04. - Modified ARCHITECTURE.md to reflect the updated compliance mapping and architectural details, including the removal of references to unsupported OS versions. - Adjusted LAYER_BOUNDARIES.md to align with the current OS support and architecture. - Enhanced ADR-05.md with an amendment regarding the scope of supported OS versions. - Updated COMPLIANCE-MAPPING-STATUS.md to clarify the status of various compliance frameworks and their implementation. - Revised INDEX.md to reflect the updated terminology regarding NIST SP 800-207. - Adjusted NIST_800_53.md to clarify compliance status and related documents. - Updated PRODUCTION_ACCEPTANCE.md to specify validation criteria for production readiness. - Revised FINOPS-BASELINE.md to clarify metrics and impacts of the transition to self-hosted solutions. - Adjusted BACKUP_STRATEGY.md to clarify the scope of the backup engine. - Updated COMPATIBILITY_MATRIX.md to reflect the current state of OS support and testing. - Revised DEVELOPER_SETUP.md to clarify common issues and resolutions. - Updated ROADMAP.md to reflect changes in planned releases and future implementations. - Adjusted DEVELOPER_WORKSTATION_GUIDE.md to reflect the shift from Zero Trust to Private Mesh model. - Revised HARDENING-STATUS.md to clarify the security baseline for developer and operator workstations. --- .ansible-lint | 2 +- .yamllint | 2 +- CHANGELOG.md | 4 + CONTRIBUTING.md | 4 +- README.md | 211 ++++++++++-------- docs/GLOSSARY.md | 16 +- docs/README.md | 2 +- docs/architecture/ARCHITECTURE.md | 38 ++-- docs/architecture/LAYER_BOUNDARIES.md | 6 +- docs/architecture/adr/ADR-05.md | 4 + docs/compliance/COMPLIANCE-MAPPING-STATUS.md | 24 +- docs/compliance/INDEX.md | 2 +- docs/compliance/NIST/NIST_800_53.md | 12 +- .../evidence/PRODUCTION_ACCEPTANCE.md | 2 +- docs/finops/FINOPS-BASELINE.md | 17 +- docs/operations/BACKUP_STRATEGY.md | 2 +- docs/operations/COMPATIBILITY_MATRIX.md | 25 +-- docs/operations/DEVELOPER_SETUP.md | 12 +- docs/project/ROADMAP.md | 10 +- docs/security/DEVELOPER_WORKSTATION_GUIDE.md | 6 +- docs/security/HARDENING-STATUS.md | 2 +- 21 files changed, 210 insertions(+), 193 deletions(-) diff --git a/.ansible-lint b/.ansible-lint index 58ad8cb..6893637 100644 --- a/.ansible-lint +++ b/.ansible-lint @@ -1,4 +1,4 @@ -# ansible-lint configuration for NIST-Compliant Hardening Suite +# ansible-lint configuration for Developmi Hardened --- profile: moderate diff --git a/.yamllint b/.yamllint index dfa6f88..da472f3 100644 --- a/.yamllint +++ b/.yamllint @@ -1,4 +1,4 @@ -# yamllint configuration for NIST-Compliant Hardening Suite +# yamllint configuration for Developmi Hardened --- extends: default diff --git a/CHANGELOG.md b/CHANGELOG.md index c3dcdcc..1a5d47e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,10 @@ status: active ## [Unreleased] +### Changed + +- Documentation: validation scope rewritten (production on up to 2 Brain and 10 Muscle nodes; 3 Brain / 30 Muscle scale test in progress), supported systems restricted to Debian 12 and Ubuntu 22.04, standards described as "mapped to" instead of "compliant", Tailscale described as a private mesh, and README closing sections reordered. + ## [8.0.0] - 2026-11-05 ### Added diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fa170e0..0b1d2d6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,9 +6,9 @@ audience: contributor status: complete --- -# Contributing to NIST-Compliant Hardening Suite +# Contributing to Developmi Hardened -Thank you for your interest in contributing to the NIST-Compliant Hardening Suite! This document provides guidelines and instructions for contributing. +Thank you for your interest in contributing to Developmi Hardened! This document provides guidelines and instructions for contributing. ## Code of Conduct diff --git a/README.md b/README.md index 9d4f50f..b671c4a 100644 --- a/README.md +++ b/README.md @@ -4,52 +4,78 @@ # Developmi Hardened -_A layered infrastructure stack built with Ansible, Docker and Zero Trust principles._ +_A layered infrastructure stack built with Ansible, Docker and private mesh access._ ![Version 8.0.0](https://img.shields.io/badge/Version-8.0.0-0A84FF?style=for-the-badge&logo=semver&logoColor=white) ![Python 3.14](https://img.shields.io/badge/Python-3.14-3776AB?style=for-the-badge&logo=python&logoColor=white) ![Ansible Core 2.21.1](https://img.shields.io/badge/Ansible_Core-2.21.1-EE0000?style=for-the-badge&logo=ansible&logoColor=white) ![Docker Ready](https://img.shields.io/badge/Docker-Ready-2496ED?style=for-the-badge&logo=docker&logoColor=white) -![Standard NIST 800-53](https://img.shields.io/badge/Standard-NIST_800--53-0B5CAD?style=for-the-badge) -![Status Production Ready](https://img.shields.io/badge/Status-Production_Ready-brightgreen?style=for-the-badge) +![Mapped to NIST 800-53](https://img.shields.io/badge/Mapped_to-NIST_800--53-0B5CAD?style=for-the-badge) +![Status: production (validated scope below)]() ![License MIT](https://img.shields.io/badge/License-MIT_Β©-blue?style=for-the-badge) ![CI GitHub Actions](https://img.shields.io/badge/CI-GitHub_Actions-blue?style=for-the-badge&logo=githubactions&logoColor=white) ![Maintainer Miguel Lozano](https://img.shields.io/badge/Maintainer-Miguel_Lozano-black?style=for-the-badge) -![Role Cloud & Infrastructure Engineer](https://img.shields.io/badge/Role-Cloud_%26_Infrastructure_Engineer-black?style=for-the-badge) +![Role Infrastructure & DevSecOps Consultant](https://img.shields.io/badge/Role-Infrastructure_%26_DevSecOps_Consultant-black?style=for-the-badge) -> **The script is free. Peace of mind is not.** +> **Status:** production (validated scope below) > -> This repository delivers a reproducible hardening baseline, zero-trust access patterns, and optional containerized application bundles for managed infrastructure. +> This repository provides a reproducible hardening baseline, private mesh access patterns and optional containerized application bundles. --- ## Table of Contents -- [Overview](#overview) -- [Features](#features) -- [Value Snapshot for CTO/CFO](#value-snapshot-for-ctocfo) -- [FinOps Field Case Study](#finops-field-case-study) -- [Field Validation Evidence](#field-validation-evidence) -- [Compliance & Standards](#compliance--standards) -- [Quick Start](#quick-start) -- [Operations with Make](#operations-with-make) -- [Architecture](#architecture) -- [Docker & Deployment](#docker--deployment) -- [Configuration & Secrets](#configuration--secrets) -- [Validation & Quality Gates](#validation--quality-gates) -- [Tests](#-tests) -- [Security](#-security) -- [Changelog](#-changelog) -- [Contributing](#-contributing) -- [License](#-license) -- [Documentation Guide](#documentation-guide) -- [Contact & Support](#contact--support) +- [Developmi Hardened](#developmi-hardened) + - [Table of Contents](#table-of-contents) + - [🎯 Overview](#-overview) + - [✨ Features](#-features) + - [πŸ’Ό Value Snapshot for CTO/CFO](#-value-snapshot-for-ctocfo) + - [πŸ’° FinOps Field Case Study](#-finops-field-case-study) + - [Business problem](#business-problem) + - [Implemented approach](#implemented-approach) + - [Measured outcomes (reported case)](#measured-outcomes-reported-case) + - [βœ… Validation Scope](#-validation-scope) + - [Tested](#tested) + - [Not tested or not confirmed](#not-tested-or-not-confirmed) + - [Deployment proof screenshots](#deployment-proof-screenshots) + - [πŸ“š Compliance \& Standards](#-compliance--standards) + - [Primary control coverage](#primary-control-coverage) + - [Where to audit compliance details](#where-to-audit-compliance-details) + - [⚑ Quick Start](#-quick-start) + - [Prerequisites](#prerequisites) + - [Setup](#setup) + - [Inventory](#inventory) + - [Secrets](#secrets) + - [Deploy](#deploy) + - [πŸ› οΈ Operations with Make](#️-operations-with-make) + - [High-frequency operator commands](#high-frequency-operator-commands) + - [Advanced and safety workflows](#advanced-and-safety-workflows) + - [πŸ—οΈ Architecture](#️-architecture) + - [Simplified Tree](#simplified-tree) + - [Execution Flow](#execution-flow) + - [🐳 Docker \& Deployment](#-docker--deployment) + - [Deploy Applications](#deploy-applications) + - [Security Notes](#security-notes) + - [πŸ”§ Configuration \& Secrets](#-configuration--secrets) + - [Core Secrets Template](#core-secrets-template) + - [Optional Observability Values](#optional-observability-values) + - [App Configuration](#app-configuration) + - [πŸ§ͺ Tests](#-tests) + - [1. Quality Gates \& Linting](#1-quality-gates--linting) + - [2. Integration Testing with Molecule](#2-integration-testing-with-molecule) + - [3. CI/CD \& Security Audit Pipelines](#3-cicd--security-audit-pipelines) + - [πŸ“– Documentation](#-documentation) + - [πŸ”’ Security](#-security) + - [πŸ“‹ Changelog](#-changelog) + - [🀝 Contributing](#-contributing) + - [πŸ“„ License](#-license) + - [πŸ“¬ Contact \& Support](#-contact--support) --- -## Overview +## 🎯 Overview Developmi Hardened is an Ansible-based infrastructure automation project focused on establishing a secure, auditable, and repeatable baseline across mixed-host environments. @@ -59,14 +85,14 @@ It is designed to standardize the security posture of: - **Muscle nodes** for workload execution and optional edge services. - **Application stacks** under `apps/` are operator-managed and deploy first-class via native Docker Compose (`git pull` + `docker compose up` on `public_net`); Portainer (Edge agent) is an optional manager when `enable_portainer: true` (ADR-07). -The project aligns to **NIST 800-53** controls and emphasizes secrets handling, least privilege, hardened networking, and operational repeatability. +The project is mapped to **NIST 800-53** controls and emphasizes secrets handling, least privilege, hardened networking, and operational repeatability. --- -## Features +## ✨ Features - πŸ›‘οΈ **Security-first hardening** with SSH restrictions, firewall controls, audit logging, CrowdSec integration, and SOPS + age encrypted secrets. -- πŸ” **Zero-trust networking** through Tailscale ACL-driven access and minimized public exposure. +- πŸ” **Private mesh networking** through Tailscale ACL-driven access and minimized public exposure. - 🧱 **Modular architecture** using Ansible roles for security, Docker orchestration, observability, compliance, ingress, and Portainer edge operations. - πŸ“¦ **Optional application bundles** for Chatwoot, Metabase, n8n, NocoDB, OpenWebUI, Twenty CRM, Uptime Kuma, and FastAPI (community template). - πŸ“ˆ **Operational visibility** with exporter and observability stack support when capacity allows. @@ -75,19 +101,19 @@ The project aligns to **NIST 800-53** controls and emphasizes secrets handling, --- -## Value Snapshot for CTO/CFO +## πŸ’Ό Value Snapshot for CTO/CFO In less than 30 seconds: - **Cost Control:** Designed for self-hosted operation on VPS/Bare Metal to avoid linear SaaS cost growth. -- **Security Baseline:** NIST-aligned hardening with zero-trust networking and auditable controls. +- **Security Baseline:** Hardening mapped to NIST controls with private mesh networking (Tailscale) and auditable controls. - **Data Sovereignty:** Sensitive workloads stay in infrastructure you control. - **Cloud-Exit Ready:** Portable Ansible playbooks and provider-agnostic architecture reduce lock-in. - **Operational Predictability:** Pull-based management model and Make-driven runbooks reduce change risk. --- -## FinOps Field Case Study +## πŸ’° FinOps Field Case Study This project pattern has been applied to a real-world sovereign cloud-exit migration scenario focused on data sovereignty, security, and OpEx reduction. @@ -106,24 +132,32 @@ This project pattern has been applied to a real-world sovereign cloud-exit migra ### Measured outcomes (reported case) -| Metric | Before (SaaS Sprawl) | After (Sovereign Self-Hosted) | Impact | -| ---------------------- | -------------------- | ----------------------------- | ------------------------- | -| Annual Software OpEx | $X (baseline) | $0.3X | **-70%** | -| Platform Uptime (Prod) | ~99.5% | 99.8% | Higher reliability | -| Data Sovereignty | 0% | 100% | Full control | -| Vendor Risk | Critical | Negligible | Supply-chain risk reduced | +| Metric | Before (SaaS Sprawl) | After (Sovereign Self-Hosted) | Impact | +| ---------------------- | -------------------- | --------------------------------------- | ------------------------- | +| Annual Software OpEx | $X (baseline) | $0.3X | **-70%** | +| Platform Uptime (Prod) | ~99.5% | 99.8% | Higher reliability | +| Data Sovereignty | Third-party hosted | Self-hosted on dedicated infrastructure | Direct control | +| Vendor Risk | Critical | Reduced | Supply-chain risk reduced | -> **Scope note:** This case study is a field implementation narrative and not a vendor benchmark report. Results depend on workload, architecture, and governance discipline. +> **Scope note:** This case study is a field implementation narrative and not a vendor benchmark report. Results depend on workload, architecture, and governance discipline. Figures come from the reported case; supporting records are not published in this repository. --- -## Field Validation Evidence +## βœ… Validation Scope -The platform architecture and hardening suite are **Production Ready**, validated across active production operations and staged topologies: +Validated in production on up to 2 Brain and 10 Muscle nodes across Oracle Cloud, AWS, Azure and GCP, on AMD64 and ARM64. A scale test to 3 Brain and 30 Muscle is in progress and not yet confirmed. -- **Production Reference Fleet**: 1 Management Node (`brain-1`) + 1 Compute Worker Node (`muscle-1`) in active operation. -- **Multi-Node Staging & Lab Validation**: Multi-node cluster topology validated across 1 Brain + 2 Muscle nodes. -- **Automated Verification**: Multi-layer Molecule verification suite (`L1_os_baseline`, `L2_compliance`, `L3_observability`, `L4_networking`, `backup`) tested on Debian 12 (`bookworm`) and Ubuntu 22.04 (`jammy`). +### Tested + +- Up to 2 Brain and 10 Muscle nodes +- Cloud providers: Oracle Cloud, AWS, Azure, GCP +- Architectures: AMD64, ARM64 +- Operating systems: Debian 12, Ubuntu 22.04 + +### Not tested or not confirmed + +- Scale test to 3 Brain and 30 Muscle nodes (in progress, not yet confirmed) +- Any operating system other than Debian 12 and Ubuntu 22.04 ### Deployment proof screenshots @@ -133,15 +167,15 @@ The platform architecture and hardening suite are **Production Ready**, validate --- -## Compliance & Standards +## πŸ“š Compliance & Standards This repository is not just "NIST-themed". It includes implementation-grounded compliance references with auditable mappings and evidence workflows. ### Primary control coverage - **NIST SP 800-53:** AC-2, CM-7, SC-7, SI-4, AU-12, and SC-28 (partial for full disk encryption). -- **NIST SP 800-207 (Zero Trust):** overlay-network control path, identity/tag-based access, and pull-based management pattern. -- **CIS Level 1 (generic Ubuntu/Debian alignment):** SSH baseline, firewall posture, brute-force mitigation, and audit telemetry. +- **NIST SP 800-207 (Zero Trust Architecture):** used as a reference for the Tailscale overlay design (identity/tag-based access, pull-based management). The project does not claim to implement a zero trust architecture. +- **CIS Level 1 (mapped to generic Ubuntu/Debian benchmarks):** SSH baseline, firewall posture, brute-force mitigation, and audit telemetry. - **DORA/ENS contextual mapping:** documented as technical-functional alignment for resilience and governance discussions. ### Where to audit compliance details @@ -153,7 +187,7 @@ This repository is not just "NIST-themed". It includes implementation-grounded c --- -## Quick Start +## ⚑ Quick Start ### Prerequisites @@ -214,7 +248,7 @@ make run PLAYBOOK=playbooks/l3/stack.yml TAGS='l3-observability,stack' --- -## Operations with Make +## πŸ› οΈ Operations with Make Make is the official command interface for this project. Day-to-day operations should run through Make targets. @@ -253,7 +287,7 @@ Operational reference index: --- -## Architecture +## πŸ—οΈ Architecture ### Simplified Tree @@ -290,13 +324,13 @@ The role structure is intentionally separated so security controls, Docker orche --- -## Docker & Deployment +## 🐳 Docker & Deployment Docker is used for application stacks and observability services, not as the primary automation runtime. ### Deploy Applications -All 8 application profiles (Chatwoot, Metabase, n8n, NocoDB, OpenWebUI, Twenty CRM, Uptime Kuma, FastAPI) deploy as Docker Compose stacks from structured profiles under `apps/`, rendered by the L6 runtime. Compose does not depend on Portainer (ADR-07): with the optional manager enabled (`enable_portainer: true`), the same stacks can be managed through Portainer's UI (Edge agent); with the default `enable_portainer: false`, a compose-only deploy needs zero `portainer_*` variables. See [ARCHITECTURE.md Β§Application Profiles](docs/architecture/ARCHITECTURE.md#application-profiles) for the full schema. +All 8 application profiles (Chatwoot, Metabase, n8n, NocoDB, OpenWebUI, Twenty CRM, Uptime Kuma, FastAPI) deploy as Docker Compose stacks from structured profiles under `apps/`, rendered by the L6 runtime. Compose does not depend on Portainer (ADR-07): with the optional manager enabled (`enable_portainer: true`), the same stacks can be managed through Portainer's UI (Edge agent); with the default `enable_portainer: false`, a compose-only deploy needs no `portainer_*` variables. See [ARCHITECTURE.md Β§Application Profiles](docs/architecture/ARCHITECTURE.md#application-profiles) for the full schema. ### Security Notes @@ -307,7 +341,7 @@ All 8 application profiles (Chatwoot, Metabase, n8n, NocoDB, OpenWebUI, Twenty C --- -## Configuration & Secrets +## πŸ”§ Configuration & Secrets This project does not require a root `.env.example`. Runtime secrets are encrypted with SOPS + age and loaded transparently by the `community.sops` vars plugin from `group_vars/all/secrets.sops.yml` and `group_vars/all/managers/portainer.sops.yml` (the Tailscale auth/ACL keys remain in the Ansible Vault until expiry). Application-specific configuration is operator-managed via `apps//.env`, templated from `apps//.env.example`. See [ARCHITECTURE.md Β§App Profiles](docs/architecture/ARCHITECTURE.md#application-profiles) for the profile schema. @@ -343,15 +377,26 @@ Apps deploy as Compose stacks (optionally managed via Portainer). See [OPERATION --- -## Validation & Quality Gates +## πŸ§ͺ Tests + +This project enforces end-to-end quality and compliance verification through a multi-tiered test pipeline spanning static validation, pre-commit hygiene, idempotency checks, and automated role/layer integration testing via **Molecule**: + +### 1. Quality Gates & Linting -The repository is validated through uv-managed tooling and Ansible-native checks. +The repository is validated through uv-managed tooling and Ansible-native checks. Validate syntax, role structure, YAML formatting, and GitHub Actions security workflows locally: ```bash +# Bootstrap toolchain and pre-commit hooks +make setup make sync make install-collections make check-toolchain + +# Run strict linting suite (yamllint + ansible-lint 26.6.0 + zizmor) +make lint make lint PLAYBOOK=playbooks/site.yml + +# Execute all pre-commit hooks make precommit-run ``` @@ -364,27 +409,6 @@ Current quality gates include: > **Operational note:** `make lint` is intentionally strict and should be used before changes are promoted to shared environments. ---- - -## πŸ§ͺ Tests - -This project enforces end-to-end quality and compliance verification through a multi-tiered test pipeline spanning static validation, pre-commit hygiene, idempotency checks, and automated role/layer integration testing via **Molecule**: - -### 1. Quality Gates & Linting - -Validate syntax, role structure, YAML formatting, and GitHub Actions security workflows locally: - -```bash -# Bootstrap toolchain and pre-commit hooks -make setup - -# Run strict linting suite (yamllint + ansible-lint 26.6.0 + zizmor) -make lint - -# Execute all pre-commit hooks -make precommit-run -``` - ### 2. Integration Testing with Molecule Automated role and layer testing is executed via [Molecule](https://molecule.readthedocs.io/) using the Docker driver against systemd-enabled Debian 12 (`bookworm`) and Ubuntu 22.04 (`jammy`) containers. Each scenario exercises the complete verification lifecycle (`dependency` β†’ `destroy` β†’ `syntax` β†’ `create` β†’ `prepare` β†’ `converge` β†’ `idempotence` β†’ `verify` β†’ `cleanup` β†’ `destroy`): @@ -408,6 +432,17 @@ make test-layer LAYER=L4_networking --- +## πŸ“– Documentation + +For the full documentation index including architecture, compliance, operations, and project docs, see [docs/README.md](docs/README.md). + +- [docs/architecture/ARCHITECTURE.md](docs/architecture/ARCHITECTURE.md) - System design and security layers +- [docs/operations/OPERATIONS_RUNBOOK.md](docs/operations/OPERATIONS_RUNBOOK.md) - Operational command reference +- [docs/compliance/COMPLIANCE-MAPPING-STATUS.md](docs/compliance/COMPLIANCE-MAPPING-STATUS.md) - Compliance framework status and mapping +- [CONTRIBUTING.md](CONTRIBUTING.md) - Contribution guide + +--- + ## πŸ”’ Security This project follows a coordinated disclosure policy. @@ -432,34 +467,16 @@ This project follows [Conventional Commits](https://www.conventionalcommits.org/ ## πŸ“„ License -Copyright Β© 2026 Miguel Lozano | Developmi. All rights reserved. +Copyright (c) 2026 Miguel Lozano | Developmi Licensed under the [MIT License](./LICENSE). --- -## Documentation Guide - -For the full documentation index including architecture, compliance, operations, and project docs, see [docs/README.md](docs/README.md). - ---- - -## Contact & Support +## πŸ“¬ Contact & Support - **Maintained by:** Miguel Lozano | Developmi -- **Role:** Cloud & Infrastructure Engineer | FinOps & Bare Metal Specialist | AI Sovereignty Strategist under NIST/DORA Standards +- **Role:** Infrastructure & DevSecOps Consultant - **Philosophy:** _Security is not a feature; it is the baseline._ - **Website:** [Developmi](https://developmi.com) - **GitHub:** [Miguel-DevOps](https://github.com/Miguel-DevOps) - **LinkedIn:** [Miguel Lozano](https://www.linkedin.com/in/miguel-dev-ops) - ---- - -Β© 2026 Miguel Lozano | Developmi. All rights reserved. - -## Related Documents - -- [docs/README.md](docs/README.md) - Documentation index -- [docs/architecture/ARCHITECTURE.md](docs/architecture/ARCHITECTURE.md) - System design and security layers -- [docs/operations/OPERATIONS_RUNBOOK.md](docs/operations/OPERATIONS_RUNBOOK.md) - Operational command reference -- [docs/compliance/COMPLIANCE-MAPPING-STATUS.md](docs/compliance/COMPLIANCE-MAPPING-STATUS.md) - Compliance framework status and mapping -- [CONTRIBUTING.md](CONTRIBUTING.md) - Contribution guide (redirect) diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md index 1e7068c..b3ef8e9 100644 --- a/docs/GLOSSARY.md +++ b/docs/GLOSSARY.md @@ -22,13 +22,13 @@ Terms defining how nodes are classified, hardened, and operated within the infra ### Core Terminology -| Term | Definition | -| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **make target** | A named Makefile command (e.g., `make deploy`, `make nuke`). The primary operator interface. | -| **overlay transport** | The policy requiring Tailscale VPN for non-bootstrap playbook operations (e.g., `engine.yml`, `exporters.yml`, `nuke.yml`). | -| **phase** | A deployment stage in the Makefile orchestration (Phase 0 through Phase 7). | -| **ponytail mode** | Lazy/YAGNI-first development mode. Enforces: stdlib before dependency, deletion over addition, shortest working diff. | -| **Zero Trust** | Security model where no actor is trusted by default. Enforced via Tailscale ACLs, overlay-only transport, and pull-based management. Aligned to NIST SP 800-207. | +| Term | Definition | +| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **make target** | A named Makefile command (e.g., `make deploy`, `make nuke`). The primary operator interface. | +| **overlay transport** | The policy requiring Tailscale VPN for non-bootstrap playbook operations (e.g., `engine.yml`, `exporters.yml`, `nuke.yml`). | +| **phase** | A deployment stage in the Makefile orchestration (Phase 0 through Phase 7). | +| **ponytail mode** | Lazy/YAGNI-first development mode. Enforces: stdlib before dependency, deletion over addition, shortest working diff. | +| **Private Mesh** | Network access model enforced via Tailscale ACLs, overlay-only transport, and pull-based management. Design informed by NIST SP 800-207 principles; not claimed as a zero trust architecture. | ### Host Classes & Profiles @@ -134,7 +134,7 @@ SOPS + age (`inventory/group_vars/all/secrets.sops.yml`, `make sops-*`) is the s | **NIST control** | Compliance | A specific security control from NIST SP 800-53 (e.g., AC-2, SC-7). | | **OpenTofu** | Toolchain | Open-source infrastructure-as-code tool (Terraform fork) used for Layer 0 provisioning. | | **Portainer** | Toolchain | Docker management UI using a pull-based Edge Agent architecture (zero open ports). | -| **Tailscale** | Toolchain | WireGuard-based zero-trust VPN mesh. Provides ACL-driven access with NAT traversal. | +| **Tailscale** | Toolchain | WireGuard-based private VPN mesh. Provides ACL-driven access with NAT traversal. | | **uv** | Toolchain | Python package manager. Used for all toolchain operations (sync, lint, playbook execution). | ### Evidence Paths diff --git a/docs/README.md b/docs/README.md index 06bf910..3b27a28 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,7 +18,7 @@ This folder centralizes project documentation by objective and operational domai ## Quick Start -The Developmi Hardened is an enterprise-grade Ansible hardening framework for NIST-aligned Debian and Ubuntu infrastructure. If you're new: +The Developmi Hardened is an Ansible hardening framework mapped to NIST 800-53 for Debian 12 and Ubuntu 22.04 infrastructure. If you're new: - **I want to run this suite** β†’ Start with the [root README](../README.md), then [OPERATIONS_RUNBOOK.md](operations/OPERATIONS_RUNBOOK.md) - **I want to contribute** β†’ Start with [CONTRIBUTING.md](../CONTRIBUTING.md) diff --git a/docs/architecture/ARCHITECTURE.md b/docs/architecture/ARCHITECTURE.md index 998d2c9..884cab7 100644 --- a/docs/architecture/ARCHITECTURE.md +++ b/docs/architecture/ARCHITECTURE.md @@ -13,7 +13,7 @@ repo: github.com/Developmi/hardened # Architecture Overview - Developmi Hardened v6.0.0 The Developmi Hardened is a multi-layer Linux hardening and application deployment framework built on Ansible. -It transforms vanilla Debian/Ubuntu servers into NIST 800-53 compliant bastion hosts +It transforms vanilla Debian/Ubuntu servers into bastion hosts mapped to NIST 800-53 with a 7-layer architecture that cleanly separates infrastructure provisioning (L0, private), OS hardening (L1-L4), application profiles (L5), and runtime adapters (L6). @@ -167,17 +167,17 @@ Layers MUST NOT reach across trust boundaries: ### OS Capability Table -| Capability | Ubuntu 22.04 (amd64) | Ubuntu 22.04 (arm64) | Ubuntu 24.04 (amd64) | Ubuntu 24.04 (arm64) | Debian 11 (amd64) | Debian 11 (arm64) | Debian 12 (amd64) | Debian 12 (arm64) | -| --------------------- | -------------------- | -------------------- | -------------------- | -------------------- | ------------------- | ------------------- | ------------------- | ------------------- | -| Package Manager | βœ… apt | βœ… apt | βœ… apt | βœ… apt | βœ… apt | βœ… apt | βœ… apt | βœ… apt | -| Update/Hold Policies | βœ… Full | βœ… Full | βœ… Full | βœ… Full | βœ… Full | βœ… Full | βœ… Full | βœ… Full | -| Auto-upgrade Checker | βœ… Full | βœ… Full | βœ… Full | βœ… Full | βœ… Full | βœ… Full | βœ… Full | βœ… Full | -| NIST 800-53 Hardening | βœ… Full | βœ… Full | βœ… Full | βœ… Full | βœ… Full | βœ… Full | βœ… Full | βœ… Full | -| CIS Benchmarks | βœ… Full | βœ… Full | βœ… Full | βœ… Full | ⚠️ Minor delta | ⚠️ Minor delta | ⚠️ Minor delta | ⚠️ Minor delta | -| Firewall | βœ… ufw | βœ… ufw | βœ… ufw | βœ… ufw | ⚠️ nftables wrapper | ⚠️ nftables wrapper | ⚠️ nftables wrapper | ⚠️ nftables wrapper | -| CrowdSec Enforcement | βœ… Full | βœ… Full | βœ… Full | βœ… Full | βœ… Full | βœ… Full | βœ… Full | βœ… Full | -| fail2ban | βœ… Full | βœ… Full | βœ… Full | βœ… Full | βœ… Full | βœ… Full | βœ… Full | βœ… Full | -| Kernel Hardening | βœ… Full | βœ… Full | βœ… Full | βœ… Full | βœ… Full | βœ… Full | βœ… Full | βœ… Full | +| Capability | Ubuntu 22.04 (amd64) | Ubuntu 22.04 (arm64) | Debian 12 (amd64) | Debian 12 (arm64) | +| --------------------- | -------------------- | -------------------- | ------------------- | ------------------- | +| Package Manager | βœ… apt | βœ… apt | βœ… apt | βœ… apt | +| Update/Hold Policies | βœ… Full | βœ… Full | βœ… Full | βœ… Full | +| Auto-upgrade Checker | βœ… Full | βœ… Full | βœ… Full | βœ… Full | +| NIST 800-53 Hardening | βœ… Full | βœ… Full | βœ… Full | βœ… Full | +| CIS Benchmarks | βœ… Full | βœ… Full | ⚠️ Minor delta | ⚠️ Minor delta | +| Firewall | βœ… ufw | βœ… ufw | ⚠️ nftables wrapper | ⚠️ nftables wrapper | +| CrowdSec Enforcement | βœ… Full | βœ… Full | βœ… Full | βœ… Full | +| fail2ban | βœ… Full | βœ… Full | βœ… Full | βœ… Full | +| Kernel Hardening | βœ… Full | βœ… Full | βœ… Full | βœ… Full | #### Architecture Columns (AMD64 / ARM64 - Ampere) @@ -190,8 +190,8 @@ Layers MUST NOT reach across trust boundaries: | Delta | Affected OS | Resolution | | --------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Firewall backend: ufw vs nftables | Debian 11/12 | Variable dispatcher: `os_firewall_backend: "{{ 'nftables' if ansible_os_family == 'Debian' and ansible_distribution_major_version == '12' else 'ufw' }}"` - role dispatches via `ansible.builtin.include_tasks: "{{ os_firewall_backend }}_rules.yml"` | -| CIS minor deltas | Debian 11/12 | Documented in `docs/compliance/NIST/INDEX.md` - Debian CIS benchmarks have minor structural differences from Ubuntu. Tagged `cis,debian-delta`. | +| Firewall backend: ufw vs nftables | Debian 12 | Variable dispatcher: `os_firewall_backend: "{{ 'nftables' if ansible_os_family == 'Debian' and ansible_distribution_major_version == '12' else 'ufw' }}"` - role dispatches via `ansible.builtin.include_tasks: "{{ os_firewall_backend }}_rules.yml"` | +| CIS minor deltas | Debian 12 | Documented in `docs/compliance/NIST/INDEX.md` - Debian CIS benchmarks have minor structural differences from Ubuntu. Tagged `cis,debian-delta`. | | ARM64 image availability | All | Every app profile MUST declare `supported_arch`. Playbook validates host arch ∈ profile's `supported_arch` before deploy. All base OS + infra components (Docker, Caddy, CrowdSec, Tailscale, Portainer) are multi-arch verified. | | OCI killswitch | Ubuntu 22.04 (OCI) | Required for Oracle Cloud nodes only. Detected at `gather_facts` time, dispatched conditionally. Not applicable to Debian or non-OCI targets. | @@ -237,7 +237,7 @@ hardening_profile: server - **`server`**: Full server hardening - in-kernel nftables firewall (`policy drop`), fail2ban brute-force protection, CrowdSec collaborative threat intelligence, VictoriaMetrics/Grafana observability stack, Restic backup automation. -The dispatcher is configured per host class in `group_vars/{brain,muscle}/main.yml` and defaults globally to `server` in `group_vars/all/main.yml`. Developer and operator workstation security follows a Zero Trust model outside Ansible management (see [DEVELOPER_WORKSTATION_GUIDE.md](../security/DEVELOPER_WORKSTATION_GUIDE.md)). +The dispatcher is configured per host class in `group_vars/{brain,muscle}/main.yml` and defaults globally to `server` in `group_vars/all/main.yml`. Developer and operator workstation security follows a private mesh model outside Ansible management (see [DEVELOPER_WORKSTATION_GUIDE.md](../security/DEVELOPER_WORKSTATION_GUIDE.md)). --- @@ -250,7 +250,7 @@ The dispatcher is configured per host class in `group_vars/{brain,muscle}/main.y | 3 | **Principle 3: Automation beats documentation** | Document by executing. Manual runbooks are code smells - automate first, document second. | Pre-flight assertions validate secrets and `supported_arch` before deploy. Zero manual validation steps. Compliance evidence is auto-collected to `/srv/evidence/nist//`. | | 4 | **Principle 4: Sovereignty beats convenience** | Keep control of your data and infrastructure. Avoid vendor lock-in that erodes autonomy. | Variable-driven OS dispatch (`os_firewall_backend`) instead of vendor-specific conditionals. Mandatory AMD64/ARM64 compatibility table prevents architecture lock-in. Tailscale OAuth-only ACL automation - no long-lived API tokens. | | 5 | **Principle 5: Evidence beats assertion** | Every compliance claim must be backed by machine-collected evidence, not human statements. | NIST 800-53 controls trace to Ansible task tags β†’ evidence files at `/srv/evidence/nist//`. `compliance.yml` playbook auto-collects evidence. `compliance/evidence/EVIDENCE_MODEL.md` documents the chain. | -| 6 | **Principle 6: Boring technology beats novel technology** | Prefer proven, widely-adopted tools. Novelty adds risk, not value. | Ansible (agentless, YAML, 10+ years). Docker Compose (every operator knows it). PostgreSQL (battle-tested). Caddy (simpler than nginx for reverse proxy). No custom DSLs, no framework lock-in. | +| 6 | **Principle 6: Boring technology beats novel technology** | Prefer proven, widely-adopted tools. Novelty adds risk, not value. | Ansible (agentless, YAML, 10+ years). Docker Compose (every operator knows it). PostgreSQL (proven, mature). Caddy (simpler than nginx for reverse proxy). No custom DSLs, no framework lock-in. | | 7 | **Principle 7: One operator, one runbook, 03:00** | A single tired operator at 3 AM must understand and fix any issue with ONE document. | Six-layer variable hierarchy makes overrides discoverable by path alone. Tag conventions separate functional, compliance, and layer concerns. Layer boundaries are explicit - an app profile never reaches into host config. | | 8 | **Principle 8: Layers don't reach across boundaries** | Each layer promises a contract. It never bypasses the layer below or above it. | L5 (app profiles) defines `what` to run; L6 (runtime) defines `how`. Profile schema contains zero Compose-specific directives. Engine (Compose) and Manager (Portainer) are independent axes - removing Portainer doesn't break Compose stacks. | | 9 | **Principle 9: Open core, not open-washing** | L1–L6 are genuinely OpenSource. L0 (provisioning, cloud) is private infrastructure - clearly documented as out of scope, never teased as "coming soon." | L0 documented as "Commercial Infra (IaC) - outside OpenSource scope, reference only." `apps/fastapi/` marked "community-provided" with explicit user config requirements. No hidden enterprise tiers. | @@ -311,8 +311,6 @@ Target Host: /srv/evidence/nist// | ------------------------------ | ------------ | -------------- | ----------------------------------------------------------------------------------------------- | | **OS - Debian 12** | βœ… Supported | βœ… Supported | ARM64 tested on Oracle Ampere A1 instances | | **OS - Ubuntu 22.04** | βœ… Supported | βœ… Supported | ARM64 tested on Oracle Ampere A1 instances | -| **OS - Ubuntu 24.04** | βœ… Supported | βœ… Supported | ARM64 tested on Oracle Ampere A1 instances | -| **OS - Debian 11** | βœ… Supported | βœ… Supported | ARM64 tested on Oracle Ampere A1 instances | | **Docker Engine** | βœ… Supported | βœ… Supported | Same version on both architectures; `docker.com` apt repo is multi-arch | | **Portainer BE** | βœ… Supported | βœ… Supported | Official multi-arch Docker image | | **Caddy** | βœ… Supported | βœ… Supported | Official binary is multi-arch (Go-compiled) | @@ -374,7 +372,7 @@ Determined by `group_vars/{brain,muscle}/main.yml`. A host's inventory group mem ### Operational Scale & Sizing Boundaries -This repository is engineered under the **"Boring is Better"** philosophy: providing enterprise-grade security hardening (NIST SP 800-53, CIS OS/Docker benchmarks, kernel confinement, Zero Trust networking via Tailscale, and automated Restic disaster recovery) directly on Bare Metal hosts or VPS instances without requiring Kubernetes. +This repository is engineered under the **"Boring is Better"** philosophy: providing security hardening (mapped to NIST SP 800-53 and CIS benchmarks, kernel confinement, private mesh networking via Tailscale, and automated Restic disaster recovery) directly on Bare Metal hosts or VPS instances without requiring Kubernetes. #### Hardware Profiles & Node Allocation @@ -397,7 +395,7 @@ Routing topology and secrets adhere to strict separation of concerns: - **Routing Catalog** (`inventory/group_vars/all/ingress.yml`): Plain YAML catalog of domains, upstreams, headers, and security profiles. Ignored by `.gitignore` to prevent leaking private client infrastructure in open-source environments (template provided in `ingress.yml.example`). - **Cryptographic Secrets** (`inventory/group_vars/all/secrets.sops.yml`): Strictly reserved for sensitive credentials (TLS private keys in `cloudflare_origin_certs`, `caddy_ui_token`, R2 access keys). -- **Ingress Template** (`roles/L4_networking/caddy/templates/Caddyfile.j2`): 100% data-driven, version-controlled Jinja2 template with zero hardcoded values, featuring automatic global `metrics` export and per-service WAF/TLS client routing. +- **Ingress Template** (`roles/L4_networking/caddy/templates/Caddyfile.j2`): data-driven, version-controlled Jinja2 template without hardcoded values, featuring automatic global `metrics` export and per-service WAF/TLS client routing. --- diff --git a/docs/architecture/LAYER_BOUNDARIES.md b/docs/architecture/LAYER_BOUNDARIES.md index 04bad43..cd7e915 100644 --- a/docs/architecture/LAYER_BOUNDARIES.md +++ b/docs/architecture/LAYER_BOUNDARIES.md @@ -77,7 +77,7 @@ external prerequisite. ### Provides To -- **L1 (OS Baseline)** - running hosts with SSH access, OS pre-installed (Ubuntu 22.04/24.04, Debian 11/12), architecture declared. +- **L1 (OS Baseline)** - running hosts with SSH access, OS pre-installed (Debian 12, Ubuntu 22.04), architecture declared. ### Trust Level @@ -135,7 +135,7 @@ L1 MUST detect the host architecture (amd64/arm64) and make it available as ### Depends On -- **L0** - a running host with SSH access, pre-installed OS (Ubuntu 22.04/24.04, Debian 11/12). +- **L0** - a running host with SSH access, pre-installed OS (Debian 12, Ubuntu 22.04). ### Provides To @@ -481,7 +481,7 @@ installation and configuration (`roles/L6_runtime/docker_compose/`), compose ren The Engine (Compose default, Swarm/K3s future) and Manager (none or Portainer BE) are **independent axes**. Compose MUST NEVER depend on Portainer. A -deployment without Portainer is 100% valid and functional. +deployment without Portainer is valid and functional. L6 also owns `roles/L6_runtime/backup/` - which protects both runtime state (Portainer configs, compose state, manager metadata) and application data (DB dumps, app configs). diff --git a/docs/architecture/adr/ADR-05.md b/docs/architecture/adr/ADR-05.md index 7eebeb8..991e2da 100644 --- a/docs/architecture/adr/ADR-05.md +++ b/docs/architecture/adr/ADR-05.md @@ -63,3 +63,7 @@ Each role dispatches to the correct backend: - [../ARCHITECTURE.md](../ARCHITECTURE.md) - OS Support Matrix, AMD64/ARM64 compatibility - [../LAYER_BOUNDARIES.md](../LAYER_BOUNDARIES.md) - L1 OS Baseline contract + +--- + +Amendment (2026-11-16): scope narrowed to Debian 12 and Ubuntu 22.04. diff --git a/docs/compliance/COMPLIANCE-MAPPING-STATUS.md b/docs/compliance/COMPLIANCE-MAPPING-STATUS.md index 76da9f6..ee29279 100644 --- a/docs/compliance/COMPLIANCE-MAPPING-STATUS.md +++ b/docs/compliance/COMPLIANCE-MAPPING-STATUS.md @@ -38,21 +38,21 @@ This master document serves as the Single Source of Truth (SSOT) and consolidate The suite provides technical implementation controls and evidence generation for the following frameworks: -| Framework | Version / Revision | Status | Applicable Controls / Scope | Controls Covered | Controls Pending | Evidence Collection | -| ------------------- | ------------------------------------------ | -------------------------------- | ---------------------------------------------------------------------------------- | ---------------- | ---------------- | ---------------------- | -| **NIST SP 800-53** | Rev 5 | Fully mapped / Implemented | AC-2, CM-7, SC-7, SI-4, AU-12, SC-28 | 5/6 | SC-28 (partial) | Yes - per control | -| **NIST SP 800-207** | Final | Implemented | Zero Trust Architecture overlay transport, identity/policy-based segmentation | - | - | - | -| **CIS Benchmarks** | Ubuntu 22.04 LTS v2.0.0 / Debian 12 v1.0.0 | Mapped per Ansible role | SSH hardening, UFW/nftables posture, sysctl tuning, filesystem permissions | - | - | Yes - role-level | -| **DORA** | EU 2022/2554 | Mapped at architectural level | ICT risk management, incident reporting, digital operational resilience testing | - | - | No | -| **ENS** | RD 311/2022 | Technical-functional equivalence | Medium category: access control (op.acc), protection (op.exp), monitoring (op.mon) | - | - | Yes - via NIST overlap | -| **MITRE ATT&CK** | v15 | Defensive controls mapped | Defense evasion (T1562), privilege escalation (T1068), persistence (T1547) | - | - | - | -| **SOC 2 Type II** | - | Stub - not yet implemented | CC6.1, CC6.6, CC7.1, CC7.2 (overlapping with NIST controls) | 0 | All | No | +| Framework | Version / Revision | Status | Applicable Controls / Scope | Controls Covered | Controls Pending | Evidence Collection | +| ------------------- | ------------------------------------------ | -------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------- | ---------------- | ---------------------- | +| **NIST SP 800-53** | Rev 5 | Mapped / Implemented | AC-2, CM-7, SC-7, SI-4, AU-12, SC-28 | 5/6 | SC-28 (partial) | Yes - per control | +| **NIST SP 800-207** | Final | Reference | Zero Trust Architecture; used as reference for Tailscale overlay design (not claimed as zero trust architecture) | - | - | - | +| **CIS Benchmarks** | Ubuntu 22.04 LTS v2.0.0 / Debian 12 v1.0.0 | Mapped per Ansible role | SSH hardening, UFW/nftables posture, sysctl tuning, filesystem permissions | - | - | Yes - role-level | +| **DORA** | EU 2022/2554 | Mapped at architectural level | ICT risk management, incident reporting, digital operational resilience testing | - | - | No | +| **ENS** | RD 311/2022 | Technical-functional equivalence | Medium category: access control (op.acc), protection (op.exp), monitoring (op.mon) | - | - | Yes - via NIST overlap | +| **MITRE ATT&CK** | v15 | Defensive controls mapped | Defense evasion (T1562), privilege escalation (T1068), persistence (T1547) | - | - | - | +| **SOC 2 Type II** | - | Stub - not yet implemented | CC6.1, CC6.6, CC7.1, CC7.2 (overlapping with NIST controls) | 0 | All | No | ### 2.1 Mapping Status Definitions | Status | Definition | | ------------------------------------ | ------------------------------------------------------------------------------------------------- | -| **Fully mapped / Implemented** | Every applicable control has a corresponding Ansible role with task tags and evidence generation | +| **Mapped / Implemented** | Every applicable control has a corresponding Ansible role with task tags and evidence generation | | **Mapped per Ansible role** | Controls are implemented by specific roles; evidence is role-level, not framework-level | | **Mapped at architectural level** | The platform design addresses the framework requirements; specific controls may not be enumerated | | **Technical-functional equivalence** | Controls are satisfied by equivalent technical measures, not 1:1 mapping | @@ -93,12 +93,14 @@ Evidence output follows a per-control hierarchy under `/srv/evidence/nist/ [!NOTE] -> Reference: [NIST SP 800-207](https://csrc.nist.gov/pubs/sp/800/207/final) +> Reference: [NIST SP 800-207 (Zero Trust Architecture)](https://csrc.nist.gov/pubs/sp/800/207/final) ### 3.3 NIST SP 800-171 (Controlled Unclassified Information) diff --git a/docs/compliance/INDEX.md b/docs/compliance/INDEX.md index 0c5e62c..6229b8f 100644 --- a/docs/compliance/INDEX.md +++ b/docs/compliance/INDEX.md @@ -22,7 +22,7 @@ The Single Source of Truth for all framework mappings, control definitions, and > πŸ“˜ **[COMPLIANCE-MAPPING-STATUS.md](COMPLIANCE-MAPPING-STATUS.md)** -Please refer to that document for the complete coverage matrix and implementation status of **NIST SP 800-53**, **NIST SP 800-207 (Zero Trust)**, **CIS Benchmarks**, **DORA**, **ENS**, **MITRE ATT&CK**, and **SOC 2 Type II**. +Please refer to that document for the complete coverage matrix and implementation status of **NIST SP 800-53**, **NIST SP 800-207 (Zero Trust Architecture)**, **CIS Benchmarks**, **DORA**, **ENS**, **MITRE ATT&CK**, and **SOC 2 Type II**. --- diff --git a/docs/compliance/NIST/NIST_800_53.md b/docs/compliance/NIST/NIST_800_53.md index d27b2f7..daf20fe 100644 --- a/docs/compliance/NIST/NIST_800_53.md +++ b/docs/compliance/NIST/NIST_800_53.md @@ -51,17 +51,17 @@ Evidence output follows a per-control hierarchy under `/srv/evidence/nist/ Source: [README.md](../../README.md) - FinOps Field Case Study -| Metric | Before (SaaS Sprawl) | After (Sovereign Self-Hosted) | Impact | -| ---------------------- | -------------------- | ----------------------------- | ------------------------- | -| Annual Software OpEx | $X (baseline) | $0.3X | **-70%** | -| Platform Uptime (Prod) | ~99.5% | 99.8% | Higher reliability | -| Data Sovereignty | 0% | 100% | Full control | -| Vendor Risk | Critical | Negligible | Supply-chain risk reduced | - -This is a field implementation narrative, not a vendor benchmark. Results depend on workload, -architecture, and governance discipline. +| Metric | Before (SaaS Sprawl) | After (Sovereign Self-Hosted) | Impact | +| ---------------------- | -------------------- | --------------------------------------- | ------------------------- | +| Annual Software OpEx | $X (baseline) | $0.3X | **-70%** | +| Platform Uptime (Prod) | ~99.5% | 99.8% | Higher reliability | +| Data Sovereignty | Third-party hosted | Self-hosted on dedicated infrastructure | Direct control | +| Vendor Risk | Critical | Reduced | Supply-chain risk reduced | + +> **Scope note:** This case study is a field implementation narrative and not a vendor benchmark report. Results depend on workload, architecture, and governance discipline. Figures come from the reported case; supporting records are not published in this repository. --- diff --git a/docs/operations/BACKUP_STRATEGY.md b/docs/operations/BACKUP_STRATEGY.md index 41b08fa..85302c8 100644 --- a/docs/operations/BACKUP_STRATEGY.md +++ b/docs/operations/BACKUP_STRATEGY.md @@ -18,7 +18,7 @@ Two-layer backup architecture for the Developmi Hardened platform, covering appl > ## ⚠️ Tier3 is out of scope (TIER-004) > -> The backup engine covers **Tier1** (guaranteed, image-discovered databases) and +> The backup engine covers **Tier1** (standard, image-discovered databases) and > **Tier2** (opt-in volumes declared in `backup.volumes[]`). **Tier3** is > explicitly **out of scope**: custom application configuration, arbitrary bind > mounts, and source/CI artifacts are **not** protected by the engine and it MUST diff --git a/docs/operations/COMPATIBILITY_MATRIX.md b/docs/operations/COMPATIBILITY_MATRIX.md index 05b937e..2800597 100644 --- a/docs/operations/COMPATIBILITY_MATRIX.md +++ b/docs/operations/COMPATIBILITY_MATRIX.md @@ -22,22 +22,16 @@ The matrix below reflects field-validated execution. Each platform has been depl ### Tested Platforms & Status -| OS / Distribution | Codename | Arch | Status | Verified Hosts | Provider | -| :---------------- | :------- | :---- | :--------------------- | :------------- | :------------ | -| Ubuntu 22.04 | jammy | amd64 | βœ… Supported | brain & muscle | Hetzner | -| Ubuntu 22.04 | jammy | arm64 | βœ… Supported | brain & muscle | Oracle Ampere | -| Ubuntu 24.04 | noble | amd64 | βœ… Partially Supported | brain & muscle | Hetzner | -| Ubuntu 24.04 | noble | arm64 | βœ… Partially Supported | brain & muscle | Oracle Ampere | -| Debian 12 | bookworm | amd64 | βœ… Supported | brain & muscle | Hetzner | -| Debian 12 | bookworm | arm64 | βœ… Supported | brain & muscle | Oracle Ampere | -| Debian 13 | trixie | amd64 | πŸ”² Planned | brain & muscle | Hetzner | -| Debian 13 | trixie | arm64 | πŸ”² Planned | brain & muscle | Oracle Ampere | +| OS / Distribution | Codename | Arch | Status | Verified Hosts | Provider | +| :---------------- | :------- | :---- | :----------- | :------------- | :------------ | +| Ubuntu 22.04 | jammy | amd64 | βœ… Supported | brain & muscle | Hetzner | +| Ubuntu 22.04 | jammy | arm64 | βœ… Supported | brain & muscle | Oracle Ampere | +| Debian 12 | bookworm | amd64 | βœ… Supported | brain & muscle | Hetzner | +| Debian 12 | bookworm | arm64 | βœ… Supported | brain & muscle | Oracle Ampere | **Status Legend:** -- **βœ… Supported:** Full playbook suite validated; idempotent and production-ready. -- **βœ… Partially Supported:** Core deployment path validated (`brain` and `muscle` roles tested successfully), but not every optional stack or edge scenario has completed validation. -- **πŸ”² Planned:** Repository mappings and package sources exist, but full validation has not yet been completed. +- **βœ… Supported:** Full playbook suite validated; idempotent (see validated scope in README). - **β›” Blocked:** Known incompatibility prevents successful deployment. ### OS Attributes & EOL Target Dates @@ -51,14 +45,13 @@ _(Note: Both distributions use AppArmor as the default security module.)_ ### Unsupported / Not Actively Tested -- **Ubuntu 20.04 (focal):** End of standard support lifecycle and not aligned with current hardening targets. -- **Debian 11 (bullseye):** Legacy compatibility may exist, but active validation and maintenance are not planned. +- Any operating system other than Debian 12 and Ubuntu 22.04 is not supported and not tested. --- ## 2. Architecture Support (AMD64 & ARM64) -Both major Linux server architectures (amd64 and arm64) are fully supported. The playbooks rely entirely on Ansible fact gathering for distribution, release codename, architecture, and kernel information, keeping the deployment flow architecture-agnostic. No architecture-specific playbook branching is required outside repository selection logic. +Both major Linux server architectures (amd64 and arm64) are supported. The playbooks rely entirely on Ansible fact gathering for distribution, release codename, architecture, and kernel information, keeping the deployment flow architecture-agnostic. No architecture-specific playbook branching is required outside repository selection logic. ### App Profile Pre-Flight Validation (L5) diff --git a/docs/operations/DEVELOPER_SETUP.md b/docs/operations/DEVELOPER_SETUP.md index 5cfa0e4..8f7404a 100644 --- a/docs/operations/DEVELOPER_SETUP.md +++ b/docs/operations/DEVELOPER_SETUP.md @@ -115,12 +115,12 @@ ssh "sysctl kernel.kptr_restrict" ## Common Issues -| Issue | Resolution | -| ------------------------------- | -------------------------------------------------------------------- | -| `ansible-core` version mismatch | `uv sync --reinstall-package ansible-core` | -| SOPS age key not found | Ensure `~/.config/sops/age/keys.txt` exists (see Step 3) | -| SSH connection refused | Target host must have SSH enabled. Verify with `ssh echo ok` | -| `uv sync` fails on ARM64 | ARM64 is fully supported. Ensure Python 3.14+ is installed for ARM64 | +| Issue | Resolution | +| ------------------------------- | ------------------------------------------------------------------- | +| `ansible-core` version mismatch | `uv sync --reinstall-package ansible-core` | +| SOPS age key not found | Ensure `~/.config/sops/age/keys.txt` exists (see Step 3) | +| SSH connection refused | Target host must have SSH enabled. Verify with `ssh echo ok` | +| `uv sync` fails on ARM64 | ARM64 is supported. Ensure Python 3.14+ is installed for ARM64 | --- diff --git a/docs/project/ROADMAP.md b/docs/project/ROADMAP.md index 39add2e..0420d24 100644 --- a/docs/project/ROADMAP.md +++ b/docs/project/ROADMAP.md @@ -27,8 +27,8 @@ This project starts at v6.0.0. Prior development history (v1.0.0 - v5.5.0) is ma - NIST-focused architecture remains consistent (`AC-2`, `CM-7`, `SC-7`, `SI-4`, `AU-12`, `SC-28` audit scope). - Security stack is cohesive: SSH hardening, UFW/fail2ban, CrowdSec, Tailscale, SOPS + age secrets workflow. - Operational playbooks (`playbooks/l6/engine.yml`, `playbooks/l3/exporters.yml`, `playbooks/ops/nuke.yml`) enforce Tailscale-only transport via `tailscale_subnet` source-of-truth variable. -- Observability deployment is fully automated end-to-end via Ansible and SOPS-encrypted secrets. -- Recommended app catalog now provides secure, Zero Trust-aligned deployment configurations for Chatwoot, Metabase, n8n, OpenWebUI, Twenty CRM, and Uptime Kuma. +- Observability deployment is automated end-to-end via Ansible and SOPS-encrypted secrets. +- Recommended app catalog now provides secure, private mesh-aligned deployment configurations for Chatwoot, Metabase, n8n, OpenWebUI, Twenty CRM, and Uptime Kuma. - **Caddy Node Isolation (v5.4.0)**: Per-node Caddyfile routing via `target_group ∩ group_names`. Three-layer variable model: SOPS (domains, certs, per-service `waf_mode`), inventory inline vars (`caddy_node_id` per host), group_vars (`caddy_type`, `caddy_admin_enabled` defaults). The legacy per-host `caddy_coraza_mode` was removed β€” nothing consumed it. - **Caddy WAF v3.2.1 Alignment (NEW)**: WAF upgraded from pinned v2 to Coraza v2.5.0 / OWASP CRS v4.28.0. WAF config (coraza.conf, CRS rules) now baked into container image at `/etc/caddy/`. Role no longer deploys host-side WAF config - just renders Caddyfile with correct snippet paths and validates per-service `waf_mode`. Healthcheck aligned to `pgrep caddy`. compose.yml.j2 streamlined (removed dead WAF bind mounts). - **APT Lock Detection (v5.3.0)**: Pre-flight lock detection using `fuser`/`pgrep` with auto-kill for stale processes (>15min) and `apt_force_cleanup=true` flag for deadlocked processes. Enhanced in v6.0.0-dev with stale lock file cleanup (empty/abandoned locks) and `changed_when: false` for idempotent runs. @@ -182,7 +182,7 @@ This project starts at v6.0.0. Prior development history (v1.0.0 - v5.5.0) is ma ### Planned Release Target -- `v8.0.0` - Production-ready bare metal & VPS hardening suite with native nftables, unified restic backup engine, decoupled ingress catalog, and zero-trust workstation baseline. +- `v8.0.0` - Bare metal & VPS hardening suite (validated scope in README) with native nftables, unified restic backup engine, decoupled ingress catalog, and private mesh workstation baseline. ## Future Implementations (Backlog) @@ -196,7 +196,7 @@ This project starts at v6.0.0. Prior development history (v1.0.0 - v5.5.0) is ma - [ ] Replace `pre-commit/mirrors-prettier` (archived mirror) with official Prettier distribution from `prettier/prettier` (MIT) via pinned `pnpm` execution in hooks (policy: no npm). - **Completed**: secrets lifecycle migrated from the transitional `ansible-vault` wrapper to the official and auditable key-management baseline (Mozilla SOPS + age/GPG), including key custody, rotation, and recovery controls. Remaining `ansible-vault` usage is limited to the Tailscale trio until gate D4 (OPERATIONS_RUNBOOK Β§7.4). - [ ] Support for advanced host metrics (`network_mode: host`) with dedicated segmentation, compensating controls, and NIST/CIS exception documentation. -- [ ] Improve cAdvisor zero-trust coverage on hardened Docker hosts (`userns-remap`) with explicit metric-tier profiles (strict, balanced, full) and documented tradeoffs per profile. +- [ ] Improve cAdvisor private mesh coverage on hardened Docker hosts (`userns-remap`) with explicit metric-tier profiles (strict, balanced, full) and documented tradeoffs per profile. - [ ] Add optional per-node cAdvisor enablement in inventory/group vars so hardened nodes can run Node Exporter only while keeping centralized scrape configuration clean. - [ ] Rename `tailscale_subnet` to a VPN-agnostic overlay variable (e.g. `management_overlay_subnet`) to support non-Tailscale overlays (Headscale, WireGuard, etc.) without requiring changes across multiple playbooks. `tailscale_subnet` would remain as an alias for backwards compatibility. Relevant controls: NIST `CM-6`, `SC-7`. - [ ] **Coraza full activation checklist**: After OWASP CRS tuning period on muscle nodes (DetectionOnly), documented activation procedure with per-service WAF bypass audit, false-positive triage runbook, and gradual rollout plan (muscle-1 β†’ muscle-2 β†’ all workers). @@ -243,7 +243,7 @@ Key v2 themes relevant to this roadmap: --- -Maintained by Miguel Lozano - Cloud Infrastructure Engineer & FinOps Specialist +Maintained by Miguel Lozano - Infrastructure & DevSecOps Consultant Last updated: 2026-07-23 ## Related Documents diff --git a/docs/security/DEVELOPER_WORKSTATION_GUIDE.md b/docs/security/DEVELOPER_WORKSTATION_GUIDE.md index c43ae76..b25608d 100644 --- a/docs/security/DEVELOPER_WORKSTATION_GUIDE.md +++ b/docs/security/DEVELOPER_WORKSTATION_GUIDE.md @@ -1,15 +1,15 @@ # Developer Workstation Security Baseline > **Security Standard** - Operator & Developer Endpoint Baseline for `developmi-platform` -> **Model**: Zero Trust (NIST SP 800-207) | **Scope**: macOS, Linux, Windows (WSL2) +> **Model**: Private Mesh (reference: NIST SP 800-207 Zero Trust Architecture) | **Scope**: macOS, Linux, Windows (WSL2) --- -## 1. Architectural Philosophy: Zero Trust Over Endpoint Push +## 1. Architectural Philosophy: Private Mesh Over Endpoint Push In `developmi-platform`, server infrastructure never trusts client workstations by default, and workstations are **not** managed via Ansible push playbooks over SSH. Laptops sleep, roam dynamic networks, and run diverse operating systems where server-grade kernel drops (`policy drop`, aggressive sysctl) break local developer experience (Docker Desktop, local test ports, debuggers). -Instead, security is enforced through **Zero Trust Network Access (ZTNA)** and **Hardware-Backed Cryptographic Identity**: +Instead, security is enforced through **Private Mesh Network Access (Tailscale)** and **Hardware-Backed Cryptographic Identity**: - The server cluster assumes client devices may be untrusted or compromised. - All access to server control planes and SSH is gated behind **Tailscale mesh ACLs**, MFA, and hardware security keys. diff --git a/docs/security/HARDENING-STATUS.md b/docs/security/HARDENING-STATUS.md index ba14af0..eb52f21 100644 --- a/docs/security/HARDENING-STATUS.md +++ b/docs/security/HARDENING-STATUS.md @@ -26,7 +26,7 @@ sets the server-grade hardening baseline: | ---------- | -------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Server** | `server` | brain, muscle | Full hardening: in-kernel nftables firewall (`policy drop`), fail2ban 1h bantime, CrowdSec enforcement, observability stack, and Restic backups enabled | -The dispatcher is set per host class in `inventory/group_vars/{brain,muscle}/main.yml`. Developer and operator workstation security follows a Zero Trust baseline outside Ansible management (see [DEVELOPER_WORKSTATION_GUIDE.md](DEVELOPER_WORKSTATION_GUIDE.md)). +The dispatcher is set per host class in `inventory/group_vars/{brain,muscle}/main.yml`. Developer and operator workstation security follows a private mesh baseline outside Ansible management (see [DEVELOPER_WORKSTATION_GUIDE.md](DEVELOPER_WORKSTATION_GUIDE.md)). ### Tag Conventions Used in Matrix