diff --git a/.env.example b/.env.example index 28e51f1..fb79a43 100644 --- a/.env.example +++ b/.env.example @@ -12,7 +12,7 @@ # PRODUCTION SETUP: # 1. cp .env.example .env (or run scripts/New-LocalSecrets.ps1) # 2. Fill INITIAL_ADMIN_PASSWORD and NATS_ACCOUNT_SIGNING_SEED -# 3. docker compose up -d --build +# 3. docker compose -f IaC/compose/docker-compose.yml up -d --build (or ./scripts/deploy.sh) # #============================================================================= @@ -44,7 +44,7 @@ REGISTRY_TOKEN= NATS_IMAGE=nats NATS_VERSION=2.12-alpine@sha256:7cef1bd3fed6034e95cf6e6bc9c28c5afa6dc58e9fb778dd7924a1ac62569f2d -# Optional in-stack reverse proxy (docker-compose.proxy.yml, opt-in) +# Optional in-stack reverse proxy (IaC/compose/docker-compose.proxy.yml, opt-in) NGINX_IMAGE=nginx NGINX_VERSION=1.29-alpine PROXY_HTTP_PORT=18080 diff --git a/IaC/README.md b/IaC/README.md new file mode 100644 index 0000000..39a0ff5 --- /dev/null +++ b/IaC/README.md @@ -0,0 +1,56 @@ +# Infrastructure as Code + +Deployment manifests for ExecuteR, in increasing order of scale: + +| Target | Folder | Use it for | +|--------|--------|-----------| +| **Docker Compose** | [`compose/`](compose) | A single host. The default; `scripts/deploy.sh` drives it. | +| **Docker Swarm** | [`swarm/`](swarm) | A few nodes, replicas behind one VIP, minimal orchestration. | +| **Kubernetes** | [`k8s/`](k8s) | Many nodes, HPA, rolling updates, cloud/multi-cloud. | + +All three run the **same images** (`executer-backend`, `executer-webui`) and +the same NATS. They differ only in how many replicas run and how state is +shared. See the [Scaling and HA](../../../wiki/Scaling-and-HA) wiki page for +the full picture and diagram. + +## What is stateless vs. stateful + +Scaling past one backend/webui instance is safe because the realtime fan-out +is NATS's job, not the backend's — agents and browsers hold their WebSocket +to NATS through the edge, so replicas don't multiply that load. + +**Stateless (scale freely):** + +- **WebUI** — pure SSR/static; any number of replicas. +- **Backend REST** — cookie auth, no server-side session store. Round-robin; + no sticky sessions needed. +- **Backend ingest workers** — subscribe with a NATS **queue group**, so each + presence/inventory/job message is processed by exactly one replica. + +**Stateful / single-owner (needs shared infrastructure):** + +- **Database** — must be Postgres or SQL Server (not the SQLite default) so + all backends share one store. +- **Data Protection key ring** — all backends must share it (cookies, CSRF, + encrypted secret blobs). Mount `DATAPROTECTION_PATH` on shared storage + (CephFS/MicroCeph, NFS) — every manifest here does. +- **Schedule worker** — must run in exactly one place or schedules fire N + times. Run web/API replicas with `SCHEDULE_WORKER=0` and one dedicated + **worker** replica with `SCHEDULE_WORKER=1` (swarm/k8s do this). +- **NATS + JetStream** — a 3-node cluster (JetStream R3) for HA; a + supercluster with gateways spans regions/clouds. + +## Cross-cutting prerequisites for multi-instance + +- **Shared storage** for the key ring (and NATS JetStream if not clustered): + MicroCeph/CephFS or NFS, exposed as a Swarm volume driver or a k8s + `ReadWriteMany` StorageClass. +- **A private overlay** between nodes/regions — WireGuard via + [Tailscale](https://tailscale.com) or [NetBird](https://netbird.io) — so + NATS cluster/gateway routes and the DB travel encrypted across sites + without public exposure. +- **Service discovery** — Swarm and k8s both provide DNS + (`tasks.` / `..svc`); NATS cluster routes and DB + hosts use those names. +- **One edge / single DNS name** terminating TLS and load-balancing the + replicas (see [Networking and TLS](../../../wiki/Networking-and-TLS)). diff --git a/IaC/compose/README.md b/IaC/compose/README.md new file mode 100644 index 0000000..129b998 --- /dev/null +++ b/IaC/compose/README.md @@ -0,0 +1,27 @@ +# Compose (single host) + +The default single-host deployment. + +```bash +# from the repository root +./scripts/deploy.sh # pull images (or build), start +./scripts/deploy.sh --with-proxy --host control.example.com + +# or directly +cp .env.example .env # then fill secrets +docker compose -f IaC/compose/docker-compose.yml up -d --build +``` + +Files: + +- `docker-compose.yml` — nats + backend + webui. Relative build contexts and + bind mounts are authored against this folder (`../..` = repo root), so run + it from the repository root as shown. +- `docker-compose.dev.yml` — development overrides (`… -f docker-compose.yml + -f docker-compose.dev.yml`). +- `docker-compose.proxy.yml` — opt-in in-stack nginx edge (`deploy.sh + --with-proxy`). + +For more than one backend/webui replica, move up to +[`../swarm`](../swarm) or [`../k8s`](../k8s) — a single-host Compose file +can't share the Data Protection key ring or split off a schedule worker. diff --git a/docker-compose.dev.yml b/IaC/compose/docker-compose.dev.yml similarity index 100% rename from docker-compose.dev.yml rename to IaC/compose/docker-compose.dev.yml diff --git a/docker-compose.proxy.yml b/IaC/compose/docker-compose.proxy.yml similarity index 100% rename from docker-compose.proxy.yml rename to IaC/compose/docker-compose.proxy.yml diff --git a/docker-compose.yml b/IaC/compose/docker-compose.yml similarity index 97% rename from docker-compose.yml rename to IaC/compose/docker-compose.yml index 6c35ab6..08f2a3e 100644 --- a/docker-compose.yml +++ b/IaC/compose/docker-compose.yml @@ -55,8 +55,8 @@ services: volumes: - /etc/timezone:/etc/timezone:ro - /etc/localtime:/etc/localtime:ro - - ./src/Infra/nats/nats.conf:/etc/nats/nats.conf:ro - - ./secrets/nats/resolver.conf:/etc/nats/resolver.conf:ro + - ../../src/Infra/nats/nats.conf:/etc/nats/nats.conf:ro + - ../../secrets/nats/resolver.conf:/etc/nats/resolver.conf:ro - "${STACK_BINDMOUNTROOT:-/mnt/data/docker/stacks}/${STACK_NAME:-stk-executer-00001}/NATS/JetStream:/data/jetstream:rw" - "${STACK_BINDMOUNTROOT:-/mnt/data/docker/stacks}/${STACK_NAME:-stk-executer-00001}/NATS/Resolver:/data/resolver:rw" healthcheck: @@ -76,7 +76,7 @@ services: pull_policy: '${IMAGE_PULL_POLICY:-missing}' container_name: EXECUTER-API-00001 build: - context: . + context: ../.. dockerfile: src/Infra/backend/Dockerfile args: UNIFIED_VERSION: ${UNIFIED_VERSION:-0.0.0.0} @@ -169,7 +169,7 @@ services: pull_policy: '${IMAGE_PULL_POLICY:-missing}' container_name: EXECUTER-WEB-00001 build: - context: . + context: ../.. dockerfile: src/Infra/webui/Dockerfile args: UNIFIED_VERSION: ${UNIFIED_VERSION:-0.0.0.0} diff --git a/IaC/k8s/00-namespace-config.yaml b/IaC/k8s/00-namespace-config.yaml new file mode 100644 index 0000000..fd7625b --- /dev/null +++ b/IaC/k8s/00-namespace-config.yaml @@ -0,0 +1,52 @@ +#============================================================================= +# ExecuteR - Kubernetes: namespace, config, secrets, shared key ring +#============================================================================= +apiVersion: v1 +kind: Namespace +metadata: + name: executer +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: executer-config + namespace: executer +data: + ASPNETCORE_URLS: 'http://0.0.0.0:8080' + DATABASE_PROVIDER: 'postgres' + DATABASE_CONNECTION_STRING: 'Host=executer-db;Database=executer;Username=executer;Password=$(POSTGRES_PASSWORD)' + DATAPROTECTION_PATH: '/keys' + NATS_URL: 'nats://executer-nats:4222' + NATS_WS_PROXY: 'ws://executer-nats:9222' + NATS_MONITOR_URL: 'http://executer-nats:8222' + TRUST_PROXY: '1' + PUBLIC_SERVER_URL: 'https://control.example.com' +--- +# Fill these in (or use a sealed-secret / external-secrets operator). +# NATS keys: `kubectl run … executer-backend nats-auth init` once, then paste. +apiVersion: v1 +kind: Secret +metadata: + name: executer-secrets + namespace: executer +type: Opaque +stringData: + POSTGRES_PASSWORD: 'change-me' + NATS_ACCOUNT_SIGNING_SEED: 'SA...' + NATS_ACCOUNT_PUBLIC_KEY: 'A...' + INITIAL_ADMIN_USERNAME: 'admin' + INITIAL_ADMIN_PASSWORD: 'change-me' +--- +# Shared Data Protection key ring: ALL backend/worker pods read it, so the +# StorageClass must support ReadWriteMany (CephFS/MicroCeph, NFS). +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: executer-keyring + namespace: executer +spec: + accessModes: ['ReadWriteMany'] + storageClassName: 'cephfs' # set to your RWX StorageClass + resources: + requests: + storage: 1Gi diff --git a/IaC/k8s/10-data.yaml b/IaC/k8s/10-data.yaml new file mode 100644 index 0000000..8d6bc58 --- /dev/null +++ b/IaC/k8s/10-data.yaml @@ -0,0 +1,97 @@ +#============================================================================= +# ExecuteR - Kubernetes: Postgres + NATS (JetStream cluster) +# For production NATS, prefer the official Helm chart; this hand StatefulSet +# is a self-contained, adaptable equivalent. +#============================================================================= +apiVersion: apps/v1 +kind: StatefulSet +metadata: + name: executer-db + namespace: executer +spec: + serviceName: executer-db + replicas: 1 + selector: { matchLabels: { app: executer-db } } + template: + metadata: { labels: { app: executer-db } } + spec: + containers: + - name: postgres + image: postgres:17-alpine + env: + - { name: POSTGRES_DB, value: executer } + - { name: POSTGRES_USER, value: executer } + - name: POSTGRES_PASSWORD + valueFrom: { secretKeyRef: { name: executer-secrets, key: POSTGRES_PASSWORD } } + ports: [{ containerPort: 5432 }] + volumeMounts: [{ name: data, mountPath: /var/lib/postgresql/data }] + volumeClaimTemplates: + - metadata: { name: data } + spec: + accessModes: ['ReadWriteOnce'] + resources: { requests: { storage: 20Gi } } +--- +apiVersion: v1 +kind: Service +metadata: { name: executer-db, namespace: executer } +spec: + selector: { app: executer-db } + ports: [{ port: 5432, targetPort: 5432 }] +--- +apiVersion: v1 +kind: Service +metadata: { name: executer-nats, namespace: executer } +spec: + selector: { app: executer-nats } + ports: + - { name: client, port: 4222, targetPort: 4222 } + - { name: ws, port: 9222, targetPort: 9222 } + - { name: monitor, port: 8222, targetPort: 8222 } +--- +# Headless service for peer discovery (JetStream clustering). +apiVersion: v1 +kind: Service +metadata: { name: executer-nats-peers, namespace: executer } +spec: + clusterIP: None + selector: { app: executer-nats } + ports: [{ name: cluster, port: 6222, targetPort: 6222 }] +--- +apiVersion: apps/v1 +kind: StatefulSet +metadata: + name: executer-nats + namespace: executer +spec: + serviceName: executer-nats-peers + replicas: 3 + selector: { matchLabels: { app: executer-nats } } + template: + metadata: { labels: { app: executer-nats } } + spec: + containers: + - name: nats + image: nats:2-alpine + command: + - nats-server + - '--name=$(POD_NAME)' + - '--jetstream' + - '--store_dir=/data' + - '--cluster_name=executer' + - '--cluster=nats://0.0.0.0:6222' + - '--routes=nats://executer-nats-0.executer-nats-peers:6222,nats://executer-nats-1.executer-nats-peers:6222,nats://executer-nats-2.executer-nats-peers:6222' + - '--http_port=8222' + env: + - name: POD_NAME + valueFrom: { fieldRef: { fieldPath: metadata.name } } + ports: + - { containerPort: 4222 } + - { containerPort: 9222 } + - { containerPort: 8222 } + - { containerPort: 6222 } + volumeMounts: [{ name: jetstream, mountPath: /data }] + volumeClaimTemplates: + - metadata: { name: jetstream } + spec: + accessModes: ['ReadWriteOnce'] + resources: { requests: { storage: 10Gi } } diff --git a/IaC/k8s/20-executer.yaml b/IaC/k8s/20-executer.yaml new file mode 100644 index 0000000..77ed1a9 --- /dev/null +++ b/IaC/k8s/20-executer.yaml @@ -0,0 +1,112 @@ +#============================================================================= +# ExecuteR - Kubernetes: backend (API) replicas, scheduler worker, WebUI +# Replace REGISTRY / VERSION before applying (or kustomize the image). +#============================================================================= +apiVersion: apps/v1 +kind: Deployment +metadata: + name: executer-api + namespace: executer +spec: + replicas: 3 + selector: { matchLabels: { app: executer-api } } + strategy: { type: RollingUpdate, rollingUpdate: { maxSurge: 1, maxUnavailable: 0 } } + template: + metadata: { labels: { app: executer-api } } + spec: + containers: + - name: backend + image: REGISTRY/executer-backend:VERSION + envFrom: + - configMapRef: { name: executer-config } + - secretRef: { name: executer-secrets } + env: + # Web/API replicas never run the scheduler — the worker owns it. + - { name: SCHEDULE_WORKER, value: '0' } + ports: [{ containerPort: 8080 }] + volumeMounts: [{ name: keyring, mountPath: /keys }] + readinessProbe: + httpGet: { path: /api/ready, port: 8080 } + initialDelaySeconds: 10 + periodSeconds: 10 + livenessProbe: + httpGet: { path: /api/health, port: 8080 } + initialDelaySeconds: 20 + periodSeconds: 20 + volumes: + - name: keyring + persistentVolumeClaim: { claimName: executer-keyring } +--- +apiVersion: v1 +kind: Service +metadata: { name: executer-api, namespace: executer } +spec: + selector: { app: executer-api } + ports: [{ port: 8080, targetPort: 8080 }] +--- +# Exactly one scheduler owner (do not scale past 1). +apiVersion: apps/v1 +kind: Deployment +metadata: + name: executer-worker + namespace: executer +spec: + replicas: 1 + strategy: { type: Recreate } + selector: { matchLabels: { app: executer-worker } } + template: + metadata: { labels: { app: executer-worker } } + spec: + containers: + - name: backend + image: REGISTRY/executer-backend:VERSION + envFrom: + - configMapRef: { name: executer-config } + - secretRef: { name: executer-secrets } + env: + - { name: SCHEDULE_WORKER, value: '1' } + volumeMounts: [{ name: keyring, mountPath: /keys }] + volumes: + - name: keyring + persistentVolumeClaim: { claimName: executer-keyring } +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: executer-web + namespace: executer +spec: + replicas: 2 + selector: { matchLabels: { app: executer-web } } + strategy: { type: RollingUpdate, rollingUpdate: { maxSurge: 1, maxUnavailable: 0 } } + template: + metadata: { labels: { app: executer-web } } + spec: + containers: + - name: webui + image: REGISTRY/executer-webui:VERSION + env: + - { name: PORT, value: '3000' } + - { name: NODE_ENV, value: 'production' } + - name: ORIGIN + valueFrom: { configMapKeyRef: { name: executer-config, key: PUBLIC_SERVER_URL } } + ports: [{ containerPort: 3000 }] +--- +apiVersion: v1 +kind: Service +metadata: { name: executer-web, namespace: executer } +spec: + selector: { app: executer-web } + ports: [{ port: 3000, targetPort: 3000 }] +--- +# Optional: scale API on load. WebUI can take an HPA too. +apiVersion: autoscaling/v2 +kind: HorizontalPodAutoscaler +metadata: { name: executer-api, namespace: executer } +spec: + scaleTargetRef: { apiVersion: apps/v1, kind: Deployment, name: executer-api } + minReplicas: 3 + maxReplicas: 10 + metrics: + - type: Resource + resource: { name: cpu, target: { type: Utilization, averageUtilization: 70 } } diff --git a/IaC/k8s/30-ingress.yaml b/IaC/k8s/30-ingress.yaml new file mode 100644 index 0000000..bd5dde5 --- /dev/null +++ b/IaC/k8s/30-ingress.yaml @@ -0,0 +1,39 @@ +#============================================================================= +# ExecuteR - Kubernetes: single-DNS ingress +# / -> WebUI +# /api/* -> backend +# /messaging/agent -> NATS WebSocket +# /messaging/browser -> NATS WebSocket +# nginx-ingress annotations shown; adapt for your controller. cert-manager +# issues the public certificate (ExecuteR itself needs no TLS behind this). +#============================================================================= +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: executer + namespace: executer + annotations: + cert-manager.io/cluster-issuer: 'letsencrypt' + nginx.ingress.kubernetes.io/proxy-read-timeout: '3600' + nginx.ingress.kubernetes.io/proxy-send-timeout: '3600' + # Preserve the WebSocket upgrade for /messaging/*. + nginx.ingress.kubernetes.io/proxy-http-version: '1.1' + nginx.ingress.kubernetes.io/proxy-body-size: '0' +spec: + ingressClassName: nginx + tls: + - hosts: ['control.example.com'] + secretName: executer-tls + rules: + - host: control.example.com + http: + paths: + - path: /messaging + pathType: Prefix + backend: { service: { name: executer-nats, port: { number: 9222 } } } + - path: /api + pathType: Prefix + backend: { service: { name: executer-api, port: { number: 8080 } } } + - path: / + pathType: Prefix + backend: { service: { name: executer-web, port: { number: 3000 } } } diff --git a/IaC/k8s/README.md b/IaC/k8s/README.md new file mode 100644 index 0000000..1230021 --- /dev/null +++ b/IaC/k8s/README.md @@ -0,0 +1,51 @@ +# Kubernetes + +Many nodes, autoscaling, rolling updates, cloud or multi-cloud. + +```bash +# Fill in secrets, the RWX StorageClass, the ingress host, and the image refs +# (REGISTRY/VERSION) first — then: +kubectl apply -f IaC/k8s/00-namespace-config.yaml +kubectl apply -f IaC/k8s/10-data.yaml +kubectl apply -f IaC/k8s/20-executer.yaml +kubectl apply -f IaC/k8s/30-ingress.yaml +``` + +Manifests: + +- `00-namespace-config.yaml` — namespace, ConfigMap, Secret template, and the + **ReadWriteMany** PVC for the shared Data Protection key ring. +- `10-data.yaml` — Postgres StatefulSet + a 3-node NATS JetStream cluster + (headless service for peer discovery). For production NATS, the official + Helm chart is a good alternative. +- `20-executer.yaml` — `executer-api` Deployment (replicas, `SCHEDULE_WORKER=0`, + HPA), the single `executer-worker` Deployment (`SCHEDULE_WORKER=1`, + `Recreate` so only one scheduler ever runs), and `executer-web`. +- `30-ingress.yaml` — one host routing `/`, `/api/*`, `/messaging/*` with + WebSocket-friendly timeouts and cert-manager TLS. + +## The load-bearing invariants + +- **`executer-keyring` PVC must be ReadWriteMany** — every API and worker pod + shares the Data Protection key ring. Set `storageClassName` to a RWX class + (CephFS/MicroCeph, NFS). With ReadWriteOnce, replicas on other nodes fail + to read cookies/CSRF/secret blobs. +- **`executer-worker` stays at replicas: 1** with `strategy: Recreate` — it is + the sole schedule owner. The API pods run `SCHEDULE_WORKER=0`. +- **Postgres** is the shared store; swap in a managed database by editing the + ConfigMap connection string and deleting the `executer-db` StatefulSet. +- Backend ingest uses a NATS queue group, so API replicas share message + processing rather than duplicating it. + +## Multi-cloud / overlay / discovery + +- Span clusters with a NATS **supercluster** (gateways between per-region + clusters); keep each region on its own ingress host or GeoDNS. +- A WireGuard mesh (Tailscale / NetBird) carries cross-cluster NATS gateway + and DB traffic privately — expose only the ingress publicly. +- In-cluster discovery is Kubernetes DNS (`executer-nats.executer.svc`); the + NATS StatefulSet uses stable pod DNS for cluster routes. + +> Environment-specific bits (StorageClass, ingress controller/annotations, +> image registry, secrets management) must be set for your cluster. Validate +> with `kubectl apply --dry-run=server` against a staging cluster. diff --git a/IaC/swarm/README.md b/IaC/swarm/README.md new file mode 100644 index 0000000..7f0bc87 --- /dev/null +++ b/IaC/swarm/README.md @@ -0,0 +1,55 @@ +# Swarm (replicated) + +Multi-node deployment with replicas behind a single VIP. + +```bash +# 1. Label the node that pins Postgres storage +docker node update --label-add executer.db=true + +# 2. Generate NATS account keys once (any host with the backend image): +docker run --rm -v "$PWD/nats:/out" /executer-backend:latest \ + nats-auth init --output /out +# -> NATS_ACCOUNT_SIGNING_SEED = account-signing.nk, NATS_ACCOUNT_PUBLIC_KEY = account.pub + +# 3. Deploy +export REGISTRY=... VERSION=... POSTGRES_PASSWORD=... \ + NATS_ACCOUNT_SIGNING_SEED=... NATS_ACCOUNT_PUBLIC_KEY=... \ + PUBLIC_SERVER_URL=https://control.example.com +docker stack deploy -c executer-stack.yml executer +``` + +Then scale: + +```bash +docker service scale executer_API=5 executer_WEB=3 +``` + +## What makes this multi-instance-safe + +- **`API` replicas** run `SCHEDULE_WORKER=0`; the single **`WORKER`** replica + runs `SCHEDULE_WORKER=1`. Keep `WORKER` at replicas: 1 — it owns the + scheduler. Everything else scales freely. +- **Shared key ring**: every `API` and `WORKER` task bind-mounts + `${STACK_BINDMOUNTROOT}/${STACK_NAME}/API/Keys`. On a multi-node swarm + `STACK_BINDMOUNTROOT` **must** be shared storage mounted at the same path + on every node (CephFS/MicroCeph, NFS) — a node-local path only works on a + single node. The same applies to the Postgres and JetStream bind mounts. +- **Postgres** backs all backends. Pin it to a node with `executer.db=true` + and durable storage, or point `DATABASE_CONNECTION_STRING` at a managed + database and drop the `DB` service. +- **NATS** is a 3-node JetStream cluster; `--routes nats://tasks.NATS:6222` + discovers peers via Swarm task DNS. For HA, create streams with R3 + (`--replicas 3`). + +## Multi-site / multi-cloud + +Join nodes across sites over a WireGuard overlay (Tailscale / NetBird) so +the overlay network, NATS cluster routes and Postgres traffic stay private. +For separate regions, run a NATS **supercluster**: one cluster per region +plus gateway connections between them, and keep each region's edge on its +own DNS name (or GeoDNS to the nearest). + +> These manifests are authored to the stack conventions and known Swarm +> semantics but are environment-specific (storage driver, node labels, cert +> edge). Validate with `docker stack config -c executer-stack.yml` and a +> staging swarm before production. diff --git a/IaC/swarm/executer-stack.yml b/IaC/swarm/executer-stack.yml new file mode 100644 index 0000000..56e830f --- /dev/null +++ b/IaC/swarm/executer-stack.yml @@ -0,0 +1,130 @@ +#============================================================================= +# ExecuteR - Docker Swarm stack (replicated, single VIP) +# docker stack deploy -c IaC/swarm/executer-stack.yml executer +# +# Differences from IaC/compose (single host): +# - No container_name (Swarm names replicas); scale via deploy.replicas. +# - Postgres shared DB (SQLite cannot back multiple backends). +# - Data Protection key ring on a SHARED volume (all backends read it) — +# back the `keyring` volume with CephFS/MicroCeph or NFS across nodes. +# - Web/API replicas run SCHEDULE_WORKER=0; one `worker` replica runs the +# scheduler (SCHEDULE_WORKER=1) so schedules fire once. +# - Backend ingest uses a NATS queue group, so replicas share the load. +# - NATS is a 3-node JetStream cluster (routes via tasks.NATS DNS). +# +# Fill the ${...} values in an env file or `docker stack deploy` environment. +# Put a TLS edge (Networking and TLS wiki) in front of the WEB/API published +# ports on one DNS name. +#============================================================================= +version: '3.9' + +networks: + EXECUTER-EXTERNAL: + driver: overlay + attachable: true + EXECUTER-INTERNAL: + driver: overlay + internal: true + attachable: true + +# Bind mounts under STACK_BINDMOUNTROOT (per the stack conventions). For a +# multi-node swarm this root MUST be shared storage mounted at the same path +# on every node (CephFS/MicroCeph, NFS) — the key ring especially is read by +# every API/WORKER task wherever it lands. + +services: + DB: + image: 'postgres:17-alpine' + networks: [EXECUTER-INTERNAL] + environment: + POSTGRES_DB: executer + POSTGRES_USER: executer + POSTGRES_PASSWORD: '${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}' + volumes: + - '${STACK_BINDMOUNTROOT:-/mnt/data/docker/stacks}/${STACK_NAME:-stk-executer-00001}/DB/Data:/var/lib/postgresql/data:rw' + deploy: + replicas: 1 + placement: + constraints: ['node.labels.executer.db == true'] + restart_policy: { condition: any } + + NATS: + image: 'nats:2-alpine' + networks: [EXECUTER-INTERNAL] + # 3-node JetStream cluster: peers discover each other via the Swarm task + # DNS (tasks.NATS). Unique server names come from the container hostname. + command: + - '--name=${HOSTNAME}' + - '--jetstream' + - '--store_dir=/data' + - '--cluster_name=executer' + - '--cluster=nats://0.0.0.0:6222' + - '--routes=nats://tasks.NATS:6222' + - '--http_port=8222' + volumes: + - '${STACK_BINDMOUNTROOT:-/mnt/data/docker/stacks}/${STACK_NAME:-stk-executer-00001}/NATS/JetStream:/data:rw' + deploy: + replicas: 3 + restart_policy: { condition: any } + # endpoint_mode dnsrr so tasks.NATS returns every node for routing. + endpoint_mode: dnsrr + + API: + image: '${REGISTRY:?set REGISTRY}/executer-backend:${VERSION:-latest}' + networks: [EXECUTER-EXTERNAL, EXECUTER-INTERNAL] + ports: + - '${BACKEND_PORT:-19080}:8080' + environment: + ASPNETCORE_URLS: 'http://0.0.0.0:8080' + DATABASE_PROVIDER: 'postgres' + DATABASE_CONNECTION_STRING: 'Host=DB;Database=executer;Username=executer;Password=${POSTGRES_PASSWORD}' + DATAPROTECTION_PATH: '/keys' + NATS_URL: 'nats://NATS:4222' + NATS_WS_PROXY: 'ws://NATS:9222' + NATS_MONITOR_URL: 'http://NATS:8222' + NATS_ACCOUNT_SIGNING_SEED: '${NATS_ACCOUNT_SIGNING_SEED:?}' + NATS_ACCOUNT_PUBLIC_KEY: '${NATS_ACCOUNT_PUBLIC_KEY:?}' + INITIAL_ADMIN_USERNAME: '${INITIAL_ADMIN_USERNAME:-admin}' + INITIAL_ADMIN_PASSWORD: '${INITIAL_ADMIN_PASSWORD:-admin}' + TRUST_PROXY: '1' + # The scheduler runs only on the dedicated worker below. + SCHEDULE_WORKER: '0' + volumes: + - '${STACK_BINDMOUNTROOT:-/mnt/data/docker/stacks}/${STACK_NAME:-stk-executer-00001}/API/Keys:/keys:rw' + deploy: + replicas: ${API_REPLICAS:-3} + restart_policy: { condition: any } + update_config: { order: start-first, parallelism: 1 } + + WORKER: + image: '${REGISTRY:?set REGISTRY}/executer-backend:${VERSION:-latest}' + networks: [EXECUTER-INTERNAL] + environment: + ASPNETCORE_URLS: 'http://0.0.0.0:8080' + DATABASE_PROVIDER: 'postgres' + DATABASE_CONNECTION_STRING: 'Host=DB;Database=executer;Username=executer;Password=${POSTGRES_PASSWORD}' + DATAPROTECTION_PATH: '/keys' + NATS_URL: 'nats://NATS:4222' + NATS_ACCOUNT_SIGNING_SEED: '${NATS_ACCOUNT_SIGNING_SEED:?}' + NATS_ACCOUNT_PUBLIC_KEY: '${NATS_ACCOUNT_PUBLIC_KEY:?}' + # The single scheduler owner. Keep this at exactly one replica. + SCHEDULE_WORKER: '1' + volumes: + - '${STACK_BINDMOUNTROOT:-/mnt/data/docker/stacks}/${STACK_NAME:-stk-executer-00001}/API/Keys:/keys:rw' + deploy: + replicas: 1 + restart_policy: { condition: any } + + WEB: + image: '${REGISTRY:?set REGISTRY}/executer-webui:${VERSION:-latest}' + networks: [EXECUTER-EXTERNAL] + ports: + - '${WEBUI_PORT:-13080}:3000' + environment: + PORT: '3000' + NODE_ENV: 'production' + ORIGIN: '${PUBLIC_SERVER_URL:-https://control.example.com}' + deploy: + replicas: ${WEB_REPLICAS:-2} + restart_policy: { condition: any } + update_config: { order: start-first, parallelism: 1 } diff --git a/README.md b/README.md index 9f3d8ab..4ded054 100644 --- a/README.md +++ b/README.md @@ -230,7 +230,7 @@ Full script-execution, enrollment, and remote-shell sequence diagrams are in Run the stack: ```powershell -docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build +docker compose -f IaC/compose/docker-compose.yml -f IaC/compose/docker-compose.dev.yml up -d --build ``` On a server, deploy straight from the repository — no clone needed. This pulls @@ -303,9 +303,15 @@ and `secrets/nats/resolver.conf` (mounted into the NATS container). ## Docker Compose -Services follow the stack conventions: `EXTERNAL` + `INTERNAL` bridge networks, -container names `EXECUTER-{NATS,API,WEB}-00001`, service-name networking, and -uncommon host ports. +Deployment manifests live under **[IaC/](IaC/)**: `IaC/compose` (single-host +Docker Compose), `IaC/swarm` (multi-node Docker Swarm with replicas), and +`IaC/k8s` (Kubernetes). All three follow the stack conventions and share the +same images; see the [scaling wiki](../../wiki/Scaling-and-HA) for when to +use each. + +The Compose stack uses `EXTERNAL` + `INTERNAL` bridge networks, container +names `EXECUTER-{NATS,API,WEB}-00001`, service-name networking, and uncommon +host ports. | Service | Container | Host port | Internal | |---------|-----------|-----------|----------| @@ -317,7 +323,9 @@ Volumes bind under `${STACK_BINDMOUNTROOT}/${STACK_NAME}/{Tier}/Data`. The NATS image is pinned by digest. See `.env.example` for every variable. ```powershell -docker compose up -d --build +# from the repository root +docker compose -f IaC/compose/docker-compose.yml up -d --build +# ...or just: ./scripts/deploy.sh ``` --- @@ -363,8 +371,17 @@ The finish page offers to **open the console in the browser** (checked by default) — a wildcard bind (`0.0.0.0` / `::`) opens `http://localhost:`, a specific bind address opens that address directly. Upgrades never overwrite existing configuration, and uninstall stops and -removes the service. The MSI installs exactly one instance — multi-instance -boxes use the ZIP with distinct ports and service names. +removes the service. By default a plain uninstall **keeps** the generated +data, sign-in and self-signed chain so a reinstall resumes where it left +off (the managed chain is located in the machine certificate stores by +subject and reused when still valid). For a fully clean removal, tick +**Also remove all data, keys and self-signed certificates** on the +uninstall page — or pass `PURGEDATA=1` to a silent uninstall. That deletes +`appsettings.json`, `data`, `logs` and `secrets` and removes the +self-signed root/intermediate/leaf from the Windows stores. The same +cleanup is available directly as `ExecuteR-Server.exe purge`. The MSI +installs exactly one instance — multi-instance boxes use the ZIP with +distinct ports and service names. Bundles ship the **agent installers** (`agent-package/` with `Agent.msi`, `Agent.zip`, the unix zips and `VERSION`), so the URL install command works @@ -448,19 +465,20 @@ Caddy / Nginx UI / nginx can bind or trust the files directly and stay current. On **Linux/macOS/containers** the PEM files are the primary store (`TLS_CERT_DIR` overrides; keep it on a persisted volume in containers). -**Agents** skip verification only when the operator says so — a -self-signed server that later gains a proxy with a real certificate must -not leave agents skipping validation needlessly. The Add-Device modal (and -the Settings token panel) carry a **Skip TLS verification** checkbox, -pre-selected only while the server is serving its self-signed chain -directly; when ticked, the one-liner and the served install script include -the skip bits and set the agent's `TlsSkipVerify` registry value -(`/etc/executer/agent.json` on unix) — still fully encrypted. The value is -GPO-manageable (`Skip TLS certificate verification` in the ADMX template, -policy key beats local config), `configure --skip-tls-verify` sets it by -hand, and the agent MSI wizard has a matching checkbox — unchecked by -default (`SKIPTLSVERIFY=1` silently). Left unticked, agents validate -normally. +**Agents trust a direct self-signed server automatically — without pinning.** +When the server serves its chain directly, the Add-Device modal (and +Settings token panel) pre-select **Trust self-signed certificate**, which +sets `ServerCaAutoInstall`. The agent then fetches the CA from +`/api/enrollment/ca` and **installs it into the OS trust store**, and a +background service keeps it current as the server rotates its chain — so +ordinary system validation trusts the server and renewals never lapse. It +is deliberately *not* pinned or forced: if a reverse proxy with a real +certificate is added later, that certificate validates normally and the +installed self-signed CA simply goes unused — nothing to break. The setting +is GPO-manageable (ADMX `Install the server's self-signed CA`), +`configure --install-server-ca` sets it by hand, and the agent MSI accepts +`CAINSTALL=1`. For an accept-any escape hatch (no validation), `insecure` / +`TlsSkipVerify=1` remains. --- diff --git a/scripts/deploy.sh b/scripts/deploy.sh index b299c6a..6438873 100755 --- a/scripts/deploy.sh +++ b/scripts/deploy.sh @@ -71,9 +71,10 @@ command -v curl >/dev/null 2>&1 || die "curl is required" docker info >/dev/null 2>&1 || die "cannot talk to the Docker daemon (need root or docker group?)" # ── Locate or fetch the stack files ───────────────────────────────────────── +COMPOSE_REL="IaC/compose" SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" 2>/dev/null && pwd || echo '')" REPO_ROOT="" -if [[ -n "$SCRIPT_DIR" && -f "$SCRIPT_DIR/../docker-compose.yml" ]]; then +if [[ -n "$SCRIPT_DIR" && -f "$SCRIPT_DIR/../$COMPOSE_REL/docker-compose.yml" ]]; then REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" fi @@ -94,12 +95,12 @@ else fi } - fetch docker-compose.yml || die "docker-compose.yml is required" + fetch "$COMPOSE_REL/docker-compose.yml" || die "docker-compose.yml is required" fetch .env.example || die ".env.example is required" fetch src/Infra/nats/nats.conf || die "nats.conf is required" - [[ $WITH_PROXY -eq 1 ]] && { fetch docker-compose.proxy.yml; fetch src/Infra/nginx/executer.conf; } + [[ $WITH_PROXY -eq 1 ]] && { fetch "$COMPOSE_REL/docker-compose.proxy.yml"; fetch src/Infra/nginx/executer.conf; } # Optional; only needed when building from source. - fetch docker-compose.dev.yml || true + fetch "$COMPOSE_REL/docker-compose.dev.yml" || true fi cd "$STACK_DIR" @@ -134,10 +135,12 @@ mkdir -p \ "$STACK_BINDMOUNTROOT/$STACK_NAME/Proxy/Acme" # ── Compose file selection ────────────────────────────────────────────────── -COMPOSE_FILES=(-f docker-compose.yml) +# Compose files live in IaC/compose; their relative build/mount paths are +# authored against that location, so they run correctly from the stack root. +COMPOSE_FILES=(-f "$COMPOSE_REL/docker-compose.yml") if [[ $WITH_PROXY -eq 1 ]]; then - [[ -f docker-compose.proxy.yml ]] || die "--with-proxy needs docker-compose.proxy.yml" - COMPOSE_FILES+=(-f docker-compose.proxy.yml) + [[ -f "$COMPOSE_REL/docker-compose.proxy.yml" ]] || die "--with-proxy needs $COMPOSE_REL/docker-compose.proxy.yml" + COMPOSE_FILES+=(-f "$COMPOSE_REL/docker-compose.proxy.yml") fi compose() { docker compose "${COMPOSE_FILES[@]}" "$@"; } diff --git a/src/Agent/Commands/AgentCli.cs b/src/Agent/Commands/AgentCli.cs index dcd0465..1fa8cb0 100644 --- a/src/Agent/Commands/AgentCli.cs +++ b/src/Agent/Commands/AgentCli.cs @@ -134,10 +134,11 @@ public static class AgentCli } } + var installServerCa = args.Contains("--install-server-ca"); var skipTlsVerify = args.Contains("--skip-tls-verify"); - if (url is null && token is null && proxy is null && !skipTlsVerify) + if (url is null && token is null && proxy is null && !installServerCa && !skipTlsVerify) { - Console.Error.WriteLine("Usage: configure --url [--token ] [--proxy ] [--skip-tls-verify]"); + Console.Error.WriteLine("Usage: configure --url [--token ] [--proxy ] [--install-server-ca] [--skip-tls-verify]"); return 1; } @@ -159,10 +160,18 @@ public static class AgentCli registry.WriteString(Branding.AgentRegistryKey, Agent.Configuration.AgentConfigurationKeys.ProxyUrl, proxy); } + if (installServerCa) + { + // Install the server's self-signed CA into the OS trust store (and + // keep it current) so system validation trusts a direct/local + // connection. Not pinning — a real cert behind a proxy still works. + registry.WriteDword(Branding.AgentRegistryKey, Agent.Configuration.AgentConfigurationKeys.ServerCaAutoInstall, 1); + } + if (skipTlsVerify) { - // For servers on the managed self-signed chain without a proxy: - // the connection stays TLS-encrypted, validation is skipped. + // Escape hatch: accept any certificate (still encrypted). Prefer + // --install-server-ca for self-signed servers. registry.WriteDword(Branding.AgentRegistryKey, Agent.Configuration.AgentConfigurationKeys.TlsSkipVerify, 1); } diff --git a/src/Agent/Configuration/AgentConfiguration.cs b/src/Agent/Configuration/AgentConfiguration.cs index 8e3e824..2eb0cc8 100644 --- a/src/Agent/Configuration/AgentConfiguration.cs +++ b/src/Agent/Configuration/AgentConfiguration.cs @@ -21,6 +21,14 @@ public sealed class AgentConfiguration public required ConfigurationValue TlsSkipVerify { get; init; } public required ConfigurationValue ProxyUrl { get; init; } + /// + /// Install the server's managed self-signed CA into the OS trust store so + /// ordinary system validation succeeds on a direct/local connection. Not + /// pinning and not forced — a later reverse proxy with a real certificate + /// still validates normally and the self-signed CA just goes unused. + /// + public ConfigurationValue ServerCaAutoInstall { get; init; } = new(false, ConfigurationSource.Default); + /// Parsed ServerURL; null when unset or invalid. public ServerUrl? ServerUrl => Shared.Infrastructure.Routing.ServerUrl.TryParse(ServerUrlText.Value, out var parsed, out _) ? parsed : null; @@ -50,6 +58,7 @@ public sealed class AgentConfigurationLoader(IRegistryStore registry, bool allow AllowScriptExecution = ResolveBool(AgentConfigurationKeys.AllowScriptExecution, defaultValue: true), TlsSkipVerify = ResolveBool(AgentConfigurationKeys.TlsSkipVerify, defaultValue: false), ProxyUrl = ResolveString(AgentConfigurationKeys.ProxyUrl, AgentConfigurationKeys.EnvironmentNames.ProxyUrl, null), + ServerCaAutoInstall = ResolveBool(AgentConfigurationKeys.ServerCaAutoInstall, defaultValue: false), }; } diff --git a/src/Agent/Configuration/AgentConfigurationKeys.cs b/src/Agent/Configuration/AgentConfigurationKeys.cs index 819389a..36f7568 100644 --- a/src/Agent/Configuration/AgentConfigurationKeys.cs +++ b/src/Agent/Configuration/AgentConfigurationKeys.cs @@ -20,6 +20,14 @@ public static class AgentConfigurationKeys /// public const string TlsSkipVerify = "TlsSkipVerify"; + /// + /// DWORD 1: fetch the server's managed self-signed CA and install it into + /// the OS trust store (and keep it current across renewals) so system + /// validation trusts a direct/local self-signed server. Not pinning — + /// a proxy with a real certificate added later still validates normally. + /// + public const string ServerCaAutoInstall = "ServerCaAutoInstall"; + /// /// Explicit outbound proxy URL (http://proxy:8080). Unset, the agent /// honors the system/environment proxy; either way it authenticates to diff --git a/src/Agent/Enrollment/EnrollmentService.cs b/src/Agent/Enrollment/EnrollmentService.cs index fcfdeb5..7697b54 100644 --- a/src/Agent/Enrollment/EnrollmentService.cs +++ b/src/Agent/Enrollment/EnrollmentService.cs @@ -80,8 +80,16 @@ public sealed class EnrollmentService( AgentVersion: BuildVersion.Resolve(typeof(EnrollmentService).Assembly), Device: ReadDeviceInfo()); - // TlsSkipVerify (registry/GPO): servers on the managed self-signed - // chain without a proxy — the connection stays TLS-encrypted. + // Self-signed servers: make the CA available to the OS trust store + // first so ordinary system validation succeeds here — not pinned, so + // a proxy with a real certificate added later still validates. + if (configuration.ServerCaAutoInstall.Value) + { + await ServerTrust.FetchAndInstallCaAsync(serverUrl, HttpClient.DefaultProxy, logger, cancellationToken); + } + + // TlsSkipVerify is the accept-any escape hatch; otherwise validate + // against the OS trust store (which now contains the CA above). using var handler = new HttpClientHandler(); if (configuration.TlsSkipVerify.Value) { diff --git a/src/Agent/Enrollment/ServerTrust.cs b/src/Agent/Enrollment/ServerTrust.cs new file mode 100644 index 0000000..a8f32d8 --- /dev/null +++ b/src/Agent/Enrollment/ServerTrust.cs @@ -0,0 +1,179 @@ +using System.Diagnostics; +using System.Net; +using System.Runtime.Versioning; +using System.Security.Cryptography.X509Certificates; +using Microsoft.Extensions.Logging; +using Shared.Contracts.Api; +using Shared.Infrastructure.Routing; + +namespace Agent.Enrollment; + +/// +/// Makes the server's managed self-signed CA available to the OS trust store +/// so ordinary system validation succeeds when the agent connects to the +/// self-signed server directly (e.g. a local URL). It is intentionally NOT +/// pinned or forced: if a reverse proxy with a real certificate is added +/// later, system validation trusts that instead, and the installed +/// self-signed CA simply goes unused — nothing to break. Certs come from +/// GET /api/enrollment/ca; a 404 means the server is not self-signed. +/// +public static class ServerTrust +{ + /// + /// Fetches the server's CA chain and installs it into the OS trust store + /// (idempotent, best-effort). The fetch accepts any certificate — it is + /// retrieving public CA certs to establish trust — then verifies the + /// payload is real PEM certificates before installing. Returns true when + /// a chain was fetched. + /// + public static async Task FetchAndInstallCaAsync( + ServerUrl serverUrl, IWebProxy? proxy, ILogger logger, CancellationToken cancellationToken) + { + using var handler = new HttpClientHandler + { + ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator, + }; + if (proxy is not null) + { + handler.Proxy = proxy; + handler.UseProxy = true; + } + + using var http = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(30) }; + var endpoint = serverUrl.ApiEndpoint(ApiRoutes.EnrollmentCaChain); + string pem; + X509Certificate2Collection chain = []; + try + { + using var response = await http.GetAsync(endpoint, cancellationToken); + if (response.StatusCode == HttpStatusCode.NotFound) + { + return false; // Server is not self-signed — nothing to install. + } + + response.EnsureSuccessStatusCode(); + pem = await response.Content.ReadAsStringAsync(cancellationToken); + chain.ImportFromPem(pem); + if (chain.Count == 0) + { + logger.LogWarning("Server CA response contained no certificates"); + return false; + } + } + catch (Exception ex) + { + logger.LogWarning(ex, "Could not fetch the server CA from {Endpoint}", endpoint); + return false; + } + + if (OperatingSystem.IsWindows()) + { + InstallWindows(chain, logger); + } + else if (OperatingSystem.IsMacOS()) + { + InstallMac(pem, logger); + } + else + { + InstallLinux(pem, logger); + } + + return true; + } + + [SupportedOSPlatform("windows")] + private static void InstallWindows(X509Certificate2Collection chain, ILogger logger) + { + try + { + foreach (var cert in chain) + { + var selfIssued = cert.SubjectName.RawData.AsSpan().SequenceEqual(cert.IssuerName.RawData); + using var store = new X509Store( + selfIssued ? StoreName.Root : StoreName.CertificateAuthority, StoreLocation.LocalMachine); + store.Open(OpenFlags.ReadWrite); + foreach (var stale in store.Certificates.Find( + X509FindType.FindBySubjectDistinguishedName, cert.Subject, validOnly: false)) + { + if (stale.Thumbprint != cert.Thumbprint) + { + store.Remove(stale); + } + } + + if (store.Certificates.Find(X509FindType.FindByThumbprint, cert.Thumbprint, validOnly: false).Count == 0) + { + store.Add(cert); + logger.LogInformation("Installed server CA into LocalMachine\\{Store}: {Subject}", + selfIssued ? "Root" : "CA", cert.Subject); + } + } + } + catch (Exception ex) + { + logger.LogWarning(ex, "Could not install the server CA into the Windows trust store"); + } + } + + private static void InstallLinux(string pem, ILogger logger) + { + try + { + // Debian/Ubuntu vs RHEL anchor locations. + if (Directory.Exists("/usr/local/share/ca-certificates")) + { + File.WriteAllText("/usr/local/share/ca-certificates/executer-server-ca.crt", pem); + RunBestEffort("update-ca-certificates", logger); + } + else if (Directory.Exists("/etc/pki/ca-trust/source/anchors")) + { + File.WriteAllText("/etc/pki/ca-trust/source/anchors/executer-server-ca.crt", pem); + RunBestEffort("update-ca-trust", logger); + } + else + { + logger.LogDebug("No known CA anchor directory found; skipping OS trust install"); + } + } + catch (Exception ex) + { + logger.LogWarning(ex, "Could not install the server CA into the Linux trust store"); + } + } + + private static void InstallMac(string pem, ILogger logger) + { + try + { + var path = Path.Combine(Path.GetTempPath(), "executer-server-ca.pem"); + File.WriteAllText(path, pem); + RunBestEffort("security", logger, + "add-trusted-cert", "-d", "-r", "trustRoot", "-k", "/Library/Keychains/System.keychain", path); + File.Delete(path); + } + catch (Exception ex) + { + logger.LogWarning(ex, "Could not install the server CA into the macOS keychain"); + } + } + + private static void RunBestEffort(string file, ILogger logger, params string[] args) + { + try + { + var psi = new ProcessStartInfo(file) { RedirectStandardError = true, RedirectStandardOutput = true }; + foreach (var arg in args) + { + psi.ArgumentList.Add(arg); + } + + using var process = Process.Start(psi); + process?.WaitForExit(15000); + } + catch (Exception ex) + { + logger.LogDebug(ex, "Trust-store refresh command '{File}' did not run", file); + } + } +} diff --git a/src/Agent/Messaging/AgentNatsOptionsFactory.cs b/src/Agent/Messaging/AgentNatsOptionsFactory.cs index 53f64c6..4e5f7e6 100644 --- a/src/Agent/Messaging/AgentNatsOptionsFactory.cs +++ b/src/Agent/Messaging/AgentNatsOptionsFactory.cs @@ -37,8 +37,11 @@ public static class AgentNatsOptionsFactory LoggerFactory = loggerFactory, }; - var skipTlsVerify = configuration.TlsSkipVerify.Value; - if (skipTlsVerify) + // TlsSkipVerify accepts any cert (still encrypted); otherwise the OS + // trust store validates the wss server cert — which contains the + // self-signed CA when ServerCaAutoInstall installed it. + var skipVerify = configuration.TlsSkipVerify.Value; + if (skipVerify) { options = options with { TlsOpts = NatsTlsOpts.Default with { InsecureSkipVerify = true } }; } @@ -54,9 +57,7 @@ public static class AgentNatsOptionsFactory // HttpClient.DefaultProxy on its own. clientOptions.Proxy = System.Net.Http.HttpClient.DefaultProxy; - // TlsSkipVerify (registry/GPO): accept the managed - // self-signed chain — the traffic stays TLS-encrypted. - if (skipTlsVerify) + if (skipVerify) { clientOptions.RemoteCertificateValidationCallback = (_, _, _, _) => true; } diff --git a/src/Agent/Service/AgentHost.cs b/src/Agent/Service/AgentHost.cs index 7a90b26..53a6863 100644 --- a/src/Agent/Service/AgentHost.cs +++ b/src/Agent/Service/AgentHost.cs @@ -69,6 +69,8 @@ public static class AgentHost builder.Services.AddSingleton(new AgentConfigurationLoader(registry, allowEnvironment: !runAsService)); builder.Services.AddHostedService(); + // Keeps the pinned server CA current across renewals (pinned mode only). + builder.Services.AddHostedService(); return builder.Build(); } diff --git a/src/Agent/Service/CaRefreshService.cs b/src/Agent/Service/CaRefreshService.cs new file mode 100644 index 0000000..3053bb8 --- /dev/null +++ b/src/Agent/Service/CaRefreshService.cs @@ -0,0 +1,45 @@ +using Agent.Configuration; +using Agent.Enrollment; +using Microsoft.Extensions.Hosting; +using Microsoft.Extensions.Logging; + +namespace Agent.Service; + +/// +/// Keeps the server's self-signed CA present in the OS trust store when +/// ServerCaAutoInstall is set: installs it on start and re-installs every few +/// hours, so a server-side chain rotation stays trusted without operator +/// action. It never forces validation against the CA — a proxy with a real +/// certificate added later is unaffected. Idle otherwise. +/// +public sealed class CaRefreshService( + AgentConfigurationLoader loader, ILogger logger) : BackgroundService +{ + protected override async Task ExecuteAsync(CancellationToken stoppingToken) + { + if (!loader.Load().ServerCaAutoInstall.Value) + { + logger.LogDebug("Server CA auto-install idle (not enabled)"); + return; + } + + using var timer = new PeriodicTimer(TimeSpan.FromHours(6)); + try + { + do + { + var configuration = loader.Load(); + if (configuration.ServerCaAutoInstall.Value && configuration.ServerUrl is { } serverUrl) + { + await ServerTrust.FetchAndInstallCaAsync( + serverUrl, System.Net.Http.HttpClient.DefaultProxy, logger, stoppingToken); + } + } + while (await timer.WaitForNextTickAsync(stoppingToken)); + } + catch (OperationCanceledException) + { + // Shutdown. + } + } +} diff --git a/src/Backend/Enrollment/InstallEndpoints.cs b/src/Backend/Enrollment/InstallEndpoints.cs index 6528af8..d1a54e3 100644 --- a/src/Backend/Enrollment/InstallEndpoints.cs +++ b/src/Backend/Enrollment/InstallEndpoints.cs @@ -24,6 +24,25 @@ public static class InstallEndpoints app.MapGet(ApiRoutes.AgentPackage, GetAgentPackage) .RequireRateLimiting(RateLimitPolicies.Enrollment) .AllowAnonymous(); + + app.MapGet(ApiRoutes.EnrollmentCaChain, GetCaChain) + .RequireRateLimiting(RateLimitPolicies.Enrollment) + .AllowAnonymous(); + } + + /// + /// Serves the managed self-signed CA chain (root + intermediate, public + /// certs only) so agents can pin it and keep validating the server across + /// renewals. 404 when the server is not running self-signed TLS — nothing + /// to distribute, agents validate against the real edge certificate. + /// + private static IResult GetCaChain(HttpContext context) + { + var manager = context.RequestServices.GetService(); + var pem = manager?.CaChainPem(); + return pem is null + ? Results.NotFound() + : Results.Text(pem, "application/x-pem-file; charset=utf-8"); } private static IResult GetInstallScript( @@ -99,17 +118,22 @@ public static class InstallEndpoints "else { [System.Net.ServicePointManager]::ServerCertificateValidationCallback = { $true } }"; // NOTE: $$""" — interpolations are {{ }}, single braces are literal PowerShell. - private static string BuildMsiScript(string baseUrl, string token, string packageUrl, bool skipVerify) => $$""" + // selfSigned: the server serves its managed self-signed chain directly, so + // the initial download skips verification (the cert isn't trusted yet) and + // the agent is told to install the server CA into the OS trust store (and + // keep it current) — system validation then trusts the server, without + // pinning, so a proxy with a real cert added later still works. + private static string BuildMsiScript(string baseUrl, string token, string packageUrl, bool selfSigned) => $$""" #Requires -RunAsAdministrator $ErrorActionPreference = 'Stop' Write-Host 'Installing ExecuteR Agent...' - {{(skipVerify ? PsSkipVerify : "")}} + {{(selfSigned ? PsSkipVerify : "")}} $server = '{{baseUrl}}' $token = '{{token}}' $msi = Join-Path $env:TEMP ('ExecuteRAgent-' + [guid]::NewGuid().ToString('N') + '.msi') try { Invoke-WebRequest -Uri '{{packageUrl}}' -OutFile $msi -UseBasicParsing - $arguments = @('/i', ('"' + $msi + '"'), '/qn', "SERVERURL=$server", "BOOTSTRAPTOKEN=$token"{{(skipVerify ? ", 'SKIPTLSVERIFY=1'" : "")}}) + $arguments = @('/i', ('"' + $msi + '"'), '/qn', "SERVERURL=$server", "BOOTSTRAPTOKEN=$token"{{(selfSigned ? ", 'CAINSTALL=1'" : "")}}) $p = Start-Process msiexec.exe -ArgumentList $arguments -Wait -PassThru if ($p.ExitCode -ne 0) { throw "msiexec exited with $($p.ExitCode)" } Write-Host 'ExecuteR Agent installed. It will enroll and start automatically.' @@ -124,7 +148,7 @@ public static class InstallEndpoints /// agent zip, unpacks to /opt/executer/agent, configures enrollment via /// the agent's own CLI and registers the systemd unit / launchd daemon. /// - private static string BuildUnixScript(string baseUrl, string token, string os, bool skipVerify) => $$""" + private static string BuildUnixScript(string baseUrl, string token, string os, bool selfSigned) => $$""" #!/usr/bin/env bash set -euo pipefail if [ "$(id -u)" -ne 0 ]; then echo 'Run with sudo/root.' >&2; exit 1; fi @@ -140,7 +164,7 @@ public static class InstallEndpoints tmp=$(mktemp -d) trap 'rm -rf "$tmp"' EXIT echo "Installing ExecuteR Agent ({{os}}-${arch})..." - curl -fsSL{{(skipVerify ? "k" : "")}} "$pkg" -o "$tmp/agent.zip" + curl -fsSL{{(selfSigned ? "k" : "")}} "$pkg" -o "$tmp/agent.zip" mkdir -p "$dest" if command -v unzip >/dev/null 2>&1; then unzip -oq "$tmp/agent.zip" -d "$dest" @@ -148,16 +172,17 @@ public static class InstallEndpoints python3 -m zipfile -e "$tmp/agent.zip" "$dest" fi chmod +x "$dest/executer-agent" - "$dest/executer-agent" configure --url "$server" --token "$token"{{(skipVerify ? " --skip-tls-verify" : "")}} + {{(selfSigned ? "# Trust the server's managed self-signed CA for host tooling too.\n curl -fsSLk \"" + baseUrl + ApiRoutes.EnrollmentCaChain + "\" -o /tmp/executer-ca.pem 2>/dev/null && {\n if [ -d /usr/local/share/ca-certificates ]; then cp /tmp/executer-ca.pem /usr/local/share/ca-certificates/executer-ca.crt && update-ca-certificates >/dev/null 2>&1 || true;\n elif [ -d /etc/pki/ca-trust/source/anchors ]; then cp /tmp/executer-ca.pem /etc/pki/ca-trust/source/anchors/executer-ca.crt && update-ca-trust >/dev/null 2>&1 || true; fi; rm -f /tmp/executer-ca.pem; }" : "")}} + "$dest/executer-agent" configure --url "$server" --token "$token"{{(selfSigned ? " --install-server-ca" : "")}} "$dest/executer-agent" initialize echo 'ExecuteR Agent installed. It will enroll and start automatically.' """; - private static string BuildZipScript(string baseUrl, string token, string packageUrl, bool skipVerify) => $$""" + private static string BuildZipScript(string baseUrl, string token, string packageUrl, bool selfSigned) => $$""" #Requires -RunAsAdministrator $ErrorActionPreference = 'Stop' Write-Host 'Installing ExecuteR Agent (portable)...' - {{(skipVerify ? PsSkipVerify : "")}} + {{(selfSigned ? PsSkipVerify : "")}} $server = '{{baseUrl}}' $token = '{{token}}' $dest = Join-Path $env:ProgramFiles 'ExecuteR\Agent' @@ -171,7 +196,7 @@ public static class InstallEndpoints New-Item -Path 'HKLM:\SOFTWARE\ExecuteR' -Force | Out-Null Set-ItemProperty -Path 'HKLM:\SOFTWARE\ExecuteR' -Name 'ServerURL' -Value $server Set-ItemProperty -Path 'HKLM:\SOFTWARE\ExecuteR' -Name 'BootstrapToken' -Value $token - {{(skipVerify ? "Set-ItemProperty -Path 'HKLM:\\SOFTWARE\\ExecuteR' -Name 'TlsSkipVerify' -Value 1 -Type DWord" : "")}} + {{(selfSigned ? "Set-ItemProperty -Path 'HKLM:\\SOFTWARE\\ExecuteR' -Name 'ServerCaAutoInstall' -Value 1 -Type DWord" : "")}} & $exe initialize Write-Host 'ExecuteR Agent installed and starting.' } diff --git a/src/Backend/Messaging/MessagingWorkers.cs b/src/Backend/Messaging/MessagingWorkers.cs index 03681f0..7f648d0 100644 --- a/src/Backend/Messaging/MessagingWorkers.cs +++ b/src/Backend/Messaging/MessagingWorkers.cs @@ -26,6 +26,11 @@ public sealed class MessagingWorkers( { private readonly Dictionary lastKnownStatus = []; + // Core NATS queue group: with multiple backend replicas, NATS delivers + // each presence/inventory/output/progress message to exactly one member, + // so ingest is load-balanced instead of every replica writing duplicates. + private const string WorkerQueueGroup = "executer-backend-workers"; + protected override async Task ExecuteAsync(CancellationToken stoppingToken) { if (!hub.IsConfigured) @@ -73,7 +78,7 @@ public sealed class MessagingWorkers( private async Task ConsumePresenceAsync(CancellationToken cancellationToken) { - await foreach (var msg in hub.Require().SubscribeAsync(NatsSubjects.AllAgentPresence, cancellationToken: cancellationToken)) + await foreach (var msg in hub.Require().SubscribeAsync(NatsSubjects.AllAgentPresence, queueGroup: WorkerQueueGroup, cancellationToken: cancellationToken)) { var payload = Parse(msg.Data); if (payload is null || !SubjectIdentifier.IsValid(payload.ClientId)) @@ -135,7 +140,7 @@ public sealed class MessagingWorkers( private async Task ConsumeInventoryAsync(CancellationToken cancellationToken) { - await foreach (var msg in hub.Require().SubscribeAsync(NatsSubjects.AllAgentInventory, cancellationToken: cancellationToken)) + await foreach (var msg in hub.Require().SubscribeAsync(NatsSubjects.AllAgentInventory, queueGroup: WorkerQueueGroup, cancellationToken: cancellationToken)) { var payload = Parse(msg.Data); var report = payload?.Report; @@ -203,7 +208,7 @@ public sealed class MessagingWorkers( /// private async Task ConsumeAgentEventsAsync(CancellationToken cancellationToken) { - await foreach (var msg in hub.Require().SubscribeAsync(NatsSubjects.AllAgentEvents, cancellationToken: cancellationToken)) + await foreach (var msg in hub.Require().SubscribeAsync(NatsSubjects.AllAgentEvents, queueGroup: WorkerQueueGroup, cancellationToken: cancellationToken)) { var payload = Parse(msg.Data); if (payload is null @@ -233,7 +238,7 @@ public sealed class MessagingWorkers( private async Task ConsumeJobOutputAsync(CancellationToken cancellationToken) { - await foreach (var msg in hub.Require().SubscribeAsync(NatsSubjects.AllJobOutput, cancellationToken: cancellationToken)) + await foreach (var msg in hub.Require().SubscribeAsync(NatsSubjects.AllJobOutput, queueGroup: WorkerQueueGroup, cancellationToken: cancellationToken)) { var payload = Parse(msg.Data); if (payload is null) @@ -277,7 +282,7 @@ public sealed class MessagingWorkers( private async Task ConsumeJobProgressAsync(CancellationToken cancellationToken) { - await foreach (var msg in hub.Require().SubscribeAsync(NatsSubjects.AllJobProgress, cancellationToken: cancellationToken)) + await foreach (var msg in hub.Require().SubscribeAsync(NatsSubjects.AllJobProgress, queueGroup: WorkerQueueGroup, cancellationToken: cancellationToken)) { var payload = Parse(msg.Data); if (payload is null) diff --git a/src/Backend/Program.cs b/src/Backend/Program.cs index 0b91fc4..8ce6b2c 100644 --- a/src/Backend/Program.cs +++ b/src/Backend/Program.cs @@ -53,6 +53,13 @@ if (args.Length > 0 && args[0] == "service") return Backend.Standalone.ServerCli.RunService(args[1..]); } +// CLI mode: clean-uninstall — forget the self-signed chain and delete +// generated runtime state (invoked by the MSI when PURGEDATA=1). +if (args.Length > 0 && args[0] == "purge") +{ + return Backend.Standalone.ServerCli.RunPurge(args[1..]); +} + // Standalone bundle: when setup generated an appsettings.json next to the // binary, anchor the content root there so the server behaves identically // however it is launched (console from any directory, SCM, systemd). diff --git a/src/Backend/Standalone/ServerCli.cs b/src/Backend/Standalone/ServerCli.cs index 9055e03..dd42e0b 100644 --- a/src/Backend/Standalone/ServerCli.cs +++ b/src/Backend/Standalone/ServerCli.cs @@ -14,6 +14,7 @@ namespace Backend.Standalone; /// downloading nats-server for this platform if absent /// service install — register as a Windows service / systemd unit /// service uninstall — stop and remove the service +/// purge [--yes] — remove the self-signed chain + generated state /// /// The same binary is the server: running it with no arguments starts the /// control plane (UI + API + WebSocket relay + optional NATS sidecar). @@ -362,6 +363,78 @@ public static class ServerCli }; } + /// + /// Clean-uninstall: forget the managed self-signed chain from the Windows + /// certificate stores and delete the runtime state `setup` generated + /// (appsettings.json, data, logs, secrets, nats.conf). MSI-owned files + /// (the binary, wwwroot, nats-server, agent-package) are left for the + /// installer to remove. Interactive callers are prompted unless --yes. + /// + public static int RunPurge(string[] args) + { + var assumeYes = args.Contains("--yes") || args.Contains("-y"); + if (!assumeYes) + { + Console.Write("Remove all ExecuteR data, keys and self-signed certificates? [y/N] "); + var answer = Console.ReadLine()?.Trim(); + if (answer is not ("y" or "Y" or "yes" or "YES")) + { + Console.WriteLine("Purge cancelled."); + return 0; + } + } + + var removed = Backend.Tls.TlsCleanup.RemoveWindowsChain(); + if (removed > 0) + { + Console.WriteLine($"Removed {removed} self-signed certificate(s) from the machine stores."); + } + + var baseDir = AppContext.BaseDirectory; + foreach (var dir in new[] { "data", "logs", "secrets" }) + { + DeleteDirectory(Path.Combine(baseDir, dir)); + } + + foreach (var file in new[] { "appsettings.json", Path.Combine("nats", "nats.conf") }) + { + var path = Path.Combine(baseDir, file); + if (File.Exists(path)) + { + try + { + File.Delete(path); + Console.WriteLine($"Deleted {path}"); + } + catch (Exception ex) + { + Console.Error.WriteLine($"Could not delete {path}: {ex.Message}"); + } + } + } + + Console.WriteLine("Purge complete."); + return 0; + } + + private static void DeleteDirectory(string path) + { + if (!Directory.Exists(path)) + { + return; + } + + try + { + Directory.Delete(path, recursive: true); + Console.WriteLine($"Deleted {path}"); + } + catch (Exception ex) + { + Console.Error.WriteLine($"Could not delete {path}: {ex.Message}"); + } + } + private static int InstallWindows(string exe, string name) { // Idempotent: create may fail when the service exists (repair or MSI diff --git a/src/Backend/Tls/SelfSignedTlsManager.cs b/src/Backend/Tls/SelfSignedTlsManager.cs index 0de3374..d9339df 100644 --- a/src/Backend/Tls/SelfSignedTlsManager.cs +++ b/src/Backend/Tls/SelfSignedTlsManager.cs @@ -60,6 +60,26 @@ public sealed class SelfSignedTlsManager /// The current server certificate; null until the first EnsureChain. public X509Certificate2? ServerCertificate => Volatile.Read(ref leaf); + /// + /// The public CA chain (intermediate then root) as PEM, for distribution + /// to agents so they can validate the leaf and keep trusting it across + /// renewals. Null before the chain exists. Contains no private keys. + /// + public string? CaChainPem() + { + lock (gate) + { + var root = persistence.Load(TlsRole.Root); + var intermediate = persistence.Load(TlsRole.Intermediate); + if (root is null || intermediate is null) + { + return null; + } + + return intermediate.ExportCertificatePem() + '\n' + root.ExportCertificatePem() + '\n'; + } + } + /// /// Creates or re-issues whatever links are missing, expiring, or no /// longer signed by the current parent (a rotated root cascades down). diff --git a/src/Backend/Tls/TlsCleanup.cs b/src/Backend/Tls/TlsCleanup.cs new file mode 100644 index 0000000..bf472be --- /dev/null +++ b/src/Backend/Tls/TlsCleanup.cs @@ -0,0 +1,17 @@ +using System.Runtime.Versioning; + +namespace Backend.Tls; + +/// Clean-uninstall helper: forget the managed self-signed chain. +public static class TlsCleanup +{ + /// + /// Removes the managed self-signed chain from the Windows machine + /// certificate stores. No-op off Windows. Returns the count removed. + /// + public static int RemoveWindowsChain() + => OperatingSystem.IsWindows() ? RemoveWindowsChainCore() : 0; + + [SupportedOSPlatform("windows")] + private static int RemoveWindowsChainCore() => WindowsStoreTlsPersistence.RemoveManagedChain(); +} diff --git a/src/Backend/Tls/TlsPersistence.cs b/src/Backend/Tls/TlsPersistence.cs index a83220d..7be213a 100644 --- a/src/Backend/Tls/TlsPersistence.cs +++ b/src/Backend/Tls/TlsPersistence.cs @@ -193,6 +193,36 @@ internal sealed class WindowsStoreTlsPersistence(string mirrorDirectory) : ITlsP return persisted; } + /// + /// Removes the managed self-signed chain (by subject) from all three + /// machine stores — the clean-uninstall counterpart to Save. Returns the + /// number of certificates removed; best-effort per store. + /// + public static int RemoveManagedChain() + { + var removed = 0; + foreach (var role in new[] { TlsRole.Root, TlsRole.Intermediate, TlsRole.Leaf }) + { + try + { + using var store = new X509Store(StoreFor(role), StoreLocation.LocalMachine); + store.Open(OpenFlags.ReadWrite); + foreach (var existing in store.Certificates.Find( + X509FindType.FindBySubjectDistinguishedName, TlsSubjects.For(role), validOnly: false)) + { + store.Remove(existing); + removed++; + } + } + catch (Exception) + { + // Best effort — a locked or missing store must not fail uninstall. + } + } + + return removed; + } + public void Complete(X509Certificate2 root, X509Certificate2 intermediate, X509Certificate2 leaf) { // SChannel serves the chain from the stores; the PEM mirror exists diff --git a/src/Backend/Tls/TlsSettings.cs b/src/Backend/Tls/TlsSettings.cs index 19034c1..d679c37 100644 --- a/src/Backend/Tls/TlsSettings.cs +++ b/src/Backend/Tls/TlsSettings.cs @@ -43,6 +43,7 @@ public sealed class TlsSettings public static TlsSettings FromConfiguration(IConfiguration configuration) { + var enabled = configuration["TLS_SELF_SIGNED"] != "0"; var certDir = configuration["TLS_CERT_DIR"]; var dataDir = Path.GetDirectoryName(Path.GetFullPath( configuration["DATABASE_PATH"] is { Length: > 0 } db ? db : "data/app.db")) ?? "data"; @@ -50,19 +51,21 @@ public sealed class TlsSettings var dnsNames = new List { "localhost" }; var ipAddresses = new List { IPAddress.Loopback, IPAddress.IPv6Loopback }; - // Verification is off at the proxy, so the SAN set only needs to be - // friendly for direct browsing: hostname, FQDN and the bind address. + // Cover every way this host is reachable directly: the hostname, the + // hostname under each adapter's connection-specific DNS suffix, the + // resolved FQDN, every IP on every adapter, plus localhost/loopback. + string? hostName = null; try { - var host = Dns.GetHostName(); - AddDns(dnsNames, host); + hostName = Dns.GetHostName(); + AddDns(dnsNames, hostName); try { - AddDns(dnsNames, Dns.GetHostEntry(host).HostName); + AddDns(dnsNames, Dns.GetHostEntry(hostName).HostName); } catch (Exception) { - // No resolvable FQDN — hostname and localhost suffice. + // No resolvable FQDN — hostname and suffix-derived names suffice. } } catch (Exception) @@ -70,6 +73,35 @@ public sealed class TlsSettings // Hostname unavailable; localhost suffices. } + AddNetworkNamesAndAddresses(dnsNames, ipAddresses, hostName); + + // A cloud VM's public IP lives on the provider's edge, not the NIC — + // discover it (metadata service, then an echo) so direct HTTPS to the + // public address validates. Best-effort and time-bounded, and only + // when we're actually generating a self-signed cert (never in tests + // or when TLS is off) so it makes no network calls otherwise. + if (enabled) + { + AddPublicIpAddresses(ipAddresses); + } + + // A configured public URL's host (name or IP) belongs in the SANs too. + if (configuration["PUBLIC_SERVER_URL"] is { Length: > 0 } publicUrl + && Uri.TryCreate(publicUrl, UriKind.Absolute, out var publicUri)) + { + if (IPAddress.TryParse(publicUri.Host, out var publicIp)) + { + if (!ipAddresses.Contains(publicIp)) + { + ipAddresses.Add(publicIp); + } + } + else + { + AddDns(dnsNames, publicUri.Host); + } + } + foreach (var url in (configuration["urls"] ?? string.Empty) .Split(';', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries)) { @@ -96,7 +128,7 @@ public sealed class TlsSettings return new TlsSettings { - Enabled = configuration["TLS_SELF_SIGNED"] != "0", + Enabled = enabled, CertificateDirectory = certDir is { Length: > 0 } ? certDir : Path.Combine(dataDir, "tls"), UseWindowsStore = OperatingSystem.IsWindows() && certDir is not { Length: > 0 }, DnsNames = dnsNames, @@ -104,6 +136,160 @@ public sealed class TlsSettings }; } + /// + /// Walks every operational network adapter: adds each adapter's DNS suffix + /// (and hostname.suffix), the global domain name, and every unicast IP. + /// + private static void AddNetworkNamesAndAddresses( + List dnsNames, List ipAddresses, string? hostName) + { + try + { + var domain = System.Net.NetworkInformation.IPGlobalProperties.GetIPGlobalProperties().DomainName; + if (!string.IsNullOrWhiteSpace(domain) && hostName is { Length: > 0 }) + { + AddDns(dnsNames, $"{hostName}.{domain}"); + } + } + catch (Exception) + { + // Global properties unavailable on this host. + } + + try + { + foreach (var nic in System.Net.NetworkInformation.NetworkInterface.GetAllNetworkInterfaces()) + { + if (nic.OperationalStatus != System.Net.NetworkInformation.OperationalStatus.Up) + { + continue; + } + + var props = nic.GetIPProperties(); + if (hostName is { Length: > 0 } && !string.IsNullOrWhiteSpace(props.DnsSuffix)) + { + AddDns(dnsNames, $"{hostName}.{props.DnsSuffix}"); + } + + foreach (var unicast in props.UnicastAddresses) + { + var ip = unicast.Address; + // Skip link-local (fe80::) — noisy and not a stable SAN. + if (ip.IsIPv6LinkLocal || ipAddresses.Contains(ip)) + { + continue; + } + + ipAddresses.Add(ip); + } + } + } + catch (Exception) + { + // Adapter enumeration unavailable; the base SANs still apply. + } + } + + /// + /// Best-effort public IP discovery so a cloud instance's public address is + /// in the cert. Tries the local cloud metadata services (Azure/GCP/AWS — + /// fast-fail off-cloud) then a public echo, within a small overall budget. + /// + private static void AddPublicIpAddresses(List ipAddresses) + { + try + { + foreach (var raw in DiscoverPublicIpsAsync().GetAwaiter().GetResult()) + { + if (IPAddress.TryParse(raw, out var ip) && !ipAddresses.Contains(ip) + && !IsPrivateOrReserved(ip)) + { + ipAddresses.Add(ip); + } + } + } + catch (Exception) + { + // Never let discovery block or fail certificate generation. + } + } + + private static async Task> DiscoverPublicIpsAsync() + { + using var budget = new CancellationTokenSource(TimeSpan.FromSeconds(3)); + var found = new List(); + + async Task GetAsync(string url, (string, string)? header, TimeSpan timeout) + { + try + { + using var http = new HttpClient { Timeout = timeout }; + using var request = new HttpRequestMessage(HttpMethod.Get, url); + if (header is { } h) + { + request.Headers.TryAddWithoutValidation(h.Item1, h.Item2); + } + + using var response = await http.SendAsync(request, budget.Token); + if (!response.IsSuccessStatusCode) + { + return null; + } + + return (await response.Content.ReadAsStringAsync(budget.Token)).Trim().Trim('"'); + } + catch (Exception) + { + return null; + } + } + + // Local metadata services fail fast when this isn't that cloud. + var azure = await GetAsync( + "http://169.254.169.254/metadata/instance/network/interface/0/ipv4/ipAddress/0/publicIpAddress?api-version=2021-02-01&format=text", + ("Metadata", "true"), TimeSpan.FromMilliseconds(800)); + if (!string.IsNullOrWhiteSpace(azure)) { found.Add(azure); } + + var gcp = await GetAsync( + "http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/0/access-configs/0/external-ip", + ("Metadata-Flavor", "Google"), TimeSpan.FromMilliseconds(800)); + if (!string.IsNullOrWhiteSpace(gcp)) { found.Add(gcp); } + + var aws = await GetAsync( + "http://169.254.169.254/latest/meta-data/public-ipv4", null, TimeSpan.FromMilliseconds(800)); + if (!string.IsNullOrWhiteSpace(aws)) { found.Add(aws); } + + // Provider-agnostic fallback if metadata yielded nothing. + if (found.Count == 0) + { + var echo = await GetAsync("https://api.ipify.org", null, TimeSpan.FromSeconds(1.5)); + if (!string.IsNullOrWhiteSpace(echo)) { found.Add(echo); } + } + + return found; + } + + /// True for loopback, link-local, and RFC1918/CGNAT/ULA ranges. + private static bool IsPrivateOrReserved(IPAddress ip) + { + if (IPAddress.IsLoopback(ip) || ip.IsIPv6LinkLocal || ip.IsIPv6SiteLocal || ip.IsIPv6UniqueLocal) + { + return true; + } + + if (ip.AddressFamily == System.Net.Sockets.AddressFamily.InterNetwork) + { + var b = ip.GetAddressBytes(); + return b[0] == 10 + || (b[0] == 172 && b[1] >= 16 && b[1] <= 31) + || (b[0] == 192 && b[1] == 168) + || (b[0] == 169 && b[1] == 254) // link-local / APIPA + || (b[0] == 100 && b[1] >= 64 && b[1] <= 127); // CGNAT + } + + return false; + } + private static void AddDns(List names, string candidate) { if (!string.IsNullOrWhiteSpace(candidate) diff --git a/src/Installer.Server/Product.wxs b/src/Installer.Server/Product.wxs index bb5d571..a1a0897 100644 --- a/src/Installer.Server/Product.wxs +++ b/src/Installer.Server/Product.wxs @@ -125,6 +125,22 @@ Impersonate="no" Return="ignore" /> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/Installer/Policies/en-US/ExecuteR.adml b/src/Installer/Policies/en-US/ExecuteR.adml index ecd6225..6bbd12d 100644 --- a/src/Installer/Policies/en-US/ExecuteR.adml +++ b/src/Installer/Policies/en-US/ExecuteR.adml @@ -111,6 +111,17 @@ If you disable or do not configure this policy, the agent uses the locally confi Do not enable this for servers reached through a proxy with a publicly trusted certificate — leave validation on there. Always follow your organization's security standards. +The agent reads configuration at service start; restart the "ExecuteR Agent" service (ExecuteRAgent) to apply a change immediately. + + Install the server's self-signed CA + Installs the ExecuteR server's managed self-signed CA (root + intermediate) into the machine trust store, and keeps it current when the server rotates its chain. + +If you enable this policy, ordinary system certificate validation trusts a direct or local connection to a self-signed server. It is not certificate pinning and it is not forced: if the server is later reached through a reverse proxy presenting a publicly trusted certificate, that certificate validates normally and the installed self-signed CA simply goes unused. + +If you disable or do not configure this policy, the agent does not install the CA. Use this for a self-signed server without a proxy; leave it off when a real edge certificate is in front. + +For an accept-any escape hatch (no validation at all), see "Skip TLS certificate verification" instead. + The agent reads configuration at service start; restart the "ExecuteR Agent" service (ExecuteRAgent) to apply a change immediately. Outbound proxy URL diff --git a/src/Installer/Product.wxs b/src/Installer/Product.wxs index a503faf..17521cc 100644 --- a/src/Installer/Product.wxs +++ b/src/Installer/Product.wxs @@ -5,7 +5,7 @@ + + + @@ -149,6 +157,10 @@ + + + @@ -222,9 +234,9 @@ Text="Blank keeps values already configured (upgrades), or set later via registry / Group Policy. The service enrolls once both values are present. Silent: SERVERURL=... BOOTSTRAPTOKEN=..." /> - + Public self-signed CA chain (root + intermediate) for agent trust. + public const string EnrollmentCaChain = "/api/enrollment/ca"; + public const string Schedules = "/api/schedules"; public const string Schedule = "/api/schedules/{id}"; public const string SchedulePreview = "/api/schedules/preview"; diff --git a/src/WebUI/src/lib/components/AddDeviceModal.svelte b/src/WebUI/src/lib/components/AddDeviceModal.svelte index 3471b49..0421be2 100644 --- a/src/WebUI/src/lib/components/AddDeviceModal.svelte +++ b/src/WebUI/src/lib/components/AddDeviceModal.svelte @@ -194,8 +194,8 @@ {/if} diff --git a/src/WebUI/src/routes/settings/+page.svelte b/src/WebUI/src/routes/settings/+page.svelte index a93f727..2afdf7c 100644 --- a/src/WebUI/src/routes/settings/+page.svelte +++ b/src/WebUI/src/routes/settings/+page.svelte @@ -136,7 +136,7 @@
{installCommand}
diff --git a/src/WebUI/vite.config.ts b/src/WebUI/vite.config.ts index f7e5391..4b6a030 100644 --- a/src/WebUI/vite.config.ts +++ b/src/WebUI/vite.config.ts @@ -22,7 +22,7 @@ export default defineConfig({ }) ], server: { - // Local development against `docker compose -f docker-compose.yml -f docker-compose.dev.yml up` + // Local development against `docker compose -f IaC/compose/docker-compose.yml -f IaC/compose/docker-compose.dev.yml up` // (or a locally running backend + NATS). Production is same-origin via the reverse proxy. proxy: { '/api': { diff --git a/tests/Backend.Tests/InstallScriptTests.cs b/tests/Backend.Tests/InstallScriptTests.cs index c565283..d6a6870 100644 --- a/tests/Backend.Tests/InstallScriptTests.cs +++ b/tests/Backend.Tests/InstallScriptTests.cs @@ -161,20 +161,31 @@ public class InstallScriptTests(BackendTestFixture fixture) : IClassFixture