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
```javascript
const osint = new OSINTFramework();
const resultado = await osint.emailReconnaissance('user@example.com');
console.log(resultado);
```

**Resultado esperado:**
```json
{
  "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
```javascript
const resultado = await osint.googleDorking('user@example.com', 'email');
console.log(resultado.resultados);
```

### Phone Lookup
```javascript
const resultado = await osint.phoneNumberLookup('+244912345678');
console.log(resultado);
```

### Username Search
```javascript
const resultado = await osint.usernameSearch('john_doe');
console.log(resultado.contas);
```

### Subdomain Enumeration
```javascript
const resultado = await osint.subdomainEnumeration('example.com');
console.log(resultado.subdomainios);
```

### Breach Search
```javascript
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
```javascript
// 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
```javascript
// 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
```javascript
GET https://urlhaus-api.abuse.ch/v1/urls/recent/
```

---

## 🔧 COMO ADICIONAR CHAVES DE API

### 1. Editar `/index/modules/OSINTFramework.js`

```javascript
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:
```bash
# .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`
```javascript
require('dotenv').config();
```

---

## 📦 DEPENDÊNCIAS NECESSÁRIAS

Todas já estão no `package.json`:

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

Se precisar adicionar:
```bash
npm install axios cheerio dotenv
```

---

## 🐳 DOCKER - FERRAMENTAS AVANÇADAS

Para integrar ferramentas reais como NMAP, SQLMAP, etc:

### Atualizar `Dockerfile`

```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

```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
```javascript
// HaveIBeenPwned: 1 req/1.5s
// VirusTotal Free: 4 req/min
// Numverify Free: 250/mês
// IPQualityScore: 5000/mês
```

### Implementar Rate Limiting
```javascript
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

```javascript
// 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