CodeQL

CodeQL은 시맨틱 쿼리와 시맨틱 분석을 사용하여 보안 취약점과 코드 품질 문제를 찾기 위한 GitHub의 정적 분석 도구입니다.

설치

macOS

# Homebrew installation
brew install codeql

# Manual download
wget https://github.com/github/codeql-cli-releases/releases/download/v2.16.0/codeql-osx64.zip
unzip codeql-osx64.zip
export PATH=$PATH:$HOME/codeql

Linux

# Ubuntu/Debian
wget https://github.com/github/codeql-cli-releases/releases/download/v2.16.0/codeql-linux64.zip
unzip codeql-linux64.zip
sudo mv codeql /usr/local/bin/

# Verify installation
codeql --version

Windows

# Download from GitHub releases
# https://github.com/github/codeql-cli-releases/releases
# Extract and add to PATH

데이터베이스 작업

CodeQL 데이터베이스 생성

# Create database for a GitHub repository
codeql database create <database-name> --language=<language> --source-root=<path>

# Example: Create JavaScript database
codeql database create my-db --language=javascript --source-root=./src

# Create multi-language database
codeql database create my-db --language=java,javascript --source-root=./src

# Create database with explicit command
codeql database create my-db \
  --language=python \
  --command="python -m pip install -r requirements.txt" \
  --source-root=./

# With database scheme
codeql database create my-db \
  --language=cpp \
  --source-root=./src \
  --db-scheme=/custom/db-scheme.yml

데이터베이스 관리

# List databases
codeql database list

# Get database info
codeql database info <database>

# Cleanup unused databases
codeql database cleanup <database>

# Remove database
rm -rf <database-path>

# Bundle database for sharing
codeql database bundle <database> --output=<bundle.zip>

# Unbundle database
codeql database unbundle <bundle.zip> --output=<database>

쿼리 실행

기본 쿼리 실행

# Run single query on database
codeql query run <query.ql> --database=<database>

# Run query suite
codeql query run <query-suite.yaml> --database=<database>

# Run query and save results as CSV
codeql query run <query.ql> --database=<database> --output=<results.csv>

# Run with JSON output
codeql query run <query.ql> --database=<database> --output=<results.json> --format=json

내장된 보안 쿼리

# Run default security and quality queries
codeql database analyze <database> security-and-quality --format=sarif-latest --output=results.sarif

# Analyze with custom query suite
codeql database analyze <database> <path/to/queries> \
  --format=sarif-latest \
  --output=results.sarif

# Analyze specific language
codeql database analyze <database> codeql/java-queries --format=csv --output=results.csv

# CWE-focused analysis
codeql database analyze <database> codeql-suites/javascript-security-and-quality.qls

언어별 명령어

JavaScript/TypeScript

# Create JavaScript database
codeql database create js-db --language=javascript --source-root=.

# Run security analysis
codeql database analyze js-db codeql/javascript-queries:security-and-quality --format=sarif-latest

# Check for SQL injection
codeql query run \
  --database=js-db \
  <path-to-query>/sql-injection.ql

Python

# Create Python database
codeql database create py-db --language=python --source-root=.

# Security analysis
codeql database analyze py-db codeql/python-queries:security --format=sarif-latest

# Path traversal detection
codeql query run \
  --database=py-db \
  <path-to-query>/path-injection.ql

Java

# Create Java database with Maven
codeql database create java-db \
  --language=java \
  --command="mvn clean install" \
  --source-root=.

# With Gradle
codeql database create java-db \
  --language=java \
  --command="gradle build" \
  --source-root=.

# Security scanning
codeql database analyze java-db codeql/java-queries:security-and-quality

C/C++

# Create C++ database with make
codeql database create cpp-db \
  --language=cpp \
  --command="make" \
  --source-root=.

# With CMake
codeql database create cpp-db \
  --language=cpp \
  --command="cmake . && make" \
  --source-root=.

쿼리 개발

커스텀 쿼리 생성

# Start query development
cat > select-sinks.ql << 'EOF'
import cpp

from FunctionCall fc
where fc.getTarget().getName() = "printf"
select fc
EOF

# Run custom query
codeql query run select-sinks.ql --database=cpp-db

쿼리 구조

import java

class SQLInjectionVulnerability extends DataFlow::FlowSink {
  SQLInjectionVulnerability() {
    asExpr() instanceof MethodAccess and
    asExpr().(MethodAccess).getMethod().hasName("execute")
  }
}

from DataFlow::PathNode source, DataFlow::PathNode sink
where TaintTracking::localTaintStep(source.getNode(), sink.getNode())
select source.getNode(), source, sink, "Potential SQL injection"

