KcMapper

O KcMapper é uma ferramenta para exportar dados de configuração do Keycloak para um banco de dados de grafo Neo4j. Essa representação permite a análise das relações entre realms, clients, usuários, grupos e papéis. A ferramenta inclui uma interface web para executar consultas Cypher pré-definidas para análise e auditoria de segurança.

Recursos

• Exportação Completa: Extrai realms, clients, papéis (incluindo compostos), grupos (com hierarquia), usuários, escopos de client, mappers e fluxos de autenticação.
• Modelagem de Grafo: Representa a configuração do Keycloak como um grafo no Neo4j.
• Análise Interativa: Fornece uma interface web local para executar consultas de análise pré-definidas sobre os dados exportados.
• Auditoria de Segurança: Inclui consultas para ajudar a identificar configurações de segurança potencialmente frágeis.
• Extensível: Consultas de análise personalizadas podem ser adicionadas modificando o arquivo webapp/queries.json.

Instalação e Uso

Este guia cobre a instalação local do KcMapper. Este método exige que você instale Python e Neo4j na sua máquina.

Pré-requisitos

• Python 3.9+
• Uma instância do Neo4j em execução (Community ou Desktop).

Instalação do Neo4j (Exemplo para Debian/Ubuntu)

Você pode instalar o Neo4j Community Edition seguindo estes passos:

# 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

Após a instalação, acesse http://localhost:7474 no seu navegador e defina a senha inicial (o padrão é neo4j/neo4j).

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

• Neo4j Desktop: Esta é a opção mais simples. Baixe e instale o Neo4j Desktop, que fornece uma interface gráfica para gerenciar seus bancos de dados.
• Outras instalações Linux: Siga as instruções oficiais na página de instalação do Neo4j.

Configuração

1. Clone o repositório

   root@kitploit:~

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

2. Configure um ambiente virtual Python (recomendado)

   root@kitploit:~

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

3. Instale as dependências

   root@kitploit:~

   pip install -r requirements.txt
   

4. Configure as variáveis de ambiente Copie o arquivo .env.example para .env.

   root@kitploit:~

   cp .env.example .env
   

   Modifique o arquivo .env para apontar para sua instância do Keycloak e para o seu banco de dados 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 Dados Execute o comando export para popular seu banco de dados Neo4j.

   root@kitploit:~

   python kcmapper_cli.py export
   

   • Para limpar o banco de dados antes de uma nova exportação, use a opção --clean:
     root@kitploit:~

     python kcmapper_cli.py export --clean
     

2. Analisar Dados Após a exportação ser concluída, inicie a interface web de análise.

   root@kitploit:~

   python kcmapper_cli.py analyze
   

   • O servidor estará acessível por padrão em http://127.0.0.1:5001.

Arquitetura

• kcmapper_cli.py: Ponto de entrada principal da linha de comando.
• /processors: Contém a lógica de extração e carregamento para cada tipo de objeto do Keycloak.
• /utils: Funções utilitárias, principalmente para conexão com o Neo4j e limpeza de dados.
• /webapp: Contém o aplicativo web Flask para análise de dados.

Contribuindo

Contribuições são bem-vindas. Sinta-se à vontade para abrir uma issue para relatar um bug ou sugerir um novo recurso. Para adicionar novas consultas de análise, modifique o arquivo webapp/queries.json e envie um pull request.

Licença

Este projeto é licenciado sob a Licença MIT. Consulte o arquivo LICENSE para obter detalhes.