│              │              │           │         │
      └──────────────┴──────────────┴───────────┴─────────┘
                       │
                       ▼
              ┌─────────────────┐
              │   SQLite DB     │
              │  (40+ Columns)  │
              └────────┬────────┘
                       │
    ┌──────────────────┼──────────────────┐
    ▼                  ▼                  ▼

### Pipeline de Processamento de Dados

1. **Fase de Descoberta** (Intervalo configurável, padrão 30 min)
   - Varredura Shodan com consultas configuráveis
   - Enriquecimento NVD com correlação CVE
   - Enriquecimento interno do sistema para contexto

2. **Fase de Análise**
   - Engenharia de recursos a partir de 40+ atributos
   - Predição do modelo ensemble (Random Forest 40% + Gradient Boosting 40% + MLP 20%)
   - Geração de rótulo de risco (0=Baixo, 1=Médio, 2=Alto)
   - Pontuação de confiança

3. **Fase de Alerta**
   - Verificar novos ativos de alto risco
   - Gerar e enviar alertas por e-mail via SendGrid
   - Atualizar status de notificação

4. **Re-treinamento do Modelo** (Intervalo configurável, padrão 60 min)
   - Carregar todos os dados históricos
   - Extrair recursos
   - Treinar ensemble com pesos de classe balanceados
   - Validar métricas de desempenho
   - Salvar metadados para auditoria

---

## 📋 Primeiros Passos

