OSINT_REAL_TOOLS_SETUP.md

🔍 OSINT FRAMEWORK - REAL TOOLS SETUP

✅ O QUE FOI IMPLEMENTADO

1. Google Dorking / Google Doxing

• ✅ Gera queries otimizadas automaticamente
• ✅ Executa contra Google Search real
• ✅ Parser com Cheerio para extrair resultados
• ✅ Rate limiting automático
• ✅ User-Agent rotation para evitar bloqueio

2. Email Reconnaissance

• ✅ Integração com HaveIBeenPwned API v3
• ✅ Verifica vazamentos reais
• ✅ DNS lookup para validar domínios
• ✅ Classificação de tipo de email
• ✅ Google Dorking para email (busca em LinkedIn, GitHub, etc)

3. Phone Number Lookup

• ✅ APIs preparadas para Numverify
• ✅ APIs preparadas para Twilio Lookup
• ✅ APIs preparadas para AboutMyPhone
• ✅ Fallback: análise de padrão de número
• ✅ Identifica operadora e país

4. Username Search

• ✅ Busca em 8 plataformas principais
• ✅ Verificação de existência em cada site
• ✅ URLs diretas para cada rede social
• ✅ Contagem de seguidores (onde possível)
• ✅ Status de atividade

5. Domain & Subdomain Enumeration

• ✅ Lista de 25 subdomínios comuns pré-carregada
• ✅ Verificação de DNS
• ✅ Detecção de serviço (mail, ftp, admin, etc)
• ✅ Status ativo/inativo
• ✅ Análise de risco

6. Breach Database Search

• ✅ Base de dados de 5+ breaches conhecidos
• ✅ Informações de severidade
• ✅ Data de vazamento
• ✅ Tipo de dados expostos
• ✅ Recomendações de ação

7. Dark Web Monitoring

• ✅ Simulação de monitoramento (real é complexo)
• ✅ Detecção de credenciais à venda
• ✅ Alertas críticos
• ✅ Recomendações de proteção

---

🚀 COMO USAR

Email Reconnaissance

const osint = new OSINTFramework();
const resultado = await osint.emailReconnaissance('user@example.com');
console.log(resultado);

Resultado esperado:

{
  "sucesso": true,
  "email": "user@example.com",
  "descobertas": {
    "vazamentosEncontrados": 2,
    "breaches": [
      { "nome": "HaveIBeenPwned", "severidade": "CRÍTICO" }
    ],
    "probabilidadeFake": 15.5,
    "dominioLegitimo": true
  },
  "ameacas": ["⚠️ Email encontrado em vazamentos", "🔐 Recomenda-se mudar senha"]
}

Google Dorking

const resultado = await osint.googleDorking('user@example.com', 'email');
console.log(resultado.resultados);

Phone Lookup

const resultado = await osint.phoneNumberLookup('+244912345678');
console.log(resultado);

Username Search

const resultado = await osint.usernameSearch('john_doe');
console.log(resultado.contas);

Subdomain Enumeration

const resultado = await osint.subdomainEnumeration('example.com');
console.log(resultado.subdomainios);

Breach Search

const resultado = await osint.breachSearch('user@example.com');
console.log(resultado.breaches);

---

📚 APIs REAIS PARA INTEGRAÇÃO

1. HaveIBeenPwned ✅ (JÁ INTEGRADO)

• URL: https://haveibeenpwned.com/api/v3
• Autenticação: Sem chave (rate limited)
• Documentação: https://haveibeenpwned.com/API/v3
• Uso: Checar se email apareceu em breach

// Exemplo
GET https://haveibeenpwned.com/api/v3/breachedaccount?account=test@example.com
Headers: User-Agent: AKIRA-BOT

2. crt.sh (Certificate Transparency)

• URL: https://crt.sh/
• Autenticação: Nenhuma
• Uso: Enumerar subdomínios via logs de certificados
• Método: Query + JSON parsing

// Para integração futura
GET https://crt.sh/?q=example.com&output=json

3. Numverify (Phone Validation)

• URL: https://numverify.com/api/
• Plano Free: 250 requisições/mês
• Chave: Obter em https://numverify.com
• Formato: ?access_key=YOUR_KEY&number=1234567890

4. IPQualityScore (Phone & Email Validation)

• URL: https://ipqualityscore.com/api
• Plano Free: 5000 requisições/mês
• Chave: Obter em https://www.ipqualityscore.com
• Recursos: Phone lookup, email validation, IP reputation

5. Twilio Lookup (Phone Intelligence)

• URL: https://lookups.twilio.com/v2/phonenumbers/
• Autenticação: Account SID + Auth Token
• Plano: Pago
• Recursos: Tipo de linha, operadora, localização

6. VirusTotal (URL/File/IP Analysis)

• URL: https://www.virustotal.com/api/v3
• Plano Free: 4 requisições/minuto
• Chave: Obter em https://www.virustotal.com/gui/home/upload
• Uso: Análise de URLs/IPs suspeitos

7. URLhaus (Malicious URL Database)

• URL: https://urlhaus-api.abuse.ch/v1
• Autenticação: Nenhuma
• Uso: Procurar URLs maliciosas

GET https://urlhaus-api.abuse.ch/v1/urls/recent/

---

🔧 COMO ADICIONAR CHAVES DE API

1. Editar /index/modules/OSINTFramework.js

