KcMapper

KcMapper — это инструмент для экспорта конфигурационных данных Keycloak в графовую базу данных Neo4j. Такое представление позволяет анализировать взаимосвязи между realm'ами, клиентами, пользователями, группами и ролями. Инструмент включает веб-интерфейс для выполнения предопределённых Cypher-запросов с целью анализа и аудита безопасности.

Возможности

• Полный экспорт: Извлекает realm'ы, клиентов, роли (включая композитные), группы (с иерархией), пользователей, клиентские скоупы, мапперы и потоки аутентификации.
• Моделирование графа: Представляет конфигурацию Keycloak в виде графа в Neo4j.
• Интерактивный анализ: Предоставляет локальный веб-интерфейс для выполнения предопределённых аналитических запросов по экспортированным данным.
• Аудит безопасности: Включает запросы, помогающие выявить потенциально слабые конфигурации безопасности.
• Расширяемость: Пользовательские аналитические запросы можно добавлять, изменяя файл webapp/queries.json.

Установка и использование

В этом руководстве рассматривается локальная установка KcMapper. Этот способ требует установки Python и Neo4j на вашем компьютере.

Предварительные требования

• Python 3.9+
• Запущенный экземпляр Neo4j (Community или Desktop).

Установка Neo4j (пример для Debian/Ubuntu)

Вы можете установить Neo4j Community Edition, выполнив следующие шаги:

# 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

После установки перейдите в браузере по адресу http://localhost:7474 и задайте начальный пароль (по умолчанию используется neo4j/neo4j).

Для других систем (Windows, macOS и т. д.):

• Neo4j Desktop: Это самый простой вариант. Загрузите и установите Neo4j Desktop, который предоставляет графический интерфейс для управления вашими базами данных.
• Другие дистрибутивы Linux: Следуйте официальным инструкциям на странице установки Neo4j.

Конфигурация

1. Клонируйте репозиторий

   root@kitploit:~

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

2. Создайте виртуальное окружение Python (рекомендуется)

   root@kitploit:~

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

3. Установите зависимости

   root@kitploit:~

   pip install -r requirements.txt
   

4. Настройте переменные окружения Скопируйте файл .env.example в .env.

   root@kitploit:~

   cp .env.example .env
   

   Измените файл .env, указав ваш экземпляр Keycloak и вашу локальную базу данных Neo4j.

   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
   

Использование

1. Экспорт данных Выполните команду export, чтобы заполнить вашу базу данных Neo4j.

   root@kitploit:~

   python kcmapper_cli.py export
   

   • Чтобы очистить базу данных перед новым экспортом, используйте опцию --clean:
     root@kitploit:~

     python kcmapper_cli.py export --clean
     

2. Анализ данных После завершения экспорта запустите веб-интерфейс анализа.

   root@kitploit:~

   python kcmapper_cli.py analyze
   

   • Сервер будет доступен по умолчанию по адресу http://127.0.0.1:5001.

Архитектура

• kcmapper_cli.py: Основная точка входа командной строки.
• /processors: Содержит логику извлечения и загрузки для каждого типа объектов Keycloak.
• /utils: Вспомогательные функции, в основном для подключения к Neo4j и очистки данных.
• /webapp: Содержит веб-приложение Flask для анализа данных.

Участие в разработке

Вклад приветствуется. Пожалуйста, не стесняйтесь открывать issue, чтобы сообщить об ошибке или предложить новую функцию. Чтобы добавить новые аналитические запросы, измените файл webapp/queries.json и отправьте pull request.

Лицензия

Этот проект лицензирован по лицензии MIT. Подробности см. в файле LICENSE.