Selbstgehostete Plattform für Phishing-Awareness — simulierte Phishing-Kampagnen planen, versenden und pro Empfänger auswerten, um Mitarbeitende messbar gegen Social Engineering zu wappnen.
HumanShield.APP hilft Organisationen, ihre menschliche Angriffsfläche zu verkleinern: realistische Phishing-Simulationen durchführen, Öffnungen/Klicks/Eingaben nachvollziehen und daraus gezielte Sensibilisierung ableiten. Die Plattform läuft vollständig bei dir — alle umgebungsspezifischen Werte (Domain, IdP, SMTP) kommen aus der Konfiguration, nichts ist im Code fest verdrahtet.
Kampagnen & Tracking
- Kampagnen-Assistent mit optionaler Zeitplanung
- Tracking von Öffnungen, Klicks und Formular-Eingaben — ausgewertet pro Empfänger, mit Session-Verlauf (Mehrfachbesuche) je Empfänger
- Engagement-Analytics — Aufschlüsselung nach Browser, Betriebssystem, Gerätetyp und Ländern (optionale lokale GeoIP-Datenbank), UTM-Parameter und Referrer
- Control-Center-Dashboard mit KPIs, Risiko-Score (Ampel), Trichter, Zeitachse, Aktivitäts-Heatmap und Human-Risk-Score; Management Report und CSV-Export
Inhalte
- Vorlagen mit HTML- oder Markdown-Editor, Personalisierungs-Variablen und Live-Vorschau
.eml-Import echter E-Mails inklusive Anhänge- Landing Pages mit optionaler Formular-Erfassung, Weiterleitung und Live-Vorschau im Editor
Empfänger
- Gruppen per manueller Eingabe, CSV oder LDAP-Import
Zugang & Sicherheit
- Lokaler Login und optionales OIDC / Single Sign-On
- Zwei-Faktor-Authentifizierung (Authenticator-App oder E-Mail-Code, erzwingbar, Backup-Codes)
- Rollen, Audit-Log, Secrets verschlüsselt at-rest (Argon2id, Fernet)
KI-Unterstützung (Business, anbieter-neutral)
- KI-gestützte Erstellung von Mail-Vorlagen und Landing Pages über eine frei konfigurierbare, OpenAI-kompatible Anbindung (OpenAI, Azure, Mistral, Groq, OpenRouter, Ollama u. a.)
Versand
- Sending Profiles (SMTP je Absender) plus globales Fallback-SMTP — beliebiger Anbieter
| Schicht | Technologie |
|---|---|
| Backend | FastAPI · SQLAlchemy · Alembic |
| Frontend | React · Vite · TypeScript · Tailwind CSS |
| Datenbank / Cache | PostgreSQL · Redis |
| Proxy / TLS | Caddy |
| Betrieb | Docker Compose (rootless, gehärtet) |
Selbstgehostet als Docker-Compose-Stack (PostgreSQL, Redis, FastAPI-Backend, Frontend, Caddy). Die Werte sind Richtwerte für einen einzelnen Host; der Bedarf steigt mit Empfängerzahl, paralleler Nutzung und optionalen Business-Features (PDF-Reports, KI).
| Ressource | Minimum | Empfohlen |
|---|---|---|
| CPU | 2 vCPU | 2–4 vCPU |
| RAM | 2 GB | 4 GB |
| Datenträger | 15 GB SSD | 20–40 GB SSD |
| OS | Linux (x86-64 oder ARM64) mit Docker Engine (≥ 24) + Docker Compose v2 | dito |
- Docker Compose v2 meint das aktuelle, integrierte
docker compose-Plugin (aktuelle Generation, Versionsstände 2.x) — nicht das eingestellte altedocker-composev1. Prüfen mitdocker compose version. - Minimum genügt für kleinere Organisationen (bis einige Hundert Empfänger, gelegentliche Kampagnen).
- Empfohlen gibt Reserve für größere Kampagnen, PDF-Reporting, KI-Funktionen und wachsende Tracking-Daten in PostgreSQL.
- SSD wird für die Datenbank empfohlen; die Tracking-Ereignisse wachsen mit jeder Kampagne.
- Netzwerk: ausgehender SMTP-Zugang (Versand) und Erreichbarkeit der
APP_DOMAINfür die Zielpersonen (Tracking).
Geführt (empfohlen): Die interaktive Installationsroutine führt durch alle wichtigen Einstellungen, generiert Secrets und schreibt eine gültige .env:
git clone https://github.com/HumanShield-Awareness/HumanShield.APP.git
cd HumanShield.APP
./install.shManuell:
git clone https://github.com/HumanShield-Awareness/HumanShield.APP.git
cd HumanShield.APP
cp .env.example .env
# .env ausfüllen: SECRET_KEY, Datenbank, SMTP, INITIAL_ADMIN_*
docker compose up -dDatenbank-Migrationen laufen beim Start automatisch. Anschließend das Dashboard über die konfigurierte Domain (bzw. https://localhost) öffnen und mit dem in .env gesetzten Initial-Admin anmelden.
📌 Tracking-Hinweis: Öffnungen/Klicks entstehen nur, wenn Empfänger die unter
APP_DOMAINgesetzte Adresse erreichen können. Da viele Mail-Clients das Öffnungs-Pixel blockieren, sind Klicks das verlässlichere Signal.
flowchart LR
U[Browser] --> C[Caddy]
C -->|/api, /track| B[FastAPI Backend]
C --> F[React Frontend]
B --> P[(PostgreSQL)]
B --> R[(Redis)]
Caddy leitet /api/* und die öffentlichen Tracking-Endpunkte /track/* an das Backend, alles Übrige an das Frontend.
Sämtliche Einstellungen kommen aus der .env — siehe .env.example für alle Optionen (App, Datenbank, SMTP, OIDC, LDAP, Lizenzierung). Login-, OIDC-, LDAP-, SMTP- und Sicherheitseinstellungen lassen sich zusätzlich im Dashboard verwalten.
- Passwörter mit Argon2id, Laufzeit-Secrets (SMTP/LDAP/OIDC/TOTP) verschlüsselt at-rest (Fernet)
- Zweistufiger Login bei aktivem 2FA, Audit-Log über Anmeldungen und Systemänderungen
- Betreiber-Secrets ausschließlich über
.env, nie im Code
Details im Sicherheits-Wiki. Awareness-Kontext zu NIS2 & BSI im entsprechenden Wiki-Artikel.
Der Kern von HumanShield.APP (alle oben genannten Funktionen) ist unter der Mozilla Public License 2.0 (MPL-2.0) quelloffen und vollständig nutzbar. Zusätzlich gibt es zwei kostenpflichtige Add-ons, die per Lizenz freigeschaltet und als separate, private Pakete ausgeliefert werden.
Business-Add-on
- LDAP-Verzeichnisimport von Empfängern (inkl. LDAPS mit eigenem CA-Zertifikat)
- Azure AD / Entra ID-Import von Empfängern (Microsoft Graph)
- E-Mail-Upload (
.eml) als Vorlagen-Entwurf - Vorlagen-Bibliothek (fertige Awareness-Vorlagen: DHL, Amazon, Rechnung, M365, HR, Bank, PayPal, LinkedIn, PDF-Köder, QR-Kampagne)
- Landing-Page-Bibliothek — passende, klonbare Landing Pages zu jeder Vorlage, direkt im Menü „Landing Pages" verfügbar
- Angriffsarten — Spear-Phishing-, Whaling- (CEO-Fraud) und dateibasierte Vorlagen (Köder-Anhang) in der Bibliothek
- KI-Anbindung — anbieter-neutrale, OpenAI-kompatible Erstellung von Mail-Vorlagen und Landing Pages
- PDF-Export (Management Report & Kampagnen-Ergebnisse)
- QR-Code-Phishing (Quishing) — QR-Codes pro Empfänger
- Webhooks — Event-Trigger (Öffnung/Klick/Submit) an externe Systeme
- Passwortabfrage — abgeschickte Formulardaten erfassen (Passwörter maskiert, nie im Klartext)
- Passkeys (WebAuthn) — phishing-resistente Zwei-Faktor-Authentifizierung
- Business-Reporting — Executive Report (PDF), Trendanalyse und Benutzerentwicklung
- Wiederkehrende Kampagnen — automatischer, terminierter Wiederversand per Scheduler
- Mehrstufige Kampagnen — Kampagnen-Sequenzen (mehrere Stufen mit zeitlichem Abstand)
- Nachweis-Center — je eigenes PDF für DSGVO (Art. 32), NIS2 (Art. 21), ISO 27001 (A.6.3), Awareness-Nachweis, Audit-Bericht, Zertifikat und Schulungsnachweise
Enterprise-Add-on (enthält alle Business-Funktionen)
- White-Label — eigenes Branding (App-Name, Akzentfarben, Logo)
- SAML-SSO — Anmeldung über SAML-2.0-Identity-Provider (signaturgeprüfte Assertions)
- Automatische/Risiko-Kampagnen — Empfänger werden automatisch nach Risiko gewählt und in festem Intervall versendet
- Enterprise-Reporting — Schulungsfortschritt, Zertifikatsstatus und individuelle Berichte je Person (PDF)
- KI-Risikoanalyse — KI-gestützte Auswertung der Human-Risk-Kennzahlen
- SIEM-Export — Tracking-Events an Splunk HEC, Elasticsearch, Microsoft Sentinel oder generisches JSON
Ohne Lizenz läuft die Plattform als reiner Open-Core-Betrieb — ohne Fehler, ohne Sperren.
Ausführliche Anleitungen im Wiki: Installation · Konfiguration · Funktionen · Architektur · FAQ
Beiträge sind willkommen. Bitte für Änderungen einen Branch anlegen, aussagekräftige Commits schreiben und einen Pull Request öffnen (siehe PR-Template).
Der Kern steht unter der Mozilla Public License 2.0 — einer OSI-anerkannten Open-Source-Lizenz mit dateibasiertem Copyleft: frei nutzbar, veränderbar und weiterverteilbar (auch kommerziell und als gehosteter Dienst); Änderungen an MPL-lizenzierten Dateien müssen unter der MPL offengelegt werden. Die kommerziellen Enterprise-Add-ons sind davon getrennt und proprietär. Kontakt für Add-on-Lizenzen: kontakt@humanshield.app.
Ein Projekt von HumanShield-Awareness UG · verantwortungsvoll für autorisierte Awareness-Schulungen einsetzen.