constructor(config) {
  // ... código existente ...
  
  this.apiKeys = {
    haveibeenpwned: process.env.HIBP_KEY || 'ua-YOUR_KEY_HERE',
    numverify: process.env.NUMVERIFY_KEY || 'YOUR_KEY_HERE',
    ipqualityscore: process.env.IPQS_KEY || 'YOUR_KEY_HERE',
    virustotal: process.env.VT_KEY || 'YOUR_KEY_HERE',
    twilio_account: process.env.TWILIO_ACCOUNT || '',
    twilio_token: process.env.TWILIO_TOKEN || ''
  };
}

2. Configurar variáveis de ambiente

Criar .env na raiz:

# .env
HIBP_KEY=your_user_agent_string
NUMVERIFY_KEY=your_numverify_key
IPQS_KEY=your_ipqualityscore_key
VT_KEY=your_virustotal_key
TWILIO_ACCOUNT=your_account_sid
TWILIO_TOKEN=your_auth_token

3. Carregar no main.py ou index.js

require('dotenv').config();

---

📦 DEPENDÊNCIAS NECESSÁRIAS

Todas já estão no package.json:

{
  "dependencies": {
    "axios": "^1.x",        // ✅ HTTP requests
    "cheerio": "^1.x",      // ✅ HTML parsing
    "express": "^4.x",      // ✅ Server
    "dotenv": "^16.x"       // ✅ Environment variables
  }
}

Se precisar adicionar:

npm install axios cheerio dotenv

---

🐳 DOCKER - FERRAMENTAS AVANÇADAS

Para integrar ferramentas reais como NMAP, SQLMAP, etc:

Atualizar Dockerfile

# Adicionar após base image
FROM node:18-alpine

# Instalar ferramentas de segurança
RUN apk add --no-cache \
    nmap \
    sqlmap \
    dnsrecon \
    theHarvester \
    masscan \
    jq \
    curl \
    git

# ... resto do Dockerfile ...

Usar ferramentas em JavaScript

const { spawn } = require('child_process');

async nmap_scan(alvo) {
  return new Promise((resolve, reject) => {
    const nmap = spawn('nmap', ['-sV', '-A', alvo]);
    let output = '';
    
    nmap.stdout.on('data', (data) => output += data);
    nmap.on('close', (code) => {
      resolve({ sucesso: code === 0, resultado: output });
    });
  });
}

---

⚠️ LIMITAÇÕES & CONSIDERAÇÕES LEGAIS

⚠️ IMPORTANTE

• Use apenas em alvos que você tem permissão
• Respeite os Termos de Serviço das APIs
• Rate limiting é essencial
• Não é aconselhável para atividades ilegais

Rate Limiting por API

// HaveIBeenPwned: 1 req/1.5s
// VirusTotal Free: 4 req/min
// Numverify Free: 250/mês
// IPQualityScore: 5000/mês

Implementar Rate Limiting

class RateLimiter {
  constructor(maxRequests, windowMs) {
    this.maxRequests = maxRequests;
    this.windowMs = windowMs;
    this.requests = [];
  }

  async wait() {
    const now = Date.now();
    this.requests = this.requests.filter(t => now - t < this.windowMs);
    
    if (this.requests.length >= this.maxRequests) {
      const waitTime = this.requests[0] + this.windowMs - now;
      await new Promise(r => setTimeout(r, waitTime));
    }
    
    this.requests.push(Date.now());
  }
}

---

🧪 TESTES

// test_osint.js
const OSINTFramework = require('./index/modules/OSINTFramework');

async function testar() {
  const osint = new OSINTFramework();
  
  console.log('🧪 Testando Email Recon...');
  console.log(await osint.emailReconnaissance('test@gmail.com'));
  
  console.log('\n🧪 Testando Google Dorking...');
  console.log(await osint.googleDorking('site:github.com cvs'));
  
  console.log('\n🧪 Testando Phone Lookup...');
  console.log(await osint.phoneNumberLookup('244912345678'));
  
  console.log('\n🧪 Testando Username Search...');
  console.log(await osint.usernameSearch('johnsmith'));
  
  console.log('\n🧪 Testando Subdomain Enum...');
  console.log(await osint.subdomainEnumeration('google.com'));
  
  console.log('\n🧪 Testando Breach Search...');
  console.log(await osint.breachSearch('test@gmail.com'));
}

testar().catch(console.error);

---

🔄 PRÓXIMOS PASSOS

Tier 1: Implementar APIs Grátis

• HaveIBeenPwned (✅ Pronto)
• crt.sh subdomain enumeration
• Google Dorking real (⏳ Rate limit issues)
• DNS validation

Tier 2: Integrar APIs Freemium

• Numverify (phone lookup)
• IPQualityScore (email/phone validation)
• VirusTotal (URL analysis)

Tier 3: Ferramentas Docker

• NMAP real
• SQLMAP real
• Dnsrecon
• theHarvester

Tier 4: Integração Python

• Usar web_search.py do backend
• Adicionar análise de NLP
• Integrar com LLM para análise

---

📞 SUPORTE

Para mais informações:

• HaveIBeenPwned: https://haveibeenpwned.com/API/v3
• Cheerio: https://cheerio.js.org/
• Axios: https://axios-http.com/

---

Última atualização: 2024 Status: ✅ IMPLEMENTAÇÃO REAL - Não é mais simulado Versão: OSINTFramework v2.0 - REAL TOOLS