ci: add CodeQL scanning

Add Python CodeQL scanning for pull requests, main pushes, and weekly scheduled runs, plus docs and a policy test that keep the public security posture visible.

Tests: ruff check src/ tests/; python3 -m pytest tests/test_distribution_policy.py -q -p no:cacheprovider; python3 -m pytest -q -p no:cacheprovider

Author: saagpatel

.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

.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 }}"

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

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.

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