From 78c3d484e60cf30baad75f1e8e9e6a0df96abe32 Mon Sep 17 00:00:00 2001
From: Saagar <saagarpatelai@gmail.com>
Date: Mon, 18 May 2026 03:05:15 -0700
Subject: [PATCH] ci: add CodeQL scanning

- add a Python CodeQL workflow for pull requests, main pushes, and weekly scans
- document public code-scanning coverage in workflow and security docs
- guard the workflow with distribution policy tests

Tests: ruff check src/ tests/; python3 -m pytest tests/test_distribution_policy.py -q -p no:cacheprovider; python3 -m pytest -q -p no:cacheprovider
---
 .github/workflows/README.md       | 15 +++++++++++
 .github/workflows/codeql.yml      | 44 +++++++++++++++++++++++++++++++
 CHANGELOG.md                      |  2 ++
 docs/security-model.md            | 10 +++++++
 tests/test_distribution_policy.py | 17 ++++++++++++
 5 files changed, 88 insertions(+)
 create mode 100644 .github/workflows/codeql.yml

diff --git a/.github/workflows/README.md b/.github/workflows/README.md
index 463ba1b..8c5ec41 100644
--- a/.github/workflows/README.md
+++ b/.github/workflows/README.md
@@ -16,6 +16,21 @@ Steps:
 
 No secrets are required for CI.
 
+## `codeql.yml` — Code Scanning
+
+Runs CodeQL analysis for Python on pushes and pull requests to `main`, plus a
+weekly scheduled scan. This uses advanced setup so the workflow is visible and
+reviewable in the repository.
+
+Steps:
+1. Check out the repository.
+2. Initialize CodeQL for Python with the security-extended and security-and-quality
+   query suites.
+3. Upload results to GitHub code scanning.
+
+No secrets are required. The workflow grants `security-events: write` only so the
+CodeQL action can upload SARIF results to GitHub code scanning.
+
 ## `pypi.yml` — Manual PyPI Publish
 
 Runs manually via `workflow_dispatch` after PyPI Trusted Publishing has been
diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
new file mode 100644
index 0000000..39b7ac7
--- /dev/null
+++ b/.github/workflows/codeql.yml
@@ -0,0 +1,44 @@
+name: CodeQL
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+  schedule:
+    - cron: "23 9 * * 1"
+
+permissions:
+  actions: read
+  contents: read
+  security-events: write
+
+concurrency:
+  group: codeql-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: ["python"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+          queries: security-extended,security-and-quality
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:${{ matrix.language }}"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ec77c23..1ccb86d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,8 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 ## [Unreleased]
 
 ### Changed
+- Added a CodeQL code-scanning workflow and documented the public security
+  coverage.
 - Replaced placeholder README badges with live CI, PyPI, release, Python, and
   license badges for the public repository.
 - Refreshed public contributor, security, release-gate, and workflow docs now
diff --git a/docs/security-model.md b/docs/security-model.md
index 346af10..37195bd 100644
--- a/docs/security-model.md
+++ b/docs/security-model.md
@@ -8,6 +8,16 @@ GithubRepoAuditor now treats security posture as a merged intelligence model ins
 - **GitHub-native**: dependency graph/SBOM availability, code scanning status, secret scanning status, open alert counts
 - **Scorecard**: optional public-repo enrichment from OpenSSF Scorecard
 
+## Repository Security Coverage
+
+This public repository runs CodeQL code scanning through
+`.github/workflows/codeql.yml`. The workflow analyzes Python on pushes and pull
+requests to `main`, plus a weekly scheduled scan, and uploads results to GitHub code
+scanning with `security-events: write`.
+
+Dependabot alerting is enabled for the repository, and dependency plus GitHub Actions
+updates are configured in `.github/dependabot.yml`.
+
 ## Availability Rules
 
 - `unavailable` means the provider could not be observed because of permissions, feature availability, or endpoint access.
diff --git a/tests/test_distribution_policy.py b/tests/test_distribution_policy.py
index 23a3473..ed8c839 100644
--- a/tests/test_distribution_policy.py
+++ b/tests/test_distribution_policy.py
@@ -60,3 +60,20 @@ def test_pypi_workflow_is_manual_trusted_publishing_only() -> None:
     assert "pypa/gh-action-pypi-publish@release/v1" in workflow
     assert "actions/upload-artifact" in workflow
     assert "actions/download-artifact" in workflow
+
+
+def test_public_repo_has_code_scanning_workflow_documented() -> None:
+    workflow = (ROOT / ".github" / "workflows" / "codeql.yml").read_text()
+    workflows_readme = (ROOT / ".github" / "workflows" / "README.md").read_text()
+    security_model = (ROOT / "docs" / "security-model.md").read_text()
+
+    assert "github/codeql-action/init@v4" in workflow
+    assert "github/codeql-action/analyze@v4" in workflow
+    assert "security-events: write" in workflow
+    assert "pull_request:" in workflow
+    assert "schedule:" in workflow
+    assert 'language: ["python"]' in workflow
+    assert "security-extended,security-and-quality" in workflow
+    assert "`codeql.yml` — Code Scanning" in workflows_readme
+    assert ".github/workflows/codeql.yml" in security_model
+    assert "Dependabot alerting is enabled" in security_model