Vulnhalla

자동화된 CodeQL 분석 및 LLM 분류

Vulnhalla의 연구 배경 및 동기에 대한 자세한 개요는 공식 CyberArk 위협 연구 블로그 게시물을 참조하십시오:

Vulnhalla: Picking the True Vulnerabilities from the CodeQL Haystack

Vulnhalla는 전체 보안 분석 파이프라인을 자동화합니다:

1. GitHub에서 특정 프로그래밍 언어의 레포지토리를 가져오기
2. 해당 CodeQL 데이터베이스를 다운로드 (가능한 경우)
3. 보안 또는 코드 품질 문제를 탐지하기 위해 해당 데이터베이스에서 CodeQL 쿼리 실행
4. LLM(ChatGPT, Gemini 등)으로 결과를 후처리하여 문제 분류 및 필터링

🚀 빠른 시작

1단계: 사전 요구 사항

시작하기 전에 다음이 필요합니다:

• Python 3.10 – 3.13 (Python 3.11 또는 3.12 권장)

  • Python 3.14+는 지원되지 않습니다 (이 도구는 Python 3.14+에서 지원되지 않는 grpcio를 사용합니다)
  • python.org에서 다운로드

• CodeQL CLI

  • CodeQL CLI 릴리스에서 다운로드
  • PATH에 codeql이 있는지 확인하거나, .env에서 경로를 설정합니다 (2단계 참조)

• (선택 사항) GitHub API 토큰

  • 데이터베이스 다운로드 시 더 높은 속도 제한을 위해 필요
  • GitHub 설정 > 토큰에서 가져오기

• LLM API 키

  • 공급자에 따라 OpenAI, Azure, Gemini 또는 Bedrock 자격 증명

2단계: 환경 구성

모든 구성은 단일 파일 .env에 있습니다.

1. 레포지토리를 클론합니다:

git clone https://github.com/cyberark/Vulnhalla
cd Vulnhalla

2. .env.example을 .env로 복사합니다:

cp .env.example .env # macOS / Linux
Copy-Item .env.example .env # Windows (PowerShell)

3. .env를 편집하고 값을 입력합니다:

OpenAI 예시:

CODEQL_PATH=codeql
GITHUB_TOKEN=ghp_your_token_here
PROVIDER=openai
MODEL=gpt-4o
OPENAI_API_KEY=your-api-key-here
LLM_TEMPERATURE=0.2
LLM_TOP_P=0.2

# 선택 사항: 로깅 구성
LOG_LEVEL=INFO                  # DEBUG, INFO, WARNING, ERROR
LOG_FILE=                       # 선택 사항: 로그 파일 경로 (예: logs/vulnhalla.log)
LOG_FORMAT=default              # default 또는 json
# LOG_VERBOSE_CONSOLE=false     # true인 경우 WARNING/ERROR에 전체 형식 사용 (timestamp - logger - level - message)

📖 전체 구성 참조는: 아래 구성 참조에서 지원되는 모든 공급자(OpenAI, Azure, Gemini, Bedrock), 필수/선택 변수 및 자세한 예시를 확인하세요.

3단계: Poetry 설치 (권장: pipx)

Windows (PowerShell):

# 사용 가능한 Python 버전 나열
py -0p

# 지원되는 Python 중 선택: 3.10 / 3.11 / 3.12 / 3.13
py -3.12 -m pip install --user -U pipx
py -3.12 -m pipx ensurepath
# 터미널을 닫고 다시 엽니다 (필수)
pipx install poetry
poetry --version

macOS / Linux:

# Python 버전 확인
python3 --version

# 지원되는 Python 중 사용: 3.10 / 3.11 / 3.12 / 3.13
python3 -m pip install --user -U pipx
python3 -m pipx ensurepath
# 터미널 재시작 (필수)
pipx install poetry
poetry --version

4단계: 종속성 설치 및 설정

Windows (PowerShell):

# 설치된 지원 버전 중 하나 선택: 3.10 / 3.11 / 3.12 / 3.13
poetry env use 3.12  # 여러 버전이 설치된 경우 지원되는 Python 버전을 강제로 사용
poetry install
poetry run vulnhalla-setup

