Thanks to visit codestin.com
Credit goes to Github.com

Skip to content

Email Parsing und Datenaufbereitung von Leitstellen Alarm Mail, zum weiterverwwenden mit alarm-messenger und alarm-monitor

License

Notifications You must be signed in to change notification settings

TimUx/alarm-mail

Repository files navigation

🚨 alarm-mail

Intelligente E-Mail-Verarbeitung für Feuerwehr-Alarmierungssysteme

License: MIT Python 3.11+

alarm-mail ist ein automatisierter Service, der Alarm-E-Mails aus einem IMAP-Postfach abruft, die XML-Einsatzinformationen parst und strukturiert an nachgelagerte Systeme weiterleitet. Als zentrale Schnittstelle zwischen der Leitstelle und den Alarmierungssystemen ermöglicht der Service eine flexible und skalierbare Verarbeitung von Einsatzmeldungen.


📋 Inhaltsverzeichnis


🎯 Überblick

Was macht alarm-mail?

Der alarm-mail Service bildet die zentrale E-Mail-Verarbeitungskomponente im Feuerwehr-Alarmierungssystem. Er:

  • Ruft automatisch Alarm-E-Mails von einem IMAP-Server ab
  • Parst XML-strukturierte Einsatzinformationen (INCIDENT-Format)
  • Verarbeitet alle relevanten Einsatzdaten (Stichwort, Ort, Einheiten, etc.)
  • Verteilt die strukturierten Daten an verschiedene Zielsysteme

Warum alarm-mail verwenden?

Zentrale E-Mail-Verarbeitung - Ein Service für mehrere Empfängersysteme
Entkopplung - Unabhängige Skalierung und Wartung der Komponenten
Flexibilität - Unterstützung mehrerer Zielsysteme gleichzeitig
Sicherheit - Verschlüsselte IMAP-Verbindung und API-Authentifizierung
Zuverlässigkeit - Robuste Fehlerbehandlung und strukturiertes Logging
Einfache Bereitstellung - Docker-Support für schnelles Setup

Anwendungsfall

Die Leitstelle sendet Alarmmeldungen als E-Mail mit XML-Anhang an ein Postfach. Der alarm-mail Service überwacht dieses Postfach kontinuierlich, extrahiert alle relevanten Informationen und leitet sie an:


⚡ Funktionsumfang

E-Mail-Verarbeitung

  • ✅ Automatisches IMAP-Polling in konfigurierbaren Intervallen
  • ✅ Unterstützung für SSL/TLS-verschlüsselte Verbindungen
  • ✅ Flexible Suchkriterien (UNSEEN, ALL, etc.)
  • ✅ Robuste Fehlerbehandlung bei Verbindungsabbrüchen

XML-Parsing

  • ✅ Vollständige Verarbeitung des INCIDENT-XML-Formats
  • ✅ Extraktion aller Einsatzinformationen:
    • Einsatznummer und Zeitstempel
    • Stichwort (Haupt- und Unterstichwort)
    • Diagnose und Bemerkungen
    • Einsatzort (Straße, Ort, Ortsteil, Koordinaten)
    • Alarmierte Einheiten (AAO)
    • Einsatzmaßnahmen (TME-Codes für Gruppenalarmierung)
  • ✅ Sichere XML-Verarbeitung mit defusedxml
  • ✅ Validierung und Fehlerbehandlung

API-Integration

  • ✅ Push an alarm-monitor mit strukturierten Alarmdaten
  • ✅ Push an alarm-messenger im Emergency-Format
  • ✅ API-Key-basierte Authentifizierung
  • ✅ Automatische Format-Konvertierung für verschiedene Zielsysteme
  • ✅ Gleichzeitige Unterstützung mehrerer Targets
  • ✅ Fehlertoleranz bei Target-Ausfällen

Betrieb & Monitoring

  • ✅ Health-Check-Endpoint für Monitoring
  • ✅ Strukturiertes Logging für einfache Fehlersuche
  • ✅ Docker und Docker Compose Support
  • ✅ Systemd-Service-Integration
  • ✅ Konfiguration über Umgebungsvariablen
  • ✅ Non-root Container-Betrieb

🏗️ Architektur

Systemübersicht

┌─────────────────────────────────────────────────────────────┐
│                     Leitstelle / ILS                         │
│  Sendet Alarm-E-Mails mit XML-Einsatzinformationen         │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        │ E-Mail (IMAP/TLS)
                        │
                        ▼
┌─────────────────────────────────────────────────────────────┐
│                  IMAP-Postfach                               │
│            (z.B. [email protected])                        │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        │ IMAP-Polling (alle 60s)
                        │
                        ▼
        ┌───────────────────────────────────────┐
        │      🚨 alarm-mail Service            │
        │                                       │
        │  ┌─────────────────────────────────┐ │
        │  │   IMAP Fetcher                  │ │
        │  │   - Verbindung zu IMAP          │ │
        │  │   - Polling neuer E-Mails       │ │
        │  └──────────┬──────────────────────┘ │
        │             │                         │
        │             ▼                         │
        │  ┌─────────────────────────────────┐ │
        │  │   XML Parser                    │ │
        │  │   - INCIDENT-XML parsen         │ │
        │  │   - Daten extrahieren           │ │
        │  │   - Strukturieren               │ │
        │  └──────────┬──────────────────────┘ │
        │             │                         │
        │             ▼                         │
        │  ┌─────────────────────────────────┐ │
        │  │   Push Service                  │ │
        │  │   - Format-Konvertierung        │ │
        │  │   - API-Authentifizierung       │ │
        │  │   - Target-Distribution         │ │
        │  └──────────┬──────────────────────┘ │
        └─────────────┼─────────────────────────┘
                      │
         ┌────────────┴────────────┐
         │                         │
         │ REST API                │ REST API
         │ (X-API-Key)             │ (X-API-Key)
         │                         │
         ▼                         ▼
┌──────────────────┐      ┌──────────────────┐
│  alarm-monitor   │      │ alarm-messenger  │
│                  │      │                  │
│  - Web-Dashboard │      │  - Mobile App    │
│  - Einsatzübersicht│    │  - Push-Alarme   │
│  - Kartendarstellung│   │  - Rückmeldung   │
│                  │      │  - Gruppierung   │
└──────────────────┘      └──────────────────┘
         │                         │
         ▼                         ▼
    Dashboard-User          Einsatzkräfte

Datenfluss

  1. E-Mail-Empfang: Leitstelle sendet Alarm-E-Mail mit XML-Inhalt
  2. Polling: alarm-mail prüft regelmäßig auf neue ungelesene E-Mails
  3. Parsing: XML-Struktur wird analysiert und in strukturiertes Format überführt
  4. Validierung: Vollständigkeit und Korrektheit der Daten werden geprüft
  5. Distribution: Daten werden an konfigurierte Zielsysteme gesendet
    • alarm-monitor: Empfängt vollständige Alarmdaten zur Anzeige
    • alarm-messenger: Empfängt Emergency-Format für mobile Alarmierung
  6. Logging: Alle Schritte werden protokolliert für Monitoring und Debugging

Komponenten

