codeql.yml

# CodeQL Security Scanning Workflow
# https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors

name: "CodeQL Security Analysis"

on:
  push:
    branches: [main]
    paths:
      - '**/*.py'
      - '.github/workflows/codeql.yml'
  pull_request:
    branches: [main]
    paths:
      - '**/*.py'
  schedule:
    # Weekly Monday 06:00 UTC — catches new CVE-relevant rules without spamming
    - cron: '0 6 * * 1'
  workflow_dispatch:

jobs:
  analyze:
    name: Analyze Code
    runs-on: ubuntu-latest
    timeout-minutes: 30
    permissions:
      # Required for all workflows
      security-events: write
      # Required to fetch internal or private CodeQL packs
      packages: read
      # Only required for workflows in private repositories
      actions: read
      contents: read

    strategy:
      fail-fast: false
      matrix:
        language: [ 'python' ]
        # CodeQL supports: 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby', 'swift'

    steps:
    - name: Checkout repository
      uses: actions/checkout@v4

    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: '3.11'
        cache: 'pip'

    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        # Install package dependencies to help CodeQL analyze usage patterns
        pip install -e .
        # Install optional dependencies for more complete analysis
        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi

    # Initializes the CodeQL tools for scanning
    - name: Initialize CodeQL
      uses: github/codeql-action/init@v3
      with:
        languages: ${{ matrix.language }}
        # Override default queries with custom security queries
        queries: +security-and-quality
        # If you wish to specify custom queries, you can do so here or in a config file.
        # By default, queries listed here will override any specified in a config file.
        # Prefix the list here with "+" to use these queries and those in the config file.

        # For more details on CodeQL's query packs, refer to:
        # https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
        # config-file: ./.github/codeql/codeql-config.yml

    # Autobuild attempts to build any compiled languages (C/C++, C#, Go, Java, or Swift).
    # For Python, this step is not strictly necessary but helps with analysis
    - name: Autobuild
      uses: github/codeql-action/autobuild@v3

    # Manual build step if autobuild fails
    # - name: Manual Build
    #   run: |
    #     echo "Manual build steps if needed"

    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v3
      with:
        category: "/language:${{matrix.language}}"
        # Upload results to GitHub Security tab
        upload: true
        # Fail the workflow if critical/high severity issues are found
        # Comment out to not fail on findings
        # fail-on: critical,high

    - name: Upload CodeQL results as artifact
      uses: actions/upload-artifact@v4
      if: always()
      with:
        name: codeql-results-${{ matrix.language }}
        path: |
          ${{ runner.temp }}/codeql_databases/
        retention-days: 7