ci: security scanning suite and governance (consolidates #305-310)

.github/CODEOWNERS

@@ -0,0 +1,8 @@
+# Code owners.
+#
+# Every file is owned by the maintainer, so that when branch protection has
+# "Require review from Code Owners" turned on, no pull request can be merged
+# without the maintainer's review. This is the human gate that backs up the
+# automated security checks. See docs/security-ci.md for how to turn it on.
+
+*       @pewdiepie-archdaemon

.github/dependabot.yml

@@ -0,0 +1,48 @@
+# Dependabot keeps dependencies and pinned action versions current.
+#
+# Why this matters for security: every workflow in this repo pins its GitHub
+# Actions to an exact commit (a SHA), which is safe but freezes them in time.
+# Dependabot opens a small, reviewable pull request whenever a newer version
+# exists -- for Python packages, npm packages, the Docker base image, and the
+# pinned Actions themselves -- so staying patched does not require manual work.
+# Updates are grouped so a week's bumps arrive as one PR per ecosystem, not a
+# flood of separate ones.
+
+version: 2
+updates:
+  # Python dependencies (requirements.txt + requirements-optional.txt).
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      python:
+        patterns: ["*"]
+
+  # Frontend / tooling npm packages (package.json).
+  - package-ecosystem: npm
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      npm:
+        patterns: ["*"]
+
+  # The pinned action SHAs used across .github/workflows.
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      actions:
+        patterns: ["*"]
+
+  # The Docker base image in the Dockerfile.
+  - package-ecosystem: docker
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5

.github/workflows/codeql.yml

@@ -0,0 +1,61 @@
+# CodeQL code scanning
+#
+# Purpose: GitHub's own static analysis engine reads the application source
+# (Python backend + the JavaScript frontend) and looks for real
+# vulnerabilities -- SQL/command injection, path traversal, auth mistakes,
+# unsafe deserialization. Findings appear in the repo's Security tab. This is
+# the deepest check in the suite and the most valuable for a high-profile
+# target.
+#
+# It runs on every push to main and on a weekly schedule (to catch newly
+# disclosed query patterns against unchanged code). It deliberately does NOT
+# run on pull requests: most PRs here come from forks, whose read-only token
+# cannot publish results, which would produce confusing failures. To scan pull
+# requests too, a maintainer can instead enable CodeQL "default setup" in
+# Settings -> Security -> Code scanning (one toggle, no file needed) -- see
+# docs/security-ci.md.
+
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  schedule:
+    # Weekly, Monday 06:00 UTC.
+    - cron: '0 6 * * 1'
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: codeql-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write  # publish results to the Security tab
+    strategy:
+      fail-fast: false
+      matrix:
+        # Both are interpreted, so CodeQL needs no build step (build-mode none).
+        language: [python, javascript-typescript]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@03e4368ac7daa2bd82b3e85262f3bf87ee112f57  # v3.36.0
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: none
+
+      - name: Perform CodeQL analysis
+        uses: github/codeql-action/analyze@03e4368ac7daa2bd82b3e85262f3bf87ee112f57  # v3.36.0
+        with:
+          category: "/language:${{ matrix.language }}"

.github/workflows/container-scan.yml

@@ -0,0 +1,52 @@
+# Container security: Dockerfile lint
+#
+# Purpose: the Docker image is how most people run Odysseus, so it is part of
+# the attack surface. hadolint lints the Dockerfile for mistakes and insecure
+# patterns (running as root longer than needed, unpinned base image, bad apt
+# usage). Blocking.
+#
+# The image vulnerability scan (Trivy, advisory) lives in its own file,
+# container-trivy.yml. Keeping it separate lets that advisory scan be
+# path-filtered and held to a read-only token on pull requests without
+# weakening this blocking gate, which must always report so a required check
+# never hangs.
+#
+# Note: a separate open PR (#120) proposes a local `scripts/scan_image.py`.
+# This job is complementary -- it is a CI gate, not a script a contributor has
+# to remember to run.
+
+name: Container scan
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: container-scan-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  hadolint:
+    name: hadolint (Dockerfile lint)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Lint Dockerfile
+        uses: hadolint/hadolint-action@2332a7b74a6de0dda2e2221d575162eba76ba5e5  # v3.3.0
+        with:
+          dockerfile: Dockerfile
+          # DL3008: pinning apt package versions is impractical on a -slim base
+          # image. Debian purges old package versions from its repos, so a
+          # pinned version breaks future rebuilds. The base image itself is
+          # what should be pinned (tracked by Dependabot's docker ecosystem).
+          ignore: DL3008

.github/workflows/container-trivy.yml

@@ -0,0 +1,125 @@
+# Container image vulnerability scan (advisory)
+#
+# Trivy builds the application image and scans it for known-vulnerable OS and
+# Python packages. Advisory only -- it reports findings to the repo's Security
+# tab without blocking a merge, because the image inevitably contains
+# already-known CVEs in upstream packages that are not this project's bug.
+#
+# Split from the Dockerfile lint (container-scan.yml) for two reasons:
+#
+#   - Least privilege. The image build runs Dockerfile instructions, which on a
+#     pull request are attacker-influenceable. That path (the `scan` job) is
+#     held to a read-only token and never publishes results. Only `publish`,
+#     which runs on push to main (curated, fast-forwarded from reviewed dev),
+#     gets security-events:write to upload SARIF.
+#   - Cost. Docs-only changes do not rebuild the image (paths-ignore below),
+#     matching docker-publish.yml. hadolint stays on the broad trigger in
+#     container-scan.yml so the blocking gate always reports.
+
+name: Container scan (Trivy)
+
+on:
+  pull_request:
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - '.github/ISSUE_TEMPLATE/**'
+  push:
+    branches: [main]
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - '.github/ISSUE_TEMPLATE/**'
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: container-trivy-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # Pull requests and manual runs: build and scan under a read-only token.
+  # The build executes PR-supplied Dockerfile instructions, so this job must
+  # not hold any write scope, and it does not upload to the Security tab.
+  scan:
+    name: Trivy (image scan, advisory)
+    if: github.event_name != 'push'
+    runs-on: ubuntu-latest
+    # Advisory: a CVE in an upstream package must not block a PR.
+    continue-on-error: true
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Set up Buildx
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5  # v4.1.0
+
+      # Build without pushing so a broken Dockerfile is caught here, and the
+      # exact image we ship is what gets scanned.
+      - name: Build image
+        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf  # v7.2.0
+        with:
+          context: .
+          push: false
+          load: true
+          tags: odysseus:ci
+
+      - name: Scan image with Trivy
+        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25  # v0.36.0
+        with:
+          image-ref: odysseus:ci
+          format: table
+          ignore-unfixed: true
+        env:
+          # Pin the vuln DB source to GHCR to avoid rate-limited Docker Hub
+          # mirrors that flake on shared runners.
+          TRIVY_DB_REPOSITORY: ghcr.io/aquasecurity/trivy-db:2
+
+  # Push to main only: build, scan, and publish SARIF to the Security tab.
+  # This is the only path that runs trusted code, so it is the only one granted
+  # security-events:write.
+  publish:
+    name: Trivy (image scan + SARIF upload)
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    permissions:
+      contents: read
+      security-events: write  # upload SARIF to the Security tab
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Set up Buildx
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5  # v4.1.0
+
+      - name: Build image
+        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf  # v7.2.0
+        with:
+          context: .
+          push: false
+          load: true
+          tags: odysseus:ci
+
+      - name: Scan image with Trivy
+        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25  # v0.36.0
+        with:
+          image-ref: odysseus:ci
+          format: sarif
+          output: trivy-results.sarif
+          ignore-unfixed: true
+        env:
+          TRIVY_DB_REPOSITORY: ghcr.io/aquasecurity/trivy-db:2
+
+      - name: Upload Trivy results
+        uses: github/codeql-action/upload-sarif@03e4368ac7daa2bd82b3e85262f3bf87ee112f57  # v3.36.0
+        with:
+          sarif_file: trivy-results.sarif
+          category: trivy-image

.github/workflows/dependency-review.yml

@@ -0,0 +1,71 @@
+# Supply-chain review
+#
+# Purpose: defend against "side-chain" / supply-chain attacks -- a pull request
+# that adds (or bumps) a dependency to a version with a known vulnerability or a
+# disallowed license. Two layers:
+#
+#   - dependency-review: runs ONLY on pull requests. It compares the
+#     dependencies before and after the PR and blocks the merge if the change
+#     pulls in a package with a known security advisory. This is the gate.
+#   - pip-audit: scans the project's current Python requirements against the
+#     advisory database. Advisory only (it never blocks a merge), because it can
+#     flag a pre-existing issue in an already-shipped dependency.
+
+name: Dependency review
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# Default-deny token; jobs grant only read access.
+permissions: {}
+
+concurrency:
+  group: dependency-review-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  dependency-review:
+    name: dependency-review (PR gate)
+    # Only meaningful on a pull request -- it needs a base..head diff to review.
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Review dependency changes
+        uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294  # v5.0.0
+        with:
+          # Fail the PR on any newly introduced moderate-or-worse advisory.
+          fail-on-severity: moderate
+
+  pip-audit:
+    name: pip-audit (advisory)
+    runs-on: ubuntu-latest
+    # Advisory: report known-vulnerable Python deps without blocking the merge.
+    continue-on-error: true
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
+        with:
+          python-version: '3.12'
+
+      - name: Run pip-audit on requirements
+        run: |
+          set -euo pipefail
+          pip install pip-audit==2.10.0
+          pip-audit -r requirements.txt -r requirements-optional.txt --strict