KcMapper

KcMapper es una herramienta para exportar los datos de configuración de Keycloak a una base de datos de grafos Neo4j. Esta representación permite analizar las relaciones entre realms, clientes, usuarios, grupos y roles. La herramienta incluye una interfaz web para ejecutar consultas Cypher predefinidas para análisis y auditoría de seguridad.

Características

• Exportación completa: Extrae realms, clientes, roles (incluidos los compuestos), grupos (con jerarquía), usuarios, ámbitos de cliente (client scopes), mapeadores y flujos de autenticación.
• Modelado de grafos: Representa la configuración de Keycloak como un grafo en Neo4j.
• Análisis interactivo: Proporciona una interfaz web local para ejecutar consultas de análisis predefinidas sobre los datos exportados.
• Auditoría de seguridad: Incluye consultas para ayudar a identificar configuraciones de seguridad potencialmente débiles.
• Extensible: Se pueden añadir consultas de análisis personalizadas modificando el archivo webapp/queries.json.

Instalación y Uso

Esta guía cubre la instalación local de KcMapper. Este método requiere que instales Python y Neo4j en tu máquina.

Prerrequisitos

• Python 3.9+
• Una instancia de Neo4j en ejecución (Community o Desktop).

Instalación de Neo4j (Ejemplo para Debian/Ubuntu)

Puedes instalar Neo4j Community Edition siguiendo estos pasos:

# 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

Después de la instalación, navega a http://localhost:7474 en tu navegador y establece la contraseña inicial (la predeterminada es neo4j/neo4j).

Para otros sistemas (Windows, macOS, etc.):

• Neo4j Desktop: Esta es la opción más sencilla. Descarga e instala Neo4j Desktop, que proporciona una interfaz gráfica para gestionar tus bases de datos.
• Otras instalaciones de Linux: Sigue las instrucciones oficiales en la página de instalación de Neo4j.

Configuración

1. Clonar el repositorio

   root@kitploit:~

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

2. Crear un entorno virtual de Python (recomendado)

   root@kitploit:~

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

3. Instalar las dependencias

   root@kitploit:~

   pip install -r requirements.txt
   

4. Configurar las variables de entorno Copia el archivo .env.example a .env.

   root@kitploit:~

   cp .env.example .env
   

   Modifica el archivo .env para que apunte a tu instancia de Keycloak y a tu base de datos Neo4j local.

   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
   

Uso

1. Exportar datos Ejecuta el comando export para poblar tu base de datos Neo4j.

   root@kitploit:~

   python kcmapper_cli.py export
   

   • Para limpiar la base de datos antes de una nueva exportación, usa la opción --clean:
     root@kitploit:~

     python kcmapper_cli.py export --clean
     

2. Analizar datos Una vez completada la exportación, lanza la interfaz web de análisis.

   root@kitploit:~

   python kcmapper_cli.py analyze
   

   • El servidor será accesible por defecto en http://127.0.0.1:5001.

Arquitectura

• kcmapper_cli.py: Punto de entrada principal de la línea de comandos.
• /processors: Contiene la lógica de extracción y carga para cada tipo de objeto de Keycloak.
• /utils: Funciones de utilidad, principalmente para la conexión a Neo4j y la limpieza de datos.
• /webapp: Contiene la aplicación web Flask para el análisis de datos.

Contribuciones

Las contribuciones son bienvenidas. No dudes en abrir un issue para reportar un bug o sugerir una nueva funcionalidad. Para añadir nuevas consultas de análisis, modifica el archivo webapp/queries.json y envía una pull request.

Licencia

Este proyecto está licenciado bajo la Licencia MIT. Consulta el archivo LICENSE para más detalles.