macOS / Linux:

# 설치된 지원 버전 중 하나 선택: 3.10 / 3.11 / 3.12 / 3.13
poetry env use 3.12  # 여러 버전이 설치된 경우 지원되는 Python 버전을 강제로 사용
poetry install
poetry run vulnhalla-setup

5단계: 파이프라인 실행

# 특정 레포지토리 분석, 예:
poetry run vulnhalla redis/redis

# 데이터베이스가 이미 존재해도 다시 다운로드
poetry run vulnhalla redis/redis --force

# 도움말 보기
poetry run vulnhalla --help

이렇게 하면 자동으로:

1. CodeQL 데이터베이스 가져오기
2. 다운로드된 모든 데이터베이스에서 CodeQL 쿼리 실행
3. LLM으로 결과를 분석하고 output/results/에 저장
4. UI를 열어 결과 탐색

로컬 CodeQL 데이터베이스 사용

이미 디스크에 CodeQL 데이터베이스가 있는 경우 (예: 수동으로 생성 또는 이전 실행에서), --local / -l 플래그를 사용하여 GitHub 가져오기 단계를 건너뛸 수 있습니다.

Windows (PowerShell):

poetry run vulnhalla --local C:\path\to\my-codeql-db

macOS / Linux:

poetry run vulnhalla --local /path/to/my-codeql-db

참고: --local 플래그는 소스 코드 폴더가 아닌 CodeQL 데이터베이스 디렉터리를 필요로 합니다. 폴더에 codeql-database.yml 파일이 있는지 확인하여 확인할 수 있습니다.

추가 명령어

# 분석 실행 없이 기존 결과 보기 위해 UI 열기
poetry run vulnhalla-ui

# 구성 유효성 검사: CodeQL, LLM, 로깅 (분석 실행 없이)
poetry run vulnhalla-validate

# 분석된 레포지토리 및 문제 수 나열
poetry run vulnhalla-list

# 예제 파이프라인 실행 (videolan/vlc 및 redis/redis 분석)
poetry run vulnhalla-example

🖥️ 사용자 인터페이스 (UI)

Vulnhalla는 분석 결과를 탐색하고 살펴보기 위한 완전한 기능의 사용자 인터페이스를 포함합니다.

UI 실행

poetry run vulnhalla-ui

UI 레이아웃

UI는 두 개의 패널 상단 영역과 하단 컨트롤 막대로 구성됩니다.

상단 영역 (좌우 나란히, 크기 조절 가능):

• 왼쪽 패널 (문제 목록):

  • ID, Repo, Issue Name, File, LLM decision, Manual decision을 표시하는 DataTable
  • 문제 수 및 정렬 표시기
  • 하단의 검색 입력 상자, 입력 시 업데이트 (대소문자 구분 안 함)

• 오른쪽 패널 (세부 정보):

  • LLM 결정 섹션: LLM의 분류 표시 (True Positive, False Positive, 또는 Needs More Data)
  • 메타데이터 섹션: Issue name, Repo, File, Line, Type, Function name
  • 코드 섹션:
    • 📌 초기 코드 컨텍스트 (LLM이 처음 본 코드 스니펫)
    • 📥 추가 코드 (LLM이 대화 중 요청한 코드) - 추가 코드가 있는 경우에만 표시
    • 취약한 줄이 빨간색으로 강조 표시
  • 요약 섹션: LLM 최종 답변/결정
  • 수동 결정 선택: 수동 판정을 설정하는 하단 드롭다운 (True Positive, False Positive, Uncertain, 또는 Not Set)

하단 컨트롤 막대:

• 언어: C (현재 지원되는 유일한 언어)
• LLM 결정별 필터 드롭다운: All, True Positive, False Positive, Needs more Info to decide
• 액션 버튼: Refresh, Run Analysis
• 키 바인딩 도움말 텍스트

키 바인딩

• ↑/↓ - 문제 목록 탐색 (행별)
• Tab / Shift+Tab - 패널 간 포커스 전환
• Enter - 선택한 문제의 세부 정보 표시
• / - 검색 입력 상자에 포커스 (왼쪽 패널)
• Esc - 검색 지우고 문제 테이블로 포커스 복귀
• r - 디스크에서 결과 다시 로드
• [ / ] - 왼쪽/오른쪽 패널 크기 조정 (분할 위치 조정)
• q - 애플리케이션 종료