IMAP Fetcher (mail_checker.py)

  • Verwaltet IMAP-Verbindung mit SSL/TLS
  • Polling-Thread mit konfigurierbarem Intervall
  • Robuste Fehlerbehandlung und Reconnect-Logik
  • Unterstützung für verschiedene Zeichensätze

XML Parser (parser.py)

  • Sichere XML-Verarbeitung mit defusedxml
  • Extraktion aller INCIDENT-Felder
  • Zeitstempel-Konvertierung ins ISO-Format
  • Koordinaten-Validierung
  • TME-Code-Extraktion für Gruppenalarmierung

Push Service (push_service.py)

  • Format-Adaption für verschiedene Zielsysteme
  • API-Key-Management
  • HTTP-Client mit Timeout und Retry-Logik
  • Separate Fehlerbehandlung pro Target

Flask App (app.py)

  • REST-API mit Health-Check
  • Service-Status-Endpunkt
  • Lifecycle-Management des Polling-Threads
  • Konfigurationsvalidierung beim Start

🚀 Schnellstart

Möchten Sie schnell loslegen? Folgen Sie der Schnellstart-Anleitung für ein Setup in 5 Minuten!

Voraussetzungen

  • Docker & Docker Compose (empfohlen) ODER
  • Python 3.11+ mit pip und venv
  • IMAP-Postfach mit Zugangsdaten
  • Optional: Laufende Instanzen von alarm-monitor und/oder alarm-messenger

Minimale Installation (Docker)

# Repository klonen
git clone https://github.com/TimUx/alarm-mail.git
cd alarm-mail

# Konfiguration erstellen
cp .env.example .env
nano .env  # IMAP-Zugangsdaten eintragen

# Service starten
docker compose up -d

# Status prüfen
curl http://localhost:8000/health

Fertig! Der Service läuft und überwacht Ihr Postfach.

Für detaillierte Installationsoptionen siehe Installation.


📦 Installation

Der alarm-mail Service kann auf verschiedene Arten installiert werden. Wählen Sie die für Ihre Umgebung passende Methode.

Option 1: Docker (Empfohlen) 🐋

Docker ist die einfachste und zuverlässigste Installationsmethode.

Vorteile:

  • Keine lokalen Abhängigkeiten außer Docker
  • Konsistente Umgebung
  • Einfache Updates
  • Isolierte Ausführung

Installation:

# Repository klonen
git clone https://github.com/TimUx/alarm-mail.git
cd alarm-mail

# Konfiguration erstellen
cp .env.example .env
nano .env  # Ihre IMAP-Zugangsdaten und API-Keys eintragen

# Service bauen und starten
docker compose up -d --build

# Logs anzeigen
docker compose logs -f

# Status prüfen
curl http://localhost:8000/health

# Service stoppen
docker compose down

Wichtig: Der Container läuft als non-root User für erhöhte Sicherheit.

Option 2: Native Python-Installation 🐍

Für direkte Installation auf dem Host-System.

Voraussetzungen:

  • Python 3.11 oder höher
  • pip und venv
  • Systemzugriff für Paketinstallation

Schritt 1: System vorbereiten

sudo apt update
sudo apt install python3 python3-venv python3-pip

Schritt 2: Projekt klonen und Umgebung erstellen

git clone https://github.com/TimUx/alarm-mail.git
cd alarm-mail
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Schritt 3: Konfiguration erstellen

cp .env.example .env
nano .env  # Ihre Zugangsdaten eintragen

Schritt 4: Service starten

Für Entwicklung:

flask --app alarm_mail.app run --host 0.0.0.0 --port 8000

Für Produktion (mit Gunicorn):

gunicorn --bind 0.0.0.0:8000 "alarm_mail.app:create_app()" --workers 1 --threads 4

Schritt 5: Als Systemd-Dienst einrichten (optional)

Erstellen Sie /etc/systemd/system/alarm-mail.service:

[Unit]
Description=Feuerwehr Alarm Mail Service
After=network.target
Documentation=https://github.com/TimUx/alarm-mail

[Service]
Type=simple
User=alarm
Group=alarm
WorkingDirectory=/opt/alarm-mail
Environment="PATH=/opt/alarm-mail/.venv/bin"
EnvironmentFile=/opt/alarm-mail/.env
ExecStart=/opt/alarm-mail/.venv/bin/gunicorn --bind 0.0.0.0:8000 "alarm_mail.app:create_app()" --workers 1 --threads 4
Restart=always
RestartSec=10

# Sicherheitsoptionen
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target

Dienst aktivieren und starten:

sudo systemctl daemon-reload
sudo systemctl enable alarm-mail
sudo systemctl start alarm-mail
sudo systemctl status alarm-mail

Option 3: Docker Build (Manuell)

Für erweiterte Kontrolle über den Container-Build.

# Image bauen
docker build -t alarm-mail:latest .

# Container starten mit Environment-Variablen
docker run -d \
  --name alarm-mail \
  -p 8000:8000 \
  --env-file .env \
  --restart unless-stopped \
  alarm-mail:latest

# Logs anzeigen
docker logs -f alarm-mail

# Container stoppen
docker stop alarm-mail
docker rm alarm-mail

⚙️ Konfiguration

Der alarm-mail Service wird vollständig über Umgebungsvariablen konfiguriert. Alle Variablen tragen das Präfix ALARM_MAIL_.

Übersicht der Konfigurationsvariablen

🔴 IMAP-Konfiguration (Pflicht)

Diese Einstellungen sind zwingend erforderlich für den Betrieb des Services.

Variable Typ Default Beschreibung
IMAP_HOST String Pflicht Hostname oder IP-Adresse des IMAP-Servers
Beispiel: imap.gmail.com
IMAP_USERNAME String Pflicht Benutzername/E-Mail für die Anmeldung
Beispiel: [email protected]
IMAP_PASSWORD String Pflicht Passwort für die Anmeldung
⚠️ Nie in Version Control einchecken!
IMAP_PORT Integer 993 Port des IMAP-Servers
Standard: 993 (SSL), 143 (unverschlüsselt)
IMAP_USE_SSL Boolean true SSL/TLS-Verschlüsselung aktivieren
Werte: true oder false
IMAP_MAILBOX String INBOX Zu überwachender E-Mail-Ordner
Beispiel: INBOX, Alarme
IMAP_SEARCH String UNSEEN IMAP-Suchkriterium für E-Mails
Werte: UNSEEN, ALL, SINCE, etc.
POLL_INTERVAL Integer 60 Abrufintervall in Sekunden
Minimum: 10, empfohlen: 60

📊 Alarm Monitor Integration (Optional)

Aktiviert die Weiterleitung an das alarm-monitor Dashboard.

Variable Typ Beschreibung
ALARM_MONITOR_URL String Basis-URL des alarm-monitor
Beispiel: http://alarm-monitor:8000 oder https://monitor.feuerwehr.de
⚠️ Muss zusammen mit ALARM_MONITOR_API_KEY gesetzt sein
ALARM_MONITOR_API_KEY String API-Schlüssel für Authentifizierung
Wird vom alarm-monitor über ALARM_DASHBOARD_API_KEY definiert
⚠️ Geheim halten!

