KcMapper

KcMapper는 Keycloak 구성 데이터를 Neo4j 그래프 데이터베이스로 내보내기 위한 도구입니다. 이러한 표현을 통해 realm, 클라이언트, 사용자, 그룹 및 역할 간의 관계를 분석할 수 있습니다. 이 도구에는 분석 및 보안 감사를 위해 사전 정의된 Cypher 쿼리를 실행할 수 있는 웹 인터페이스가 포함되어 있습니다.

기능

• 전체 내보내기: Realm, 클라이언트, 역할(복합 역할 포함), 그룹(계층 구조 포함), 사용자, 클라이언트 scope, 매퍼 및 인증 흐름을 추출합니다.
• 그래프 모델링: 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 웹 애플리케이션을 포함합니다.

기여

기여는 환영합니다. 버그를 신고하거나 새 기능을 제안하려면 이슈를 열어 주세요. 새 분석 쿼리를 추가하려면 webapp/queries.json 파일을 수정하고 풀 리퀘스트를 제출하세요.

라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.