KcMapper

KcMapper 是一个将 Keycloak 配置数据导出到 Neo4j 图数据库的工具。这种表示方式允许分析 realm、客户端、用户、组和角色之间的关系。该工具包含一个 Web 界面，用于运行预定义的 Cypher 查询以进行分析和安全审计。

功能特性

• 完全导出：提取 realm、客户端、角色（包括复合角色）、组（含层级结构）、用户、客户端 scope、映射器和身份验证流程。
• 图建模：将 Keycloak 配置表示为 Neo4j 中的图。
• 交互式分析：提供本地 Web 界面，用于对导出的数据执行预定义的分析查询。
• 安全审计：包含有助于识别潜在薄弱安全配置的查询。
• 可扩展：可通过修改 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. 分析数据 导出完成后，启动 Web 分析界面。

   root@kitploit:~

   python kcmapper_cli.py analyze
   

   • 服务器默认可通过 http://127.0.0.1:5001 访问。

架构

• kcmapper_cli.py：主要命令行入口点。
• /processors：包含每种 Keycloak 对象类型的提取和加载逻辑。
• /utils：工具函数，主要用于 Neo4j 连接和数据清理。
• /webapp：包含用于数据分析的 Flask Web 应用程序。

贡献

欢迎贡献。请随时提出问题（issue）以报告错误或建议新功能。要添加新的分析查询，请修改 webapp/queries.json 文件并提交拉取请求（pull request）。

许可证

本项目基于 MIT 许可证授权。详情请参阅 LICENSE 文件。