From 4899c98ef706d75c51c740e1641cff5cf9c6bd17 Mon Sep 17 00:00:00 2001 From: Miguel Lozano Date: Sun, 1 Nov 2026 13:22:51 -0500 Subject: [PATCH 1/9] refactor(ingress): extract routing catalog from sops into dedicated ingress vars - Move ingress_services and ingress_security_profiles out of secrets.sops.yml.example - Provide neutral RFC 2606 templates in inventory/group_vars/all/ingress.yml.example - Add inventory/group_vars/all/ingress.yml to .gitignore to prevent client domain leakage - Define baseline ingress_security_profiles in inventory/group_vars/all/main.yml --- .gitignore | 3 +- inventory/group_vars/all/ingress.yml.example | 54 +++++++++++++++++++ inventory/group_vars/all/main.yml | 17 +++++- .../group_vars/all/secrets.sops.yml.example | 52 ++++-------------- 4 files changed, 82 insertions(+), 44 deletions(-) create mode 100644 inventory/group_vars/all/ingress.yml.example diff --git a/.gitignore b/.gitignore index 74a7c4f..58f02c5 100644 --- a/.gitignore +++ b/.gitignore @@ -66,7 +66,6 @@ override.tf.json # Caddyfile Caddyfile -Caddyfile.j2 # ================================================= # SSH Keys & Certificates # ================================================= @@ -121,6 +120,8 @@ inventory/hosts.ini.generated inventory/hosts.ini inventory/host_vars/*.yml !inventory/host_vars/*.example +inventory/group_vars/all/ingress.yml +!inventory/group_vars/all/ingress.yml.example # SOPS / age (secrets management) # Operator age private key - backed up offline; NEVER commit diff --git a/inventory/group_vars/all/ingress.yml.example b/inventory/group_vars/all/ingress.yml.example new file mode 100644 index 0000000..379e49c --- /dev/null +++ b/inventory/group_vars/all/ingress.yml.example @@ -0,0 +1,54 @@ +--- +# ============================================================================= +# Ingress Services & Security Profiles (Routing Catalog) +# ============================================================================= +# Single Source of Truth for reverse proxy routing (Caddy / Nginx / Traefik). +# Copy this file to inventory/group_vars/all/ingress.yml (ignored by .gitignore). +# +# PRIVACY & SECURITY: +# Domain names, upstreams, and routing topology are uncommitted configuration +# to protect client privacy in this open-source repository. +# Sensitive cryptographic secrets (TLS private keys, UI tokens) stay in +# inventory/group_vars/all/secrets.sops.yml (SOPS + age encrypted). +# +# VARIABLE OWNERSHIP (four layers - NEVER mix): +# Layer 1 | SOPS (secrets.sops.yml) → certs (privkeys), API keys, UI tokens +# Layer 2 | Ingress (ingress.yml) → domains, upstreams, routes, security profiles +# Layer 3 | Inventory (hosts.ini) → caddy_node_id, waf_mode_default (per host) +# Layer 4 | Group vars (brain/muscle) → caddy_type, caddy_admin_enabled (group defaults) +# ============================================================================= + +# Security profiles referenced by ingress_services[*].security_profile. +# Each profile toggles the WAF (Coraza) and VPN-only restriction. +# Default baseline profiles can also be overridden here. +ingress_security_profiles: + public_waf: + import_waf: true + import_vpn_only: false + + basicauth: + import_waf: false + import_vpn_only: false + + vpn_only: + import_waf: true + import_vpn_only: true + +# Routing catalog: one entry per domain Caddy must serve. +# Rendered by roles/L4_networking/caddy/templates/Caddyfile.j2. +# Filtered per node: target_group matching node group or caddy_node_id. +# Examples: "brain" | "muscle" | "muscle-1" | ["muscle-1", "brain-1"]. +ingress_services: + - name: app-example # label only - used in logs/warnings + domain: app.example.invalid # required - public hostname (RFC 2606) + upstream: app:8080 # required - container:port + client: client_primary # required - cert source; MUST exist in + # cloudflare_origin_certs in secrets.sops.yml + target_group: brain # required - routing filter (node group or ID) + security_profile: public_waf # required - MUST exist in ingress_security_profiles + tls_client_auth: cloudflare # optional - enables Cloudflare Origin Pull mTLS + proxy_headers: + standard: true # forward Host + X-Real-IP to the backend + websocket: false # true = bypass WAF for WebSocket upgrades + headers: + X-Custom-Header: "PLACEHOLDER_HEADER_VALUE" diff --git a/inventory/group_vars/all/main.yml b/inventory/group_vars/all/main.yml index cece1f4..7578dc2 100644 --- a/inventory/group_vars/all/main.yml +++ b/inventory/group_vars/all/main.yml @@ -197,9 +197,24 @@ caddy_admin_network_name: "caddy-admin-net" # Ingress routing catalog (single-tenant). Each entry maps a domain # to an upstream backend with WAF and cert isolation. -# Defined in the SOPS file: inventory/group_vars/all/secrets.sops.yml. +# Defined in inventory/group_vars/all/ingress.yml (see ingress.yml.example). ingress_services: [] +# Standard security profiles available to ingress services. +# Override or extend in inventory/group_vars/all/ingress.yml. +ingress_security_profiles: + public_waf: + import_waf: true + import_vpn_only: false + + basicauth: + import_waf: false + import_vpn_only: false + + vpn_only: + import_waf: true + import_vpn_only: true + # Default WAF mode for services without an explicit waf_mode. # enforcement: block violations (return 403) # detection_only: log violations but forward request (safe default for rollout) diff --git a/inventory/group_vars/all/secrets.sops.yml.example b/inventory/group_vars/all/secrets.sops.yml.example index cf030eb..fcbed70 100644 --- a/inventory/group_vars/all/secrets.sops.yml.example +++ b/inventory/group_vars/all/secrets.sops.yml.example @@ -123,50 +123,18 @@ cloudflare_origin_certs: # ============================================================================= -# INGRESS SERVICES (routing catalog) +# INGRESS SERVICES & SECURITY PROFILES (Decoupled to ingress.yml) # ============================================================================= -# Security profiles referenced by ingress_services[*].security_profile. -# Each profile toggles the WAF (Coraza) and the VPN-only restriction. -# Used by roles/L4_networking/caddy/tasks/main.yml:27 and -# roles/L4_networking/caddy/templates/Caddyfile.example.j2:142. -# Required by L4 deployment (preflight asserts it is defined). -ingress_security_profiles: - - public_waf: - import_waf: true - import_vpn_only: false - - basicauth: - import_waf: false - import_vpn_only: false - - vpn_only: - import_waf: true - import_vpn_only: true - -# Routing catalog: one entry per domain Caddy must serve. -# Rendered by roles/L4_networking/caddy/templates/Caddyfile.example.j2:135, -# preflight-checked in roles/L4_networking/caddy/tasks/main.yml:22. -# Overrides the default [] in inventory/group_vars/all/main.yml:185. -# Required by L4 deployment - an empty catalog aborts deployment. -# Add one entry per domain; target_group examples: "brain" | "muscle" | -# "muscle-1" | ["muscle-1", "brain-1"]. -ingress_services: - - - name: app-example # label only - used in logs/warnings - domain: app.example.invalid # required - public hostname - upstream: app:8080 # required - container:port - client: client_primary # required - cert source; MUST exist in - # cloudflare_origin_certs (path /etc/caddy/certs//) - target_group: brain # required - routing filter (see above) - security_profile: public_waf # required - MUST exist in ingress_security_profiles - tls_client_auth: cloudflare # optional - enables Cloudflare Origin Pull mTLS - proxy_headers: - standard: true # forward Host + X-Real-IP to the backend - websocket: true # true = bypass WAF for WebSocket upgrades - headers: - X-Custom-Header: "PLACEHOLDER_HEADER_VALUE" +# Ingress routing configuration (domains, upstreams, headers, security profiles) +# has been decoupled from secrets.sops.yml to protect client privacy in Git +# while keeping routing configuration as plain YAML. +# +# Define your routes in: +# inventory/group_vars/all/ingress.yml (copy from ingress.yml.example) +# +# Only cryptographic secrets (TLS cert private keys in cloudflare_origin_certs, +# caddy_ui_token, etc.) stay in this SOPS-encrypted file. # ============================================================================= From f17f5f44bd06153aaa14253881f18679db4787e4 Mon Sep 17 00:00:00 2001 From: Miguel Lozano Date: Sun, 1 Nov 2026 13:23:05 -0500 Subject: [PATCH 2/9] refactor(caddy): track unified Caddyfile template and remove example copy requirement - Promote Caddyfile.example.j2 to tracked SSOT template roles/L4_networking/caddy/templates/Caddyfile.j2 - Add global metrics directive aligned with upstream Developmi/caddy-waf - Update .dockerignore to align template exclusion patterns --- .dockerignore | 1 - .../{Caddyfile.example.j2 => Caddyfile.j2} | 19 +++++++++++-------- 2 files changed, 11 insertions(+), 9 deletions(-) rename roles/L4_networking/caddy/templates/{Caddyfile.example.j2 => Caddyfile.j2} (95%) diff --git a/.dockerignore b/.dockerignore index dbb211c..bce198d 100644 --- a/.dockerignore +++ b/.dockerignore @@ -30,7 +30,6 @@ inventory/hosts.mapping.yml # Sensitive templates (contain vault variable references) **/Caddyfile.j2 -**/Caddyfile.example.j2 # Local Development Tooling & Binaries tools/ diff --git a/roles/L4_networking/caddy/templates/Caddyfile.example.j2 b/roles/L4_networking/caddy/templates/Caddyfile.j2 similarity index 95% rename from roles/L4_networking/caddy/templates/Caddyfile.example.j2 rename to roles/L4_networking/caddy/templates/Caddyfile.j2 index ca99b3a..106287c 100644 --- a/roles/L4_networking/caddy/templates/Caddyfile.example.j2 +++ b/roles/L4_networking/caddy/templates/Caddyfile.j2 @@ -1,16 +1,16 @@ -# Caddyfile.example - L4_networking/caddy role (Single Source of Truth) -# Rendered from SOPS (secrets.sops.yml), filtered per-node via target_group ∩ group_names. +# Caddyfile.j2 - L4_networking/caddy role (Single Source of Truth) +# Rendered from inventory/group_vars/all/ingress.yml, filtered per-node via target_group ∩ group_names. # -# VARIABLE OWNERSHIP (three layers - NEVER mix): -# Layer 1 | SOPS (secrets.sops.yml) → domains, certs, routes, API keys -# Layer 2 | inventory (hosts.ini) → caddy_node_id, waf_mode_default (per host) -# Layer 3 | group_vars (brain|muscle) → caddy_type, caddy_admin_enabled (group defaults) +# VARIABLE OWNERSHIP (four layers - NEVER mix): +# Layer 1 | SOPS (secrets.sops.yml) → certs (privkeys), API keys, UI tokens +# Layer 2 | Ingress (ingress.yml) → domains, upstreams, routes, security profiles +# Layer 3 | inventory (hosts.ini) → caddy_node_id, waf_mode_default (per host) +# Layer 4 | group_vars (brain|muscle) → caddy_type, caddy_admin_enabled (group defaults) # # L4-NETWORKING / EDGE (SDD l4-networking-edge): # Per-client cert path: /etc/caddy/certs//fullchain.pem # ADR-04 - Hot-reload via docker exec caddy reload (no connection drops) # ADR-05 - Per-service WAF mode via waf_mode (enforcement | detection_only) -# SC-28 | All domains and upstreams live exclusively in the encrypted SOPS file. # SC-7 | Per-service security headers in site blocks. # SC-8 | TLS 1.2/1.3 enforced; HTTP→HTTPS redirect; Cloudflare Origin Pull supported. # AU-12 | D6 log pipeline: access + runtime + Coraza audit logs as FILES in @@ -65,6 +65,9 @@ order coraza_waf first order rate_limit before basicauth + # Enable Caddy HTTP metrics collection (caddy_http_*); served on the admin /metrics endpoint. + metrics + # AU-12 (D6) | Runtime/global log → FILE (Caddy internal events, NOT access logs). # Contract §7: single writer per stream; promtail scrapes /data/logs/caddy.log. # Native rotation: roll at 30MiB, keep 5 files, max 720h (30 days) per file. @@ -209,7 +212,7 @@ # ── Dynamic application routes (client-scoped cert paths) ───── # -# Example ingress_services entry in group_vars/all/secrets.sops.yml (SOPS): +# Example ingress_services entry in group_vars/all/ingress.yml: # # - name: my-app # domain: app.example.com From aa7d25a9dffa9249cf06f6e5881cad5e0d366205 Mon Sep 17 00:00:00 2001 From: Miguel Lozano Date: Sun, 1 Nov 2026 13:23:14 -0500 Subject: [PATCH 3/9] refactor(caddy): streamline edge playbook preflight and role ingress assertions - Remove controller-side Caddyfile.j2 existence check in playbooks/l4/edge.yml - Update preflight error message in roles/L4_networking/caddy/tasks/main.yml pointing to ingress.yml.example --- playbooks/l4/edge.yml | 36 ++++-------------------- roles/L4_networking/caddy/tasks/main.yml | 3 +- 2 files changed, 6 insertions(+), 33 deletions(-) diff --git a/playbooks/l4/edge.yml b/playbooks/l4/edge.yml index dcf826c..89cda0d 100644 --- a/playbooks/l4/edge.yml +++ b/playbooks/l4/edge.yml @@ -5,12 +5,11 @@ # Purpose: Deploy reverse proxy + WAF via L4_networking adapter. # Extracted from stacks.yml Play 2. # -# Controller-side preflight plays run BEFORE the remote play: they validate -# controller-local files (backend task file, Caddyfile.j2) using -# connection: local + become: false as PLAY keywords (never vars), mirroring -# playbooks/ops/bootstrap.yml. Tasks delegated to localhost with task-level -# become: false are fragile because an ansible_become var wins over task -# keywords (see ansible.cfg [privilege_escalation]). +# Controller-side preflight play runs BEFORE the remote play: validates +# controller-local files (backend task file) using connection: local + become: false +# as PLAY keywords (never vars), mirroring playbooks/ops/bootstrap.yml. Tasks +# delegated to localhost with task-level become: false are fragile because an +# ansible_become var wins over task keywords (see ansible.cfg [privilege_escalation]). # ============================================================================== - name: "L4 | Preflight - assert backend task file exists (controller side)" @@ -39,31 +38,6 @@ when: not _backend_task_file.stat.exists tags: [l4-networking] -- name: "L4 | Preflight - assert Caddyfile.j2 exists (controller side)" - hosts: all - connection: local - gather_facts: false - become: false - tags: [l4-networking, ingress] - - tasks: - - name: "Validate Caddyfile.j2 presence" - ansible.builtin.stat: - path: "{{ playbook_dir }}/../../roles/L4_networking/caddy/templates/Caddyfile.j2" - run_once: true - register: caddyfile_j2_stat - tags: [l4-networking, ingress] - - - name: "Fail if Caddyfile.j2 is missing" - ansible.builtin.fail: - msg: | - Caddyfile.j2 is missing! - Copy roles/L4_networking/caddy/templates/Caddyfile.example.j2 to Caddyfile.j2 - and adjust it for your deployment. - run_once: true - when: not caddyfile_j2_stat.stat.exists - tags: [l4-networking, ingress] - - name: "L4 | Networking & Edge - Reverse Proxy + WAF" hosts: "{{ target_group | default('muscle') }}" # gather_facts is required: the L4_networking role's cert-expiry validation diff --git a/roles/L4_networking/caddy/tasks/main.yml b/roles/L4_networking/caddy/tasks/main.yml index 70e496f..3903dd8 100644 --- a/roles/L4_networking/caddy/tasks/main.yml +++ b/roles/L4_networking/caddy/tasks/main.yml @@ -27,9 +27,8 @@ - ingress_security_profiles is defined fail_msg: >- ingress_services is empty or undefined. - SOPS secrets may not be decryptable or secrets.sops.yml is malformed. + Ensure inventory/group_vars/all/ingress.yml exists (copy from ingress.yml.example). Aborting to prevent deploying an empty Caddyfile. - Verify: make sops-view success_msg: "Ingress routing catalog is present - {{ ingress_services | length }} service(s) defined." tags: [l4-networking] From 15c9724d0927d9f5566b443e4640844107e325c3 Mon Sep 17 00:00:00 2001 From: Miguel Lozano Date: Sun, 1 Nov 2026 13:23:22 -0500 Subject: [PATCH 4/9] test(molecule): update L4 scenario contract to tracked Caddyfile and 0640 audit log mode - Render Caddyfile.j2 instead of obsolete example template in converge.yml - Update audit log mode assertion from 0644 to 0640 in verify.yml to match hardened task defaults --- molecule/L4_networking/converge.yml | 9 ++++----- molecule/L4_networking/verify.yml | 12 ++++++------ 2 files changed, 10 insertions(+), 11 deletions(-) diff --git a/molecule/L4_networking/converge.yml b/molecule/L4_networking/converge.yml index e8a1168..2c941e2 100644 --- a/molecule/L4_networking/converge.yml +++ b/molecule/L4_networking/converge.yml @@ -75,13 +75,12 @@ post_tasks: # --------------------------------------------------------------------------- - # Contract render: Caddyfile.example.j2 is the TRACKED SSOT (convention: live - # Caddyfile/Caddyfile.j2 are never tracked). Verify assertions run against - # this render so the contract test pins the tracked file, never the local one. + # Contract render: Caddyfile.j2 is the TRACKED SSOT. Verify assertions run against + # this render so the contract test pins the tracked file. # --------------------------------------------------------------------------- - - name: "Post | Render Caddyfile.example.j2 (tracked SSOT) for contract assertions" + - name: "Post | Render Caddyfile.j2 (tracked SSOT) for contract assertions" ansible.builtin.template: - src: ../../roles/L4_networking/caddy/templates/Caddyfile.example.j2 + src: ../../roles/L4_networking/caddy/templates/Caddyfile.j2 dest: "{{ app_base_dir }}/ingress/Caddyfile.contract" mode: "0644" diff --git a/molecule/L4_networking/verify.yml b/molecule/L4_networking/verify.yml index 5aa8786..1617bc9 100644 --- a/molecule/L4_networking/verify.yml +++ b/molecule/L4_networking/verify.yml @@ -151,7 +151,7 @@ # --------------------------------------------------------------------------- # CONTRACT: ui_managed overlay import contract (D2) # Mirrors caddy-waf-ui tests/integration/caddyfile_test.go assertions against - # the tracked SSOT render (Caddyfile.example.j2 -> Caddyfile.contract). + # the tracked SSOT render (Caddyfile.j2 -> Caddyfile.contract). # --------------------------------------------------------------------------- - name: "GIVEN: Slurp the contract-rendered Caddyfile" ansible.builtin.slurp: @@ -383,18 +383,18 @@ fail_msg: "SDD Failed: UI service depends_on must reference the compose SERVICE key 'caddy' (container_name is caddy-waf) with service_healthy" success_msg: "UI service depends_on caddy (service name) with service_healthy condition" - - name: "THEN: Audit log file exists with mode 0644" + - name: "THEN: Audit log file exists with mode 0640" ansible.builtin.stat: path: /opt/user/apps/testing/ingress/caddy-data/logs/coraza-audit.log register: audit_log_stat - - name: "THEN: Audit log mode is 0644 (UI can read)" + - name: "THEN: Audit log mode is 0640 (hardened)" ansible.builtin.assert: that: - audit_log_stat.stat.exists - - audit_log_stat.stat.mode == "0644" - fail_msg: "SDD Failed: audit log missing or mode is not 0644 (got {{ audit_log_stat.stat.mode | default('missing') }})" - success_msg: "Audit log exists with mode 0644" + - audit_log_stat.stat.mode == "0640" + fail_msg: "SDD Failed: audit log missing or mode is not 0640 (got {{ audit_log_stat.stat.mode | default('missing') }})" + success_msg: "Audit log exists with mode 0640" # --------------------------------------------------------------------------- # E2E ASSERTS (gated on ghcr images being present in local daemon) From fb2786928aabd3364962e56925c0401b6fe504db Mon Sep 17 00:00:00 2001 From: Miguel Lozano Date: Sun, 1 Nov 2026 13:23:29 -0500 Subject: [PATCH 5/9] docs(architecture): define operational scale boundaries and bare metal positioning - Document node sizing thresholds (1-5 Brain nodes, 50-100 Muscle workers) - Clarify Phase 1 bare metal and VPS hardening baseline prior to hyperscale K8s orchestration - Clarify configuration topology boundary between host variables and non-secret ingress catalog --- docs/architecture/ARCHITECTURE.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/architecture/ARCHITECTURE.md b/docs/architecture/ARCHITECTURE.md index 63beb16..8d7fc65 100644 --- a/docs/architecture/ARCHITECTURE.md +++ b/docs/architecture/ARCHITECTURE.md @@ -376,6 +376,32 @@ Determined by `group_vars/{brain,muscle,local}/main.yml`. A host's inventory gro - `muscle/main.yml` → `hardening_profile: server` - `local/main.yml` → `hardening_profile: workstation` +### 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. + +#### Hardware Profiles & Node Allocation + +| Host Class | Hardware Profile | Recommended Count | Architectural Role & Workload Distribution | +| :--- | :--- | :--- | :--- | +| **`brain`** | **High-Spec** (8–16 vCPU, 32–64 GB RAM) | **1 – 3 nodes** | Centralized control plane: VictoriaMetrics, Loki, Grafana, Portainer. 3 nodes provide active quorum for HA. | +| **`brain`** | **Low-Spec** (2–4 vCPU, 4–8 GB RAM) | **3 – 5 nodes** | Role-partitioned control plane: dedicated nodes for Ingress/VPN, metrics ingestion, log indexing (Loki), and management across low-cost VPS instances. | +| **`muscle`** | **Any compute tier** | **1 – 50 nodes** | Standard push-based Ansible sweet spot. Full parallel execution with low drift and minimal latency. | +| **`muscle`** | **Any compute tier** | **50 – 100 nodes** | Upper operational ceiling for push-based Ansible. Deployments should target specific nodes or tags (`--limit muscle-X`). | + +#### Scaling Beyond 100 Nodes (Ecosystem Positioning) + +> [!NOTE] +> **Surpassing 100 worker nodes does NOT invalidate this repository.** +> This project serves as **Phase 1: Hardened Foundations**. For hyper-scale topologies (>100 muscle nodes), push-based SSH routing can be transitioned to dynamic service discovery (Consul, CoreDNS) or container orchestrators (Nomad, Kubernetes). This repository remains the foundational hardening and compliance baseline that configures OS security, sysctl, firewalls, and storage across bare metal before any higher-level orchestrator runs. + +#### Ingress Routing Catalog & Secrets Architecture + +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. + --- ## 8. Application Profile Schema (Reduced 6-Field Specification) From b31acb0b7b559ecd8aa83e1e6f1e9ff55a4bdd1a Mon Sep 17 00:00:00 2001 From: Miguel Lozano Date: Sun, 1 Nov 2026 13:23:55 -0500 Subject: [PATCH 6/9] chore(deps): bump caddy-waf image to v3.6.2 and update sha256 digest - Update caddy_image pin to ghcr.io/developmi/caddy-waf:v3.6.2 - Update multi-arch OCI index sha256 digest to sha256:572968506168150bed96e293c9461578d911a980ecb8ef91d6672f381dda2cbb --- inventory/group_vars/all/images.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/inventory/group_vars/all/images.yml b/inventory/group_vars/all/images.yml index cbf2117..1fa47b3 100644 --- a/inventory/group_vars/all/images.yml +++ b/inventory/group_vars/all/images.yml @@ -10,13 +10,13 @@ # ----------------------------------------------------------------------------- # Custom image namespace image_namespace: "{{ vault_image_namespace }}" # AC-3: value from secrets.sops.yml only -# Caddy image (SSOT: caddy-waf repo releases; v3.6.1) -caddy_image: "ghcr.io/developmi/caddy-waf:v3.6.1" +# Caddy image (SSOT: caddy-waf repo releases; v3.6.2) +caddy_image: "ghcr.io/developmi/caddy-waf:v3.6.2" # SHA256 digest (OCI index, multi-arch amd64+arm64) for supply chain verification. # Enforced as a verification gate by the L4 role (docker_image_info digest match, # tasks/caddy.yml 'Verify Caddy image digest if specified'). -caddy_image_digest: "sha256:d6a824c83e7edbc97391907cb404c44782c75305ac9d07c1278797cffc17ed93" +caddy_image_digest: "sha256:572968506168150bed96e293c9461578d911a980ecb8ef91d6672f381dda2cbb" # Caddy WAF UI sidecar image (SSOT: caddy-waf-ui repo releases; v1.4.0) caddy_ui_image: "ghcr.io/developmi/caddy-waf-ui:v1.4.0" From e8dc1da5cd21b6ca0701dae6b67c47fa7f6cb6e5 Mon Sep 17 00:00:00 2001 From: Miguel Lozano Date: Sun, 1 Nov 2026 13:24:03 -0500 Subject: [PATCH 7/9] fix(compliance): replace pip command with uv and document twenty compose entrypoint - Replace pip install graphifyy with uv tool run in docs/project/ROADMAP.md - Document official upstream container entrypoint requirement for yarn in apps/twenty-crm/docker-compose.yml --- apps/twenty-crm/docker-compose.yml | 1 + docs/project/ROADMAP.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/apps/twenty-crm/docker-compose.yml b/apps/twenty-crm/docker-compose.yml index 2ce2f4a..051d0e9 100644 --- a/apps/twenty-crm/docker-compose.yml +++ b/apps/twenty-crm/docker-compose.yml @@ -139,6 +139,7 @@ services: read_only: true tmpfs: - /tmp + # Upstream contract: Twenty CRM official image entrypoint requirement command: ["yarn", "worker:prod"] depends_on: twenty-db: diff --git a/docs/project/ROADMAP.md b/docs/project/ROADMAP.md index ef952de..6dc5234 100644 --- a/docs/project/ROADMAP.md +++ b/docs/project/ROADMAP.md @@ -169,7 +169,7 @@ This project starts at v6.0.0. Prior development history (v1.0.0 - v5.5.0) is ma ### U2.4 Graphify Codebase Mapping (Evaluation) -- Evaluate `pip install graphifyy` for generating cross-reference documentation. +- Evaluate `uv tool run graphifyy` for generating cross-reference documentation. - **Known limitation**: Like CodeGraph, Graphify treats YAML as DOCS type only (no symbolic analysis). Useful for general project topology, not Ansible-specific navigation. - If evaluation passes: integrate into CI as optional documentation artifact. - If evaluation fails: document the limitation and rely on `make graph` + structured docs. From 88a1416613ba4584c776392c50f068560e3e211b Mon Sep 17 00:00:00 2001 From: Miguel Lozano Date: Sun, 1 Nov 2026 13:24:09 -0500 Subject: [PATCH 8/9] build(make): implement doctor, tools, test-security, and release-ready targets - Add make tools target aliased to local toolchain setup - Add make doctor target for diagnostic environment and playbook readiness verification - Add make test-security target combining pip-audit and zizmor workflow scanning - Add make release-ready comprehensive verification gate --- Makefile | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/Makefile b/Makefile index 6d97e88..62096ee 100644 --- a/Makefile +++ b/Makefile @@ -59,6 +59,32 @@ setup: ## Bootstrap local environment (sync + collections + pre-commit) $(PKG) run pre-commit install @echo "=== Toolchain Ready ===" +tools: setup ## Standard contract: Bootstrap and verify local toolchain + +doctor: ## Diagnostic environment and playbook readiness check + @echo "=== System & Toolchain Doctor ===" + @echo "OS: $$(uname -s) $$(uname -m)" + @which uv >/dev/null && echo "uv: $$(uv --version)" || echo "uv: MISSING" + @which python3 >/dev/null && echo "python3: $$(python3 --version)" || echo "python3: MISSING" + @$(PKG) run ansible --version | head -n 1 + @which sops >/dev/null && echo "sops: $$(sops --version)" || echo "sops: NOT FOUND in PATH (optional host tool)" + @which trivy >/dev/null && echo "trivy: $$(trivy --version | head -n 1)" || echo "trivy: NOT FOUND in PATH" + @which cosign >/dev/null && echo "cosign: $$(cosign version 2>&1 | head -n 1)" || echo "cosign: NOT FOUND in PATH" + @echo "=== Playbook & Inventory Validation ===" + @./scripts/setup.sh --validate + +test-security: ## Audit Python dependencies (pip-audit) and workflow security (zizmor) + @echo "==> 1/2 Auditing Python dependencies (pip-audit)..." + @$(PKG) run --group dev pip-audit + @echo "==> 2/2 Auditing GitHub Actions workflows (zizmor)..." + @$(PKG) run zizmor . + @echo "=== Security Gates: ALL PASSED ===" + +release-ready: lint test-security ## Comprehensive pre-release gate (lint + security + doctor) + @echo "==> Running environment & playbook validation..." + @$(MAKE) doctor + @echo "=== Release Readiness Gate: ALL CHECKS PASSED ===" + sync: ## Sync Python dependencies with uv @echo "Running $(PKG) sync..." $(PKG) sync @@ -283,6 +309,7 @@ test-layer: @$(MAKE) test LAYER=$(LAYER) .PHONY: help setup sync lint precommit test show-inventory \ + tools doctor test-security release-ready \ sops-init sops-edit sops-encrypt sops-view \ deploy-bootstrap deploy-hardening deploy-engine deploy-edge \ deploy-monitoring deploy-backups deploy-portainer deploy-platform \ From bf7fbdbbc629158ecbb10f24b691ce27564e7494 Mon Sep 17 00:00:00 2001 From: Miguel Lozano Date: Sun, 1 Nov 2026 13:24:16 -0500 Subject: [PATCH 9/9] docs(changelog): document unreleased ingress decoupling and toolchain gates - Add [Unreleased] section detailing Make targets, sizing boundaries, and ingress decoupling --- CHANGELOG.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 50eec22..b246c90 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,20 @@ status: active # Changelog +## [Unreleased] + +### Added +- **Deterministic Make Toolchain Contract**: Standardized developer and automation entrypoints with `make doctor`, `make tools`, `make test-security`, and `make release-ready`. +- **Operational Scale & Sizing Boundaries**: Documented capacity ceilings for Bare Metal / VPS topologies (Brain: 1–3 High-Spec, 3–5 Low-Spec; Muscle: 50–100 workers) prior to hyperscale K8s orchestration. + +### Changed +- **Ingress & Secrets Decoupling**: Decoupled `ingress_services` catalog from SOPS encryption into tracked `ingress.yml.example` and gitignored `ingress.yml` to prevent merge conflict friction and protect client domain confidentiality without encrypting non-secret routing topology. +- **Unified Caddyfile SSOT**: Removed `.example.j2` copy requirement in favor of a single tracked `Caddyfile.j2` incorporating global `metrics` directive aligned with upstream. +- **Upstream Caddy WAF Upgrade**: Pinned `ghcr.io/developmi/caddy-waf:v3.6.2` (Coraza v3.8.1, CRS v4) with cryptographic multi-arch sha256 digest validation. + +### Fixed +- **Preflight Toolchain Compliance**: Replaced legacy `pip` reference in roadmap with `uv tool run` and documented upstream container entrypoint requirement in Twenty CRM compose worker. + ## [7.0.0] - 2026-10-27 ### Added