대화형 기능

열 정렬

• 열 헤더를 클릭하면 해당 열로 정렬
• 기본 정렬: Repo (오름차순), 그 다음 ID (오름차순)

크기 조절 가능한 패널

• 드래그 가능한 구분선 문제 목록과 세부 정보 패널 사이
• 마우스: 구분선을 클릭하고 드래그하여 크기 조절
• 키보드: [를 사용하여 구분선을 왼쪽으로, ]를 사용하여 오른쪽으로 이동
• 분할 위치는 세션 동안 유지됩니다

📊 출력 구조

파이프라인 실행 후 결과는 output/results/<LANG>/<ISSUE_TYPE>/에 정리됩니다:

output/results/c/Copy_function_using_source_size/
├── 1_raw.json      # 원본 CodeQL 문제 데이터
├── 1_final.json    # LLM 대화 및 분류
├── 2_raw.json
├── 2_final.json
└── ...

각 *_final.json 파일에는 다음이 포함됩니다:

• 전체 LLM 대화 (시스템 프롬프트, 사용자 메시지, 어시스턴트 응답, 도구 호출)
• 최종 상태 코드 (1337 = 취약, 1007 = 안전, 7331/3713 = 추가 정보 필요)

각 *_raw.json 파일에는 다음이 포함됩니다:

• 원본 CodeQL 문제 데이터
• 함수 컨텍스트
• 데이터베이스 경로 (org/repo 정보 포함: output/databases/<LANG>/<ORG>/<REPO>)
• 문제 위치

🛠 문제 해결

• CodeQL CLI를 찾을 수 없음: .env 파일의 CODEQL_PATH에 CodeQL 실행 파일의 전체 경로를 설정하십시오. Windows에서: 경로는 .cmd로 끝나야 합니다 (예: C:\path\to\codeql\codeql.cmd).

