ThreatSentry-AI — ThreatSentry AI est un tableau de bord intelligent de chasse aux menaces qui exploite l'apprentissage automatique pour identifier et hiérarchiser de manière proactive les risques dans votre réseau. Il automatise le processus de collecte des informations sur les appareils, leur enrichissement avec des données de vulnérabilité et l'évaluation des niveaux de risque, permettant aux équipes de sécurité de se concentrer sur les menaces les plus critiques. | Kitploit

Couche	Technologies
Backend	Python 3.9+, SQLAlchemy ORM, APScheduler
ML/AI	Scikit-learn (Random Forest, Gradient Boosting, MLP), NumPy, Joblib
Frontend	PyQt5, Matplotlib, Custom theme manager
Données	Pandas, NumPy, SQLite3
API	Shodan, NVDLib, SendGrid, Requests
Utilitaires	Python-dotenv, Logging module, Config management

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

### Pipeline de Traitement des Données

1. **Phase de Découverte** (Intervalle configurable, par défaut 30 min)
   - Scan Shodan avec requêtes configurables
   - Enrichissement NVD avec corrélation CVE
   - Enrichissement du système interne pour le contexte

2. **Phase d'Analyse**
   - Ingénierie des caractéristiques à partir de 40+ attributs
   - Prédiction du modèle d'ensemble (Random Forest 40% + Gradient Boosting 40% + MLP 20%)
   - Génération d'étiquettes de risque (0=Faible, 1=Moyen, 2=Élevé)
   - Score de confiance

3. **Phase d'Alerte**
   - Vérification des nouveaux actifs à haut risque
   - Génération et envoi d'alertes par e-mail via SendGrid
   - Mise à jour du statut de notification

4. **Réentraînement du Modèle** (Intervalle configurable, par défaut 60 min)
   - Chargement de toutes les données historiques
   - Extraction des caractéristiques
   - Entraînement de l'ensemble avec des poids de classe équilibrés
   - Validation des métriques de performance
   - Sauvegarde des métadonnées pour audit

---

## 📋 Pour Commencer

