Recon-Scan

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

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

Nota: A demo não está no ar porque fiquei sem tokens de IA. Você ainda pode hospedar por conta própria.

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

• É reconhecimento passivo. Não faz brute force de endpoints, fuzzing ou executa lógica ativa de exploração.
• É bom para snapshots 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
  • Fingerprinting de tecnologias
  • Detecção de WAF
  • Verificações de CORS
  • Verificações de segurança de cookies
  • Verificações de exposição de 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 caso o enfileiramento falhe.
• Resumo de IA opcional via OpenRouter / Anthropic / OpenAI.
• Geração de relatório PDF a partir do scan + resumo de IA.
• Frontend servido diretamente pelo FastAPI (uma URL, um app).

Início com Um Comando (Desenvolvimento Local)

Se você só quer colocá-lo em execução rapidamente:

./start.sh

O que isso faz:

• Cria .env a partir de .env.example se estiver ausente.
• Cria .venv se necessário.
• Instala dependências de requirements.txt.
• Inicia o FastAPI com hot reload em http://localhost:8000.
• Força USE_ARQ_QUEUE=false para facilitar a inicialização local 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 ausente.
• 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 de ambiente:

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 um scan, clique em Download PDF na interface.

Endpoint do backend:

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

O relatório inclui:

• Metadados do alvo e do scan
• Resumo executivo de IA (curto + narrativa completa quando disponível)
• Tabela de snapshot de severidade
• Descobertas detalhadas módulo a módulo

API

• GET /health
• POST /scans
  • exemplo de corpo:
    • { "target": "example.com" }
    • { "target": "example.com", "byoapi_key": "...", "byoapi_provider": "your_provider" }
  • observações:
    • byoapi_key é rejeitado a menos que ALLOW_BYO_API_KEY=true
    • alvos privados / loopback / reservados são bloqueados
    • user_id é opcional e mantido por 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: false)
• OPENROUTER_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY (opcional)
• VIRUSTOTAL_API_KEY, GOOGLE_SAFE_BROWSING_API_KEY (opcional)

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 de fallback local.
• SQLite é o mecanismo de armazenamento padrão para facilitar o uso local.
• Este repositório é intencionalmente leve e amigável para auto-hospedagem.

Licença

MIT. Veja LICENSE.