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 파일의 환경 변수를 통해 관리됩니다. 전체 참조는 다음과 같습니다:

필수 변수

변수	필수 대상	설명
CODEQL_PATH	모든 사용자	CodeQL 실행 파일 경로. CodeQL이 PATH에 있으면 기본값은 codeql입니다. PATH에 없으면 전체 경로를 사용하십시오 (Windows의 경우 예: C:\path\to\codeql\codeql.cmd)
PROVIDER	모든 사용자	LLM 공급자: openai, azure, gemini, bedrock, anthropic, mistral, groq, openrouter, ollama 등
MODEL	모든 사용자	모델 이름 (예: gpt-4o, gpt-4-turbo, gemini-2.5-flash)

공급자별 필수 변수

OpenAI:

변수	설명
OPENAI_API_KEY	platform.openai.com에서 얻은 OpenAI API 키

Azure OpenAI:

변수	설명
AZURE_OPENAI_API_KEY 또는 AZURE_API_KEY	Azure OpenAI API 키
AZURE_OPENAI_ENDPOINT 또는 AZURE_API_BASE	Azure OpenAI 엔드포인트 URL (예: https://your-resource.openai.azure.com)
AZURE_OPENAI_API_VERSION 또는 AZURE_API_VERSION	API 버전 (기본값: 2024-08-01-preview)

Gemini (Google):

변수	설명
GOOGLE_API_KEY	Google AI Studio에서 얻은 Google API 키