### Prérequis
- **Python** : 3.9 ou ultérieur
- **Clés API** (requises) :
  - Clé API Shodan (https://www.shodan.io/)
  - Clé API SendGrid (https://sendgrid.com/) - pour les alertes par e-mail
- **Clés API Optionnelles** (pour un enrichissement amélioré) :
  - Point de terminaison et identifiants CMDB
  - Point de terminaison et identifiants SIEM
  - Point de terminaison et identifiants du système de gestion des correctifs
  - Point de terminaison et identifiants de supervision réseau

### Installation

#### Étape 1 : Cloner le Dépôt```bash
git clone https://github.com/EclipseManic/ThreatSentry-AI.git
cd ThreatSentry-AI

Modifiez `.env` avec vos identifiants:```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

#### Collecteurs internes personnalisés
Implémenter dans le répertoire `collectors/` :
1. Copier le modèle depuis un collecteur existant
2. Mettre à jour la méthode `_collect()` avec vos appels API
3. Retourner les données d'enrichissement
4. Enregistrer dans le planificateur (`core/scheduler.py`)

#### Personnalisation des alertes par e-mail
Modifier `alerts/email_alerts.py` :
- Modifier le modèle HTML pour des e-mails personnalisés
- Ajouter des descriptions personnalisées des facteurs de risque
- Ajuster les recommandations de correction

---

## 📊 Modèle de données

### Table des appareils (40+ colonnes)```
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

---

## 🔄 Exemples de flux de travail

### Scénario 1 : Chasse aux menaces quotidienne
1. Ouvrir le tableau de bord → Examiner les appareils à risque élevé (rouge)
2. Cliquer sur un appareil → Voir la liste détaillée des CVE
3. Noter l'organisation et le type d'infrastructure
4. Recouper avec le SIEM pour les activités suspectes récentes
5. Prioriser la correction en fonction de la criticité et du retard de correctif

### Scénario 2 : Réponse aux incidents
1. Recevoir une alerte concernant un nouvel appareil à haut risque
2. Le tableau de bord affiche les détails de la vulnérabilité et les facteurs de risque
3. Vérifier l'onglet Gestion des actifs → Voir si l'appareil est connu
4. Envoyer une alerte manuelle à l'équipe SOC d'astreinte
5. Après correction, le tableau de bord se met à jour automatiquement lorsque Shodan reflète les changements

### Scénario 3 : Rapports de risques
1. Aller dans l'onglet Analyses
2. Exporter les graphiques de répartition des risques et de tendance
3. Identifier les points chauds de risque organisationnel
4. Générer une feuille de route de correction
5. Suivre la progression dans le temps avec des réexportations périodiques

---

## 🔧 Dépannage

### Problèmes courants

#### Problème : "Clé API Shodan invalide" (403 Interdit)
- **Solution** : Vérifier la clé API Shodan dans le fichier `.env`. Le tableau de bord affichera une erreur mais continuera à traiter
- **Remarque** : L'enrichissement NVD ne s'exécutera pas (évite la perte de données en cas d'échec de l'API)

#### Problème : "Aucune CVE trouvée pour l'appareil"
- **Solution** : Vérifier l'extraction de la bannière. Modifier la liste des mots-clés dans `collectors/nvd_collector.py`
- **Prévention** : Enrichissement manuel via l'import CSV pour définir les données CVE manuellement

#### Problème : "Confiance du modèle trop faible"
- **Solution** : Réentraîner avec plus de données étiquetées. Fournir des retours sur les appareils mal classifiés
- **Prévention** : Utiliser le système de retour pour améliorer la qualité des données d'entraînement

#### Problème : Les alertes par e-mail ne s'envoient pas
- **Solution** : Vérifier la clé API SendGrid et l'adresse e-mail de l'expéditeur vérifiée
- **Vérification** : Variable d'environnement `ENABLE_EMAIL_ALERTS` définie sur True

#### Problème : Base de données verrouillée ou requêtes lentes
- **Solution** : S'assurer que les index sont créés (init_db() le fait)
- **Vérification** : Pas de connexions dupliquées à la base de données (rafraîchissement de l'interface uniquement, pas d'écriture constante)

---

## 🛡️ Considérations de sécurité

1. **Gestion des clés API** : Utiliser des variables d'environnement, ne jamais commiter `.env` dans Git
2. **Sécurité de la base de données** : SQLite adapté pour un seul utilisateur ; migrer vers PostgreSQL pour plusieurs utilisateurs
3. **Sécurité réseau** : Exécuter sur un réseau de confiance ; mettre en œuvre la segmentation du réseau si l'API est exposée
4. **Confidentialité des données** : Configurer la rotation des journaux pour limiter l'espace disque. Mettre en œuvre des politiques de conservation des données
5. **Journalisation d'audit** : Toutes les décisions du modèle sont journalisées avec les valeurs des caractéristiques pour l'auditabilité

---

## 📈 Conseils d'optimisation des performances

| Problème | Solution |
|----------|----------|
| Chargement lent du tableau de bord | Augmenter la taille de la pagination dans la configuration |
| CPU élevé pendant l'entraînement | Réduire `n_estimators` dans `model/advanced_model.py` |
| Utilisation mémoire élevée | Activer le nettoyage des journaux, réduire la résolution des graphiques |
| Analyses Shodan lentes | Réduire `MAX_SHODAN_RESULTS`, utiliser des requêtes plus spécifiques |
| Enrichissement NVD lent | Mettre en œuvre la mise en cache de l'API, réduire l'extraction des mots-clés de produits |

---

## 🤝 Contribution

Les contributions sont les bienvenues ! Veuillez consulter [CONTRIBUTING.md](https://raw.githubusercontent.com/eclipsemanic/threatsentry-ai/HEAD/CONTRIBUTING.md) pour les directives.

Domaines d'amélioration :
- Implémentations de collecteurs supplémentaires (intégration Nessus, Tenable, Qualys)
- API Web pour un accès programmatique
- Prise en charge multi-utilisateur avec contrôle d'accès basé sur les rôles
- Visualisation avancée (intégration Grafana/ELK)
- Prise en charge du déploiement Kubernetes

---

## 📄 Licence

Ce projet est sous licence MIT — voir le fichier [LICENSE](https://github.com/eclipsemanic/threatsentry-ai/blob/main/LICENSE) pour les détails.

---

## 📞 Support et contact

- **Problèmes** : GitHub Issues pour les rapports de bogues et les demandes de fonctionnalités
- **Documentation** : Voir le répertoire [docs/](https://github.com/eclipsemanic/threatsentry-ai/blob/main/docs) pour la documentation technique détaillée
- **Email** : Informations du responsable dans [CODE_OF_CONDUCT.md](https://github.com/eclipsemanic/threatsentry-ai/blob/main/CODE_OF_CONDUCT.md)

---

## 🙏 Remerciements

- **Shodan** : Pour la découverte complète des appareils exposés sur Internet
- **NVD/NIST** : Pour les données de vulnérabilité faisant autorité
- **Scikit-learn** : Bibliothèques ML robustes et documentation
- **PyQt5** : Excellent framework d'interface graphique
- **Communauté** : Tous les contributeurs et utilisateurs fournissant des retours

---

**Fait avec ❤️ par EclipseManic | Sécuriser l'infrastructure de demain aujourd'hui**
pip install -r requirements.txt```

---

## 🔐 Configuration

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

```bash
# --- Clé API Shodan (Obligatoire) ---
SHODAN_API_KEY="YOUR_SHODAN_API_KEY"

# --- Alertes e-mail SendGrid (Obligatoire) ---
SENDGRID_API_KEY="YOUR_SENDGRID_API_KEY"
SENDER_EMAIL="[email protected]"
ALERT_RECIPIENTS="[email protected],[email protected]"

# --- Base de données ---
SQLITE_PATH="threat_sentric_ai.db"

# --- Modèle ---
MODEL_PATH="threatsentry_model.pkl"

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

# --- Contrôle du comportement des requêtes Shodan ---
SHODAN_QUERY=""
SHODAN_QUERY_EMPTY_TO_PRESET="True"

# --- Journalisation ---
LOG_LEVEL="INFO" # DEBUG, INFO, WARNING, ERROR, CRITICAL

# --- Informations d'identification internes du système (Optionnel - Ajoutez selon les besoins de vos collecteurs) ---
# 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
# Générer 1000 enregistrements
python scripts/generate_realistic_training_data.py --count 1000

# Afficher les options de nettoyage
python scripts/clear_db_enhanced.py --help

# Supprimer tous les appareils et vulnérabilités
python scripts/clear_db_enhanced.py --delete-devices --delete-vulns

# Réinitialiser le drapeau notifié
python scripts/clear_db_enhanced.py --reset-notified

# Réinitialisation complète dangereuse
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.

ThreatSentry-AI

Populaires

À propos

👨‍💻 Auteur et remerciements

📋 Résumé exécutif

✨ Fonctionnalités principales

🤖 Moteur intelligent d'évaluation des risques

🌐 Découverte automatisée d'actifs et fusion de renseignements

📊 Tableau de bord exécutif et outils d'analyse

📧 Alertes e-mail proactives

Exemple d'e-mail d'alerte

📈 Transparence du modèle et amélioration continue

⚡ Performance et fiabilité

� Aperçu visuel

Tableau de bord principal

Tableau d'évaluation des risques des appareils

Panneau de filtrage avancé

Capacité de recherche dans toute la base de données

Panneau d'analyse et de reporting

Outils et configuration

Notifications d'alertes par e-mail

Flux de travail d'analyse manuelle

🛠️ Pile technologique

🏗️ Architecture et flux de données```

Étape 2 : Créer un environnement virtuel```bash

On Windows

On macOS/Linux

Étape 4: Configurer l'environnement

Étape 5 : Initialiser la base de données```bash

🚀 Guide d'utilisation

Aperçu des composants du tableau de bord

1. Tableau des appareils et découverte

2. Graphique de répartition des risques

3. Boutons d'action clés

Fonctionnalités avancées

Onglet Analyses

Onglet Outils

Configuration

Requêtes prédéfinies (Modifier `core/config.py`)```python

Tableau des Vulnérabilités```