Recon-Scan

ReconScan é um scanner de reconhecimento passivo de código aberto com backend FastAPI, pipeline de worker assíncrono e frontend de página única. Você pode verificar o site implantado em https://recon-scan.vercel.app/

O objetivo é sinal rápido: execute uma varredura, obtenha resultados módulo por módulo e obtenha um resumo de IA que agora pode ser exportado como um relatório PDF refinado.

O Que Este Projeto É (E Não É)

• É reconhecimento passivo. Não força endpoints, não faz fuzzing nem executa lógica de exploração ativa.
• É bom para instantâneos de postura, triagem e relatórios.
• Não é um substituto para testes de penetração completos.

Funcionalidades

• 13 módulos passivos:
  • Cabeçalhos de segurança
  • SSL/TLS
  • DNS + autenticação de e-mail (SPF/DMARC/MX)
  • WHOIS
  • Robots/sitemap
  • Enumeração de subdomínios
  • Identificação de tecnologia
  • Detecção de WAF
  • Verificações CORS
  • Verificações de segurança de cookies
  • Verificações de exposição JS
  • Verificações de exposição de diretórios
  • Verificações de reputação
• Execução assíncrona com Redis + worker ARQ.
• Fallback para execução em segundo plano no processo se a fila falhar.
• Resumo opcional de IA via OpenRouter / Anthropic / OpenAI.
• Geração de relatório PDF a partir da varredura + resumo de IA.
• Frontend servido diretamente pelo FastAPI (uma URL, um aplicativo).

Início com Um Comando (Desenvolvimento Local)

Se você quer apenas executá-lo rapidamente:

./start.sh

O que isso faz:

• Cria .env a partir de .env.example se estiver faltando.
• Cria .venv se necessário.
• Instala dependências de requirements.txt.
• Inicia FastAPI com recarga automática em http://localhost:8000.
• Força USE_ARQ_QUEUE=false para inicialização local mais fácil sem Redis.

Pare com Ctrl+C.

Início com Um Comando (Docker)

./start-docker.sh

O que isso faz:

• Cria .env a partir de .env.example se estiver faltando.
• Inicia API + worker + Redis com Docker Compose.

Início com Docker (Manual)

cp .env.example .env
docker compose up --build

Desenvolvimento Local (Sem Docker)

1. Instale as dependências:

pip install -r requirements.txt

2. Crie o arquivo env:

cp .env.example .env

3. Inicie a API:

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

4. Inicie o worker em outro terminal (recomendado):

arq app.worker.WorkerSettings

5. Abra:

http://localhost:8000

Executando Testes

Instale as dependências de teste:

pip install -r requirements-dev.txt

Execute a suíte completa:

pytest -q

Relatórios PDF

Após a conclusão de uma varredura, clique em Download PDF na interface.

Endpoint do backend:

• GET /scans/{scan_id}/report.pdf

O relatório inclui:

• Metadados de destino e varredura
• Resumo executivo de IA (curto + narrativa completa quando disponível)
• Tabela de instantâneo de gravidade
• Resultados detalhados módulo por módulo

API

• GET /health
• POST /scans
  • exemplo de corpo:
    • { "target": "example.com" }
    • { "target": "example.com", "byoapi_key": "...", "byoapi_provider": "your_provider" }
  • notas:
    • byoapi_key rejeitado a menos que ALLOW_BYO_API_KEY=true
    • destinos privados / loopback / reservados são bloqueados
    • user_id é opcional e mantido para compatibilidade
• GET /scans/{scan_id}
• GET /scans/{scan_id}/report.pdf

Configuração

De .env.example:

• DATABASE_URL (padrão: sqlite:///./reconscan.db)
• REDIS_URL (padrão: redis://localhost:6379)
• USE_ARQ_QUEUE (padrão: true)
• RATE_LIMIT_PER_MINUTE (padrão: 10)
• RATE_LIMIT_PER_DAY (padrão: 200)
• ALLOWED_HOSTS (padrão: localhost,127.0.0.1)
• CORS_ALLOWED_ORIGINS (padrão: origens de desenvolvimento local)
• ALLOW_BYO_API_KEY (padrão: )

Contribuindo

Contribuições são bem-vindas, especialmente em torno de módulos de reconhecimento passivo, relatórios, UX do frontend e cobertura de testes.

Por favor, leia as diretrizes completas de contribuição antes de abrir um pull request:

Guia de Contribuição

Notas

• Se nenhuma chave de IA externa estiver configurada, o ReconScan armazena um resumo local de fallback.
• SQLite é o mecanismo de armazenamento padrão para uso local fácil.
• Este repositório é intencionalmente leve e amigável para auto-hospedagem.

Licença

MIT. Veja LICENSE.