### Pré-requisitos
- **Python**: 3.9 ou posterior
- **Chaves de API (obrigatório)**:
  - Chave de API Shodan (https://www.shodan.io/)
  - Chave de API SendGrid (https://sendgrid.com/) - para alertas por e-mail
- **Chaves de API opcionais (para enriquecimento aprimorado)**:
  - Endpoint e credenciais CMDB
  - Endpoint e credenciais SIEM
  - Endpoint e credenciais do sistema de gerenciamento de patches
  - Endpoint e credenciais de monitoramento de rede

### Instalação

#### Passo 1: Clonar Repositório```bash
git clone https://github.com/EclipseManic/ThreatSentry-AI.git
cd ThreatSentry-AI

#### Passo 3: Instalar Dependências```bash
pip install -r requirements.txt

Edite `.env` com suas credenciais:```ini
# Required - Threat Discovery
SHODAN_API_KEY=your_shodan_api_key_here
SHODAN_QUERY=                          # Leave empty to use presets
SHODAN_QUERY_EMPTY_TO_PRESET=True      # Use preset queries when SHODAN_QUERY is empty

# Optional - Email Alerts
SENDGRID_API_KEY=your_sendgrid_key_here
[email protected]    # Must be verified in SendGrid
[email protected],[email protected]

# Optional - Internal Enrichment (Implement in collectors/)
CMDB_API_ENDPOINT=https://cmdb.internal/api
CMDB_API_KEY=your_cmdb_key
SIEM_API_ENDPOINT=https://siem.internal/api
SIEM_API_KEY=your_siem_key

# Configuration
SCAN_INTERVAL_MINUTES=30               # How often to scan for new assets
RETRAIN_INTERVAL_MINUTES=60            # How often to retrain the model
MAX_SHODAN_RESULTS=50                  # Results per Shodan query
LOG_LEVEL=INFO                         # DEBUG, INFO, WARNING, ERROR

# Paths (Optional)
SQLITE_PATH=data/db/threat_sentric_ai.db
MODEL_PATH=data/models/rf_model.pkl
LOG_FILE_PATH=data/logs/threat_sentric_ai.log

#### Etapa 6: Executar a Aplicação```bash
python run.py

#### Coletores Internos Personalizados
Implemente no diretório `collectors/`:
1. Copie o modelo de um coletor existente
2. Atualize o método `_collect()` com suas chamadas de API
3. Retorne os dados de enriquecimento
4. Registre no agendador (`core/scheduler.py`)

#### Personalização de Alertas por E-mail
Edite `alerts/email_alerts.py`:
- Modifique o modelo HTML para e-mails com marca
- Adicione descrições personalizadas de fatores de risco
- Ajuste as recomendações de remediação

---

## 📊 Modelo de Dados

### Tabela de Dispositivos (40+ Colunas)```
Core Identifiers:  ip, org, country, first_seen, last_seen
Vulnerability:     cve_count, max_cvss, vulnerabilities (rel)
Security Metrics:  auth_failures_24h, traffic_anomaly_score, patch_lag_days
Risk Assessment:   risk_label, risk_score, confidence_score
Context:          network_segment, service_category, is_critical_service
Compliance:       compliance_requirements, data_sensitivity_level
Historical:       incident_history_count, last_compromise_date, false_positive_count
Alerting:         notified, alert_history

## 🔄 Exemplos de Fluxo de Trabalho

### Cenário 1: Caça a Ameaças Diária
1. Abra o painel → Revise dispositivos de Risco=Alto (vermelho)
2. Clique no dispositivo → Veja a lista detalhada de CVEs
3. Observe a organização e o tipo de infraestrutura
4. Faça referência cruzada com o SIEM para atividades suspeitas recentes
5. Priorize a remediação com base na criticidade e no atraso de patches

### Cenário 2: Resposta a Incidentes
1. Recebeu alerta sobre novo dispositivo de alto risco
2. O painel mostra detalhes de vulnerabilidades e fatores de risco
3. Verifique a aba Gerenciamento de Ativos → Veja se o dispositivo é conhecido
4. Envie alerta manual para a equipe SOC de plantão
5. Após a remediação, o painel é atualizado automaticamente quando o Shodan reflete as alterações

### Cenário 3: Relatório de Riscos
1. Vá para a aba Analytics
2. Exporte gráficos de distribuição e tendências de riscos
3. Identifique pontos críticos de risco organizacional
4. Gere um roteiro de remediação
5. Acompanhe o progresso ao longo do tempo com reexportações periódicas

---

## 🔧 Solução de Problemas

### Problemas Comuns

#### Problema: "Chave de API Shodan inválida" (403 Proibido)
- **Solução**: Verifique a chave de API Shodan no arquivo `.env`. O painel mostrará erro, mas continuará processando
- **Nota**: O enriquecimento NVD não será executado (evita perda de dados em falhas de API)

#### Problema: "Nenhum CVE encontrado para o dispositivo"
- **Solução**: Verifique a extração de banner. Edite a lista de palavras-chave em `collectors/nvd_collector.py`
- **Prevenção**: Enriquecimento manual via upload CSV para definir dados de CVE manualmente

#### Problema: "Confiança do modelo muito baixa"
- **Solução**: Treine novamente com mais dados rotulados. Forneça feedback sobre dispositivos classificados incorretamente
- **Prevenção**: Use o sistema de feedback para melhorar a qualidade dos dados de treinamento

#### Problema: Alertas de e-mail não estão sendo enviados
- **Solução**: Verifique a chave de API do SendGrid e se o e-mail remetente está verificado
- **Verifique**: variável de ambiente `ENABLE_EMAIL_ALERTS` definida como True

#### Problema: Banco de dados bloqueado ou consultas lentas
- **Solução**: Certifique-se de que os índices foram criados (init_db() faz isso)
- **Verifique**: Sem conexões duplicadas com o banco de dados (apenas atualização da interface, sem escrita constante)

---

## 🛡️ Considerações de Segurança

1. **Gerenciamento de Chaves de API**: Use variáveis de ambiente, nunca faça commit do `.env` no Git
2. **Segurança do Banco de Dados**: SQLite adequado para usuário único; migrar para PostgreSQL para multiusuário
3. **Segurança de Rede**: Execute em rede confiável; implemente segmentação de rede se expuser a API
4. **Privacidade de Dados**: Configure rotação de logs para limitar espaço em disco. Implemente políticas de retenção de dados
5. **Registro de Auditoria**: Todas as decisões do modelo são registradas com valores de recursos para auditabilidade

---

## 📈 Dicas de Otimização de Desempenho

| Problema | Solução |
|-------|----------|
| Carregamento lento do painel | Aumente o tamanho da paginação na configuração |
| Alto uso de CPU durante treinamento | Reduza `n_estimators` em `model/advanced_model.py` |
| Alto uso de memória | Ative a limpeza de logs, reduza a resolução dos gráficos |
| Escaneamentos lentos do Shodan | Reduza `MAX_SHODAN_RESULTS`, use consultas mais específicas |
| Enriquecimento NVD lento | Implemente cache de API, reduza a extração de palavras-chave de produtos |

---

## 🤝 Contribuindo

Contribuições são bem-vindas! Consulte [CONTRIBUTING.md](https://raw.githubusercontent.com/eclipsemanic/threatsentry-ai/HEAD/CONTRIBUTING.md) para diretrizes.

Áreas para melhoria:
- Implementações adicionais de coletores (integração com Nessus, Tenable, Qualys)
- API Web para acesso programático
- Suporte a múltiplos usuários com acesso baseado em funções
- Visualização avançada (integração com Grafana/ELK)
- Suporte a implantação em Kubernetes

---

## 📄 Licença

Este projeto está licenciado sob a Licença MIT—veja o arquivo [LICENSE](https://github.com/eclipsemanic/threatsentry-ai/blob/main/LICENSE) para detalhes.

---

## 📞 Suporte e Contato

- **Issues**: Issues do GitHub para relatórios de bugs e solicitações de funcionalidades
- **Documentação**: Consulte o diretório [docs/](https://github.com/eclipsemanic/threatsentry-ai/blob/main/docs) para documentação técnica detalhada
- **Email**: Informações do mantenedor em [CODE_OF_CONDUCT.md](https://github.com/eclipsemanic/threatsentry-ai/blob/main/CODE_OF_CONDUCT.md)

---

## 🙏 Agradecimentos

- **Shodan**: Pela descoberta abrangente de dispositivos voltados para a internet
- **NVD/NIST**: Pelos dados autoritativos de vulnerabilidades
- **Scikit-learn**: Bibliotecas de ML robustas e documentação
- **PyQt5**: Excelente framework de interface gráfica
- **Comunidade**: Todos os contribuidores e usuários que fornecem feedback

---

**Feito com ❤️ por EclipseManic | Protegendo a Infraestrutura de Amanhã Hoje**
pip install -r requirements.txt```

---

## 🔐 Configuration

### 1. Environment Variables (`.env` file)
Create a `.env` file in the root directory with the following structure:

```bash
# --- Chave de API do Shodan (Obrigatório) ---
SHODAN_API_KEY="YOUR_SHODAN_API_KEY"

# --- Alertas de E-mail do SendGrid (Obrigatório) ---
SENDGRID_API_KEY="YOUR_SENDGRID_API_KEY"
SENDER_EMAIL="[email protected]"
ALERT_RECIPIENTS="[email protected],[email protected]"

# --- Banco de Dados ---
SQLITE_PATH="threat_sentric_ai.db"

# --- Modelo ---
MODEL_PATH="threatsentry_model.pkl"

# --- Agendador ---
SCAN_INTERVAL_MINUTES="30"
RETRAIN_INTERVAL_MINUTES="60"
RETRAIN_ON_SCHEDULE="True"

# --- Controle de Comportamento da Consulta Shodan ---
SHODAN_QUERY=""
SHODAN_QUERY_EMPTY_TO_PRESET="True"

# --- Logging ---
LOG_LEVEL="INFO" # DEBUG, INFO, AVISO, ERRO, CRÍTICO

# --- Credenciais Internas do Sistema (Opcional - Adicione conforme necessário para seus coletores) ---
# CMDB_API_ENDPOINT="..."
# CMDB_API_KEY="..."
# SIEM_API_ENDPOINT="..."
# SIEM_API_KEY="..."
# PATCH_API_ENDPOINT="..."
# PATCH_API_KEY="..."
# NETWORK_MONITOR_ENDPOINT="..."
# NETWORK_MONITOR_KEY="..."```

> The app loads environment variables via `os.getenv()` in `config.py`.  
> Never commit this file to version control.

---

## 🔍 Shodan Query Presets (`config.py`)

Modify the `SHODAN_QUERIES` dictionary to define your custom query presets:

```python
SHODAN_QUERIES = {
    "default": "product:apache",
    "org": 'org:"Your Company Name"',
    "net": 'net:"123.45.67.0/24"',
    "ssl": 'ssl:"yourcompany.com"',
    "hostname": 'hostname:".yourcompany.com"',
    "rdp": 'port:3389 "remote desktop"',
    "mongodb": 'port:27017 "mongodb"',
    "ics_modbus": 'port:502 "modbus"',
    "vuln_example": 'vuln:CVE-2024-12345',
    "http_login": 'http.title:"Login" org:"Your Company"'
}```

If `SHODAN_QUERY` in `.env` is empty **and** `SHODAN_QUERY_EMPTY_TO_PRESET=True`,  
the scheduler will automatically cycle through these presets.

---

## 🧠 Implementing Internal Collectors

> ⚠️ **Important:** The internal collectors (`cmdb_collector.py`, `siem_collector.py`, `patch_collector.py`, `network_monitor_collector.py`) are **placeholders**.  
> Replace the placeholder logic with real integrations to your systems.

You’ll need to:
- Fetch internal data using APIs, databases, or SDKs.
- Map fetched data to the `Device` model attributes.
- Update the database session with this enriched information.

Without these integrations, the model will lack context for accurate predictions.

---

## 🧪 Running the Application

### (Optional) Generate Initial Training Data
```bash
python scripts/generate_realistic_training_data.py --count 1000```
Creates `scripts/my_training_data.json`.  
You can upload this file through the GUI’s **Upload** option to initialize training data.

### Launch the Application
```bash
python run.py```
The GUI will open and the scheduler will start scanning, enriching, and predicting automatically.

---

## ⚡ Quick Demo with Generated Data

1. Complete installation (steps 1–3).  
2. Set up your `.env` file (even with placeholder keys).  
3. Optionally adjust Shodan presets in `config.py`.  
4. Generate data:
   ```bash
python scripts/generate_realistic_training_data.py --count 500   ```
5. Launch the app:
   ```bash
python run.py   ```
6. In the GUI:
   - Select **Upload** → Choose `scripts/my_training_data.json`
   - Click **Refresh** to view populated device data and risk levels.

---

## 🛠️ Scripts and Usage Guide

| Script | Description |
|--------|--------------|
| **run.py** | Main entry point. Starts DB, scheduler, and GUI. |
| **scheduler.py** | Handles periodic scanning, enrichment, prediction, and retraining. |
| **scripts/generate_realistic_training_data.py** | Generates realistic training data for testing or bootstrapping. |
| **scripts/clear_db_enhanced.py** | Interactively clean database or reset notification flags. |
| **scripts/reset_db.py** | Completely resets the database. Use with caution. |

### Example Commands

```bash
# Gerar 1000 registros
python scripts/generate_realistic_training_data.py --count 1000

# Ver opções de limpeza
python scripts/clear_db_enhanced.py --help

# Excluir todos os dispositivos e vulnerabilidades
python scripts/clear_db_enhanced.py --delete-devices --delete-vulns

# Redefinir sinalizador notificado
python scripts/clear_db_enhanced.py --reset-notified

# Reinicialização completa perigosa
python scripts/reset_db.py```

---

## 💬 Feedback & Suggestions

This project was developed by **EclipseManic**.  
While code contributions are currently closed, your **feedback and bug reports** are highly appreciated.

Please open an [Issue](https://github.com/EclipseManic/ThreatSentry-AI/issues) to share your thoughts or report a problem.

---

## 📄 License

This project is licensed under the **MIT License**.  
See the [LICENSE](https://github.com/eclipsemanic/threatsentry-ai/blob/main/LICENSE) file for details.