action.yml

---
name: 'PyGuard Security Scanner'
description: >-
  Comprehensive Python security and code quality analysis with
  auto-fix capabilities.
author: 'cboyd0319'

branding:
  icon: 'shield'
  color: 'blue'

inputs:
  paths:
    description: >-
      Paths to scan (space-separated). Supports files and directories.
      Example: "src/ app.py lib/"
    required: false
    default: '.'
  python-version:
    description: >-
      Python version to use for scanning. Should match your project version.
      Supports 3.11, 3.12, 3.13.
    required: false
    default: '3.13'
  scan-only:
    description: >-
      Only scan without fixing issues. Recommended for CI/CD to avoid code changes.
      Set to "false" to enable auto-fix.
    required: false
    default: 'true'
  security-only:
    description: >-
      Only run security checks, skipping code quality analysis.
      Faster scans focused on vulnerabilities.
    required: false
    default: 'false'
  severity:
    description: >-
      Minimum severity level to report (LOW, MEDIUM, HIGH, CRITICAL).
      Higher levels filter out lower severity issues.
    required: false
    default: 'LOW'
  exclude:
    description: >-
      File patterns to exclude from scanning (space-separated).
      Supports glob patterns. Example: "tests/* *.pyc __pycache__/*"
    required: false
    default: >-
      tests/* venv/* .venv/* build/* dist/* .git/* .github/* node_modules/*
  sarif-file:
    description: >-
      Output SARIF file path for GitHub Code Scanning integration.
      Must end in .sarif
    required: false
    default: 'pyguard-report.sarif'
  upload-sarif:
    description: >-
      Upload SARIF results to GitHub Security tab.
      Requires security-events: write permission.
    required: false
    default: 'true'
  fail-on-issues:
    description: >-
      Fail the workflow if security issues are found.
      Useful for security gates on pull requests.
    required: false
    default: 'false'
  unsafe-fixes:
    description: >-
      Enable unsafe auto-fixes that may change code behavior.
      WARNING: Only use with scan-only=false. Review changes carefully!
    required: false
    default: 'false'

outputs:
  issues-found:
    description: 'Number of security issues found'
    value: ${{ steps.scan.outputs.issues-found }}
  sarif-file:
    description: 'Path to generated SARIF report'
    value: ${{ steps.scan.outputs.sarif-file }}

runs:
  using: 'composite'
  steps:
    - name: Set up Python
      uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548  # v6.1.0
      with:
        python-version: ${{ inputs.python-version }}

    - name: Install PyGuard
      shell: bash
      run: |
        python -m pip install --upgrade pip
        pip install -e .
    - name: Run PyGuard Security Scan
      id: scan
      shell: bash
      run: |
        set -euo pipefail  # Exit on error, undefined vars, pipe failures

        echo "::group::PyGuard Configuration"
        echo "Paths: ${{ inputs.paths }}"
        echo "Python Version: ${{ inputs.python-version }}"
        echo "Scan Only: ${{ inputs.scan-only }}"
        echo "Security Only: ${{ inputs.security-only }}"
        echo "Severity: ${{ inputs.severity }}"
        echo "SARIF File: ${{ inputs.sarif-file }}"
        echo "Upload SARIF: ${{ inputs.upload-sarif }}"
        echo "Fail on Issues: ${{ inputs.fail-on-issues }}"
        echo "::endgroup::"

        # Verify PyGuard is installed
        if ! command -v pyguard &> /dev/null; then
          echo "::error::PyGuard is not installed or not in PATH"
          exit 1
        fi

        # Show PyGuard version
        echo "::group::PyGuard Version"
        pyguard --version
        echo "::endgroup::"

        # Disable glob expansion to prevent pattern expansion
        set -f

        # Build PyGuard command - paths MUST come before --exclude due to nargs="+"
        # Add paths first
        IFS=' ' read -ra PATH_ARGS <<< "${{ inputs.paths }}"
        ARGS=("${PATH_ARGS[@]}")

        # Add flags based on inputs
        if [ "${{ inputs.scan-only }}" == "true" ]; then
          ARGS+=("--scan-only")
        fi

        if [ "${{ inputs.security-only }}" == "true" ]; then
          ARGS+=("--security-only")
        fi

        if [ "${{ inputs.unsafe-fixes }}" == "true" ]; then
          if [ "${{ inputs.scan-only }}" == "true" ]; then
            echo "::warning::unsafe-fixes is enabled but scan-only is true."
            echo "::warning::Auto-fixes will not be applied."
          fi
          ARGS+=("--unsafe-fixes")
        fi

        # Add output format flags
        ARGS+=("--sarif" "--no-html")

        # Add exclude patterns last (glob expansion disabled)
        # IMPORTANT: --exclude must come AFTER paths due to nargs="+"
        IFS=' ' read -ra EXCLUDE_PATTERNS <<< "${{ inputs.exclude }}"
        for pattern in "${EXCLUDE_PATTERNS[@]}"; do
          if [ -n "$pattern" ]; then
            ARGS+=("--exclude" "$pattern")
          fi
        done

        # Run PyGuard and capture exit code
        echo "::group::Running PyGuard"
        echo "Command: pyguard ${ARGS[*]}"
        echo "Number of args: ${#ARGS[@]}"
        for i in "${!ARGS[@]}"; do
          echo "  ARG[$i]: ${ARGS[$i]}"
        done
        set +e  # Don't exit on error
        pyguard "${ARGS[@]}"
        EXIT_CODE=$?
        set -e
        set +f  # Re-enable glob expansion
        echo "::endgroup::"

        # PyGuard always writes to pyguard-report.sarif, rename if custom name requested
        if [ "${{ inputs.sarif-file }}" != "pyguard-report.sarif" ] && [ -f "pyguard-report.sarif" ]; then
          mv pyguard-report.sarif "${{ inputs.sarif-file }}"
          echo "Renamed SARIF file to ${{ inputs.sarif-file }}"
        fi

        # Validate SARIF file exists
        if [ ! -f "${{ inputs.sarif-file }}" ]; then
          echo "::warning::SARIF file not generated at ${{ inputs.sarif-file }}"
          echo "issues-found=0" >> $GITHUB_OUTPUT
          echo "sarif-file=" >> $GITHUB_OUTPUT
          exit ${EXIT_CODE}
        fi

        # Validate SARIF is valid JSON
        if ! jq empty "${{ inputs.sarif-file }}" 2>/dev/null; then
          echo "::error::Generated SARIF file is not valid JSON"
          exit 1
        fi

        # Count issues from SARIF file
        SARIF_FILE="${{ inputs.sarif-file }}"
        ISSUES=$(jq '[.runs[0].results // []] | length' "$SARIF_FILE" 2>/dev/null || echo "0")
        echo "issues-found=$ISSUES" >> $GITHUB_OUTPUT
        echo "sarif-file=${{ inputs.sarif-file }}" >> $GITHUB_OUTPUT

        # Create summary
        echo "::group::Scan Summary"
        echo "[OK] Scan completed"
        echo " Issues found: $ISSUES"
        echo "📄 SARIF report: ${{ inputs.sarif-file }}"

        if [ "${{ inputs.upload-sarif }}" == "true" ]; then
          echo "📤 SARIF will be uploaded to GitHub Security tab"
        fi
        echo "::endgroup::"

        # Add to GitHub Actions summary
        {
          echo "## PyGuard Security Scan Results"
          echo ""
          echo "- **Issues Found:** $ISSUES"
          echo "- **SARIF Report:** \`${{ inputs.sarif-file }}\`"
          echo "- **Severity Filter:** ${{ inputs.severity }}"
          SCAN_TYPE="${{ inputs.security-only == 'true' && 'Security Only' || 'Security + Quality' }}"
          echo "- **Scan Type:** $SCAN_TYPE"
          if [ "${{ inputs.upload-sarif }}" == "true" ]; then
            SECURITY_URL="https://github.com/${{ github.repository }}/security/code-scanning"
            echo "- **Results uploaded to [Security tab]($SECURITY_URL)**"
          fi
        } >> $GITHUB_STEP_SUMMARY

        # Fail if requested and issues found
        if [ "${{ inputs.fail-on-issues }}" == "true" ] && [ "$ISSUES" != "0" ]; then
          echo "::error::Found $ISSUES security issues (severity: ${{ inputs.severity }}+), failing as requested"
          SECURITY_URL="https://github.com/${{ github.repository }}/security/code-scanning"
          echo "::error::Review issues in the Security tab: $SECURITY_URL"
          exit 1
        fi

        # Exit with original code if not failing on issues
        exit ${EXIT_CODE}
      continue-on-error: ${{ inputs.fail-on-issues != 'true' }}

    - name: Upload SARIF results to GitHub Security tab
      if: ${{ inputs.upload-sarif == 'true' && always() }}
      uses: >-
        github/codeql-action/upload-sarif@fdbfb4d2750291e159f0156def62b853c2798ca2
      with:
        sarif_file: ${{ inputs.sarif-file }}
        category: pyguard