Hinweis: Beide Variablen müssen gesetzt sein, damit die Integration aktiv ist.

📱 Alarm Messenger Integration (Optional)

Aktiviert die Weiterleitung an den alarm-messenger für mobile Alarmierung.

Variable Typ Beschreibung
ALARM_MESSENGER_URL String Basis-URL des alarm-messenger
Beispiel: http://alarm-messenger:3000 oder https://messenger.feuerwehr.de
⚠️ Muss zusammen mit ALARM_MESSENGER_API_KEY gesetzt sein
ALARM_MESSENGER_API_KEY String API-Schlüssel für Authentifizierung
Wird vom alarm-messenger über API_SECRET_KEY definiert
⚠️ Geheim halten!

Hinweis: Beide Variablen müssen gesetzt sein, damit die Integration aktiv ist.

Konfigurationsbeispiele

Minimal-Konfiguration (nur IMAP)

# Nur E-Mail-Parsing, keine Weiterleitung
ALARM_MAIL_IMAP_HOST=imap.mailserver.de
[email protected]
ALARM_MAIL_IMAP_PASSWORD=geheimes-passwort

Standard-Konfiguration (mit alarm-monitor)

# IMAP Konfiguration
ALARM_MAIL_IMAP_HOST=imap.mailserver.de
ALARM_MAIL_IMAP_PORT=993
ALARM_MAIL_IMAP_USE_SSL=true
[email protected]
ALARM_MAIL_IMAP_PASSWORD=geheimes-passwort
ALARM_MAIL_IMAP_MAILBOX=INBOX
ALARM_MAIL_IMAP_SEARCH=UNSEEN
ALARM_MAIL_POLL_INTERVAL=60

# Alarm Monitor Integration
ALARM_MAIL_ALARM_MONITOR_URL=http://alarm-monitor:8000
ALARM_MAIL_ALARM_MONITOR_API_KEY=monitor-secret-key-123

Vollständige Konfiguration (beide Integrationen)

# IMAP Konfiguration
ALARM_MAIL_IMAP_HOST=imap.mailserver.de
ALARM_MAIL_IMAP_PORT=993
ALARM_MAIL_IMAP_USE_SSL=true
[email protected]
ALARM_MAIL_IMAP_PASSWORD=geheimes-passwort
ALARM_MAIL_IMAP_MAILBOX=INBOX
ALARM_MAIL_IMAP_SEARCH=UNSEEN
ALARM_MAIL_POLL_INTERVAL=60

# Alarm Monitor Integration
ALARM_MAIL_ALARM_MONITOR_URL=http://alarm-monitor:8000
ALARM_MAIL_ALARM_MONITOR_API_KEY=monitor-secret-key-123

# Alarm Messenger Integration
ALARM_MAIL_ALARM_MESSENGER_URL=http://alarm-messenger:3000
ALARM_MAIL_ALARM_MESSENGER_API_KEY=messenger-secret-key-456

Sicherheitshinweise für die Konfiguration

⚠️ Wichtig:

  1. Niemals Passwörter oder API-Keys in Git committen
  2. Verwenden Sie .env für lokale Entwicklung (bereits in .gitignore)
  3. In Produktion: Nutzen Sie Docker Secrets oder Vault-Systeme
  4. API-Keys sollten mindestens 32 Zeichen lang sein
  5. Rotieren Sie Secrets regelmäßig (empfohlen: alle 90 Tage)

Generierung sicherer API-Keys:

# Linux/macOS
openssl rand -hex 32

# Python
python3 -c "import secrets; print(secrets.token_hex(32))"

🔗 Integration

Der alarm-mail Service fungiert als zentrale Schnittstelle und kann mit verschiedenen Zielsystemen integriert werden.

Integration mit alarm-monitor

Der alarm-monitor ist ein Web-Dashboard zur Visualisierung von Einsätzen mit Kartendarstellung.

Datenfluss

alarm-mail  →  POST /api/alarm  →  alarm-monitor
            ↓
    Vollständige Alarmdaten (JSON)
            ↓
    {
      "incident_number": "2024-001",
      "timestamp": "2024-12-08T14:30:00",
      "keyword": "BRAND 3 – Wohnungsbrand",
      "location": "Hauptstraße 123, Musterstadt",
      "latitude": 51.2345,
      "longitude": 9.8765,
      "groups": [...],
      ...
    }

Konfiguration alarm-mail

ALARM_MAIL_ALARM_MONITOR_URL=http://alarm-monitor:8000
ALARM_MAIL_ALARM_MONITOR_API_KEY=ihr-geheimer-monitor-key

Konfiguration alarm-monitor

Der alarm-monitor muss einen API-Endpunkt bereitstellen. Beispiel-Implementation:

@app.route("/api/alarm", methods=["POST"])
def api_alarm():
    """Receive alarm data from alarm-mail service."""
    # API-Key-Authentifizierung
    api_key = request.headers.get("X-API-Key")
    expected_key = os.environ.get("ALARM_DASHBOARD_API_KEY")
    
    if not api_key or api_key != expected_key:
        return jsonify({"error": "Unauthorized"}), 401
    
    # Alarm-Daten verarbeiten
    alarm_data = request.get_json()
    
    # Alarm speichern und anzeigen
    # ... Ihre Logik hier ...
    
    return jsonify({"status": "ok", "message": "Alarm received"}), 200

Umgebungsvariable in alarm-monitor .env:

ALARM_DASHBOARD_API_KEY=ihr-geheimer-monitor-key

Wichtig: Der API-Key muss in beiden Services identisch sein!

Übertragene Datenfelder

Feld Typ Beschreibung
incident_number String Einsatznummer der Leitstelle
timestamp String (ISO) Zeitpunkt des Alarms
timestamp_display String Formatierter Zeitstempel zur Anzeige
keyword String Kombiniertes Stichwort für Anzeige
keyword_primary String Hauptstichwort (z.B. "F3Y")
keyword_secondary String Unterstichwort
diagnosis String Einsatzdiagnose
description String Einsatzbeschreibung
remark String Bemerkungen zum Einsatz
location String Vollständige Ortsangabe
location_details Object Strukturierte Ortsinformationen
latitude Float Breitengrad (WGS84)
longitude Float Längengrad (WGS84)
groups Array Liste aller Einheiten (AAO + TME)
aao_groups Array Alarmierte Einheiten (AAO)
dispatch_groups Array Einsatzmaßnahmen (TME)
dispatch_group_codes Array Extrahierte TME-Codes
subject String E-Mail-Betreff

Integration mit alarm-messenger

Der alarm-messenger ermöglicht die mobile Alarmierung von Einsatzkräften mit Push-Benachrichtigungen und Rückmeldung.

Datenfluss

alarm-mail  →  POST /api/emergencies  →  alarm-messenger
            ↓
    Emergency-Format (JSON)
            ↓
    {
      "emergencyNumber": "2024-001",
      "emergencyDate": "2024-12-08T14:30:00",
      "emergencyKeyword": "F3Y",
      "emergencyDescription": "Wohnungsbrand",
      "emergencyLocation": "Hauptstraße 123, Musterstadt",
      "groups": "WIL26,WIL41"  // Optional für Gruppenalarmierung
    }