쿼리 테스트

# Run query tests
codeql test run <test-dir>

# Test with verbose output
codeql test run <test-dir> --verbose

# Test specific test file
codeql test run <test-file.ql>

CI/CD 통합

GitHub Actions

name: CodeQL Analysis
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Initialize CodeQL
        uses: github/codeql-action/init@v2
        with:
          languages: 'javascript,python'

      - name: Build
        run: |
          npm install
          npm run build

      - name: Perform CodeQL Analysis
        uses: github/codeql-action/analyze@v2

수동 CI 통합

#!/bin/bash
set -e

# Create database
codeql database create codeql-db --language=javascript --source-root=.

# Run analysis
codeql database analyze codeql-db security-and-quality --format=sarif-latest --output=results.sarif

# Upload results
curl -H "Authorization: token $GITHUB_TOKEN" \
  -F "payload=@results.sarif" \
  "https://api.github.com/repos/$GITHUB_REPOSITORY/code-scanning/sarif"

문제 해결

일반적인 문제

데이터베이스 생성 실패

# Check language support
codeql describe languages

# Verify build command
codeql database create db \
  --language=java \
  --command="mvn clean install" \
  --source-root=. \
  --verbose

쿼리 시간 초과

# Increase timeout (default 3600 seconds)
codeql query run query.ql --database=db --timeout=7200

메모리 문제

# Increase heap size
export CODEQL_JAVA_TOOL_OPTIONS=-Xmx4g
codeql database analyze db query-suite

결과 없음

# Verify database was created correctly
codeql database info <database>

# Check database stats
codeql database log-summary <database>

# Run simple test query
codeql query run tests/test-query.ql --database=db

고급 워크플로

Taint Tracking 분석

import javascript
import DataFlow
import TaintTracking

class Configuration extends TaintTracking::Configuration {
  Configuration() { this = "UserControlledFileName" }

  override predicate isSource(DataFlow::Node source) {
    source instanceof RemoteFlowSource
  }

  override predicate isSink(DataFlow::Node sink) {
    sink = any(FileSystemAccess fs).getAPathArgument()
  }
}

from Configuration cfg, DataFlow::PathNode source, DataFlow::PathNode sink
where cfg.hasFlowPath(source, sink)
select sink, "User input flows to filesystem access"

데이터 흐름 구성

import java
import DataFlow
import FlowSources

class MyConfiguration extends TaintTracking::Configuration {
  MyConfiguration() { this = "MyDataFlow" }

  override predicate isSource(DataFlow::Node n) {
    n instanceof RemoteFlowSource
  }

  override predicate isSink(DataFlow::Node n) {
    exists(MethodAccess m |
      m.getMethod().hasName("exec") and
      n.asExpr() = m.getAnArgument()
    )
  }

  override predicate isAdditionalTaintStep(DataFlow::Node n1, DataFlow::Node n2) {
    any()
  }
}

성능 최적화

데이터베이스 튜닝

# Create database with optimizations
codeql database create db \
  --language=javascript \
  --source-root=. \
  --dbscheme=/path/to/optimized-scheme.yml

# Use max threads for analysis
codeql database analyze db \
  security-and-quality \
  --threads=0  # Use all available CPU cores

쿼리 최적화

# Run pre-filtering queries
codeql query run prefilter.ql --database=db

# Analyze only changed files (if tracked)
codeql database analyze db \
  --threads=4 \
  --sarif-category="javascript" \
  security-and-quality

환경 변수

변수	설명
CODEQL_HOME	설치 디렉토리
CODEQL_JAVA_TOOL_OPTIONS	JVM 옵션 (예: -Xmx4g)
GITHUB_TOKEN	GitHub API 인증
CODEQL_THREADS	처리를 위한 스레드 수

모범 사례

• 재현성을 위해 데이터베이스를 버전 관리에 저장
• 일관된 언어 및 쿼리 스위트 버전 사용
• pre-commit hook에 CodeQL 포함하여 조기 감지
• CodeQL CLI 및 쿼리 팩 정기적으로 업데이트
• 명확한 설명과 함께 커스텀 쿼리 문서화
• 실제 취약점에 대해 쿼리 테스트
• 다른 도구와의 통합을 위해 SARIF 출력 사용
• 변경 사항뿐만 아니라 주기적으로 전체 분석 실행
• 거짓 긍정 비율 모니터링 및 쿼리 조정
• 추세 분석을 위해 과거 결과 보관

리소스

• CodeQL 문서
• 쿼리 언어 참조
• 보안 쿼리 팩
• CodeQL 커뮤니티 포럼

---

최종 업데이트: 2025-03-30