• GitHub 속도 제한: .env 파일의 GITHUB_TOKEN을 설정하십시오 (토큰은 https://github.com/settings/tokens에서 가져오기).

• LLM 문제: .env 파일의 API 키가 선택한 공급자와 일치하는지 확인하십시오.

• UI에서 가져오기 오류: 프로젝트 루트 디렉터리에서 실행 중인지 확인하거나, 경로 설정을 처리하는 python examples/ui_example.py를 사용하십시오.

⚙️ 구성 참조

환경 변수

모든 구성은 .env 파일의 환경 변수를 통해 관리됩니다. 전체 참조는 다음과 같습니다:

필수 변수

공급자별 필수 변수

OpenAI:

Azure OpenAI:

Gemini (Google):

AWS Bedrock:

* 인증: AWS_PROFILE 또는 AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY (+ 선택적 AWS_SESSION_TOKEN for STS)를 사용하십시오.

Bedrock .env 예시 (SSO):

PROVIDER=bedrock
MODEL=anthropic.claude-3-5-sonnet-20241022-v2:0
AWS_REGION_NAME=us-east-1
AWS_PROFILE=your-profile

⚠️ 사전 요구 사항:

• Bedrock 모델을 호출할 수 있는 권한이 있는 AWS 자격 증명(SSO, IAM 프로필 또는 액세스 키)이 구성되어 있어야 합니다.
• SSO 사용자의 경우: Vulnhalla를 사용하기 전에 aws sso login --profile your-profile을 실행하십시오.

🔧 중요 - 모델 선택: Bedrock 모델을 선택할 때 도구 호출/함수 호출을 지원하는지 확인하십시오 (모든 Bedrock 모델이 지원하는 것은 아닙니다). 도구 호출은 Vulnhalla 분석 흐름의 핵심 부분이므로 호환 가능한 모델을 선택하면 기능과 결과에 큰 차이가 있습니다. 호환 가능한 모델은 Claude 3.x, Mistral 또는 Cohere Command R을 포함합니다.

선택적 변수

⚠️ 중요: LLM_TEMPERATURE 또는 LLM_TOP_P를 영향을 완전히 이해하지 않고는 증가시키지 마십시오. 낮은 값은 모델을 안정적이고 결정적으로 유지하며, 이는 보안 분석에 중요합니다. 높은 값은 모델이 일관성이 없어지거나 창의적이 되거나 결과를 환각(hallucinate)할 수 있습니다.

📝 참고: 추가 구성 예시는 프로젝트 루트의 .env.example 파일을 참조하십시오.

구성 유효성 검사

Vulnhalla는 시작 시 구성을 검증합니다. 필수 변수가 누락되거나 잘못된 경우 수정해야 할 사항을 나타내는 명확한 오류 메시지가 표시됩니다.

일반적인 유효성 검사 오류:

• 선택한 공급자에 대한 API 키 누락
• 잘못된 공급자 이름 (지원되는 값은 PROVIDER 참조)
• Azure 엔드포인트 누락 (Azure 공급자에 필요)
• AWS 자격 증명 또는 리전 누락 (Bedrock 공급자에 필요)
• 잘못된 CodeQL 경로 (CODEQL_PATH가 설정되었지만 파일이 존재하지 않는 경우)

📝 상태 코드

LLM은 다음 상태 코드를 사용합니다:

• 1337: 보안 취약점 발견 (True Positive)
• 1007: 코드가 안전함, 취약점 없음 (False Positive)
• 7331: 보안을 검증하기 위해 더 많은 코드/정보 필요
• 3713: 보안 문제일 가능성이 낮지만 추가 정보 필요 (7331과 함께 사용)

UI는 이를 다음과 같이 매핑합니다:

• 1337 → "True Positive"
• 1007 → "False Positive"
• 7331 또는 3713 → "Needs More Data"

🔧 개발

테스트 실행

이 프로젝트는 pytest를 사용한 기본 테스트 인프라를 포함합니다:

# 모든 테스트 실행
poetry run pytest

# 상세 출력으로 실행
poetry run pytest -v

테스트 스위트에는 테스트 인프라가 올바르게 설정되었는지 확인하는 smoke 테스트가 포함되어 있습니다.

타입 검사

이 프로젝트는 mypy를 사용한 정적 타입 검사를 사용합니다:

poetry run mypy src

타입 검사는 pyproject.toml의 [tool.mypy]에서 구성됩니다. 구성은 점진적 적용을 허용하기 위해 모듈별 재정의가 있는 보수적인 기준선을 사용합니다.

프로젝트 종속성

종속성은 pyproject.toml의 Poetry를 통해 관리됩니다:

• requests - GitHub API용 HTTP 요청
• pySmartDL - CodeQL 데이터베이스용 스마트 다운로드 관리자
• litellm - 여러 공급자를 지원하는 통합 LLM 인터페이스
• python-dotenv - 환경 변수 관리
• PyYAML - CodeQL 팩 파일용 YAML 파싱
• textual - 터미널 UI 프레임워크
• pytest - 테스트 프레임워크 (개발 종속성)
• mypy - 정적 타입 검사기 (개발 종속성)

CodeQL 쿼리

CodeQL 쿼리는 data/queries/<LANG>/에 구성되어 있습니다:

• issues/ - 보안 문제 탐지 쿼리
• tools/ - 도우미 쿼리 (함수 트리, 클래스, 전역 변수, 매크로)

각 디렉터리에는 CodeQL 팩을 정의하는 qlpack.yml 파일이 포함되어 있습니다.

📄 라이선스

Copyright (c) 2025 CyberArk Software Ltd. All rights reserved.

이 저장소는 Apache License, Version 2.0에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE.txt를 참조하십시오.

🤝 기여

모든 종류의 기여를 환영합니다. 시작하는 방법과 개발 워크플로에 대한 설명은 기여 가이드를 참조하십시오.

행동 강령

행동 강령을 읽고 준수해 주십시오. 모든 기여자에게 환영하고 포용적인 환경을 제공하기 위해 최선을 다하고 있습니다.

📧 연락처

기능 요청이나 프로젝트 문제가 있는 경우 GitHub 이슈를 통해 자유롭게 문의해 주십시오.