Konfiguration alarm-mail

ALARM_MAIL_ALARM_MESSENGER_URL=http://alarm-messenger:3000
ALARM_MAIL_ALARM_MESSENGER_API_KEY=ihr-geheimer-messenger-key

Konfiguration alarm-messenger

Umgebungsvariable in alarm-messenger .env:

API_SECRET_KEY=ihr-geheimer-messenger-key

Wichtig: Der API-Key muss in beiden Services identisch sein!

Format-Konvertierung

Der alarm-mail Service konvertiert die XML-Daten automatisch in das von alarm-messenger erwartete Format:

alarm-mail (Intern) alarm-messenger (API)
incident_number emergencyNumber
timestamp emergencyDate
keyword_primary emergencyKeyword
diagnosis / description emergencyDescription
location emergencyLocation
dispatch_group_codes groups (optional)

Gruppenalarmierung

Wenn in der XML TME-Codes vorhanden sind, werden diese extrahiert und als groups übergeben:

Beispiel XML:

<EINSATZMASSNAHMEN>
  <TME>
    <BEZEICHNUNG>Wilersdorf 1 (TME WIL26)</BEZEICHNUNG>
    <BEZEICHNUNG>Wilersdorf 2 (TME WIL41)</BEZEICHNUNG>
  </TME>
</EINSATZMASSNAHMEN>

Resultat:

{
  "groups": "WIL26,WIL41"
}

Der alarm-messenger nutzt diese Codes zur selektiven Alarmierung der entsprechenden Gruppen.

Gleichzeitige Integration beider Systeme

Sie können alarm-mail gleichzeitig mit beiden Systemen betreiben:

# Beide Integrationen aktiv
ALARM_MAIL_ALARM_MONITOR_URL=http://alarm-monitor:8000
ALARM_MAIL_ALARM_MONITOR_API_KEY=monitor-key

ALARM_MAIL_ALARM_MESSENGER_URL=http://alarm-messenger:3000
ALARM_MAIL_ALARM_MESSENGER_API_KEY=messenger-key

Vorteile:

  • Redundante Alarmierung
  • Dashboard-Anzeige + Mobile Alarmierung
  • Unabhängige Fehlerbehandlung (Ausfall eines Systems beeinträchtigt das andere nicht)

Beispiel-Szenario:

  1. Alarm-E-Mail wird empfangen
  2. alarm-mail parst die Daten
  3. Push an alarm-monitor → Dashboard zeigt Einsatz an
  4. Push an alarm-messenger → Einsatzkräfte werden per Push benachrichtigt
  5. Beide Systeme arbeiten unabhängig

📡 API-Dokumentation

Der alarm-mail Service stellt zwei REST-Endpunkte bereit.

GET /health

Health-Check-Endpunkt für Monitoring und Load Balancer.

Request:

curl http://localhost:8000/health

Response: 200 OK

{
  "status": "ok",
  "service": "alarm-mail"
}

Verwendung:

  • Docker Health-Checks
  • Kubernetes Liveness/Readiness Probes
  • Monitoring-Systeme (Prometheus, Nagios, etc.)
  • Load Balancer Health-Checks

Beispiel Docker Health-Check:

HEALTHCHECK --interval=30s --timeout=5s --start-period=30s \
  CMD curl --fail http://localhost:8000/health || exit 1

GET /

Service-Status-Endpunkt mit erweiterten Informationen.

Request:

curl http://localhost:8000/

Response: 200 OK

{
  "service": "alarm-mail",
  "status": "running",
  "targets": ["alarm-monitor", "alarm-messenger"],
  "poll_interval": 60
}

Response-Felder:

Feld Typ Beschreibung
service String Servicename (immer "alarm-mail")
status String Aktueller Status (immer "running")
targets Array Liste der konfigurierten Zielsysteme
poll_interval Integer Konfiguriertes Polling-Intervall in Sekunden

Beispiel - Nur alarm-monitor konfiguriert:

{
  "service": "alarm-mail",
  "status": "running",
  "targets": ["alarm-monitor"],
  "poll_interval": 60
}

Beispiel - Keine Targets konfiguriert:

{
  "service": "alarm-mail",
  "status": "running",
  "targets": [],
  "poll_interval": 60
}

📧 E-Mail-Format-Spezifikation

Der alarm-mail Service erwartet E-Mails mit XML-strukturierten Einsatzinformationen im <INCIDENT>-Format. Dieses Format wird von vielen Leitstellen-Systemen in Deutschland verwendet.

Unterstützte XML-Struktur

Vollständiges Beispiel:

<?xml version="1.0" encoding="UTF-8"?>
<INCIDENT>
  <!-- Einsatz-Stichwörter -->
  <STICHWORT>F3Y</STICHWORT>
  <ESTICHWORT_1>F3Y</ESTICHWORT_1>
  <ESTICHWORT_2>Personen in Gefahr</ESTICHWORT_2>
  
  <!-- Einsatz-Identifikation -->
  <ENR>7850001123</ENR>
  <EBEGINN>08.12.2024 14:30:00</EBEGINN>
  
  <!-- Einsatz-Informationen -->
  <DIAGNOSE>Brand in Wohngebäude</DIAGNOSE>
  <EO_BEMERKUNG>Starke Rauchentwicklung im 2. OG</EO_BEMERKUNG>
  
  <!-- Einsatzort -->
  <ORT>Musterstadt</ORT>
  <ORTSTEIL>Nordviertel</ORTSTEIL>
  <STRASSE>Hauptstraße</STRASSE>
  <HAUSNUMMER>123</HAUSNUMMER>
  <OBJEKT>Mehrfamilienhaus</OBJEKT>
  <ORTSZUSATZ>Hintereingang</ORTSZUSATZ>
  
  <!-- Koordinaten (WGS84) -->
  <KOORDINATE_LAT>51.2345</KOORDINATE_LAT>
  <KOORDINATE_LON>9.8765</KOORDINATE_LON>
  
  <!-- Alarmierte Einheiten (AAO) -->
  <AAO>LF Musterstadt 1;DLK Musterstadt;ELW 1</AAO>
  
  <!-- Einsatzmaßnahmen / TME-Codes -->
  <EINSATZMASSNAHMEN>
    <TME>
      <BEZEICHNUNG>Musterstadt Nord 1 (TME MUS11)</BEZEICHNUNG>
      <BEZEICHNUNG>Musterstadt Innenstadt (TME MUS05)</BEZEICHNUNG>
      <BEZEICHNUNG>Nachbarort Zentrum (TME NAC22)</BEZEICHNUNG>
    </TME>
  </EINSATZMASSNAHMEN>
</INCIDENT>

XML-Feld-Referenz

