# Pre-commit Hook Configuration for Bandit
#
# This configuration integrates Bandit security scanning into your git workflow,
# preventing commits that introduce HIGH severity security vulnerabilities.
#
# Installation:
#   1. Install pre-commit: pip install pre-commit
#   2. Copy this file to .pre-commit-config.yaml in your repository root
#   3. Install hooks: pre-commit install
#   4. (Optional) Run on all files: pre-commit run --all-files
#
# Usage:
#   - Hooks run automatically on 'git commit'
#   - Bypass hooks temporarily: git commit --no-verify (use sparingly!)
#   - Update hooks: pre-commit autoupdate
#   - Test hooks: pre-commit run --all-files

repos:
  # Python code formatting and linting
  - repo: https://github.com/psf/black
    rev: 23.12.1
    hooks:
      - id: black
        language_version: python3.11

  - repo: https://github.com/pycqa/isort
    rev: 5.13.2
    hooks:
      - id: isort
        args: ["--profile", "black"]

  - repo: https://github.com/pycqa/flake8
    rev: 7.0.0
    hooks:
      - id: flake8
        args: ['--max-line-length=100', '--extend-ignore=E203,W503']

  # Security scanning with Bandit
  - repo: https://github.com/PyCQA/bandit
    rev: '1.7.5'
    hooks:
      - id: bandit
        name: Bandit Security Scan
        args:
          # Block HIGH and MEDIUM severity issues
          - '-ll'
          # Recursive scan
          - '--recursive'
          # Use custom config if present
          - '--configfile'
          - '.bandit.yaml'
          # Skip low-priority tests to reduce false positives
          # Uncomment to skip specific tests:
          # - '-s'
          # - 'B101,B601'
        # Only scan Python files
        files: \.py$
        # Exclude test files (adjust pattern as needed)
        exclude: |
          (?x)^(
              tests/.*|
              test_.*\.py|
              .*_test\.py
          )$

  # Alternative Bandit configuration with stricter settings
  # Uncomment to use this instead of the above
  # - repo: https://github.com/PyCQA/bandit
  #   rev: '1.7.5'
  #   hooks:
  #     - id: bandit
  #       name: Bandit Security Scan (Strict)
  #       args:
  #         # Block only HIGH severity with HIGH confidence (Critical findings)
  #         - '-ll'
  #         - '-i'
  #         - '--recursive'
  #         - '--configfile'
  #         - '.bandit.yaml'
  #       files: \.py$

  # Alternative: Run Bandit with custom script for enhanced reporting
  # Uncomment to use enhanced analyzer
  # - repo: local
  #   hooks:
  #     - id: bandit-enhanced
  #       name: Bandit Enhanced Security Scan
  #       entry: python scripts/bandit_analyzer.py
  #       args:
  #         - '.'
  #         - '--config'
  #         - '.bandit.yaml'
  #         - '--min-priority'
  #         - '4'  # HIGH priority
  #       language: python
  #       files: \.py$
  #       pass_filenames: false

  # Additional security and quality checks
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      # Prevent commits to main/master
      - id: no-commit-to-branch
        args: ['--branch', 'main', '--branch', 'master']

      # Check for merge conflicts
      - id: check-merge-conflict

      # Detect private keys
      - id: detect-private-key

      # Check for large files (>500KB)
      - id: check-added-large-files
        args: ['--maxkb=500']

      # Check YAML syntax
      - id: check-yaml
        args: ['--safe']

      # Check JSON syntax
      - id: check-json

      # Check for files that would conflict on case-insensitive filesystems
      - id: check-case-conflict

      # Ensure files end with newline
      - id: end-of-file-fixer

      # Trim trailing whitespace
      - id: trailing-whitespace

      # Check for debugger imports
      - id: debug-statements

  # Dependency security scanning
  - repo: https://github.com/Lucas-C/pre-commit-hooks-safety
    rev: v1.3.3
    hooks:
      - id: python-safety-dependencies-check
        files: requirements.*\.txt$

  # Secret detection
  - repo: https://github.com/Yelp/detect-secrets
    rev: v1.4.0
    hooks:
      - id: detect-secrets
        args: ['--baseline', '.secrets.baseline']
        exclude: package.lock.json

# Configuration for progressive security hardening
#
# Phase 1: Start with warnings only (for legacy codebases)
#   Set bandit args to ['-r', '.', '--configfile', '.bandit.yaml', '--exit-zero']
#   This runs Bandit but doesn't block commits
#
# Phase 2: Block HIGH severity only
#   Set bandit args to ['-lll', '--recursive', '--configfile', '.bandit.yaml']
#
# Phase 3: Block MEDIUM and HIGH severity
#   Set bandit args to ['-ll', '--recursive', '--configfile', '.bandit.yaml']
#
# Phase 4: Block all findings (strictest)
#   Set bandit args to ['-l', '--recursive', '--configfile', '.bandit.yaml']

# Bypassing hooks (use judiciously)
#
# Skip all hooks for a single commit:
#   git commit --no-verify -m "Emergency hotfix"
#
# Skip specific hook:
#   SKIP=bandit git commit -m "Commit message"
#
# Note: All bypasses should be documented and reviewed in code review

# Troubleshooting
#
# Hook fails with "command not found":
#   - Ensure pre-commit is installed: pip install pre-commit
#   - Reinstall hooks: pre-commit install
#
# Hook fails with import errors:
#   - Install dependencies: pip install -r requirements.txt
#   - Update hooks: pre-commit autoupdate
#
# Too many false positives:
#   - Adjust exclude patterns in .bandit.yaml
#   - Use inline # nosec comments with justification
#   - Adjust severity threshold in args (-l, -ll, -lll)
#
# Performance issues:
#   - Exclude virtual environments in .bandit.yaml
#   - Use 'files' and 'exclude' patterns to limit scope
#   - Consider running stricter checks only on CI/CD

# CI/CD Integration
#
# Run pre-commit checks in CI/CD:
#
# GitHub Actions:
#   - name: Pre-commit checks
#     uses: pre-commit/action@v3.0.0
#
# GitLab CI:
#   pre-commit:
#     image: python:3.11
#     script:
#       - pip install pre-commit
#       - pre-commit run --all-files
#
# Jenkins:
#   stage('Pre-commit') {
#     steps {
#       sh 'pip install pre-commit'
#       sh 'pre-commit run --all-files'
#     }
#   }