KcMapper

KcMapper ist ein Werkzeug zum Exportieren von Keycloak-Konfigurationsdaten in eine Neo4j-Graphdatenbank. Diese Darstellung ermöglicht die Analyse der Beziehungen zwischen Realms, Clients, Benutzern, Gruppen und Rollen. Das Tool enthält eine Weboberfläche zum Ausführen vordefinierter Cypher-Abfragen für Analyse und Sicherheitsaudits.

Features

• Vollständiger Export: Extrahiert Realms, Clients, Rollen (einschließlich Composite-Rollen), Gruppen (mit Hierarchie), Benutzer, Client-Scopes, Mapper und Authentifizierungsabläufe.
• Graphenmodellierung: Stellt die Keycloak-Konfiguration als Graph in Neo4j dar.
• Interaktive Analyse: Bietet eine lokale Weboberfläche zum Ausführen vordefinierter Analyseabfragen auf den exportierten Daten.
• Sicherheitsaudit: Enthält Abfragen, die dabei helfen, potenziell schwache Sicherheitskonfigurationen zu identifizieren.
• Erweiterbar: Benutzerdefinierte Analyseabfragen können durch Änderung der Datei webapp/queries.json hinzugefügt werden.

Installation und Verwendung

Dieser Leitfaden behandelt die lokale Installation von KcMapper. Diese Methode erfordert, dass Sie Python und Neo4j auf Ihrem Rechner installieren.

Voraussetzungen

• Python 3.9+
• Eine laufende Neo4j-Instanz (Community oder Desktop).

Neo4j-Installation (Beispiel für Debian/Ubuntu)

Sie können Neo4j Community Edition mit den folgenden Schritten installieren:

# Add the Neo4j GPG key
wget -O - https://debian.neo4j.com/neotechnology.gpg.key | sudo apt-key add -

# Add the Neo4j repository
echo 'deb https://debian.neo4j.com stable 5' | sudo tee /etc/apt/sources.list.d/neo4j.list

# Update packages and install Neo4j
sudo apt-get update
sudo apt-get install neo4j -y

# Start the Neo4j service
sudo systemctl start neo4j

Nach der Installation öffnen Sie http://localhost:7474 in Ihrem Browser und legen Sie das anfängliche Passwort fest (Standard ist neo4j/neo4j).

Für andere Systeme (Windows, macOS usw.):

• Neo4j Desktop: Dies ist die einfachste Option. Laden Sie Neo4j Desktop herunter und installieren Sie es. Es bietet eine grafische Oberfläche zur Verwaltung Ihrer Datenbanken.
• Andere Linux-Installationen: Folgen Sie den offiziellen Anweisungen auf der Neo4j-Installationsseite.

Konfiguration

1. Klonen Sie das Repository

   root@kitploit:~

   git clone https://github.com/synacktiv/kcmapper.git
   cd kcmapper
   

2. Richten Sie eine virtuelle Python-Umgebung ein (empfohlen)

   root@kitploit:~

   python -m venv venv
   source venv/bin/activate  # On Windows, use `venv\Scripts\activate`
   

3. Abhängigkeiten installieren

   root@kitploit:~

   pip install -r requirements.txt
   

4. Umgebungsvariablen konfigurieren Kopieren Sie die Datei .env.example nach .env.

   root@kitploit:~

   cp .env.example .env
   

   Ändern Sie die Datei .env, sodass sie auf Ihre Keycloak-Instanz und Ihre lokale Neo4j-Datenbank verweist.

   root@kitploit:~

   # --- Keycloak Connection ---
   KEYCLOAK_URL=http://your-keycloak-server:8080/
   KEYCLOAK_USER=admin
   KEYCLOAK_PASSWORD=your_keycloak_admin_password
   # Optional - for confidential clients
   KEYCLOAK_CLIENT_SECRET=
   # Optional - for users with 2FA enabled
   KEYCLOAK_TOTP=
   # Optional - for mTLS authentication
   KEYCLOAK_CERT_PATH=
   
   # --- Neo4j Connection (for local environment) ---
   NEO4J_URI=bolt://localhost:7687
   NEO4J_USER=neo4j
   NEO4J_PASSWORD=your_local_neo4j_password
   

Verwendung

1. Daten exportieren Führen Sie den Befehl export aus, um Ihre Neo4j-Datenbank zu befüllen.

   root@kitploit:~

   python kcmapper_cli.py export
   

   • Um die Datenbank vor einem neuen Export zu bereinigen, verwenden Sie die Option --clean:
     root@kitploit:~

     python kcmapper_cli.py export --clean
     

2. Daten analysieren Sobald der Export abgeschlossen ist, starten Sie die Web-Analyseoberfläche.

   root@kitploit:~

   python kcmapper_cli.py analyze
   

   • Der Server ist standardmäßig unter http://127.0.0.1:5001 erreichbar.

Architektur

• kcmapper_cli.py: Haupt-Einstiegspunkt für die Befehlszeile.
• /processors: Enthält die Extraktions- und Ladungslogik für jeden Keycloak-Objekttyp.
• /utils: Hilfsfunktionen, hauptsächlich für die Neo4j-Verbindung und Datenbereinigung.
• /webapp: Enthält die Flask-Webanwendung zur Datenanalyse.

Mitwirken

Beiträge sind willkommen. Eröffnen Sie gerne ein Issue, um einen Fehler zu melden oder eine neue Funktion vorzuschlagen. Um neue Analyseabfragen hinzuzufügen, ändern Sie die Datei webapp/queries.json und reichen Sie einen Pull-Request ein.

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert. Weitere Details finden Sie in der Datei LICENSE.