XML-Feld Pflicht Beschreibung Beispiel
<STICHWORT> Nein Allgemeines Stichwort F3Y, TH1
<ESTICHWORT_1> Nein Hauptstichwort (bevorzugt) F3Y
<ESTICHWORT_2> Nein Unterstichwort Personen in Gefahr
<ENR> Ja Einsatznummer 7850001123
<EBEGINN> Ja Einsatzbeginn 08.12.2024 14:30:00
<DIAGNOSE> Nein Einsatzdiagnose Brand in Wohngebäude
<EO_BEMERKUNG> Nein Bemerkungen Starke Rauchentwicklung
<EOZUSATZ> Nein Alternative zu EO_BEMERKUNG
<ORT> Ja Ortsname Musterstadt
<ORTSTEIL> Nein Ortsteil Nordviertel
<STRASSE> Nein Straßenname Hauptstraße
<HAUSNUMMER> Nein Hausnummer 123, 45a
<OBJEKT> Nein Objektbezeichnung Mehrfamilienhaus
<ORTSZUSATZ> Nein Zusatzinformationen Hintereingang
<KOORDINATE_LAT> Nein Breitengrad (WGS84) 51.2345
<KOORDINATE_LON> Nein Längengrad (WGS84) 9.8765
<AAO> Nein Alarmierte Einheiten (AAO) LF 1;DLK;ELW
<EINSATZMASSNAHMEN> Nein Container für TME siehe unten

AAO-Format (Alarmierte Einheiten)

Die AAO (Alarm- und Ausrückeordnung) listet die alarmierten Fahrzeuge/Einheiten auf:

<AAO>Löschzug Musterstadt;Drehleiter;Einsatzleitwagen;RW</AAO>
  • Trennung durch Semikolon (;)
  • Wird als Liste gespeichert: ["Löschzug Musterstadt", "Drehleiter", "Einsatzleitwagen", "RW"]

TME-Format (Einsatzmaßnahmen / Gruppen)

TME-Codes werden für die Gruppenalarmierung verwendet:

<EINSATZMASSNAHMEN>
  <TME>
    <BEZEICHNUNG>Musterstadt Nord 1 (TME MUS11)</BEZEICHNUNG>
    <BEZEICHNUNG>Musterstadt Süd (TME MUS22)</BEZEICHNUNG>
  </TME>
</EINSATZMASSNAHMEN>

Code-Extraktion:

  • Der Service extrahiert Codes im Format: [A-Z]+[0-9]+
  • Aus Musterstadt Nord 1 (TME MUS11) wird: MUS11
  • Mehrere Codes werden als kommaseparierte Liste weitergegeben: MUS11,MUS22

Verwendung:

  • alarm-messenger nutzt diese Codes zur selektiven Alarmierung
  • Nur Mitglieder der entsprechenden Gruppen werden benachrichtigt

Zeitstempel-Format

Unterstützte Formate für <EBEGINN>:

08.12.2024 14:30:00  →  2024-12-08T14:30:00 (ISO 8601)
08.12.2024 14:30     →  2024-12-08T14:30:00 (ISO 8601)

Der Service konvertiert automatisch in ISO 8601 Format für einheitliche Weiterverarbeitung.

Minimal-Beispiel

Minimal erforderliche XML-Struktur für erfolgreiche Verarbeitung:

<?xml version="1.0" encoding="UTF-8"?>
<INCIDENT>
  <ENR>2024-001</ENR>
  <EBEGINN>08.12.2024 14:30:00</EBEGINN>
  <ESTICHWORT_1>F3Y</ESTICHWORT_1>
  <ORT>Musterstadt</ORT>
</INCIDENT>

🚀 Deployment

Deployment-Szenarien

Je nach Infrastruktur und Anforderungen gibt es verschiedene Deployment-Möglichkeiten.

Szenario 1: All-in-One mit Docker Compose

Ideal für: Kleine bis mittlere Feuerwehren, Test-Umgebungen

Alle Services (alarm-mail, alarm-monitor, alarm-messenger) laufen zusammen auf einem Host.

Vorteile:

  • Einfaches Setup
  • Alle Services in einem Netzwerk
  • Gemeinsames Management
  • Ressourcensparend

Verzeichnisstruktur:

feuerwehr-alarm/
├── alarm-mail/          # Dieses Repository
├── alarm-monitor/       # Dashboard Repository
├── alarm-messenger/     # Messenger Repository
└── docker-compose.yaml  # Zentrale Compose-Datei

Gemeinsame docker-compose.yaml:

version: '3.8'

services:
  alarm-mail:
    build: ./alarm-mail
    restart: unless-stopped
    environment:
      # IMAP Konfiguration
      - ALARM_MAIL_IMAP_HOST=${IMAP_HOST}
      - ALARM_MAIL_IMAP_USERNAME=${IMAP_USERNAME}
      - ALARM_MAIL_IMAP_PASSWORD=${IMAP_PASSWORD}
      - ALARM_MAIL_IMAP_MAILBOX=INBOX
      - ALARM_MAIL_POLL_INTERVAL=60
      # Targets
      - ALARM_MAIL_ALARM_MONITOR_URL=http://alarm-monitor:8000
      - ALARM_MAIL_ALARM_MONITOR_API_KEY=${API_KEY_SHARED}
      - ALARM_MAIL_ALARM_MESSENGER_URL=http://alarm-messenger:3000
      - ALARM_MAIL_ALARM_MESSENGER_API_KEY=${API_KEY_SHARED}
    depends_on:
      - alarm-monitor
      - alarm-messenger
    networks:
      - alarm-network

  alarm-monitor:
    build: ./alarm-monitor
    restart: unless-stopped
    ports:
      - "8000:8000"
    environment:
      - ALARM_DASHBOARD_API_KEY=${API_KEY_SHARED}
    volumes:
      - monitor-data:/app/data
    networks:
      - alarm-network

  alarm-messenger:
    build: ./alarm-messenger/server
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - API_SECRET_KEY=${API_KEY_SHARED}
      - DATABASE_URL=postgresql://postgres:postgres@postgres:5432/messenger
    depends_on:
      - postgres
    networks:
      - alarm-network

  postgres:
    image: postgres:15-alpine
    restart: unless-stopped
    environment:
      - POSTGRES_DB=messenger
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - alarm-network

volumes:
  monitor-data:
  postgres-data:

networks:
  alarm-network:
    driver: bridge

.env Datei für Compose:

# IMAP Zugangsdaten
IMAP_HOST=imap.mailserver.de
[email protected]
IMAP_PASSWORD=geheimes-passwort

# Gemeinsamer API-Key für alle Services
API_KEY_SHARED=ihr-sehr-geheimer-api-key-min-32-zeichen

Starten:

docker compose up -d
docker compose logs -f

Szenario 2: Getrennte Server (Verteiltes Setup)

Ideal für: Größere Organisationen, Hochverfügbarkeit

Services laufen auf separaten Servern mit externer Kommunikation.

Architektur:

Server 1 (alarm-mail)     →  HTTPS  →  Server 2 (alarm-monitor)
                          →  HTTPS  →  Server 3 (alarm-messenger)

Vorteile:

  • Unabhängige Skalierung
  • Höhere Verfügbarkeit
  • Getrennte Wartungsfenster
  • Bessere Lastverteilung

Konfiguration alarm-mail:

# Externe HTTPS-URLs verwenden
ALARM_MAIL_ALARM_MONITOR_URL=https://monitor.feuerwehr.de
ALARM_MAIL_ALARM_MESSENGER_URL=https://messenger.feuerwehr.de

