python-security.yml

name: '🔐 Security Scanning'

on:
  workflow_call:
    inputs:
      python-version:
        description: 'Python version to use'
        type: string
        default: '3.11'
      uv-version:
        description: 'UV version to use'
        type: string
        default: '0.11.3'
      source-paths:
        description: 'Source paths for security scanning'
        type: string
        default: 'src/'
      run-bandit:
        description: 'Run Bandit static analysis'
        type: boolean
        default: true
      run-pip-audit:
        description: 'Run pip-audit dependency check'
        type: boolean
        default: true
      # Off by default, matching what this workflow has always done: the audit
      # was wrapped in `|| true`, so a finding never stopped a build.
      fail-on-vulnerability:
        description: 'Fail the job when pip-audit reports a known vulnerability'
        type: boolean
        default: false
      ignore-vulnerabilities:
        description: 'Advisory IDs the project has accepted, comma-separated'
        type: string
        default: ''
      run-trufflehog:
        description: 'Run TruffleHog secret scanning'
        type: boolean
        default: true
      run-gitleaks:
        description: 'Run Gitleaks secret scanning'
        type: boolean
        default: true
      run-codeql:
        description: 'Run CodeQL analysis'
        type: boolean
        default: false
      bandit-severity:
        description: 'Bandit minimum severity level (ll=low, l=medium, default=high)'
        type: string
        default: '-ll'

permissions:
  contents: read
  security-events: write

jobs:
  # ==================================================================================
  # 🔒 Static Security Analysis
  # ==================================================================================
  static-analysis:
    name: 🔒 Static Analysis
    runs-on: ubuntu-24.04
    steps:
      - name: 📥 Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1

      # scripts/ come from the commit this reusable workflow is running from,
      # so a caller's SHA pin covers them too rather than always taking the
      # moving tag. Falls back to v0 under act, which leaves
      # job_workflow_sha empty.
      - name: 📥 Checkout ci-tooling
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          repository: provide-io/ci-tooling
          ref: ${{ github.job_workflow_sha || 'v0' }}
          path: .ci-tooling

      - name: 🐍 Setup Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
        with:
          python-version: ${{ inputs.python-version }}

      - name: ⚡ Install UV
        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4  # v10.1.0
        with:
          version: ${{ inputs.uv-version }}
          enable-cache: true

      # Bandit is invoked from this virtualenv, so it is installed into it.
      # pip-audit is not: auditing the environment a scanner was just installed
      # into is what made advisories against the scanner's own dependencies get
      # reported as the project's.
      - name: 📦 Install dependencies
        run: |
          uv sync --group dev
          source .venv/bin/activate
          uv pip install bandit

      - name: 🔒 Run Bandit security scan
        if: inputs.run-bandit
        run: |
          source .venv/bin/activate
          echo "## 🔒 Bandit Security Scan" >> $GITHUB_STEP_SUMMARY
          bandit -r ${{ inputs.source-paths }} -f json -o bandit-report.json ${{ inputs.bandit-severity }} || true
          bandit -r ${{ inputs.source-paths }} ${{ inputs.bandit-severity }} || true

      # Audits the resolved lock with pip-audit run from `uvx`, through the same
      # script python-ci.yml uses. No virtualenv is activated: reading the lock
      # does not need one, and not having one is the point.
      - name: 🔍 Run pip-audit
        if: inputs.run-pip-audit
        run: |
          echo "## 🔍 Dependency Vulnerability Check" >> $GITHUB_STEP_SUMMARY
          .ci-tooling/scripts/security/run-pip-audit.sh pip-audit-report.json ${{ inputs.fail-on-vulnerability }} '${{ inputs.ignore-vulnerabilities }}'

      - name: 📤 Upload security reports
        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f  # v7.0.0
        if: always()
        with:
          name: security-reports
          path: |
            bandit-report.json
            pip-audit-report.json

  # ==================================================================================
  # 🔐 Secret Scanning
  # ==================================================================================
  secret-scan:
    name: 🔐 Secret Scan
    runs-on: ubuntu-24.04
    steps:
      - name: 📥 Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          fetch-depth: 0

      - name: 🔐 TruffleHog Scan (PR)
        if: inputs.run-trufflehog && github.event_name == 'pull_request'
        uses: trufflesecurity/trufflehog@main
        continue-on-error: true
        with:
          path: ./
          base: ${{ github.event.pull_request.base.sha }}
          head: ${{ github.event.pull_request.head.sha }}

      - name: 🔐 TruffleHog Scan (Push)
        if: inputs.run-trufflehog && github.event_name == 'push' && github.event.before != '0000000000000000000000000000000000000000'
        uses: trufflesecurity/trufflehog@main
        continue-on-error: true
        with:
          path: ./
          base: ${{ github.event.before }}
          head: ${{ github.sha }}

      - name: 🔐 TruffleHog Scan (Full)
        if: inputs.run-trufflehog && (github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || (github.event_name == 'push' && github.event.before == '0000000000000000000000000000000000000000'))
        uses: trufflesecurity/trufflehog@main
        continue-on-error: true
        with:
          path: ./
          extra_args: --only-verified

      - name: 🔐 Gitleaks Scan
        if: inputs.run-gitleaks
        uses: gitleaks/gitleaks-action@ff98106e4c7b2bc287b24eaf42907196329070c7  # v2.3.9
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        continue-on-error: true

  # ==================================================================================
  # 🔬 CodeQL Analysis
  # ==================================================================================
  codeql:
    name: 🔬 CodeQL Analysis
    if: inputs.run-codeql
    runs-on: ubuntu-24.04
    permissions:
      security-events: write
      contents: read
    steps:
      - name: 📥 Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1

      - name: 🔬 Initialize CodeQL
        uses: github/codeql-action/init@v3
        with:
          languages: python

      - name: 🔬 Perform CodeQL Analysis
        uses: github/codeql-action/analyze@v3

  # ==================================================================================
  # 📋 Security Summary
  # ==================================================================================
  summary:
    name: 📋 Security Summary
    needs: [static-analysis, secret-scan, codeql]
    if: always()
    runs-on: ubuntu-24.04
    steps:
      - name: 📋 Generate Summary
        run: |
          echo "## 🔐 Security Scan Results" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "| Check | Status |" >> $GITHUB_STEP_SUMMARY
          echo "|-------|--------|" >> $GITHUB_STEP_SUMMARY
          echo "| Static Analysis | ${{ needs.static-analysis.result == 'success' && '✅ Passed' || '⚠️ Issues' }} |" >> $GITHUB_STEP_SUMMARY
          echo "| Secret Scan | ${{ needs.secret-scan.result == 'success' && '✅ Passed' || '⚠️ Issues' }} |" >> $GITHUB_STEP_SUMMARY
          if [ "${{ inputs.run-codeql }}" = "true" ]; then
            echo "| CodeQL | ${{ needs.codeql.result == 'success' && '✅ Passed' || '⚠️ Issues' }} |" >> $GITHUB_STEP_SUMMARY
          fi
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "Security reports uploaded as artifacts for detailed review." >> $GITHUB_STEP_SUMMARY