KcMapper

KcMapper è uno strumento per esportare i dati di configurazione di Keycloak in un database a grafi Neo4j. Questa rappresentazione consente l'analisi delle relazioni tra realm, client, utenti, gruppi e ruoli. Lo strumento include un'interfaccia web per eseguire query Cypher predefinite per analisi e audit di sicurezza.

Funzionalità

• Esportazione Completa: Estrae realm, client, ruoli (inclusi quelli compositi), gruppi (con gerarchia), utenti, client scope, mapper e flussi di autenticazione.
• Modellazione a Grafi: Rappresenta la configurazione di Keycloak come un grafo in Neo4j.
• Analisi Interattiva: Fornisce un'interfaccia web locale per eseguire query di analisi predefinite sui dati esportati.
• Audit di Sicurezza: Include query per aiutare a identificare configurazioni di sicurezza potenzialmente deboli.
• Estendibile: È possibile aggiungere query di analisi personalizzate modificando il file webapp/queries.json.

Installazione e Utilizzo

Questa guida copre l'installazione locale di KcMapper. Questo metodo richiede di installare Python e Neo4j sulla propria macchina.

Prerequisiti

• Python 3.9+
• Un'istanza Neo4j in esecuzione (Community o Desktop).

Installazione di Neo4j (Esempio per Debian/Ubuntu)

È possibile installare Neo4j Community Edition seguendo questi passaggi:

# 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

Dopo l'installazione, apri http://localhost:7474 nel browser e imposta la password iniziale (quella predefinita è neo4j/neo4j).

Per altri sistemi (Windows, macOS, ecc.):

• Neo4j Desktop: È l'opzione più semplice. Scarica e installa Neo4j Desktop, che fornisce un'interfaccia grafica per la gestione dei tuoi database.
• Altre installazioni Linux: Segui le istruzioni ufficiali nella pagina di installazione di Neo4j.

Configurazione

1. Clona il repository

   root@kitploit:~

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

2. Configura un ambiente virtuale Python (consigliato)

   root@kitploit:~

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

3. Installa le dipendenze

   root@kitploit:~

   pip install -r requirements.txt
   

4. Configura le variabili d'ambiente Copia il file .env.example in .env.

   root@kitploit:~

   cp .env.example .env
   

   Modifica il file .env per puntare alla tua istanza Keycloak e al tuo database Neo4j locale.

   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
   

Utilizzo

1. Esporta i Dati Esegui il comando export per popolare il tuo database Neo4j.

   root@kitploit:~

   python kcmapper_cli.py export
   

   • Per pulire il database prima di una nuova esportazione, usa l'opzione --clean:
     root@kitploit:~

     python kcmapper_cli.py export --clean
     

2. Analizza i Dati Una volta completata l'esportazione, avvia l'interfaccia web di analisi.

   root@kitploit:~

   python kcmapper_cli.py analyze
   

   • Il server sarà accessibile per impostazione predefinita all'indirizzo http://127.0.0.1:5001.

Architettura

• kcmapper_cli.py: Punto di ingresso principale da riga di comando.
• /processors: Contiene la logica di estrazione e caricamento per ogni tipo di oggetto Keycloak.
• /utils: Funzioni di utilità, principalmente per la connessione a Neo4j e la pulizia dei dati.
• /webapp: Contiene l'applicazione web Flask per l'analisi dei dati.

Contributi

I contributi sono benvenuti. Non esitare ad aprire un issue per segnalare un bug o suggerire una nuova funzionalità. Per aggiungere nuove query di analisi, modifica il file webapp/queries.json e invia una pull request.

Licenza

Questo progetto è concesso in licenza sotto la MIT License. Vedi il file LICENSE per i dettagli.