name: DevSkim Security Linter

on:
  workflow_dispatch:
  workflow_call:  # Called by release-gate.yml
  schedule:
    # Run security linter daily at 10 AM UTC
    - cron: '0 10 * * *'

permissions: {}  # Minimal top-level for OSSF Scorecard Token-Permissions

jobs:
  devskim-scan:
    name: DevSkim Security Linter
    runs-on: ubuntu-latest
    timeout-minutes: 30
    permissions:
      contents: read
      security-events: write
      actions: read

    steps:
      - name: Harden the runner (Audit all outbound calls)
        uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
        with:
          egress-policy: audit

      - name: Checkout repository
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

        with:
          persist-credentials: false

      - name: Run DevSkim security linter
        uses: microsoft/DevSkim-Action@4b5047945a44163b94642a1cecc0d93a3f428cc6 # v1.0.16
        with:
          # Scan all source code
          directory-to-scan: '.'

          # Output SARIF for GitHub Security tab
          output-filename: 'devskim-results.sarif'

          # Ignore test fixtures and documentation
          # - tests/: All test code uses mock data and localhost URLs
          # - examples/: Example code with placeholder values
          # - docs/: Documentation with example URLs
          # - node_modules/: Third-party code
          ignore-globs: 'tests/**,examples/**,docs/**,node_modules/**,**/node_modules/**'

          # Exclude rules that produce false positives in this codebase:
          #
          # DS176209 - "Suspicious comment" (TODO/FIXME/HACK)
          #   These are standard development annotations, not security issues.
          #   Every codebase has TODO comments for tracking technical debt.
          #
          # DS162092 - "Hardcoded URL"
          #   This research tool integrates with legitimate external APIs
          #   (ArXiv, PubMed, Semantic Scholar, etc.). All URLs are intentional
          #   service endpoints, not security vulnerabilities.
          #
          # DS137138 - "Hardcoded credentials"
          #   Analysis showed 100% of alerts are test fixtures (api_key="test_key",
          #   password="testpass", etc.). Zero real credentials found. Gitleaks
          #   handles actual secret detection separately.
          #
          # DS148264 - "Use cryptographic random"
          #   Flags ALL Python `random` module usage without context. This codebase
          #   correctly uses `secrets` for security (session tokens, auth tokens,
          #   Flask keys) and `random` only for non-security purposes: ML fairness
          #   shuffling in search strategies, distributed systems jitter in scheduler,
          #   and session cleanup probability. None involve cryptographic operations.
          #
          # DS172411 - "setTimeout code injection"
          #   Flags ALL JavaScript setTimeout() calls. The dangerous pattern is
          #   setTimeout("string", delay) which can execute arbitrary code. However,
          #   100% of usages in this codebase (80+) pass safe function references:
          #   setTimeout(() => {...}, delay) or setTimeout(functionName, delay).
          #   No string-based setTimeout usage exists.
          #
          # DS126858 - "Weak/Broken Hash Algorithm"
          #   Flags any occurrence of the literal string "sha1". In this codebase
          #   the only matches are the JSON key name `"sha1"` inside SLSA provenance
          #   attestations (.github/workflows/prerelease-docker.yml) — that key name
          #   is *required* by the SLSA in-toto schema for git-commit digests, and
          #   Git itself uses SHA-1 for commit identifiers. It is not a cryptographic
          #   choice we make. Legitimate SHA-1 references elsewhere (PBKDF2_HMAC_SHA1,
          #   HMAC_SHA1 in db_config.py for SQLCipher backwards compatibility) carry
          #   their own inline `# DevSkim: ignore DS126858` annotations explaining the
          #   rationale. See .github/SECURITY_ALERTS.md for the full assessment.
          #
          exclude-rules: 'DS176209,DS162092,DS137138,DS148264,DS172411,DS126858'

      - name: Upload DevSkim results to GitHub Security
        uses: github/codeql-action/upload-sarif@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
        if: always()
        with:
          sarif_file: 'devskim-results.sarif'
          category: devskim

      - name: Upload DevSkim results as artifact
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        if: always()
        with:
          name: devskim-results
          path: devskim-results.sarif
          retention-days: 7  # Reduced for security

      - name: Generate summary
        run: |
          {
            echo "## DevSkim Security Linter Summary"
            echo ""
            echo "✅ DevSkim security scan completed"
            echo ""
            echo "### What was scanned:"
            echo "- 🔍 All source code in the repository"
            echo "- 🛡️ Common security issues and anti-patterns"
            echo "- 📋 Insecure coding practices"
            echo "- 🔑 Hardcoded secrets and credentials"
            echo ""
            echo "### Security checks include:"
            echo "- **Hardcoded Credentials**: Passwords, API keys, tokens"
            echo "- **Insecure Functions**: Dangerous API usage"
            echo "- **Buffer Overflows**: Memory safety issues"
            echo "- **Crypto Issues**: Weak encryption practices"
            echo "- **Network Security**: Insecure protocols and configurations"
            echo "- **File System**: Insecure file operations"
            echo "- **Input Validation**: Missing input sanitization"
            echo ""
            echo "### Language Support:"
            echo "- 🐍 Python (.py files)"
            echo "- 📜 JavaScript/TypeScript (.js, .ts files)"
            echo "- 🖥️ C/C++ (.c, .cpp, .h files)"
            echo "- 🔷 C# (.cs files)"
            echo "- 📝 More languages supported"
            echo ""
            echo "### Why DevSkim?"
            echo "- **Microsoft Maintained**: Backed by Microsoft security team"
            echo "- **Truly Free**: No registration, no API keys, no upsells"
            echo "- **Fast & Lightweight**: Quick scans with minimal overhead"
            echo "- **Comprehensive Rules**: 200+ security rules"
            echo "- **Open Source**: Community-driven rule improvements"
            echo ""
            echo "📊 **Results uploaded to:**"
            echo "- GitHub Security tab (if issues found)"
            echo "- Workflow artifacts (SARIF files)"
            echo ""
            echo "🔗 **Learn more about DevSkim:**"
            echo "- [DevSkim GitHub](https://github.com/microsoft/DevSkim)"
            echo "- [DevSkim Documentation](https://microsoft.github.io/DevSkim/)"
            echo "- [DevSkim Rules](https://github.com/microsoft/DevSkim/tree/main/rules)"
          } >> "$GITHUB_STEP_SUMMARY"