Wichtig:

  • Nutzen Sie HTTPS für externe Kommunikation
  • Firewall-Regeln für API-Zugriffe einrichten
  • API-Keys über sichere Kanäle austauschen

Szenario 3: Standalone alarm-mail

Ideal für: Entwicklung, Testing, spätere Integration

Nur alarm-mail läuft, keine Weiterleitung an Targets.

Konfiguration:

# Nur IMAP konfigurieren
ALARM_MAIL_IMAP_HOST=imap.mailserver.de
[email protected]
ALARM_MAIL_IMAP_PASSWORD=geheim

# Keine Target-URLs setzen
# Alarme werden geparst aber nicht weitergeleitet

Verwendung:

  • Testen der E-Mail-Verarbeitung
  • Validierung des XML-Formats
  • Log-Analyse ohne Live-Alarmierung

Szenario 4: Kubernetes Deployment

Ideal für: Enterprise-Umgebungen, Cloud-Deployment

Beispiel Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: alarm-mail
  namespace: feuerwehr
spec:
  replicas: 1
  selector:
    matchLabels:
      app: alarm-mail
  template:
    metadata:
      labels:
        app: alarm-mail
    spec:
      containers:
      - name: alarm-mail
        image: alarm-mail:latest
        ports:
        - containerPort: 8000
        env:
        - name: ALARM_MAIL_IMAP_HOST
          valueFrom:
            secretKeyRef:
              name: alarm-mail-secrets
              key: imap-host
        - name: ALARM_MAIL_IMAP_USERNAME
          valueFrom:
            secretKeyRef:
              name: alarm-mail-secrets
              key: imap-username
        - name: ALARM_MAIL_IMAP_PASSWORD
          valueFrom:
            secretKeyRef:
              name: alarm-mail-secrets
              key: imap-password
        - name: ALARM_MAIL_ALARM_MONITOR_URL
          value: "http://alarm-monitor:8000"
        - name: ALARM_MAIL_ALARM_MONITOR_API_KEY
          valueFrom:
            secretKeyRef:
              name: alarm-mail-secrets
              key: monitor-api-key
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 30
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 10
          periodSeconds: 10
---
apiVersion: v1
kind: Service
metadata:
  name: alarm-mail
  namespace: feuerwehr
spec:
  selector:
    app: alarm-mail
  ports:
  - port: 8000
    targetPort: 8000

Reverse Proxy Setup

Für externen Zugriff empfiehlt sich ein Reverse Proxy (nginx, Traefik, etc.).

Beispiel nginx-Konfiguration:

