feat: Add VEX Lens CI and Load Testing Plan

- Introduced a comprehensive CI job structure for VEX Lens, including build, test, linting, and load testing. - Defined load test parameters and SLOs for VEX Lens API and Issuer Directory. - Created Grafana dashboards and alerting mechanisms for monitoring API performance and error rates. - Established offline posture guidelines for CI jobs and load testing. feat: Implement deterministic projection verification script - Added `verify_projection.sh` script for verifying the integrity of projection exports against expected hashes. - Ensured robust error handling for missing files and hash mismatches. feat: Develop Vuln Explorer CI and Ops Plan - Created CI jobs for Vuln Explorer, including build, test, and replay verification. - Implemented backup and disaster recovery strategies for MongoDB and Redis. - Established Merkle anchoring verification and automation for ledger projector. feat: Introduce EventEnvelopeHasher for hashing event envelopes - Implemented `EventEnvelopeHasher` to compute SHA256 hashes for event envelopes. feat: Add Risk Store and Dashboard components - Developed `RiskStore` for managing risk data and state. - Created `RiskDashboardComponent` for displaying risk profiles with filtering capabilities. - Implemented unit tests for `RiskStore` and `RiskDashboardComponent`. feat: Enhance Vulnerability Detail Component - Developed `VulnerabilityDetailComponent` for displaying detailed information about vulnerabilities. - Implemented error handling for missing vulnerability IDs and loading failures.
2025-12-02 07:18:28 +02:00
parent 44171930ff
commit 885ce86af4
83 changed files with 2090 additions and 97 deletions
--- a/ops/devops/docker/Dockerfile.hardened.template
+++ b/ops/devops/docker/Dockerfile.hardened.template
@@ -0,0 +1,53 @@
+# syntax=docker/dockerfile:1.7
+# Hardened multi-stage template for StellaOps services
+# Parameters are build-time ARGs so this file can be re-used across services.
+
+ARG SDK_IMAGE=mcr.microsoft.com/dotnet/sdk:10.0-bookworm-slim
+ARG RUNTIME_IMAGE=mcr.microsoft.com/dotnet/aspnet:10.0-bookworm-slim
+ARG APP_PROJECT=src/Service/Service.csproj
+ARG CONFIGURATION=Release
+ARG PUBLISH_DIR=/app/publish
+ARG APP_USER=stella
+ARG APP_UID=10001
+ARG APP_GID=10001
+ARG APP_PORT=8080
+
+FROM ${SDK_IMAGE} AS build
+ENV DOTNET_CLI_TELEMETRY_OPTOUT=1 \
+    DOTNET_NOLOGO=1 \
+    SOURCE_DATE_EPOCH=1704067200
+WORKDIR /src
+# Expect restore sources to be available offline via local-nugets/
+COPY . .
+RUN dotnet restore ${APP_PROJECT} --packages /src/local-nugets && \
+    dotnet publish ${APP_PROJECT} -c ${CONFIGURATION} -o ${PUBLISH_DIR} \
+      /p:UseAppHost=true /p:PublishTrimmed=false
+
+FROM ${RUNTIME_IMAGE} AS runtime
+# Create non-root user/group with stable ids for auditability
+RUN groupadd -r -g ${APP_GID} ${APP_USER} && \
+    useradd  -r -u ${APP_UID} -g ${APP_GID} -d /var/lib/${APP_USER} ${APP_USER} && \
+    mkdir -p /app /var/lib/${APP_USER} /var/run/${APP_USER} /tmp && \
+    chown -R ${APP_UID}:${APP_GID} /app /var/lib/${APP_USER} /var/run/${APP_USER} /tmp
+
+WORKDIR /app
+COPY --from=build --chown=${APP_UID}:${APP_GID} ${PUBLISH_DIR}/ ./
+# Ship healthcheck helper; callers may override with their own script
+COPY --chown=${APP_UID}:${APP_GID} ops/devops/docker/healthcheck.sh /usr/local/bin/healthcheck.sh
+
+ENV ASPNETCORE_URLS=http://+:${APP_PORT} \
+    DOTNET_EnableDiagnostics=0 \
+    DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 \
+    COMPlus_EnableDiagnostics=0
+
+USER ${APP_UID}:${APP_GID}
+EXPOSE ${APP_PORT}
+HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
+  CMD /usr/local/bin/healthcheck.sh
+
+# Harden filesystem; deploys should also set readOnlyRootFilesystem true
+RUN chmod 500 /app && \
+    find /app -maxdepth 1 -type f -exec chmod 400 {} \; && \
+    find /app -maxdepth 1 -type d -exec chmod 500 {} \;
+
+ENTRYPOINT ["./StellaOps.Service"]
--- a/ops/devops/docker/base-image-guidelines.md
+++ b/ops/devops/docker/base-image-guidelines.md
@@ -0,0 +1,68 @@
+# Docker hardening blueprint (DOCKER-44-001)
+
+Use this template for core services (API, Console, Orchestrator, Task Runner, Concelier, Excititor, Policy, Notify, Export, AdvisoryAI).
+
+The reusable multi-stage scaffold lives at `ops/devops/docker/Dockerfile.hardened.template` and expects:
+- .NET 10 SDK/runtime images provided via offline mirror (`SDK_IMAGE` / `RUNTIME_IMAGE`).
+- `APP_PROJECT` path to the service csproj.
+- `healthcheck.sh` copied from `ops/devops/docker/` (already referenced by the template).
+
+Copy the template next to the service and set build args in CI (per-service matrix) to avoid maintaining divergent Dockerfiles.
+
+```Dockerfile
+# syntax=docker/dockerfile:1.7
+ARG SDK_IMAGE=mcr.microsoft.com/dotnet/sdk:10.0-bookworm-slim
+ARG RUNTIME_IMAGE=mcr.microsoft.com/dotnet/aspnet:10.0-bookworm-slim
+ARG APP_PROJECT=src/Service/Service.csproj
+ARG CONFIGURATION=Release
+ARG APP_USER=stella
+ARG APP_UID=10001
+ARG APP_GID=10001
+ARG APP_PORT=8080
+
+FROM ${SDK_IMAGE} AS build
+ENV DOTNET_CLI_TELEMETRY_OPTOUT=1 DOTNET_NOLOGO=1 SOURCE_DATE_EPOCH=1704067200
+WORKDIR /src
+COPY . .
+RUN dotnet restore ${APP_PROJECT} --packages /src/local-nugets && \
+    dotnet publish ${APP_PROJECT} -c ${CONFIGURATION} -o /app/publish /p:UseAppHost=true /p:PublishTrimmed=false
+
+FROM ${RUNTIME_IMAGE} AS runtime
+RUN groupadd -r -g ${APP_GID} ${APP_USER} && \
+    useradd -r -u ${APP_UID} -g ${APP_GID} -d /var/lib/${APP_USER} ${APP_USER}
+WORKDIR /app
+COPY --from=build --chown=${APP_UID}:${APP_GID} /app/publish/ ./
+COPY --chown=${APP_UID}:${APP_GID} ops/devops/docker/healthcheck.sh /usr/local/bin/healthcheck.sh
+ENV ASPNETCORE_URLS=http://+:${APP_PORT} \
+    DOTNET_EnableDiagnostics=0 \
+    DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 \
+    COMPlus_EnableDiagnostics=0
+USER ${APP_UID}:${APP_GID}
+EXPOSE ${APP_PORT}
+HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 CMD /usr/local/bin/healthcheck.sh
+RUN chmod 500 /app && find /app -maxdepth 1 -type f -exec chmod 400 {} \; && find /app -maxdepth 1 -type d -exec chmod 500 {} \;
+ENTRYPOINT ["./StellaOps.Service"]
+```
+
+Build stage (per service) should:
+- Use `mcr.microsoft.com/dotnet/sdk:10.0-bookworm-slim` (or mirror) with `DOTNET_CLI_TELEMETRY_OPTOUT=1`.
+- Restore from `local-nugets/` (offline) and run `dotnet publish -c Release -o /app/out`.
+- Set `SOURCE_DATE_EPOCH` to freeze timestamps.
+
+Required checks:
+- No `root` user in final image.
+- `CAP_NET_RAW` dropped (default with non-root).
+- Read-only rootfs enforced at deploy time (`securityContext.readOnlyRootFilesystem: true` in Helm/Compose).
+- Health endpoints exposed: `/health/liveness`, `/health/readiness`, `/version`, `/metrics`.
+- Image SBOM generated (syft) in pipeline; attach cosign attestations (see DOCKER-44-002).
+
+SBOM & attestation helper (DOCKER-44-002):
+- Script: `ops/devops/docker/sbom_attest.sh <image> [out-dir] [cosign-key]`
+- Emits SPDX (`*.spdx.json`) and CycloneDX (`*.cdx.json`) with `SOURCE_DATE_EPOCH` pinned for reproducibility.
+- Attaches both as cosign attestations (`--type spdx` / `--type cyclonedx`); supports keyless when `COSIGN_EXPERIMENTAL=1` or explicit PEM key.
+- Integrate in CI after image build/push; keep registry creds offline-friendly (use local registry mirror during air-gapped builds).
+
+Health endpoint verification (DOCKER-44-003):
+- Script: `ops/devops/docker/verify_health_endpoints.sh <image> [port]` spins container, checks `/health/liveness`, `/health/readiness`, `/version`, `/metrics`, and warns if `/capabilities.merge` is not `false` (for Concelier/Excititor).
+- Run in CI after publishing the image; requires `docker` and `curl` (or `wget`).
+- Endpoint contract and ASP.NET wiring examples live in `ops/devops/docker/health-endpoints.md`; service owners should copy the snippet and ensure readiness checks cover DB/cache/bus.
--- a/ops/devops/docker/health-endpoints.md
+++ b/ops/devops/docker/health-endpoints.md
@@ -0,0 +1,44 @@
+# Health & capability endpoint contract (DOCKER-44-003)
+
+Target services: API, Console, Orchestrator, Task Runner, Concelier, Excititor, Policy, Notify, Export, AdvisoryAI.
+
+## HTTP paths
+- `GET /health/liveness` — fast, dependency-free check; returns `200` and minimal body.
+- `GET /health/readiness` — may hit critical deps (DB, bus, cache); returns `503` when not ready.
+- `GET /version` — static payload with `service`, `version`, `commit`, `buildTimestamp` (ISO-8601 UTC), `source` (channel).
+- `GET /metrics` — Prometheus text exposition; reuse existing instrumentation.
+- `GET /capabilities` — if present for Concelier/Excititor, must include `"merge": false`.
+
+## Minimal ASP.NET 10 wiring (per service)
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+// health checks; add real checks as needed
+builder.Services.AddHealthChecks();
+var app = builder.Build();
+
+app.MapHealthChecks("/health/liveness", new() { Predicate = _ => false });
+app.MapHealthChecks("/health/readiness");
+
+app.MapGet("/version", () => Results.Json(new {
+    service = "StellaOps.Policy", // override per service
+    version = ThisAssembly.AssemblyInformationalVersion,
+    commit = ThisAssembly.Git.Commit,
+    buildTimestamp = ThisAssembly.Git.CommitDate.UtcDateTime,
+    source = Environment.GetEnvironmentVariable("STELLA_CHANNEL") ?? "edge"
+}));
+
+app.UseHttpMetrics();
+app.MapMetrics();
+
+app.Run();
+```
+- Ensure `ThisAssembly.*` source generators are enabled or substitute build vars.
+- Keep `/health/liveness` lightweight; `/health/readiness` should test critical dependencies (Mongo, Redis, message bus) with timeouts.
+- When adding `/capabilities`, explicitly emit `merge = false` for Concelier/Excititor.
+
+## CI verification
+- After publishing an image, run `ops/devops/docker/verify_health_endpoints.sh <image> [port]`.
+- CI should fail if any required endpoint is missing or non-200.
+
+## Deployment
+- Helm/Compose should set `readOnlyRootFilesystem: true` and wire readiness/liveness probes to these paths/port.
--- a/ops/devops/docker/healthcheck.sh
+++ b/ops/devops/docker/healthcheck.sh
@@ -0,0 +1,24 @@
+#!/bin/sh
+set -eu
+HOST="${HEALTH_HOST:-127.0.0.1}"
+PORT="${HEALTH_PORT:-8080}"
+LIVENESS_PATH="${LIVENESS_PATH:-/health/liveness}"
+READINESS_PATH="${READINESS_PATH:-/health/readiness}"
+USER_AGENT="stellaops-healthcheck"
+
+fetch() {
+  target_path="$1"
+  # BusyBox wget is available in Alpine; curl not assumed.
+  wget -qO- "http://${HOST}:${PORT}${target_path}" \
+    --header="User-Agent: ${USER_AGENT}" \
+    --timeout="${HEALTH_TIMEOUT:-4}" >/dev/null
+}
+
+fail=0
+if ! fetch "$LIVENESS_PATH"; then
+  fail=1
+fi
+if ! fetch "$READINESS_PATH"; then
+  fail=1
+fi
+exit "$fail"
--- a/ops/devops/docker/sbom_attest.sh
+++ b/ops/devops/docker/sbom_attest.sh
@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Deterministic SBOM + attestation helper for DOCKER-44-002
+# Usage: ./sbom_attest.sh <image-ref> [output-dir] [cosign-key]
+# - image-ref: fully qualified image (e.g., ghcr.io/stellaops/policy:1.2.3)
+# - output-dir: defaults to ./sbom
+# - cosign-key: path to cosign key (PEM). If omitted, uses keyless if allowed (COSIGN_EXPERIMENTAL=1)
+
+set -euo pipefail
+IMAGE_REF=${1:?"image ref required"}
+OUT_DIR=${2:-sbom}
+COSIGN_KEY=${3:-}
+
+mkdir -p "${OUT_DIR}"
+
+# Normalize filename (replace / and : with _)
+name_safe() {
+  echo "$1" | tr '/:' '__'
+}
+
+BASENAME=$(name_safe "${IMAGE_REF}")
+SPDX_JSON="${OUT_DIR}/${BASENAME}.spdx.json"
+CDX_JSON="${OUT_DIR}/${BASENAME}.cdx.json"
+ATTESTATION="${OUT_DIR}/${BASENAME}.sbom.att"
+
+# Freeze timestamps for reproducibility
+export SOURCE_DATE_EPOCH=${SOURCE_DATE_EPOCH:-1704067200}
+
+# Generate SPDX 3.0-ish JSON (syft formats are stable and offline-friendly)
+syft "${IMAGE_REF}" -o spdx-json > "${SPDX_JSON}"
+# Generate CycloneDX 1.6 JSON
+syft "${IMAGE_REF}" -o cyclonedx-json > "${CDX_JSON}"
+
+# Attach SBOMs as cosign attestations (one per format)
+export COSIGN_EXPERIMENTAL=${COSIGN_EXPERIMENTAL:-1}
+COSIGN_ARGS=("attest" "--predicate" "${SPDX_JSON}" "--type" "spdx" "${IMAGE_REF}")
+if [[ -n "${COSIGN_KEY}" ]]; then
+  COSIGN_ARGS+=("--key" "${COSIGN_KEY}")
+fi
+cosign "${COSIGN_ARGS[@]}"
+
+COSIGN_ARGS=("attest" "--predicate" "${CDX_JSON}" "--type" "cyclonedx" "${IMAGE_REF}")
+if [[ -n "${COSIGN_KEY}" ]]; then
+  COSIGN_ARGS+=("--key" "${COSIGN_KEY}")
+fi
+cosign "${COSIGN_ARGS[@]}"
+
+echo "SBOMs written to ${SPDX_JSON} and ${CDX_JSON}" >&2
+echo "Attestations pushed for ${IMAGE_REF}" >&2
--- a/ops/devops/docker/verify_health_endpoints.sh
+++ b/ops/devops/docker/verify_health_endpoints.sh
@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# Smoke-check /health and capability endpoints for a built image (DOCKER-44-003)
+# Usage: ./verify_health_endpoints.sh <image-ref> [port]
+# Requires: docker, curl or wget
+set -euo pipefail
+IMAGE=${1:?"image ref required"}
+PORT=${2:-8080}
+CONTAINER_NAME="healthcheck-$$"
+TIMEOUT=30
+SLEEP=1
+
+have_curl=1
+if ! command -v curl >/dev/null 2>&1; then
+  have_curl=0
+fi
+
+req() {
+  local path=$1
+  local url="http://127.0.0.1:${PORT}${path}"
+  if [[ $have_curl -eq 1 ]]; then
+    curl -fsS --max-time 3 "$url" >/dev/null
+  else
+    wget -qO- --timeout=3 "$url" >/dev/null
+  fi
+}
+
+cleanup() {
+  docker rm -f "$CONTAINER_NAME" >/dev/null 2>&1 || true
+}
+trap cleanup EXIT
+
+echo "[info] starting container ${IMAGE} on port ${PORT}" >&2
+cleanup
+if ! docker run -d --rm --name "$CONTAINER_NAME" -p "${PORT}:${PORT}" "$IMAGE" >/dev/null; then
+  echo "[error] failed to start image ${IMAGE}" >&2
+  exit 1
+fi
+
+# wait for readiness
+start=$(date +%s)
+while true; do
+  if req /health/liveness 2>/dev/null; then break; fi
+  now=$(date +%s)
+  if (( now - start > TIMEOUT )); then
+    echo "[error] liveness endpoint did not come up in ${TIMEOUT}s" >&2
+    exit 1
+  fi
+  sleep $SLEEP
+done
+
+# verify endpoints
+fail=0
+for path in /health/liveness /health/readiness /version /metrics; do
+  if ! req "$path"; then
+    echo "[error] missing or failing ${path}" >&2
+    fail=1
+  fi
+done
+
+# capability endpoint optional; if present ensure merge=false for Concelier/Excititor
+if req /capabilities 2>/dev/null; then
+  body="$(curl -fsS "http://127.0.0.1:${PORT}/capabilities" 2>/dev/null || true)"
+  if echo "$body" | grep -q '"merge"[[:space:]]*:[[:space:]]*false'; then
+    :
+  else
+    echo "[warn] /capabilities present but merge flag not false" >&2
+  fi
+fi
+
+exit $fail