ci: add CodeQL workflow for Python static analysis

[naorpeled]

Summary

Adds a CodeQL workflow so security findings surface under the repo's Security → Code scanning tab instead of relying solely on Dependabot alerts.

```yaml
on:
push: [main]
pull_request: [main]
schedule: weekly (Mon 06:00 UTC)
```

• Language: `python` (pr-agent is pure Python; no C extensions).
• Build mode: `none` — CodeQL's source-only analysis is enough here, and it's faster than the autobuild path.
• Queries: the standard `security-extended,security-and-quality` suites (a step above the default).
• Schedule: the weekly cron catches advisories that land without a corresponding code change in this repo, which the push/PR triggers wouldn't otherwise re-evaluate.
• Action pinning: `actions/checkout` and `github/codeql-action` pinned to commit SHAs — matches the policy already in `publish.yml`.

Out of scope

• JavaScript/TypeScript analysis for the `docs/` tree (Docusaurus). Easy to add later via a second matrix entry if useful, but those files are documentation tooling, not shipped code.
• Custom query packs / suppressions. Start with the defaults and tune from real findings.

Test plan

• After merge, watch the first run on `main` complete and confirm results show up at `/security/code-scanning` for the repo.
• Open a synthetic PR that introduces a known vulnerability pattern (e.g., an obvious SQLi sink) on a throwaway branch to verify PR annotations work — then close it.

[qodo-free-for-open-source-projects]

Review Summary by Qodo

Add CodeQL workflow for Python static analysis

✨ Enhancement

Walkthroughs

Description

• Adds CodeQL workflow for automated Python security analysis
• Runs on push to main, PRs, and weekly schedule
• Uses security-extended and security-and-quality query suites
• Pins third-party actions to commit SHAs for reproducibility

Diagram

flowchart LR
  trigger["Push/PR/Schedule"] --> codeql["CodeQL Analysis"]
  codeql --> queries["Security Queries"]
  queries --> results["Code Scanning Results"]
  results --> tab["Security Tab"]

Loading

File Changes

1. .github/workflows/codeql.yml ✨ Enhancement +44/-0

New CodeQL workflow for Python security scanning

• Creates new CodeQL workflow triggered on push to main, PRs targeting main, and weekly schedule
• Configures Python analysis with build-mode set to none for source-only analysis
• Uses security-extended and security-and-quality query suites for comprehensive security coverage
• Pins actions/checkout and github/codeql-action to specific commit SHAs for reproducibility

.github/workflows/codeql.yml

---

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (0)

1. Fork PR upload blocked 🐞 Bug ☼ Reliability

Description

This workflow runs on pull_request, but for PRs opened from forks GitHub does not grant
security-events: write to the workflow token. As a result, the CodeQL analyze step cannot publish
results to code scanning for external contributor PRs (which the repo explicitly encourages via
fork-based contributions).

Code

.github/workflows/codeql.yml[R3-27]

+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  schedule:
+    # Weekly on Monday at 06:00 UTC — catches advisories that landed
+    # without a corresponding code change in this repo.
+    - cron: '0 6 * * 1'
+
+permissions:
+  contents: read
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      packages: read
+      actions: read
+      contents: read
+    strategy:

Evidence

The workflow is configured to run on pull_request and requests security-events: write in order
to upload code scanning results. The repo’s contributing guide instructs contributors to fork the
repository and open PRs, which are exactly the cases where GitHub restricts the token permissions
for security-sensitive scopes like code scanning uploads.

.github/workflows/codeql.yml[3-9]
.github/workflows/codeql.yml[22-27]
.github/workflows/codeql.yml[42-44]
CONTRIBUTING.md[7-18]
Best Practice: GitHub Actions security model
Best Practice: Code scanning upload requires security-events: write

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The CodeQL workflow runs on `pull_request` and attempts to upload results using `security-events: write`, but fork PRs cannot get that permission. This prevents publishing code scanning results for external contributor PRs.

### Issue Context
This repo explicitly expects fork-based contributions.

### Fix Focus Areas
- .github/workflows/codeql.yml[3-9]
- .github/workflows/codeql.yml[19-27]
- .github/workflows/codeql.yml[42-44]

### Suggested fix approaches (pick one)
1) **Skip CodeQL for fork PRs** (avoid failing checks / futile uploads): add a job-level `if:` that only runs on non-fork PRs (or only on `push`/`schedule`).
2) If you still want analysis on fork PRs, ensure the workflow does not attempt to upload code scanning results in that context (e.g., conditionalize the analyze/upload behavior), so the job remains green while acknowledging uploads are not possible.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Excess token permissions 🐞 Bug ⛨ Security

Description

The CodeQL job grants packages: read (and explicitly actions: read) even though the job only
checks out the repo and runs CodeQL, expanding the GITHUB_TOKEN scope unnecessarily. This increases
blast radius if any action in the job is ever compromised.

Code

.github/workflows/codeql.yml[R22-26]

+    permissions:
+      security-events: write
+      packages: read
+      actions: read
+      contents: read

Evidence

The job permissions include packages: read and actions: read, but the steps only run checkout
and CodeQL actions; there is no interaction with GitHub Packages. Least-privilege suggests removing
unused scopes.

.github/workflows/codeql.yml[22-27]
.github/workflows/codeql.yml[33-44]
Best Practice: GitHub Actions least-privilege guidance

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The CodeQL job requests permissions that are not used by its steps (`packages: read`, and potentially `actions: read`).

### Issue Context
The job only checks out code and runs CodeQL init/analyze.

### Fix Focus Areas
- .github/workflows/codeql.yml[22-27]
- .github/workflows/codeql.yml[33-44]

### Suggested fix
Remove unused permissions (start by deleting `packages: read`; consider also removing `actions: read` if not required by your environment) and keep only what’s needed, typically:
- `contents: read`
- `security-events: write`

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[github-advanced-security]

You are seeing this message because GitHub Code Scanning has recently been set up for this repository, or this pull request contains the workflow file for the Code Scanning tool.

What Enabling Code Scanning Means:

• The 'Security' tab will display more code scanning analysis results (e.g., for the default branch).
• Depending on your configuration and choice of analysis tool, future pull requests will be annotated with code scanning analysis results.
• You will be able to see the analysis results for the pull request's branch on this overview once the scans have completed and the checks have passed.

For more information about GitHub Code Scanning, check out the documentation.

[Copilot]

Pull request overview

Adds a dedicated GitHub Actions workflow to run CodeQL static analysis for the Python codebase so results appear in GitHub’s Security → Code scanning UI.

Changes:

• Introduces a new .github/workflows/codeql.yml workflow triggered on push, pull_request, and a weekly scheduled run.
• Configures CodeQL for python with build-mode: none and enables security-extended + security-and-quality query suites.
• Pins actions/checkout and github/codeql-action to specific commit SHAs.

---

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