server {
    listen 443 ssl http2;
    server_name alarm-mail.feuerwehr.de;

    ssl_certificate /etc/ssl/certs/alarm-mail.crt;
    ssl_certificate_key /etc/ssl/private/alarm-mail.key;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Backup-Strategie

Was sollte gesichert werden:

  1. Konfiguration (.env Dateien)

    • Regelmäßige verschlüsselte Backups
    • Sichere Aufbewahrung außerhalb des Servers
  2. Logs (optional)

    • Für Compliance und Debugging
    • Rotation nach 30-90 Tagen
  3. Keine E-Mail-Inhalte

    • alarm-mail speichert keine E-Mails
    • Nur Parsing und Weiterleitung

Backup-Beispiel:

#!/bin/bash
# Backup-Script
DATE=$(date +%Y%m%d_%H%M%S)
tar -czf backup-alarm-mail-${DATE}.tar.gz .env docker-compose.yaml
gpg -c backup-alarm-mail-${DATE}.tar.gz
rm backup-alarm-mail-${DATE}.tar.gz

📊 Monitoring & Logging

Log-Ausgabe

Der Service nutzt strukturiertes Logging mit verschiedenen Log-Levels.

Log-Format:

2024-12-08 14:30:00 - alarm_mail.mail_checker - INFO - Fetching new message UID 123
2024-12-08 14:30:01 - alarm_mail.parser - INFO - Parsed alarm: 2024-001 - F3Y
2024-12-08 14:30:02 - alarm_mail.push_service - INFO - Successfully pushed alarm to alarm-monitor

Logs anzeigen:

Docker:

# Live-Logs
docker compose logs -f alarm-mail

# Nur Fehler
docker compose logs alarm-mail | grep ERROR

# Letzte 100 Zeilen
docker compose logs --tail=100 alarm-mail

Systemd:

# Live-Logs
sudo journalctl -u alarm-mail -f

# Nur heute
sudo journalctl -u alarm-mail --since today

# Nur Fehler
sudo journalctl -u alarm-mail -p err

Health-Checks

Manueller Check:

curl http://localhost:8000/health

# Expected: {"status":"ok","service":"alarm-mail"}

Automatisches Monitoring mit Prometheus:

Für erweitertes Monitoring kann ein Prometheus-Exporter hinzugefügt werden.

Shell-Script für Monitoring:

#!/bin/bash
# check-alarm-mail.sh

HEALTH_URL="http://localhost:8000/health"
RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" $HEALTH_URL)

if [ "$RESPONSE" != "200" ]; then
    echo "CRITICAL - alarm-mail health check failed (HTTP $RESPONSE)"
    exit 2
fi

echo "OK - alarm-mail is running"
exit 0

Monitoring-Integration

Nagios/Icinga:

check_http -H localhost -p 8000 -u /health -s "ok"

Prometheus mit Blackbox Exporter:

- job_name: 'alarm-mail'
  metrics_path: /probe
  params:
    module: [http_2xx]
  static_configs:
    - targets:
      - http://alarm-mail:8000/health
  relabel_configs:
    - source_labels: [__address__]
      target_label: __param_target
    - source_labels: [__param_target]
      target_label: instance
    - target_label: __address__
      replacement: blackbox-exporter:9115

Uptime Kuma:

  • Monitor-Typ: HTTP(s)
  • URL: http://alarm-mail:8000/health
  • Intervall: 60 Sekunden
  • Expected Status: 200

🔧 Entwicklung

Projekt-Setup für Entwickler

# Repository klonen
git clone https://github.com/TimUx/alarm-mail.git
cd alarm-mail

# Virtual Environment erstellen
python3 -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

# Dependencies installieren
pip install -r requirements.txt

# Development Dependencies (optional)
pip install pytest pytest-cov black flake8 mypy

Projektstruktur

alarm-mail/
├── alarm_mail/              # Hauptanwendung (Python Package)
│   ├── __init__.py         # Package-Initialisierung
│   ├── app.py              # Flask-Applikation & Lifecycle
│   ├── config.py           # Konfigurationsverwaltung
│   ├── mail_checker.py     # IMAP-Polling-Thread
│   ├── parser.py           # XML-Parsing-Logik
│   └── push_service.py     # API-Push-Service
│
├── docs/                    # Dokumentation (erweitert)
│   ├── images/             # Screenshots & Diagramme
│   └── examples/           # Beispiel-Konfigurationen
│
├── .env.example            # Beispiel-Konfiguration
├── .gitignore              # Git-Ignore-Regeln
├── compose.yaml            # Docker Compose Definition
├── Dockerfile              # Container-Image-Build
├── LICENSE                 # MIT Lizenz
├── README.md               # Hauptdokumentation
├── QUICKSTART.md           # Schnellstart-Anleitung
├── requirements.txt        # Python-Abhängigkeiten
└── alarm-mail.service      # Systemd-Service-Datei

Lokale Entwicklung

Service im Debug-Modus starten:

# Flask Development Server
export FLASK_ENV=development
flask --app alarm_mail.app run --host 0.0.0.0 --port 8000 --reload

# Oder mit Python direkt
python -m alarm_mail.app

Mit Test-E-Mail-Server:

Für Tests ohne echten IMAP-Server:

# MailHog starten (Test-IMAP-Server)
docker run -d -p 1025:1025 -p 8025:8025 mailhog/mailhog

# In .env konfigurieren
ALARM_MAIL_IMAP_HOST=localhost
ALARM_MAIL_IMAP_PORT=1025
ALARM_MAIL_IMAP_USE_SSL=false

Code-Qualität

Linting mit flake8:

flake8 alarm_mail/

Formatting mit black:

black alarm_mail/

Type Checking mit mypy:

mypy alarm_mail/

Testing

Unit Tests (falls vorhanden):

# Alle Tests ausführen
pytest

# Mit Coverage
pytest --cov=alarm_mail --cov-report=html

# Spezifische Tests
pytest tests/test_parser.py -v

Beitragen

Beiträge sind willkommen! Bitte beachten Sie:

  1. Fork des Repositories erstellen
  2. Feature-Branch erstellen (git checkout -b feature/amazing-feature)
  3. Code-Stil einhalten (black, flake8)
  4. Commits mit aussagekräftigen Nachrichten
  5. Tests hinzufügen für neue Features
  6. Pull Request erstellen

Commit-Message-Format:

feat: Add support for new XML field
fix: Correct timestamp parsing for edge case
docs: Update installation instructions
refactor: Simplify parser logic
test: Add tests for push service

🔒 Sicherheit

Implementierte Sicherheitsmaßnahmen

Verschlüsselte Kommunikation

  • IMAP-Verbindung über SSL/TLS (Port 993)
  • Unterstützung für TLS-verschlüsselte SMTP-Server
  • Sichere XML-Verarbeitung mit defusedxml (verhindert XXE-Angriffe)

Authentifizierung & Autorisierung

  • API-Key-basierte Authentifizierung für alle Zielsysteme
  • HTTP-Header: X-API-Key
  • Keine Authentifizierung für Health-Checks erforderlich

Datensicherheit

  • Keine Speicherung von E-Mail-Inhalten
  • E-Mails werden nur im Speicher verarbeitet
  • Geparste Daten werden direkt weitergeleitet
  • Keine Persistierung sensibler Informationen

Container-Sicherheit

  • Container läuft als non-root User (appuser)
  • Minimales Python-Base-Image (python:3.11-slim)
  • Nur notwendige Abhängigkeiten installiert
  • Multi-Stage-Build für kleinere Images (optional erweiterbar)

Konfigurationssicherheit

  • Secrets nur über Umgebungsvariablen
  • Keine Hard-coded Credentials im Code
  • .env in .gitignore
  • Health-Check enthält keine sensitiven Daten

Sicherheits-Best Practices

1. Starke API-Keys verwenden

# Generieren Sie sichere, zufällige API-Keys (mindestens 32 Zeichen)
openssl rand -hex 32

# Oder mit Python
python3 -c "import secrets; print(secrets.token_hex(32))"

Anforderungen:

  • Mindestens 32 Zeichen
  • Zufällig generiert
  • Eindeutig für jeden Service

2. Secrets-Management

Entwicklung:

# .env Datei verwenden (nicht in Git!)
cp .env.example .env
nano .env

Produktion mit Docker Secrets:

services:
  alarm-mail:
    image: alarm-mail:latest
    secrets:
      - imap_password
      - api_key_monitor
      - api_key_messenger
    environment:
      - ALARM_MAIL_IMAP_PASSWORD_FILE=/run/secrets/imap_password
      - ALARM_MAIL_ALARM_MONITOR_API_KEY_FILE=/run/secrets/api_key_monitor

secrets:
  imap_password:
    external: true
  api_key_monitor:
    external: true
  api_key_messenger:
    external: true

Produktion mit Vault:

# Secrets aus HashiCorp Vault laden
vault kv get -field=imap_password secret/alarm-mail

3. Netzwerk-Sicherheit

Firewall-Regeln (iptables-Beispiel):

# Nur IMAP-Server erlauben
iptables -A OUTPUT -p tcp --dport 993 -d imap.mailserver.de -j ACCEPT

# Nur Target-Services erlauben
iptables -A OUTPUT -p tcp --dport 8000 -d alarm-monitor -j ACCEPT
iptables -A OUTPUT -p tcp --dport 3000 -d alarm-messenger -j ACCEPT

# Alles andere blockieren
iptables -A OUTPUT -j DROP

Docker-Netzwerk isolieren:

networks:
  alarm-network:
    driver: bridge
    internal: true  # Kein Internet-Zugang

4. TLS/HTTPS für externe Kommunikation

Verwenden Sie für externe Zielsysteme immer HTTPS:

# ❌ NICHT für öffentliche Netze
ALARM_MAIL_ALARM_MONITOR_URL=http://monitor.example.com

# ✅ HTTPS verwenden
ALARM_MAIL_ALARM_MONITOR_URL=https://monitor.example.com

5. Logging-Sicherheit

Sensible Daten werden nicht geloggt:

  • ✅ Einsatznummern werden geloggt
  • ✅ Stichwörter werden geloggt
  • ❌ IMAP-Passwörter werden NICHT geloggt
  • ❌ API-Keys werden NICHT geloggt
  • ❌ E-Mail-Inhalte werden NICHT geloggt

6. Regelmäßige Updates

# Dependencies aktualisieren
pip install --upgrade -r requirements.txt

# Docker-Image neu bauen
docker compose build --no-cache

# Security-Patches für Base-Image
docker pull python:3.11-slim
docker compose up -d --build

7. Minimale Berechtigungen

Systemd-Service mit eingeschränkten Rechten:

[Service]
# Keine Root-Rechte
User=alarm
Group=alarm

# Sicherheitsoptionen
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/alarm-mail

Sicherheits-Checkliste

Vor dem Produktiv-Einsatz:

  • Starke, zufällige API-Keys generiert (mind. 32 Zeichen)
  • SSL/TLS für IMAP-Verbindung aktiviert (IMAP_USE_SSL=true)
  • HTTPS für externe API-Kommunikation
  • Firewall-Regeln konfiguriert
  • Secrets nicht in Git eingecheckt
  • Container läuft als non-root User
  • Regelmäßige Update-Strategie definiert
  • Monitoring und Alerting eingerichtet
  • Backup-Strategie für Konfiguration
  • Logging auf sensible Daten überprüft

Schwachstellen melden

Wenn Sie eine Sicherheitslücke entdecken:

  1. NICHT als öffentliches Issue melden
  2. Nutzen Sie GitHub Security Advisories für vertrauliche Meldungen
  3. Oder erstellen Sie ein privates Security Issue auf GitHub
  4. Fügen Sie hinzu:
    • Detaillierte Beschreibung der Schwachstelle
    • Proof-of-Concept (falls möglich)
    • Betroffene Versionen
    • Vorgeschlagene Fixes (optional)
  5. Verantwortungsvolle Offenlegung (Responsible Disclosure)

Wir werden uns bemühen, innerhalb von 48 Stunden zu antworten und zeitnah einen Fix bereitzustellen.


🔧 Fehlerbehebung

Häufige Probleme und Lösungen

Problem: Service startet nicht

Symptome:

  • Container startet und stoppt sofort
  • docker compose up zeigt Fehler

Lösung:

# Logs prüfen
docker compose logs alarm-mail

# Häufige Ursachen:
# 1. Fehlende Pflicht-Konfiguration
# Prüfen: IMAP_HOST, IMAP_USERNAME, IMAP_PASSWORD gesetzt?

# 2. Syntax-Fehler in .env
# Prüfen: Keine Leerzeichen um "=" , Werte in Anführungszeichen bei Sonderzeichen

# 3. Port bereits belegt
docker compose ps
netstat -tulpn | grep 8000

Problem: E-Mails werden nicht abgerufen

Symptome:

  • Service läuft, aber keine Alarme werden verarbeitet
  • Logs zeigen keine neuen Nachrichten

Diagnose:

# 1. IMAP-Verbindung testen
telnet imap.mailserver.de 993

# 2. Zugangsdaten überprüfen
docker compose exec alarm-mail env | grep IMAP

# 3. Mailbox-Namen prüfen (Case-sensitive!)
# INBOX vs Inbox vs inbox

# 4. Suchkriterien anpassen
# Vielleicht sind alle E-Mails bereits gelesen?
ALARM_MAIL_IMAP_SEARCH=ALL  # Temporär zum Testen

Häufige Ursachen:

  • ❌ Falsche IMAP-Zugangsdaten
  • ❌ Firewall blockiert Port 993
  • ❌ SSL-Zertifikat-Problem
  • ❌ 2FA ohne App-Passwort
  • ❌ Mailbox-Name inkorrekt

Lösungen:

# SSL-Verbindung deaktivieren (nur für Debugging!)
ALARM_MAIL_IMAP_USE_SSL=false
ALARM_MAIL_IMAP_PORT=143

# Alternativen Mailbox-Namen versuchen
ALARM_MAIL_IMAP_MAILBOX=INBOX
# oder
ALARM_MAIL_IMAP_MAILBOX=Inbox

# Für Gmail: App-Passwort verwenden
# https://myaccount.google.com/apppasswords

Problem: Push zu Targets fehlschlägt

Symptome:

  • E-Mails werden geparst
  • Logs zeigen Fehler beim Push

Diagnose:

# 1. Target-Erreichbarkeit prüfen
curl http://alarm-monitor:8000/health
curl http://alarm-messenger:3000/api/health

# 2. API-Keys vergleichen
# alarm-mail .env:
grep ALARM_MONITOR_API_KEY .env
# alarm-monitor .env:
grep ALARM_DASHBOARD_API_KEY ../alarm-monitor/.env

# 3. Netzwerk-Verbindung prüfen
docker compose exec alarm-mail ping alarm-monitor

Häufige Ursachen:

  • ❌ API-Keys stimmen nicht überein
  • ❌ Target-Service läuft nicht
  • ❌ Netzwerk-Konfiguration falsch
  • ❌ Endpoint-URL falsch

Lösungen:

# API-Keys synchronisieren
# Beide Services müssen denselben Key verwenden!

# Service-Namen in Docker-Netzwerk verwenden
ALARM_MAIL_ALARM_MONITOR_URL=http://alarm-monitor:8000
# NICHT: http://localhost:8000

# Target-Service neu starten
docker compose restart alarm-monitor

Problem: Parsing fehlschlägt

Symptome:

  • E-Mail wird abgerufen
  • Log: "Received email without valid INCIDENT XML"

Diagnose:

# 1. E-Mail-Format prüfen
# Enthält die E-Mail wirklich <INCIDENT> XML?

# 2. Logs im Detail anschauen
docker compose logs alarm-mail | grep -A 10 "without valid"

# 3. Encoding-Probleme?
# XML muss UTF-8 oder ISO-8859-1 sein

Lösungen:

  • XML-Format der Leitstelle überprüfen
  • Beispiel-E-Mail zur Analyse bereitstellen
  • Parser erweitern für alternative Formate

Problem: Health-Check schlägt fehl

Symptome:

  • Container wird als "unhealthy" markiert
  • Restart-Loop

Diagnose:

# Health-Check manuell ausführen
docker compose exec alarm-mail curl http://localhost:8000/health

# Oder von außen
curl http://localhost:8000/health

Lösung:

# Service-Port überprüfen
docker compose ps

# Firewall-Regeln prüfen
iptables -L -n

# Health-Check-Intervall anpassen
# In Dockerfile oder compose.yaml

Debug-Modus aktivieren

Für erweiterte Fehlersuche:

# Python-Logging-Level auf DEBUG setzen
# In app.py temporär ändern:
# logging.basicConfig(level=logging.DEBUG, ...)

# Oder via Umgebungsvariable (falls implementiert)
export ALARM_MAIL_LOG_LEVEL=DEBUG

Support erhalten

Bei weiterhin bestehenden Problemen:

  1. Logs sammeln:

    docker compose logs --tail=100 alarm-mail > logs.txt
  2. Konfiguration anonymisieren:

    # Passwörter und Keys entfernen!
    cat .env | sed 's/PASSWORD=.*/PASSWORD=***/' > config-anonymized.txt
  3. Issue auf GitHub öffnen:


💬 Support & Beiträge

Community & Kontakt

Beiträge sind willkommen!

Wir freuen uns über jede Form von Beitrag:

  • 🐛 Bug-Reports und Feature-Requests
  • 📖 Verbesserungen der Dokumentation
  • 💻 Code-Beiträge (Pull Requests)
  • 🌐 Übersetzungen
  • ⭐ Sterne auf GitHub

Contribution Workflow:

  1. Fork erstellen
  2. Feature-Branch erstellen (feature/amazing-feature)
  3. Änderungen committen
  4. Pull Request öffnen

Siehe auch: CONTRIBUTING.md (falls vorhanden)


📄 Lizenz

Dieses Projekt ist lizenziert unter der MIT License.

MIT License

Copyright (c) 2024 TimUx

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Siehe LICENSE für den vollständigen Lizenztext.


🙏 Danksagungen

  • Alle Beiträge zur Entwicklung
  • Die Open-Source-Community
  • Feuerwehren, die das System testen und Feedback geben

Entwickelt mit ❤️ für Feuerwehren

⬆️ Nach oben

About

Email Parsing und Datenaufbereitung von Leitstellen Alarm Mail, zum weiterverwwenden mit alarm-messenger und alarm-monitor

Resources

License

Contributing

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors 2

  •  
  •