ci.yml

name: OpenShield CI

on:
  pull_request:
    branches:
      - dev
      - main
  # Post-merge assurance: re-run the full gate on the merged result, so a green
  # PR run against an older base is not the only evidence for dev and main.
  push:
    branches:
      - dev
      - main

# Cancel superseded runs on the same PR to save runner minutes. Post-merge runs
# are never cancelled, so every commit on dev and main keeps its own result.
concurrency:
  group: ci-${{ github.workflow }}-${{ github.event_name == 'push' && github.sha || github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

# Least privilege: jobs only read repo contents
permissions:
  contents: read

jobs:
  # ── Lint & format gate (ruff) ───────────────────────────────────────────
  lint:
    name: Lint (ruff)
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1

      - name: Set up Python 3.11
        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
        with:
          python-version: "3.11"
          cache: pip

      - name: Install ruff
        run: |
          python -m pip install --require-hashes --only-binary=:all: -r requirements-dev.txt

      - name: ruff check
        run: ruff check .

      - name: ruff format --check
        run: ruff format --check .

  # ── Rule/compliance/API static validation (no DB required) ──────────────
  rule-validation:
    name: Rule & Compliance Validation
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1

      - name: Set up Python 3.11
        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
        with:
          python-version: "3.11"
          cache: pip

      - name: Install dependencies
        run: |
          python -m pip install --require-hashes --only-binary=:all: -r requirements.txt
          python -m pip check

      - name: Verify dependency locks
        run: |
          LOCK_TOOL_ENV="${RUNNER_TEMP}/openshield-lock-tools"
          python -m venv "$LOCK_TOOL_ENV"
          "$LOCK_TOOL_ENV/bin/python" -m pip install --require-hashes --only-binary=:all: -r requirements-lock.txt
          "$LOCK_TOOL_ENV/bin/python" scripts/lock_dependencies.py --check

      # ── CHECK 1: Python syntax on all rule files ───────────────────────
      - name: Python syntax check (rule files)
        id: syntax_check
        run: |
          echo "=== Checking Python syntax on scanner/rules/ ==="
          FAIL=0
          shopt -s nullglob
          files=(scanner/rules/az_*.py)
          if [ ${#files[@]} -eq 0 ]; then
            echo "ERROR: No rule files found matching scanner/rules/az_*.py"
            exit 1
          fi
          for f in "${files[@]}"; do
            if ! python -m py_compile "$f" 2>&1; then
              echo "SYNTAX ERROR: $f"
              FAIL=1
            else
              echo "OK: $f"
            fi
          done
          if [ "$FAIL" -eq 1 ]; then
            echo "One or more rule files have syntax errors."
            exit 1
          fi

      # ── CHECK 2: Rule structure validation + RULE_ID uniqueness ──────
      - name: Rule structure validation
        id: structure_check
        run: |
          echo "=== Validating rule file structure ==="
          python - <<'PYEOF'
          import os
          import importlib.util
          import sys
          from collections import defaultdict
          from openshield.severity import CANONICAL_SEVERITIES

          rules_dir = "scanner/rules"
          required_fields = ["RULE_ID", "SEVERITY", "FRAMEWORKS"]
          failures = []
          seen_ids = defaultdict(list)

          for filename in sorted(os.listdir(rules_dir)):
              is_helper = filename == "__init__.py" or (
                  filename.startswith("_") and filename.endswith("_common.py")
              )
              if filename.endswith(".py") and not (filename.startswith("az_") or is_helper):
                  failures.append(
                      f"{filename}: rule-directory Python files must match az_*.py or _*_common.py"
                  )
                  continue
              if not filename.startswith("az_") or not filename.endswith(".py"):
                  continue

              filepath = os.path.join(rules_dir, filename)
              spec = importlib.util.spec_from_file_location("rule", filepath)
              mod = importlib.util.module_from_spec(spec)

              try:
                  spec.loader.exec_module(mod)
              except Exception as e:
                  failures.append(f"{filename}: import error — {e}")
                  continue

              for field in required_fields:
                  if not hasattr(mod, field):
                      failures.append(f"{filename}: missing field '{field}'")

              if hasattr(mod, "SEVERITY"):
                  if mod.SEVERITY not in CANONICAL_SEVERITIES:
                      failures.append(
                          f"{filename}: SEVERITY '{mod.SEVERITY}' not in "
                          f"{sorted(CANONICAL_SEVERITIES)}"
                      )

              if hasattr(mod, "FRAMEWORKS"):
                  if not isinstance(mod.FRAMEWORKS, dict) or len(mod.FRAMEWORKS) == 0:
                      failures.append(f"{filename}: FRAMEWORKS must be a non-empty dict")

              if hasattr(mod, "RULE_ID"):
                  seen_ids[mod.RULE_ID].append(filename)

          # Two files sharing a RULE_ID silently corrupt scan reports
          for rule_id, files in seen_ids.items():
              if len(files) > 1:
                  failures.append(
                      f"DUPLICATE RULE_ID '{rule_id}' in: {', '.join(files)}"
                  )

          if failures:
              print("RULE STRUCTURE FAILURES:")
              for f in failures:
                  print(f"  - {f}")
              sys.exit(1)
          else:
              print(f"All {len(seen_ids)} rule files passed structure validation.")
          PYEOF

      # ── CHECK 3: Hardcoded credential scan ────────────────────────────
      - name: Hardcoded credential scan
        id: cred_scan
        run: |
          echo "=== Scanning for hardcoded credentials ==="
          # Each credential-name pattern requires a quoted string literal on the
          # right-hand side. This flags real hardcoded values (api_key = "sk-...")
          # while ignoring safe assignments to function calls or expressions
          # (api_key = str(data.get(...)) , _SECRET = secrets.token_urlsafe(32)).
          PATTERNS=(
            "password\s*=\s*['\"]"
            "secret\s*=\s*['\"]"
            "api_key\s*=\s*['\"]"
            "client_secret\s*=\s*['\"]"
            "AZURE_CLIENT_SECRET\s*=\s*['\"][^'\"]\+"
            "-----BEGIN.*PRIVATE KEY-----"
            "AccountKey="
          )

          FAIL=0
          for pattern in "${PATTERNS[@]}"; do
            matches=$(grep -rniE "$pattern" \
              --include="*.py" --include="*.sh" --include="*.json" --include="*.yml" \
              --exclude-dir=".git" \
              --exclude-dir="venv" \
              --exclude="ci.yml" \
              . 2>/dev/null | \
              grep -v "\.env" | \
              grep -v "os\.environ" | \
              grep -v "os\.getenv" | \
              grep -vE '^\s*#' | \
              grep -v "example" | \
              grep -v "placeholder" | \
              grep -v "\.get(" | \
              grep -v "request\." | \
              grep -v "config\." || true)

            if [ -n "$matches" ]; then
              echo "POTENTIAL CREDENTIAL LEAK — pattern '$pattern':"
              echo "$matches"
              FAIL=1
            fi
          done

          if [ "$FAIL" -eq 1 ]; then
            echo "Hardcoded credentials detected. Remove them and use environment variables."
            exit 1
          else
            echo "No hardcoded credentials found."
          fi

      # ── CHECK 4: Playbook existence + bash syntax ─────────────────────
      - name: Playbook existence and syntax check
        id: playbook_check
        run: |
          echo "=== Checking playbooks exist and are valid bash ==="
          FAIL=0
          shopt -s nullglob
          files=(scanner/rules/az_*.py)
          if [ ${#files[@]} -eq 0 ]; then
            echo "ERROR: No rule files found matching scanner/rules/az_*.py"
            exit 1
          fi
          for rule_file in "${files[@]}"; do
            filename=$(basename "$rule_file" .py)
            playbook="playbooks/cli/fix_${filename}.sh"

            if [ ! -f "$playbook" ]; then
              echo "MISSING PLAYBOOK: $playbook (required for $rule_file)"
              FAIL=1
            elif ! bash -n "$playbook" 2>&1; then
              echo "BASH SYNTAX ERROR: $playbook"
              FAIL=1
            else
              echo "OK: $playbook"
            fi
          done

          if [ "$FAIL" -eq 1 ]; then
            echo "Fix the missing or broken playbook(s) before this PR can merge."
            exit 1
          fi

      # ── CHECK 5: Compliance JSON validation ───────────────────────────
      - name: Compliance JSON validation
        id: json_check
        run: |
          echo "=== Validating compliance framework JSON files ==="
          python - <<'PYEOF'
          import json
          import sys
          import os

          framework_dir = "compliance/frameworks"
          expected_files = [
              "cis_azure_benchmark.json",
              "nist_csf.json",
              "iso27001.json",
              "soc2.json",
          ]
          failures = []

          for fname in expected_files:
              fpath = os.path.join(framework_dir, fname)

              if not os.path.exists(fpath):
                  failures.append(f"MISSING FILE: {fpath}")
                  continue

              try:
                  with open(fpath) as f:
                      data = json.load(f)

                  if not isinstance(data, dict) or len(data) == 0:
                      failures.append(f"{fname}: must be a non-empty JSON object")
                      continue

                  n_controls = len(data.get("controls", {}))
                  print(f"OK: {fname} ({n_controls} controls)")

              except json.JSONDecodeError as e:
                  failures.append(f"{fname}: invalid JSON — {e}")

          if failures:
              print("COMPLIANCE JSON FAILURES:")
              for f in failures:
                  print(f"  - {f}")
              sys.exit(1)
          PYEOF

      # ── CHECK 6: API syntax check ──────────────────────────────────────
      - name: API syntax check
        id: api_check
        run: |
          echo "=== Checking Python syntax on API files ==="
          FAIL=0
          for dir in api ai scanner sentinel; do
            if [ -d "$dir" ]; then
              while IFS= read -r -d '' f; do
                if ! python -m py_compile "$f" 2>&1; then
                  echo "SYNTAX ERROR: $f"
                  FAIL=1
                else
                  echo "OK: $f"
                fi
              done < <(find "$dir/" -name "*.py" -print0)
            fi
          done

          if [ "$FAIL" -eq 1 ]; then
            echo "One or more files have syntax errors."
            exit 1
          fi

      # ── CHECK 7: Compliance JSON ↔ rule file cross-reference ──────────
      - name: Compliance rule cross-reference
        id: xref_check
        run: |
          echo "=== Cross-referencing compliance controls against rule files ==="
          python - <<'PYEOF'
          import json
          import os
          import importlib.util
          import sys

          rules_dir = "scanner/rules"
          framework_dir = "compliance/frameworks"

          existing_ids = set()
          for filename in os.listdir(rules_dir):
              if not filename.startswith("az_") or not filename.endswith(".py"):
                  continue
              filepath = os.path.join(rules_dir, filename)
              spec = importlib.util.spec_from_file_location("rule", filepath)
              mod = importlib.util.module_from_spec(spec)
              try:
                  spec.loader.exec_module(mod)
                  if hasattr(mod, "RULE_ID"):
                      existing_ids.add(mod.RULE_ID)
              except Exception:
                  pass

          failures = []

          for fname in os.listdir(framework_dir):
              if not fname.endswith(".json"):
                  continue
              fpath = os.path.join(framework_dir, fname)
              try:
                  with open(fpath) as f:
                      data = json.load(f)
              except (json.JSONDecodeError, OSError):
                  continue

              for rule_id in data.get("controls", {}):
                  if rule_id not in existing_ids:
                      failures.append(
                          f"{fname}: references '{rule_id}' but no matching rule file found"
                      )

          if failures:
              print("COMPLIANCE CROSS-REFERENCE FAILURES:")
              for f in failures:
                  print(f"  - {f}")
              print()
              print("Either add the missing rule file or remove the stale control mapping.")
              sys.exit(1)
          else:
              print(f"All compliance controls map to existing rule files. ({len(existing_ids)} rules checked)")
          PYEOF

      # ── CHECK 8: Compliance mapping-pack semantics validation ─────────
      # Every control must carry evidence-based mapping metadata, not just
      # exist in the file (issue #302). This is what actually stops a
      # future PR from force-mapping a rule into a framework with no
      # rationale for the relationship, or leaving a synthetic non-mapping
      # misclassified as direct technical evidence. Logic lives in
      # .github/scripts/validate_mapping_pack.py so it's unit-testable
      # (tests/test_mapping_pack_validation.py) rather than only exercised
      # here, embedded in workflow YAML.
      - name: Compliance mapping semantics validation
        id: mapping_semantics_check
        run: python .github/scripts/validate_mapping_pack.py

  # ── Secret scanning (Gitleaks CLI, no gitleaks-action license needed) ─────
  secret-scan:
    name: Secret Scan (Gitleaks)
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1

      - name: Install gitleaks
        run: |
          GITLEAKS_VERSION="8.30.1"
          curl -sSL "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz" -o /tmp/gitleaks.tar.gz
          tar -xzf /tmp/gitleaks.tar.gz -C /tmp gitleaks
          sudo mv /tmp/gitleaks /usr/local/bin/gitleaks
          gitleaks version

      - name: Run gitleaks
        run: gitleaks detect --source . --no-git -v --exit-code 1

  # ── SAST (Bandit) ──────────────────────────────────────────────────────────
  sast-bandit:
    name: SAST (Bandit)
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1

      - name: Set up Python 3.11
        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
        with:
          python-version: "3.11"
          cache: pip

      - name: Install bandit
        run: pip install bandit

      - name: Run bandit
        run: bandit -r api/ scanner/ ai/ -ll

  # ── SAST (Semgrep) ──────────────────────────────────────────────────────────
  sast-semgrep:
    name: SAST (Semgrep)
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1

      - name: Set up Python 3.11
        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
        with:
          python-version: "3.11"
          cache: pip

      - name: Install semgrep
        run: pip install semgrep

      - name: Run semgrep
        id: semgrep
        continue-on-error: true
        run: |
          semgrep scan \
            --config p/security-audit \
            --config p/owasp-top-ten \
            --config p/python \
            --config p/javascript \
            --exclude venv \
            --exclude frontend/node_modules \
            --exclude frontend/dist \
            --metrics=off \
            --sarif --output semgrep.sarif \
            --error \
            .

      - name: Upload SARIF to GitHub code scanning
        if: always()
        uses: github/codeql-action/upload-sarif@411c4c9a36b3fca4d674f06b6396b2c6d23522c6 # v3.36.3
        with:
          sarif_file: semgrep.sarif
          category: semgrep

      - name: Fail job if Semgrep found issues
        if: steps.semgrep.outcome == 'failure'
        run: exit 1

  # ── SCA / dependency scanning (pip-audit) ─────────────────────────────────
  sca-pip-audit:
    name: SCA (pip-audit)
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1

      - name: Set up Python 3.11
        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
        with:
          python-version: "3.11"
          cache: pip

      - name: Install pip-audit
        run: pip install pip-audit

      # transformers (transitive via sentence-transformers) has no non-breaking fix yet; tracked separately
      - name: Run pip-audit
        run: |
          pip-audit -r requirements.txt \
            --ignore-vuln PYSEC-2025-217 \
            --ignore-vuln CVE-2026-1839 \
            --ignore-vuln CVE-2026-4372

  # ── Software Bill of Materials (Syft, CycloneDX) ──────────────────────────
  sbom:
    name: SBOM (Syft)
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1

      - name: Install syft
        env:
          SYFT_VERSION: "1.46.0"
          SYFT_SHA256: d654f678b709eb53c393d38519d5ed7d2e57205529404018614cfefa0fb2b5ca
        run: |
          SYFT_ARCHIVE="syft_${SYFT_VERSION}_linux_amd64.tar.gz"
          curl --fail --silent --show-error --location \
            --output "$SYFT_ARCHIVE" \
            "https://github.com/anchore/syft/releases/download/v${SYFT_VERSION}/${SYFT_ARCHIVE}"
          echo "${SYFT_SHA256}  ${SYFT_ARCHIVE}" | sha256sum --check --strict
          sudo tar --extract --gzip --file "$SYFT_ARCHIVE" --directory /usr/local/bin syft

      - name: Generate SBOM
        run: syft dir:. --source-name openshield --source-version "${{ github.sha }}" -o cyclonedx-json=sbom.cyclonedx.json

      - name: Upload SBOM artifact
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: sbom-cyclonedx
          path: sbom.cyclonedx.json
          retention-days: 90

  # ── Container runtime contract + image scan (Trivy) ───────────────────────
  container-scan:
    name: Container Scan (Trivy)
    runs-on: ubuntu-latest
    env:
      IMAGE_TAG: openshield-ci-scan:${{ github.sha }}
      CONTAINER_NAME: openshield-ci-runtime
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_USER: ci
          POSTGRES_PASSWORD: ci
          POSTGRES_DB: ci_db
        ports:
          - 5432/tcp
        options: >-
          --health-cmd "pg_isready -U ci -d ci_db"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      - name: Checkout repository
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1

      - name: Build image
        id: build
        run: docker build --tag "$IMAGE_TAG" --file Dockerfile .

      - name: Verify BM25 retrieval in fresh image
        run: |
          docker run --rm --entrypoint python "$IMAGE_TAG" -c \
            "from ai.retriever import retrieve; results = retrieve('Azure storage account security', n_results=5); assert results; print(results[0]['source'])"

      - name: Start image
        env:
          POSTGRES_PORT: ${{ job.services.postgres.ports[5432] }}
        run: |
          set -euo pipefail
          JWT_SECRET="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"
          docker run --detach \
            --name "$CONTAINER_NAME" \
            --network host \
            --env "DATABASE_URL=postgresql://ci:ci@127.0.0.1:${POSTGRES_PORT}/ci_db" \
            --env OPENSHIELD_ENV=production \
            --env OPENSHIELD_PUBLIC_DEMO=false \
            --env ALLOWED_ORIGINS=http://127.0.0.1:8000 \
            --env PORT=8000 \
            --env "JWT_SECRET=$JWT_SECRET" \
            "$IMAGE_TAG"

      - name: Verify readiness and non-root runtime
        run: |
          python3 - <<'PYEOF'
          import json
          import time
          import urllib.error
          import urllib.request

          url = "http://127.0.0.1:8000/ready"
          last_error = "container did not answer"
          for attempt in range(1, 31):
              try:
                  with urllib.request.urlopen(url, timeout=3) as response:
                      status = response.status
                      payload = json.load(response)
                  if status == 200 and payload == {"status": "ready"}:
                      print(f"Runtime readiness passed on attempt {attempt}: {payload}")
                      break
                  last_error = f"HTTP {status}: {payload!r}"
              except (OSError, ValueError, urllib.error.URLError) as exc:
                  last_error = repr(exc)
              time.sleep(2)
          else:
              raise SystemExit(f"Runtime readiness failed after 30 attempts: {last_error}")
          PYEOF

          RUNTIME_UID="$(docker exec "$CONTAINER_NAME" id -u)"
          if [ "$RUNTIME_UID" = "0" ]; then
            echo "ERROR: container is running as root."
            exit 1
          fi
          echo "Container runtime UID is $RUNTIME_UID (non-root)."

      - name: Show runtime logs on failure
        if: failure()
        run: docker logs "$CONTAINER_NAME" || true

      - name: Remove runtime smoke container
        if: always()
        run: docker rm --force "$CONTAINER_NAME" || true

      - name: Run Trivy
        if: ${{ !cancelled() && steps.build.outcome == 'success' }}
        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
        with:
          image-ref: ${{ env.IMAGE_TAG }}
          severity: CRITICAL,HIGH
          ignore-unfixed: true
          exit-code: "1"

  # ── Backend test suite with coverage ─────────────────────────────────────
  backend-tests:
    name: Backend Tests (pytest + coverage)
    runs-on: ubuntu-latest

    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_USER: ci
          POSTGRES_PASSWORD: ci
          POSTGRES_DB: ci_db
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    steps:
      - name: Checkout repository
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1

      - name: Set up Python 3.11
        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
        with:
          python-version: "3.11"
          cache: pip

      - name: Install dependencies
        run: |
          python -m pip install --require-hashes --only-binary=:all: -r requirements-dev.txt
          python -m pip check

      - name: Check Alembic revision graph has exactly one head
        env:
          DATABASE_URL: "postgresql://ci:ci@localhost:5432/ci_db"
        # A migration branched from the same down_revision as another
        # unmerged PR's migration (a fork) is invisible to a single PR's own
        # CI run - each PR only has its own migration file, so `alembic
        # upgrade head` succeeds in isolation. It's only detectable once both
        # land on the same branch. This check catches that state explicitly
        # instead of leaving `alembic upgrade head` to fail unhelpfully on
        # whichever branch merges second.
        run: |
          HEAD_COUNT=$(alembic heads | grep -c '(head)')
          if [ "$HEAD_COUNT" -ne 1 ]; then
            echo "Alembic revision graph has $HEAD_COUNT heads, expected exactly 1:"
            alembic heads
            exit 1
          fi
          echo "Alembic revision graph has exactly one head."

      - name: Apply database migrations
        env:
          DATABASE_URL: "postgresql://ci:ci@localhost:5432/ci_db"
        run: alembic upgrade head

      - name: Run test suite with coverage
        env:
          DATABASE_URL: "postgresql://ci:ci@localhost:5432/ci_db"
        run: |
          pytest tests/ -v --tb=short --cov=api --cov=scanner --cov-report=term --cov-report=xml --cov-fail-under=80

  # ── Frontend lint + build ────────────────────────────────────────────────
  frontend:
    name: Frontend (lint + build)
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: frontend
    steps:
      - name: Checkout repository
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1

      - name: Set up Node.js
        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version: "22.22.0"
          cache: npm
          cache-dependency-path: frontend/package-lock.json

      - name: Install dependencies
        run: npm ci

      - name: Lint
        run: npm run lint

      - name: Run API utility tests
        run: node src/utils/api.test.mjs && node src/utils/scanPolling.test.mjs && node src/utils/aiApi.test.mjs

      - name: Run dashboard load-state tests
        run: node src/hooks/usePageData.test.mjs

      - name: Run severity contract tests
        run: npm run test:severity

      - name: Run score/compliance null-state tests
        run: node src/utils/api.test.mjs

      - name: Run accessibility and internationalization checks
        run: npm run test:a11y && npm run test:i18n

      - name: Build
        # A canary bearer value proves a build-time token variable can no
        # longer reach the public bundle (issue #294). It is assembled at run
        # time so the workflow file itself contains no JWT-shaped string.
        env:
          CANARY_HEADER: eyJhbGciOiJIUzI1NiJ9
          CANARY_PAYLOAD: eyJjYW5hcnkiOiJvcGVuc2hpZWxkLWNpIn0
        run: VITE_JWT_TOKEN="${CANARY_HEADER}.${CANARY_PAYLOAD}.canary-signature" npm run build

      - name: Assert no bearer credential in the public bundle
        run: |
          if grep -rnoE 'eyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}|dev-local-token|canary-signature' dist; then
            echo "::error::A JWT-shaped credential or token bootstrap value is present in frontend/dist."
            exit 1
          fi
          echo "OK: no bearer credential found in frontend/dist"

  # Website validation joins CI Summary; website.yml handles Pages deployment.
  website:
    name: Website (Astro build + verification)
    runs-on: ubuntu-latest
    timeout-minutes: 10
    defaults:
      run:
        working-directory: website
    steps:
      - name: Checkout repository with full history
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          fetch-depth: 0
          persist-credentials: false

      - name: Set up Node.js
        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version: "22.22.0"
          cache: npm
          cache-dependency-path: website/package-lock.json

      - name: Install dependencies
        run: npm ci

      - name: Build and verify CMS-disabled and CMS-enabled output
        run: npm run check

  # ── Enforce branch flow: main may only receive PRs from dev ───────────────
  # No-op on dev PRs (step skipped -> job succeeds). To allow hotfixes straight
  # to main, widen the condition below to also accept a 'hotfix/*' head branch.
  enforce-source-branch:
    name: Enforce dev to main source
    runs-on: ubuntu-latest
    steps:
      - name: Require main PRs to originate from dev
        if: github.base_ref == 'main'
        env:
          HEAD_REF: ${{ github.head_ref }}
        run: |
          if [ "$HEAD_REF" != "dev" ]; then
            echo "PRs into 'main' must come from 'dev' (got '$HEAD_REF')."
            echo "Merge your work into 'dev' first, then open a dev -> main PR."
            exit 1
          fi
          echo "OK: main PR originates from dev."

  # ── Final summary — always runs, aggregates all jobs ──────────────────────
  ci-summary:
    name: CI Summary
    runs-on: ubuntu-latest
    needs:
      [lint, rule-validation, secret-scan, sast-bandit, sast-semgrep, sca-pip-audit, sbom, container-scan, backend-tests, frontend, website, enforce-source-branch]
    if: always()
    steps:
      - name: Build summary
        env:
          LINT: ${{ needs.lint.result }}
          RULE_VALIDATION: ${{ needs.rule-validation.result }}
          SECRET_SCAN: ${{ needs.secret-scan.result }}
          SAST_BANDIT: ${{ needs.sast-bandit.result }}
          SAST_SEMGREP: ${{ needs.sast-semgrep.result }}
          SCA_PIP_AUDIT: ${{ needs.sca-pip-audit.result }}
          SBOM: ${{ needs.sbom.result }}
          CONTAINER_SCAN: ${{ needs.container-scan.result }}
          BACKEND_TESTS: ${{ needs.backend-tests.result }}
          FRONTEND: ${{ needs.frontend.result }}
          WEBSITE: ${{ needs.website.result }}
          ENFORCE_SOURCE: ${{ needs.enforce-source-branch.result }}
        run: |
          python3 - <<'PYEOF'
          import os

          checks = [
              ("Lint (ruff)",                       os.environ["LINT"]),
              ("Rule & Compliance Validation",       os.environ["RULE_VALIDATION"]),
              ("Secret Scan (Gitleaks)",             os.environ["SECRET_SCAN"]),
              ("SAST (Bandit)",                      os.environ["SAST_BANDIT"]),
              ("SAST (Semgrep)",                     os.environ["SAST_SEMGREP"]),
              ("SCA (pip-audit)",                    os.environ["SCA_PIP_AUDIT"]),
              ("SBOM (Syft)",                        os.environ["SBOM"]),
              ("Container Runtime + Scan (Trivy)",        os.environ["CONTAINER_SCAN"]),
              ("Backend Tests (pytest + coverage)",  os.environ["BACKEND_TESTS"]),
              ("Frontend (lint + build)",            os.environ["FRONTEND"]),
              ("Website (Astro build + verification)", os.environ["WEBSITE"]),
              ("Enforce dev to main source",        os.environ["ENFORCE_SOURCE"]),
          ]

          labels = {
              "success":   "PASS",
              "failure":   "FAIL",
              "skipped":   "SKIP",
              "cancelled": "CANCELLED",
          }

          lines = [
              "## OpenShield CI Results",
              "",
              "| Job | Result |",
              "|---|---|",
          ]

          all_passed = True
          for name, outcome in checks:
              label = labels.get(outcome, outcome.upper())
              lines.append(f"| {name} | {label} |")
              if outcome != "success":
                  all_passed = False

          lines.append("")
          if all_passed:
              lines.append("**Result: All checks passed.**")
          else:
              lines.append("**Result: One or more checks failed. See the job logs above for details.**")

          summary = "\n".join(lines)
          print(summary)

          summary_path = os.environ.get("GITHUB_STEP_SUMMARY")
          if summary_path:
              with open(summary_path, "a") as f:
                  f.write(summary + "\n")
          PYEOF

      - name: Fail if any required job failed
        if: |
          needs.lint.result != 'success' ||
          needs.rule-validation.result != 'success' ||
          needs.secret-scan.result != 'success' ||
          needs.sast-bandit.result != 'success' ||
          needs.sast-semgrep.result != 'success' ||
          needs.sca-pip-audit.result != 'success' ||
          needs.sbom.result != 'success' ||
          needs.container-scan.result != 'success' ||
          needs.backend-tests.result != 'success' ||
          needs.frontend.result != 'success' ||
          needs.website.result != 'success' ||
          needs.enforce-source-branch.result != 'success'
        run: exit 1