Skip to content

chore: implement pre-commit hooks with security focus - #63

Merged
miguellsfilho merged 5 commits into
mainfrom
chore/add-pre-commit-hooks
Aug 21, 2026
Merged

miguellsfilho merged 5 commits into
mainfrom
chore/add-pre-commit-hooks

Conversation

@miguellsfilho

Copy link
Copy Markdown
Contributor

Objetivo

Implementar pre-commit hooks abrangentes no repositório scraper, com foco em segurança para operações de web scraping.

Hooks Implementados (5 fases)

Fase 1: File Hygiene (< 1s)

  • trailing-whitespace, end-of-file-fixer, mixed-line-ending
  • check-yaml, check-json, check-toml
  • check-merge-conflict, check-added-large-files

Fase 2: Security (2-4s) — CRÍTICO

  • detect-secrets: Previne vazamento de credenciais (DATABASE_URL, Pub/Sub tokens, Telegram bot tokens)
  • bandit: Detecta SSRF, injection, insecure deserialization (web scraping = alto risco)

Fase 3: Python Quality (3-5s)

  • ruff-check: Linter (substitui Black/isort/flake8)
  • ruff-format: Formatter (line-length 100)

Fase 4: Type Checking (1-2s)

  • mypy: Modo permissivo, habilitado apenas para models/, config.py

Fase 5: Custom Validators (< 2s) — EXCLUSIVOS DO SCRAPER

  • validate-site-urls: Valida schema YAML (scraper_type, URL format)
  • validate-ssrf-allowlist: Valida cobertura de domínios no allowlist SSRF
  • test-config-sync: Valida sync entre src/ e dags/ site_urls.yaml (155 DAGs dependem disso)

Arquivos Criados

  • .pre-commit-config.yaml: 15+ hooks em 5 fases
  • .bandit: Config focada em riscos de web scraping (skip subprocess/SQL legítimos)
  • .secrets.baseline: Baseline de false positives (8 arquivos, revisado manualmente)
  • .gitattributes: Enforce LF line endings (commitado separadamente)
  • scripts/validate_site_urls.py: Validador schema YAML
  • scripts/validate_ssrf_allowlist.py: Validador cobertura SSRF

Arquivos Modificados

  • pyproject.toml: Adiciona pre-commit, mypy, bandit + configs
  • README.md: Seção "Development Setup" com instruções
  • ~70 arquivos Python: Formatação automática Ruff (whitespace, EOF, imports)

Performance

  • Commit típico: ~7-9 segundos
  • Primeiro commit: ~30-60 segundos (instala ambientes dos hooks, one-time)

Teste Local

# Instalar
poetry install
poetry run pre-commit install

# Testar em todos os arquivos
poetry run pre-commit run --all-files

# Teste positivo (deve passar)
echo "# test" >> README.md
git add README.md
git commit -m "test"

# Teste negativo (deve falhar)
echo 'DATABASE_URL="postgresql://user:pass@host/db"' > test.py
git add test.py
git commit -m "test"  # DEVE BLOQUEAR (secret detectado)

Baseado em

