ci(codeql): Guardrail gegen Default-Setup Drift

[tomtastisch]

Ziel & Scope

Guardrail implementieren, der PR-Merges fail-closed blockiert, sobald GitHub CodeQL Default Setup aktiv ist (Drift), und zusaetzlich einen taeglichen Drift-Check ausfuehrt, der bei Drift ein Issue (idempotent) erstellt.

Non-Goals:

• Keine Aenderung an Produkt-APIs.
• Keine Aenderung an SECURITY.md.

Umgesetzte Aufgaben (abhaken)

• Preflight-Check hinzugefuegt: Default Setup muss not-configured sein.
• Evidenz-Artefakte fuer Preflight (raw/summary/json) werden geschrieben.
• Scheduled Workflow hinzugefuegt (daily + workflow_dispatch).
• Scheduled Workflow erstellt bei Drift ein Issue (idempotent, gleicher Titel).
• Scheduled Workflow ist fail-closed (Run wird rot bei Drift).
• Token-Wiring: optionales Secret CODEQL_DEFAULT_SETUP_GUARDRAIL_TOKEN wird in PR-CI + Scheduled Workflow genutzt.
• GitHub Actions Permissions minimiert (contents: read, issues: write).
• Actions sind SHA-gepinnt (checkout).
• Doku hinzugefuegt, warum Default Setup nicht aktiv sein darf.

Nachbesserungen aus Review (iterativ)

• TBD
• TBD

Security- und Merge-Gates

• Branch Protection/Required Checks: muessen gruen sein.
• Code Scanning Gate: security/code-scanning/tools muss 0 offene Alerts liefern.
• Fail-Closed: API-Fehler beim Default-Setup-Check blockiert Merge (Preflight).

Wichtig (Token):

• Der Endpoint GET /repos/{owner}/{repo}/code-scanning/default-setup ist in GitHub Actions mit GITHUB_TOKEN in diesem Repo aktuell nicht erreichbar (HTTP 403 Resource not accessible by integration).
• Daher ist fuer deterministische PR-CI + Scheduled Drift Detection ein Fine-Grained PAT als Secret CODEQL_DEFAULT_SETUP_GUARDRAIL_TOKEN erforderlich (Repo-spezifisch, Read-only).

Evidence (auditierbar)

• Lokal Preflight:
  • CI_DEFER_ARTIFACT_LINK_RESOLUTION=1 GITHUB_REPOSITORY=tomtastisch/FileClassifier bash tools/ci/bin/run.sh preflight
  • Artefakte: artifacts/ci/preflight/codeql-default-setup-guardrail/
• Lokal Build:
  • bash tools/ci/bin/run.sh build
  • Artefakte: artifacts/ci/build/
• Lokal Tests:
  • bash tools/ci/bin/run.sh tests-bdd-coverage
  • Artefakte: artifacts/ci/tests-bdd-coverage/
• CI Failure (wenn Secret fehlt): Preflight-Artefakt codeql-default-setup-guardrail/summary.md enthaelt die 403-Reason inkl. Hinweis auf CODEQL_DEFAULT_SETUP_GUARDRAIL_TOKEN.

DoD (mindestens 2 pro Punkt)

1. Preflight-Guardrail

• Evidence: artifacts/ci/preflight/codeql-default-setup-guardrail/summary.md existiert und Check ist pass.
• Evidence: tools/ci/bin/run.sh preflight exit code == 0.

2. Scheduled Drift Detection

• Evidence: .github/workflows/codeql-default-setup-guardrail.yml existiert und nutzt least-privilege permissions.
• Evidence: Bei Drift wird ein Issue mit festem Titel erstellt (idempotent).

3. Dokumentation

• Evidence: docs/security/010_CODEQL_DEFAULT_SETUP_GUARDRAIL.MD erklaert Impact, Fix und Token-Anforderung.
• Evidence: Keine Aenderung an SECURITY.md.

[Copilot]

Pull request overview

Implementiert einen CI-Guardrail gegen Drift durch aktiviertes GitHub CodeQL Default Setup: PR-Merges werden fail-closed blockiert, und ein täglicher Scheduled-Check erstellt bei Drift ein (idempotentes) Issue und markiert den Run als fehlgeschlagen.

Changes:

• Neuer Preflight-Check tools/ci/check-codeql-default-setup.sh inkl. Audit-Artefakten (raw/summary/json) und fail-closed Verhalten.
• Neuer Scheduled Workflow .github/workflows/codeql-default-setup-guardrail.yml (daily + workflow_dispatch) mit Drift-Detection und Issue-Erstellung.
• Neue Guardrail-Helferskripte (get_state.sh, ensure_issue.sh) sowie Security-Doku.

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tools/ci/codeql-default-setup-guardrail/get_state.sh	Liest Default-Setup-State per GitHub API und exposed state/drift als GitHub Actions Outputs.
tools/ci/codeql-default-setup-guardrail/ensure_issue.sh	Erstellt bei Drift ein Issue (idempotent) und setzt optional Labels.
tools/ci/check-codeql-default-setup.sh	Preflight-Gate inkl. Artefakt-/Evidence-Output und fail-closed Merge-Block.
tools/ci/bin/run.sh	Bindet den neuen Preflight-Guardrail in die bestehende Preflight-Pipeline ein.
docs/security/010_CODEQL_DEFAULT_SETUP_GUARDRAIL.MD	Dokumentiert Motivation, Verifikation und Guardrails.
.github/workflows/codeql-default-setup-guardrail.yml	Scheduled Drift-Detection Workflow mit minimalen Permissions und fail-closed Run.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[tomtastisch]

Preflight faellt aktuell erwartbar mit HTTP 403 am Endpoint /code-scanning/default-setup, solange das Secret fehlt. Bitte in Repo Settings -> Secrets and variables -> Actions ein Fine-Grained PAT als hinterlegen (Repository permissions: Administration=Read-only, Security events=Read-only). Danach erneut laufen lassen (Re-run failed jobs).

[tomtastisch]

Preflight faellt aktuell erwartbar mit HTTP 403 am Endpoint /code-scanning/default-setup, solange das Secret fehlt.

Bitte in Repo Settings -> Secrets and variables -> Actions ein Fine-Grained PAT als Secret namens CODEQL_DEFAULT_SETUP_GUARDRAIL_TOKEN hinterlegen (Repository permissions: Administration=Read-only, Security events=Read-only).

Danach im PR: Actions -> CI -> preflight "Re-run failed jobs".

[Copilot]

Pull request overview

Copilot reviewed 6 out of 7 changed files in this pull request and generated 16 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.