KcMapper

KcMapper は、Keycloak の設定データを Neo4j グラフデータベースにエクスポートするためのツールです。この表現により、レルム、クライアント、ユーザー、グループ、ロール間の関係を分析できます。このツールには、分析とセキュリティ監査のための定義済み Cypher クエリを実行する Web インターフェースが含まれています。

特徴

• 完全なエクスポート: レルム、クライアント、ロール（コンポジットを含む）、グループ（階層を含む）、ユーザー、クライアントスコープ、マッパー、認証フローを抽出します。
• グラフモデリング: 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
   

   自分の Keycloak インスタンスとローカルの Neo4j データベースを指すように .env ファイルを変更します。

   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 ファイルを変更し、プルリクエストを送信してください。

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細については、LICENSE ファイルを参照してください。