Implementação bem-sucedida em data-platform (PR #197).

Aprendizados aplicados:

  • Estrutura de 5 fases (feedback rápido primeiro)
  • Pragmatismo com legacy code (per-file-ignores)
  • Mypy parcial/permissivo ao invés de strict global
  • .gitattributes para prevenir line ending issues
  • Bandit para SSRF protection (crítico para scraper)
  • Documentação clara para adoção do time

Impacto

✅ Security: Múltiplas camadas de proteção (secrets, SSRF, allowlist)
✅ Quality: Formatação e linting automáticos
✅ Reliability: Validações que previnem quebra de 155 DAGs Airflow
✅ DX: Feedback imediato (10s local vs 5min no CI)

🎯 Trade-off consciente: 7-9s/commit vs potencial de incident (secret leak, SSRF exploit, DAGs quebradas)

Miguel Lopes Da Silva Filho and others added 3 commits August 18, 2026 10:31
Adds .gitattributes file to enforce LF line endings across all text files.
This must be done first to prevent conflicts with pre-commit's
mixed-line-ending hook and Git's autocrlf behavior.

Part of pre-commit hooks implementation (based on data-platform PR #197).
Implements comprehensive pre-commit hooks for the scraper repository
with emphasis on security for web scraping operations.

Hooks added (5 phases):
- File hygiene: whitespace, line endings, YAML/JSON validation
- Security: detect-secrets, bandit (SSRF, injection risks)
- Custom: site_urls.yaml sync, SSRF allowlist validation
- Python: Ruff linter + formatter
- Type checking: mypy (permissive mode, core modules only)

Changes:
- Add .pre-commit-config.yaml with 15+ hooks
- Add .bandit config (skip legitimate subprocess/SQL patterns)
- Add .secrets.baseline (reviewed for false positives)
- Add scripts/validate_site_urls.py (schema validation)
- Add scripts/validate_ssrf_allowlist.py (SSRF coverage)
- Wire tests/unit/test_config_sync.py as pre-commit hook
- Add pre-commit, mypy, bandit to dev dependencies
- Add mypy config (permissive, models + config only)
- Add per-file-ignores for legacy code (tests, scrapers, api)
- Format all Python files with Ruff (automated changes)
- Add # nosec comments to legitimate code patterns
- Update README.md with Development Setup section

Performance: ~7-9s for typical commits

Based on successful data-platform implementation (PR #197).

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Fixes critical and high-priority issues discovered in code review:

## Critical Fixes
- Fix Python 3.14 breaking change: elt.s → elt.value in AST parsing
- Add support for ast.List and ast.Set in _ALLOWED_URL_PREFIXES extraction
- Document setup prerequisites in README (poetry install before pre-commit)

## High Priority Fixes
- Move Bandit B105 skip from global to per-file-ignores (via inline # nosec)
- Add # nosec B105 inline comments for password fallbacks
- Document inverted prefix logic in SSRF allowlist validation
- Clarify B608 skip justification (SQLAlchemy parameterized queries)

## Medium Priority Fixes
- Regenerate .secrets.baseline to sync with current codebase
- Document www.gov.br subdomain limitation in validate_site_urls.py

## Details

**validate_ssrf_allowlist.py:**
- Line 22: isinstance now accepts (ast.Tuple, ast.List, ast.Set)
- Line 23: elt.s → elt.value (forward-compatible with Python 3.14)
- Lines 74-79: Added comment explaining inverted prefix validation logic

**.bandit:**
- Removed B105 skip (now handled via inline # nosec comments)
- Enhanced B608 skip comment with detailed justification

**postgres_manager.py:**
- Lines 100, 102, 106: Added # nosec B105 inline comments

**README.md:**
- Added warning about setup order (poetry install before pre-commit)
- Enhanced documentation with numbered steps
- Added note about "poetry: command not found" error

**validate_site_urls.py:**
- Added comment documenting www.gov.br subdomain limitation

**.secrets.baseline:**
- Regenerated to sync with current codebase

## Testing
- ✅ poetry run python scripts/validate_ssrf_allowlist.py
- ✅ poetry run python scripts/validate_site_urls.py
- ✅ poetry run pre-commit run validate-ssrf-allowlist --all-files
- ✅ poetry run pre-commit run validate-site-urls --all-files
@miguellsfilho

Copy link
Copy Markdown
Contributor Author

Correções Implementadas após Análise Crítica da Revisão

Implementei correções para os problemas validados na revisão de código. A análise detalhada está documentada em:

  • Análise crítica: /l/disk0/mfilho/.claude/plans/estamos-trabalhando-no-pr-bright-turing.md
  • Revisão original: /l/disk0/mfilho/inspire/m7/github/review-pr63-scraper.md

🔍 Metodologia

Investiguei o código real com 3 agentes Explore para validar cada ponto da revisão. Descobri:

  • ✅ 5 problemas reais confirmados e corrigidos
  • ❌ 5 falsos positivos refutados (código já estava correto)
  • 🆕 2 novos problemas descobertos (não estavam na revisão original)

✅ Correções Implementadas (Commit b90029f)

🔴 CRÍTICAS (bloqueavam merge)

  1. Fix Python 3.14 breaking change - scripts/validate_ssrf_allowlist.py:23

    • ❌ elt.s → deprecated, removido em Python 3.14
    • ✅ elt.value → forward-compatible
    • Novo problema descoberto (não estava na revisão!)
  2. Suporte AST para List/Set - scripts/validate_ssrf_allowlist.py:22

    • Antes: isinstance(node.value, ast.Tuple)
    • Agora: isinstance(node.value, (ast.Tuple, ast.List, ast.Set))
    • Se _ALLOWED_URL_PREFIXES for refatorado para lista/set, validação não falhará silenciosamente
  3. Documentação de setup - README.md

    • ⚠️ Important: Run poetry install BEFORE pre-commit install
    • Passos numerados (1, 2, 3)
    • Nota sobre erro "poetry: command not found"
    • Novo problema descoberto (impactava onboarding)

🟡 ALTAS (devem ser corrigidas)

  1. Bandit B105 scope limitado - .bandit + postgres_manager.py

    • Removido skip global de B105
    • Adicionado # nosec B105 inline nas linhas 100, 102, 106
    • Comentário: "local dev fallback only (not used in production)"
  2. Documentação lógica de prefixo - scripts/validate_ssrf_allowlist.py:74-79

    • Comentário explicando lógica invertida: prefix.startswith(domain)
    • Exemplo: mandatory: "https://storage.googleapis.com/" + allowlist: "https://storage.googleapis.com/destaquesgovbr-thumbnails/" ✅ válido
  3. Clarificação B608 - .bandit

    • Enhanced comment: "all SQL uses SQLAlchemy parameterized queries with %s placeholders, no .format() or % string interpolation"

🟢 MÉDIAS (recomendadas)

  1. Regeneração de .secrets.baseline

    • Sincronizado com codebase atual
  2. Documentação de limitação - scripts/validate_site_urls.py:26-28

    • Comentário sobre www.gov.br hardcoded
    • Caminho para expansão futura (dados.gov.br, api.gov.br)

❌ Falsos Positivos Refutados

1. Bandit B608 SQL injection skip perigoso

Revisão afirmou: Skip global pode mascarar injeções reais.

Análise real:

  • ✅ Código é 100% seguro - todo SQL usa parametrização %s
  • ✅ Nenhum .format() ou % dinâmico encontrado
  • ✅ Exemplo: execute("SELECT ... WHERE x = %s", (value,))
  • Decisão: Manter skip com comentário melhorado

2. active: yes não detectado como string

Revisão afirmou: Validação não detecta strings "yes"/"no" vs booleanos.

Análise real:

  • ✅ PyYAML safe_load() converte automaticamente: yes/no → True/False
  • ✅ String quoted "yes" seria detectada pelo isinstance(x, bool)
  • Decisão: Validação já é robusta, nenhuma mudança necessária

3. Mypy 10% de cobertura é problema

Revisão afirmou: 90% do código sem type checking.

Análise real:

  • ✅ Decisão consciente seguindo aprendizado do data-platform
  • ✅ Scraper tem poucos type hints historicamente
  • ✅ Mypy strict global bloquearia todos os commits
  • Decisão: Manter modo permissivo, expansão incremental é follow-up futuro

4. ruff --exit-non-zero-on-fix causa loop infinito

Revisão afirmou: Pode causar loop infinito de fixes.

Análise real:

  • ✅ Comportamento correto e esperado:
    1. Primeiro commit: ruff aplica fixes → hook falha (exit 1)
    2. Dev re-stageia: git add .
    3. Segundo commit: sem mudanças → hook passa
  • ✅ Não é loop infinito, são 2 passos determinísticos
  • Decisão: Manter como está

5. .secrets.baseline 37min desatualizado

Revisão afirmou: Baseline desatualizado 37min.

Análise real:

  • ⚠️ Timestamp não validável no código
  • ✅ Regeneração é quick win (30 segundos)
  • Decisão: Regenerado por precaução

🧪 Testes Realizados

✅ poetry run python scripts/validate_ssrf_allowlist.py
   → ✓ All 4 domains covered by 7 allowlist prefixes

✅ poetry run python scripts/validate_site_urls.py
   → ✓ Validated 162 agencies

✅ poetry run pre-commit run validate-ssrf-allowlist --all-files
   → Passed

✅ poetry run pre-commit run validate-site-urls --all-files
   → Passed

✅ All 17 pre-commit hooks passed on commit

📋 Follow-ups (NÃO implementados - criar issues)

Issue 1: Testes Unitários para Validation Scripts

  • tests/unit/test_validate_site_urls.py
  • tests/unit/test_validate_ssrf_allowlist.py
  • Edge cases: URL malformada, AST com list/set, mandatory domains
  • Esforço: ~2h

Issue 2: Validação de URL Uniqueness

  • Adicionar check para garantir URLs únicas entre agências
  • Previne conflitos de scraping
  • Esforço: ~30min

Issue 3: Validação de Agency Key Format

  • Regex ^[a-z0-9_-]+$ para keys
  • Previne espaços, uppercase, special chars
  • Esforço: ~15min

📊 Resumo Estatístico

Categoria Quantidade
Problemas reais confirmados 5
Falsos positivos refutados 5
Novos problemas descobertos 2
Arquivos modificados 6
Linhas adicionadas 25
Linhas removidas 17

Impacto:

  • ✅ Previne breaking change em Python 3.14
  • ✅ Melhora experiência de primeiro uso (onboarding)
  • ✅ Scope de segurança mais preciso (inline # nosec)
  • ✅ Documentação de lógica não-óbvia
  • ✅ Nenhum impacto negativo - mudanças são defensivas

Status: ✅ Pronto para merge após estas correções.

@miguellsfilho
miguellsfilho merged commit 3bef175 into main Aug 21, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant