ThreatSentry-AI — ThreatSentry AI ist ein intelligentes Threat-Hunting-Dashboard, das maschinelles Lernen nutzt, um Risiken in Ihrem Netzwerk proaktiv zu identifizieren und zu priorisieren. Es automatisiert den Prozess der Erfassung von Geräteinformationen, der Anreicherung mit Schwachstellendaten und der Bewertung von Risikostufen, sodass sich Sicherheitsteams auf die kritischsten Bedrohungen konzentrieren können. | Kitploit

Ebene	Technologien
Backend	Python 3.9+, SQLAlchemy ORM, APScheduler
ML/AI	Scikit-learn (Random Forest, Gradient Boosting, MLP), NumPy, Joblib
Frontend	PyQt5, Matplotlib, Custom theme manager
Daten	Pandas, NumPy, SQLite3
APIs	Shodan, NVDLib, SendGrid, Requests
Hilfsprogramme	Python-dotenv, Logging module, Config management

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

### Datenverarbeitungspipeline

1. **Erkennungsphase** (Konfigurierbares Intervall, Standard 30 Minuten)
   - Shodan-Scan mit konfigurierbaren Abfragen
   - NVD-Anreicherung mit CVE-Korrelation
   - Interne Systemanreicherung für Kontext

2. **Analysephase**
   - Feature Engineering aus 40+ Attributen
   - Ensemble-Modellvorhersage (Random Forest 40% + Gradient Boosting 40% + MLP 20%)
   - Risikolabel-Generierung (0=Niedrig, 1=Mittel, 2=Hoch)
   - Konfidenzbewertung

3. **Alarmierungsphase**
   - Prüfung auf neue Hochrisiko-Assets
   - Erstellung und Versand von E-Mail-Benachrichtigungen über SendGrid
   - Aktualisierung des Benachrichtigungsstatus

4. **Modell-Neutraining** (Konfigurierbares Intervall, Standard 60 Minuten)
   - Laden aller historischen Daten
   - Feature-Extraktion
   - Training des Ensembles mit balancierten Klassen-Gewichten
   - Validierung der Leistungskennzahlen
   - Speicherung der Metadaten für die Prüfung

---

## 📋 Erste Schritte

### Voraussetzungen
- **Python**: 3.9 oder höher
- **API-Schlüssel** (erforderlich):
  - Shodan-API-Schlüssel (https://www.shodan.io/)
  - SendGrid-API-Schlüssel (https://sendgrid.com/) – für E-Mail-Benachrichtigungen
- **Optionale API-Schlüssel** (für erweiterte Anreicherung):
  - CMDB-Endpunkt und Berechtigungsnachweise
  - SIEM-Endpunkt und Berechtigungsnachweise
  - Patch-Management-System-Endpunkt und Berechtigungsnachweise
  - Netzwerküberwachungs-Endpunkt und Berechtigungsnachweise

### Installation

#### Schritt 1: Repository klonen```bash
git clone https://github.com/EclipseManic/ThreatSentry-AI.git
cd ThreatSentry-AI

Bearbeiten Sie `.env` mit Ihren Anmeldedaten:```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

#### Benutzerdefinierte interne Kollektoren
Implementieren Sie im Verzeichnis `collectors/`:
1. Kopieren Sie die Vorlage von einem vorhandenen Kollektor
2. Aktualisieren Sie die `_collect()`-Methode mit Ihren API-Aufrufen
3. Geben Sie Anreicherungsdaten zurück
4. Registrieren Sie im Scheduler (`core/scheduler.py`)

#### Anpassung von E-Mail-Benachrichtigungen
Bearbeiten Sie `alerts/email_alerts.py`:
- Ändern Sie die HTML-Vorlage für Marken-E-Mails
- Fügen Sie benutzerdefinierte Risikofaktorbeschreibungen hinzu
- Passen Sie Empfehlungen zur Behebung an

---

## 📊 Datenmodell

### Gerätetabelle (40+ Spalten)```
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

## 🔄 Workflow-Beispiele

### Szenario 1: Tägliche Bedrohungsjagd
1. Dashboard öffnen → Geräte mit Risiko=Hoch (rot) überprüfen
2. Auf Gerät klicken → Detaillierte CVE-Liste anzeigen
3. Organisation und Infrastrukturtyp notieren
4. Mit SIEM auf kürzliche verdächtige Aktivitäten abgleichen
5. Abhilfe nach Kritikalität und Patch-Verzögerung priorisieren

### Szenario 2: Incident Response
1. Alarm über neues Hochrisiko-Gerät erhalten
2. Dashboard zeigt Schwachstellendetails und Risikofaktoren
3. Reiter Asset-Management prüfen → Ob Gerät bekannt ist
4. Manuellen Alarm an das diensthabende SOC-Team senden
5. Nach Abhilfe aktualisiert sich das Dashboard automatisch, wenn Shodan Änderungen widerspiegelt

### Szenario 3: Risikoberichterstattung
1. Zum Reiter Analysen gehen
2. Risikoverteilungs- und Trenddiagramme exportieren
3. Organisatorische Risikohotspots identifizieren
4. Abhilfe-Fahrplan erstellen
5. Fortschritt im Laufe der Zeit mit regelmäßigen Neu-Exporten verfolgen

---

## 🔧 Fehlerbehebung

### Häufige Probleme

#### Problem: "Shodan-API-Schlüssel ungültig" (403 Forbidden)
- **Lösung**: Shodan-API-Schlüssel in `.env`-Datei überprüfen. Dashboard zeigt Fehler an, verarbeitet aber weiter
- **Hinweis**: NVD-Anreicherung wird nicht ausgeführt (verhindert Datenverlust bei API-Fehlern)

#### Problem: "Keine CVEs für Gerät gefunden"
- **Lösung**: Banner-Extraktion prüfen. Schlüsselwortliste in `collectors/nvd_collector.py` bearbeiten
- **Vorbeugung**: Manuelle Anreicherung per CSV-Upload, um CVE-Daten manuell zu setzen

#### Problem: "Modell-Konfidenz zu niedrig"
- **Lösung**: Mit mehr beschrifteten Daten erneut trainieren. Feedback zu falsch klassifizierten Geräten geben
- **Vorbeugung**: Feedbacksystem nutzen, um Trainingsdatenqualität zu verbessern

#### Problem: E-Mail-Benachrichtigungen werden nicht gesendet
- **Lösung**: SendGrid-API-Schlüssel und verifizierte Absender-E-Mail prüfen
- **Prüfen**: Umgebungsvariable `ENABLE_EMAIL_ALERTS` auf True gesetzt

#### Problem: Datenbank gesperrt oder langsame Abfragen
- **Lösung**: Sicherstellen, dass Indizes erstellt wurden (init_db() erledigt das)
- **Prüfen**: Keine doppelten Datenbankverbindungen (nur UI-Aktualisierung, kein ständiges Schreiben)

---

## 🛡️ Sicherheitsaspekte

1. **API-Schlüsselverwaltung**: Umgebungsvariablen verwenden, niemals `.env` in Git committen
2. **Datenbanksicherheit**: SQLite für Einzelbenutzer geeignet; für Mehrbenutzer auf PostgreSQL migrieren
3. **Netzwerksicherheit**: In vertrauenswürdigem Netzwerk ausführen; Netzwerksegmentierung implementieren, falls API offengelegt wird
4. **Datenschutz**: Log-Rotation konfigurieren, um Festplattenspeicher zu begrenzen. Datenaufbewahrungsrichtlinien implementieren
5. **Prüfprotokollierung**: Alle Modellentscheidungen werden mit Feature-Werten für die Nachvollziehbarkeit protokolliert

---

## 📈 Tipps zur Leistungsoptimierung

| Problem | Lösung |
|---------|--------|
| Langsames Dashboard-Laden | Seitengröße in der Konfiguration erhöhen |
| Hohe CPU-Auslastung beim Training | `n_estimators` in `model/advanced_model.py` reduzieren |
| Hoher Speicherverbrauch | Log-Bereinigung aktivieren, Diagrammauflösung reduzieren |
| Langsame Shodan-Scans | `MAX_SHODAN_RESULTS` reduzieren, spezifischere Abfragen verwenden |
| Langsame NVD-Anreicherung | API-Caching implementieren, Produktschlüsselwort-Extraktion reduzieren |

---

## 🤝 Mitwirken

Beiträge sind willkommen! Siehe [CONTRIBUTING.md](https://raw.githubusercontent.com/eclipsemanic/threatsentry-ai/HEAD/CONTRIBUTING.md) für Richtlinien.

Bereiche für Verbesserungen:
- Zusätzliche Collector-Implementierungen (Nessus, Tenable, Qualys-Integration)
- Web-API für programmatischen Zugriff
- Multi-User-Unterstützung mit rollenbasiertem Zugriff
- Erweiterte Visualisierung (Grafana/ELK-Integration)
- Kubernetes-Bereitstellungsunterstützung

---

## 📄 Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert – siehe [LICENSE](https://github.com/eclipsemanic/threatsentry-ai/blob/main/LICENSE) für Details.

---

## 📞 Support & Kontakt

- **Issues**: GitHub Issues für Fehlerberichte und Funktionsanfragen
- **Dokumentation**: Siehe Verzeichnis [docs/](https://github.com/eclipsemanic/threatsentry-ai/blob/main/docs) für detaillierte technische Dokumentation
- **E-Mail**: Betreuerinformationen in [CODE_OF_CONDUCT.md](https://github.com/eclipsemanic/threatsentry-ai/blob/main/CODE_OF_CONDUCT.md)

---

## 🙏 Danksagungen

- **Shodan**: Für umfassende Erkennung von internetfähigen Geräten
- **NVD/NIST**: Für maßgebliche Schwachstellendaten
- **Scikit-learn**: Robuste ML-Bibliotheken und Dokumentation
- **PyQt5**: Hervorragendes GUI-Framework
- **Community**: Allen Mitwirkenden und Nutzern, die Feedback geben

---

**Mit ❤️ gemacht von EclipseManic | Sicherung der Infrastruktur von morgen heute**
pip install -r requirements.txt```

---

## 🔐 Configuration

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

```bash
# --- Shodan API-Schlüssel (Erforderlich) ---
SHODAN_API_KEY="YOUR_SHODAN_API_KEY"

# --- SendGrid E-Mail-Benachrichtigungen (Erforderlich) ---
SENDGRID_API_KEY="YOUR_SENDGRID_API_KEY"
SENDER_EMAIL="[email protected]"
ALERT_RECIPIENTS="[email protected],[email protected]"

# --- Datenbank ---
SQLITE_PATH="threat_sentric_ai.db"

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

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

# --- Shodan Abfrageverhalten-Steuerung ---
SHODAN_QUERY=""
SHODAN_QUERY_EMPTY_TO_PRESET="True"

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

# --- Interne System-Anmeldeinformationen (Optional - Nach Bedarf für Ihre Sammler hinzufügen) ---
# 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
# Generiere 1000 Datensätze
python scripts/generate_realistic_training_data.py --count 1000

# Bereinigungsoptionen anzeigen
python scripts/clear_db_enhanced.py --help

# Alle Geräte und Schwachstellen löschen
python scripts/clear_db_enhanced.py --delete-devices --delete-vulns

# Benachrichtigungs-Flag zurücksetzen
python scripts/clear_db_enhanced.py --reset-notified

# Gefährlicher vollständiger Reset
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.

Beliebteste

ThreatSentry-AI

Über

ThreatSentry AI: KI-gestütztes Tool zur Bedrohungsjagd

🚀 Leitbild

👨‍💻 Autor & Danksagungen

📋 Executive Summary

✨ Kernfunktionen

🤖 Intelligente Risikobewertungs-Engine

🌐 Automatisierte Asset-Erkennung & Intelligenzfusion

📊 Executive Dashboard & Analysetools

📧 Proaktive E-Mail-Benachrichtigungen

Beispiel für eine Alarm-E-Mail

📈 Modelltransparenz & kontinuierliche Verbesserung

⚡ Leistung & Zuverlässigkeit

🖖 Visuelle Übersicht

Haupt-Dashboard

Geräte-Risikobewertungstabelle

Erweitertes Filterpanel

Suchfunktion für die gesamte Datenbank

Intelligente Paginierung & Unterstützung großer Datensätze

Analyse- und Berichterstattungspanel

Tools & Konfiguration

E-Mail-Benachrichtigungen

Manueller Scan-Workflow

🛠️ Technologie-Stack

🏗️ Architektur & Datenfluss```

Schritt 2: Virtuelle Umgebung erstellen```bash

On Windows

On macOS/Linux

Schritt 4: Umgebung konfigurieren

Schritt 5: Datenbank initialisieren```bash

🚀 Nutzungsanleitung

Übersicht der Dashboard-Komponenten

1. Gerätetabelle & Erkennung

2. Risikoverteilungsdiagramm

3. Wichtige Aktionsschaltflächen

Erweiterte Funktionen

Registerkarte Analyse

Registerkarte Tools

Konfiguration

Voreingestellte Abfragen (Bearbeiten Sie core/config.py)```python

Schwachstellentabelle```

Voreingestellte Abfragen (Bearbeiten Sie `core/config.py`)```python