CodeQL 분석
지원 언어: Python, JavaScript/TypeScript, Go, Java/Kotlin, C/C++, C#, Ruby, Swift.
스킬 리소스: 참조 파일과 템플릿은 {baseDir}/references/ 및 {baseDir}/workflows/에 있습니다.
핵심 원칙
-
데이터베이스 품질은 타협할 수 없습니다. 빌드된 데이터베이스가 자동으로 좋은 것은 아닙니다 — 캐시된 빌드는 아무것도 추출하지 않고 성공을 보고합니다.
-
데이터 확장은 CodeQL이 놓치는 부분을 잡아냅니다. Django, Spring, Express 프로젝트는 여전히 데이터베이스 호출, 요청 파싱, 셸 실행을 프로젝트별 API로 래핑하며, 어떤 제공 모델도 이를 다루지 않습니다.
-
명시적인 스위트 참조는 쿼리가 조용히 제거되는 것을 방지합니다.
codeql database analyze에 팩 이름을 직접 전달하지 마십시오 — 각 팩의defaultSuiteFile은 숨겨진 필터를 적용하여 결과가 개일 수 있습니다. 항상.qls파일을 생성하십시오. -
발견 결과가 0개이면 축하할 일이 아니라 조사해야 합니다. 이는 추출 불량, 모델 누락, 잘못된 팩 또는 스위트 필터링을 의미할 수 있습니다. 빌드 후
{baseDir}/scripts/check_db_quality.py를 실행하고, 사용 중인 스위트에 대해{baseDir}/scripts/verify_query_suite.py가 0을 반환했는지 확인하십시오 — 생성 스크립트가 이를 실행하므로, 재사용하거나 수동으로 편집한 스위트에 대해서만 직접 호출하십시오. 보고서에 둘 다 통과했다고 명시하십시오. -
macOS Apple Silicon은 컴파일 언어에 대해 해결 방법이 필요합니다. 종료 코드 137은
arm64e/arm64불일치이지 빌드 실패가 아닙니다.build-mode=none으로 대체하기 전에 Homebrew arm64 도구 또는 Rosetta를 시도하십시오. -
워크플로우를 단계별로 따르십시오. 각 단계는 다음 단계로 이어집니다. 품질 평가 또는 데이터 확장을 건너뛰면 결과에서 그 공백이 눈에 띄지 않게 됩니다.
각 Bash 호출은 새로운 셸입니다
Bash 호출 간에는 아무것도 전달되지 않습니다: 변수, 배열, build_log.sh에서 가져온 함수 모두 포함됩니다. 아래의 각 블록은 동일한 블록 내에서 필요한 값을 다시 설정해야 합니다. 워크플로우는 이를 반복하는 대신 여기를 참조합니다. 워크플로우가 명시하는 것은 해당 사이트의 특정 문제이며, 각각 다르게 그리고 조용히 실패하기 때문입니다:
- 손실된 함수는
run_logged가 127로 종료되도록 하며, 빌드 사다리는 이를 실패한 메서드로 읽고--build-mode=none으로 내려가 CodeQL을 호출하지 않습니다. - 손실된 배열은 아무것도 확장되지 않으므로 사용자가 선택한 모든
--threat-model과--model-packs가 삭제되고 최종 보고서는 여전히 사용된 것으로 나열합니다. set -u아래에서 손실된 스칼라는unbound variable로 블록을 중단시킵니다.
출력 디렉토리
모든 생성된 파일(데이터베이스, 빌드 로그, 진단, 확장, 결과)은 단일 출력 디렉토리에 저장됩니다.
- 사용자가 프롬프트에서 출력 디렉토리를 지정한 경우
OUTPUT_DIR으로 사용합니다. - 지정되지 않은 경우 기본값은
./static_analysis_codeql_1입니다. 이미 존재하는 경우_2,_3등으로 증가시킵니다.
두 경우 모두, 파일을 쓰기 전에 항상 mkdir -p로 디렉토리를 생성해야 합니다.
USER_SPECIFIED_DIR을 실행 전에 사용자 프롬프트의 리터럴 경로로 설정하거나, 자동 증가를 위해 설정되지 않은 상태로 둡니다. 다른 어떤 것도 이를 할당하지 않습니다.
# 출력 디렉토리 확인
USER_SPECIFIED_DIR="${USER_SPECIFIED_DIR:-}" # 사용자의 경로가 있으면 여기에 대체
if [ -n "$USER_SPECIFIED_DIR" ]; then
OUTPUT_DIR="$USER_SPECIFIED_DIR"
else
BASE="static_analysis_codeql"
N=1
while [ -e "${BASE}_${N}" ]; do
N=$((N + 1))
done
OUTPUT_DIR="${BASE}_${N}"
fi
mkdir -p "$OUTPUT_DIR"
출력 디렉토리는 워크플로우 실행 전에 한 번 설정됩니다. 모든 워크플로우는 $OUTPUT_DIR을 받아 아티팩트를 그곳에 저장합니다:
$OUTPUT_DIR/
├── rulesets.txt # 선택된 쿼리 팩 (3단계 후 기록)
├── codeql.db/ # CodeQL 데이터베이스 (codeql-database.yml을 포함하는 디렉토리)
├── build.log # 빌드 로그
├── codeql-config.yml # 제외 설정 (인터프리티드 언어)
├── diagnostics/ # 진단 쿼리 및 CSV
├── extensions/ # 데이터 확장 YAML
├── raw/ # 필터링되지 않은 분석 출력
│ ├── results.sarif
│ └── run-all.qls | important-only.qls
└── results/ # 최종 결과 (important-only의 경우 필터링됨, run-all의 경우 복사)
└── results.sarif
데이터베이스 검색
CodeQL 데이터베이스는 해당 디렉토리 내에 codeql-database.yml 마커 파일이 있는지로 식별됩니다. 기존 데이터베이스를 검색할 때는 항상 모든 일치 항목을 수집하십시오 — 이전 실행이나 다른 언어에 대한 여러 데이터베이스가 있을 수 있습니다.
검색 명령어. find_databases.sh는 한 줄에 하나의 데이터베이스 경로를 출력하며, 실패한 빌드가 남긴 마커 파일을 걸러냅니다. 배열을 선택하는 동일한 블록에서 빌드하십시오 — 각 Bash 호출은 새로운 셸이므로, 여기서 빌드된 배열은 다음 호출에서 비어 있으며, 실행은 데이터베이스가 없다고 결론 내립니다:
# 명령어 대체 사용, `done < <(...)` 사용 안 함: 프로세스 대체는 스크립트의 종료 상태를
# 폐기하므로 "이 셸의 PATH에 codeql이 없습니다"(종료 2)가 빈 목록으로 도착하여 디스크에
# 세 개의 좋은 데이터베이스가 있는데 "새 데이터베이스 빌드"로 이어집니다.
if ! DB_LIST=$("{baseDir}/scripts/find_databases.sh" "${OUTPUT_DIR:-.}" .); then
echo "ERROR: 데이터베이스 검색 실패 — 위 메시지를 확인하십시오" >&2
exit 1
fi
FOUND_DBS=()
while IFS= read -r db; do
[ -n "$db" ] || continue
FOUND_DBS+=("$db")
done <<<"$DB_LIST"
echo "발견된 기존 데이터베이스: ${#FOUND_DBS[@]}개"
# 선택 프롬프트에 필요한 메타데이터, 자체 블록이 아닌 여기서 수집: FOUND_DBS는 다음
# Bash 호출에서 사라지며, 더 이상 존재하지 않는 배열에 대한 루프는 아무것도 출력하지 않고
# 성공을 보고합니다.
for db in "${FOUND_DBS[@]}"; do
CODEQL_LANG=$(codeql resolve database --format=json -- "$db" 2>/dev/null | jq -r '.languages[0]')
CREATED=$(grep '^creationMetadata:' -A5 "$db/codeql-database.yml" 2>/dev/null | grep 'creationTime' | awk '{print $2}')
echo "$db — 언어: $CODEQL_LANG, 생성일: $CREATED"
done
데이터베이스가 codeql.db라고 이름 지어졌다고 가정하지 마십시오 — 마커 파일로 검색하십시오.
여러 데이터베이스가 발견된 경우: AskUserQuestion을 사용하여 사용자가 위에 출력된 언어와 생성 시간을 바탕으로 사용할 데이터베이스를 선택하거나 새 데이터베이스를 빌드하도록 합니다. AskUserQuestion은 최대 4개의 옵션을 받으므로, 그보다 더 많은 데이터베이스가 있는 경우 가장 최근 3개와 "새 데이터베이스 빌드"를 제공하고 나머지는 프롬프트 텍스트에 나열하십시오. 사용자가 프롬프트에서 사용할 데이터베이스를 명시적으로 지정했거나 새 데이터베이스를 빌드하라고 한 경우 AskUserQuestion을 건너뛰십시오.
빠른 시작
일반적인 경우("이 코드베이스의 취약점 스캔"):
# CodeQL이 설치되었는지 확인합니다. 설치되지 않은 경우 여기서 중단하십시오 — 이후의 모든 명령은
# 덜 유익한 오류와 함께 실패하며, 실행은 이유를 알기 전에 빌드 주기를 낭비합니다.
if ! command -v codeql >/dev/null 2>&1; then
echo "ERROR: PATH에 codeql이 없습니다. 다음 중 하나로 설치하십시오:" >&2
echo " gh extension install github/gh-codeql # 그런 다음: gh codeql install-stub" >&2
echo " brew install --cask codeql" >&2
echo " https://github.com/github/codeql-action/releases (codeql-bundle)" >&2
exit 1
fi
# jq는 다음 단계에서 `codeql resolve database --format=json`을 파싱합니다. 이것 없이
# CODEQL_LANG은 비어 돌아오고 실행은 잘못된 언어로 계속됩니다.
if ! command -v jq >/dev/null 2>&1; then
echo "ERROR: PATH에 jq가 없습니다 (brew install jq / apt install jq)" >&2
exit 1
fi
# uv는 두 가드 스크립트와 두 스위트 생성기를 실행합니다. 스위트 생성 시점이 아닌 여기서
# 확인하십시오 — 그렇지 않으면 uv가 없는 머신은 빌드 전체를 소비한 후 실패합니다.
if ! command -v uv >/dev/null 2>&1; then
echo "ERROR: PATH에 uv가 없습니다 (https://docs.astral.sh/uv/getting-started/)" >&2
exit 1
fi
codeql --version
그런 다음 위의 출력 디렉토리 블록을 사용하여 OUTPUT_DIR을 확인하십시오 — 이는 사용자 지정 디렉토리를 존중하며, 단순한 자동 증가는 그렇지 않습니다.
그런 다음 아래 워크플로우를 사용하여 전체 파이프라인을 실행하십시오: 데이터베이스 빌드 → 데이터 확장 생성 → 분석 실행
거부해야 할 합리화
이러한 지름길은 발견을 놓치게 합니다. 받아들이지 마십시오:
- "security-extended이면 충분합니다" - 기준선일 뿐입니다. 항상 해당 언어에 대해 Trail of Bits 팩과 Community Packs를 사용할 수 있는지 확인하십시오. 이들은
security-extended가 완전히 놓치는 범주를 잡습니다. - "security-and-quality이 가장 광범위한 스위트입니다" -
security-and-quality는 모든experimental/쿼리 경로를 제외합니다. run-all 모드에서는security-and-quality와security-experimental을 모두 가져오십시오. 언어에 따라 차이는 1–52개 쿼리입니다. - "데이터베이스가 빌드되었으므로 좋습니다" - 데이터베이스가 빌드된다고 해서 추출이 잘 되었다는 의미는 아닙니다. 항상 품질 평가를 실행하고 예상 소스 파일 수와 파일 수를 확인하십시오.
- "표준 프레임워크에는 데이터 확장이 필요하지 않습니다" - Django/Spring 앱에도 CodeQL이 모델링하지 않는 커스텀 래퍼가 있습니다. 확장을 건너뛰면 취약점을 놓칩니다.
- "컴파일 언어에는 build-mode=none이 괜찮습니다" - 심각하게 불완전한 분석을 생성합니다. 최후의 수단으로만 사용하십시오. macOS에서는 먼저 arm64 툴체인 해결 방법 또는 Rosetta를 시도하십시오.
- "macOS에서 빌드가 실패하니 그냥 build-mode=none을 사용하세요" - 종료 코드 137은
arm64e/arm64불일치로 인한 것이지 근본적인 빌드 실패가 아닙니다. macos-arm64e-workaround.md를 참조하십시오. - "발견 결과가 없으면 코드가 안전한 것입니다" -
check_db_quality.py와verify_query_suite.py를 실행하고 통과했다고 보고하십시오. 이것들이 없으면, 0개의 발견 결과와 아무것도 추출하지 않은 데이터베이스는 동일한 출력입니다. - "그냥 기본 스위트를 실행하겠습니다" / "그냥 팩 이름을 직접 전달하겠습니다" - 각 팩의
defaultSuiteFile은 숨겨진 필터를 적용하여 결과가 0개일 수 있습니다. 항상 명시적인 스위트 참조를 사용하십시오. - "파일을 현재 디렉토리에 놓겠습니다" - 모든 생성된 파일은
$OUTPUT_DIR에 있어야 합니다. 작업 디렉토리에 파일을 흩뿌리면 정리가 불가능하고 이전 실행을 덮어쓸 위험이 있습니다. - "그냥 찾은 첫 번째 데이터베이스를 사용하세요" - 다른 언어나 이전 실행의 여러 데이터베이스가 존재할 수 있습니다. 둘 이상 발견되면 모든 옵션을 사용자에게 제시하십시오. 사용자가 이미 사용할 데이터베이스를 지정한 경우에만 프롬프트를 건너뛰십시오.
- "사용자가 '스캔'이라고 말했으니 데이터베이스를 선택하라는 뜻입니다" - "스캔"은 데이터베이스 선택이 아닙니다. 여러 데이터베이스가 존재하고 사용자가 하나를 지정하지 않은 경우 물어보십시오.
워크플로우 선택
이 스킬에는 세 가지 워크플로우가 있습니다. 워크플로우가 선택되면 단계를 건너뛰지 않고 순차적으로 실행하십시오.
이러한 실행은 오래 걸립니다. 데이터베이스 빌드에는 네 가지 대체 방법이 있으므로, 작업 도구를 사용하여 진행 상황을 추적하십시오. 실행에 따라 추적할 가치가 있는 단계를 결정하십시오.
| 워크플로우 | 목적 |
|---|---|
| build-database | 순차적으로 빌드 방법을 사용하여 CodeQL 데이터베이스 생성 |
| create-data-extensions | 프로젝트 API에 대한 데이터 확장 모델 감지 또는 생성 |
| run-analysis | 규칙 세트 선택, 쿼리 실행, 결과 처리 |
무인 빌드
이 플러그인은 /static-analysis:codeql-build를 제공하며, 이는 build-database 단계를 처음부터 끝까지 실행합니다: 언어 및 툴체인 감지, build-fixes.md의 수정사항을 단계 사이에 적용하며 메서드 사다리를 따라 이동, 품질 게이트 적용.
/static-analysis:codeql-build {"target": "/abs/path", "lang": "cpp"}
아무것도 묻지 않습니다. 모든 메서드가 실패하고 품질 임계값 아래로 빌드된 데이터베이스는 상태(no-method-succeeded 및 built-below-threshold)로 반환되어 여기서 조치를 취할 수 있습니다. 나머지 추출기 오류가 분석이 필요 없는 코드에 국한되어 있는지 여부는 실행이 내릴 수 없는 판단이기 때문입니다.
빌드가 길고 불확실한 부분이며 결론에 도달하도록 하고 싶을 때 사용하십시오. 어떤 메서드를 시도할지 결정하거나 빌드 실패가 발생할 때 해석이 필요할 때는 build-database.md를 직접 작업하십시오.
자동 감지 로직
사용자가 명시적으로 수행할 작업을 지정한 경우(예: "데이터베이스 빌드", "./my-db에서 분석 실행") 해당 워크플로우를 직접 실행하십시오. 사용자의 프롬프트가 의도를 명확히 하는 경우 데이터베이스 선택을 위해 AskUserQuestion을 호출하지 마십시오 — 예: "새 데이터베이스 빌드", "static_analysis_codeql_2의 codeql 데이터베이스 분석", "처음부터 전체 스캔 실행".
"test", "scan", "analyze" 등의 기본 파이프라인: 위의 데이터베이스 검색의 명령어를 사용하여 기존 데이터베이스를 검색한 후 결정합니다.
| 조건 | 작업 |
|---|---|
| 데이터베이스 없음 | 새 $OUTPUT_DIR 확인, 빌드 → 확장 → 분석 실행 (전체 파이프라인) |
| 하나의 데이터베이스 발견 | AskUserQuestion 사용: 재사용 또는 새로 빌드? |
| 여러 데이터베이스 발견 | AskUserQuestion 사용, 최대 4개 옵션 — 데이터베이스 검색 참조 |
| 사용자가 의도를 명시적으로 밝힘 | AskUserQuestion 건너뛰고 지시 사항에 따라 직접 실행 |
데이터베이스 선택 프롬프트
기존 데이터베이스가 발견되었고 사용자가 사용할 데이터베이스를 명시적으로 지정하지 않은 경우, "기존 CodeQL 데이터베이스"라는 헤더 아래 AskUserQuestion을 통해 제시하십시오. 각 옵션을 위에서 수집된 경로, 언어 및 생성 시간으로 레이블 지정하십시오 — ./static_analysis_codeql_1/codeql.db (언어: python, 생성일: 2026-02-24) — 마지막 옵션을 "새 데이터베이스 빌드"로 만듭니다.
선택 후:
- 사용자가 기존 데이터베이스를 선택한 경우:
$OUTPUT_DIR을 상위 디렉토리(또는 포함하는 디렉토리)로 설정하고$DB_NAME을 선택한 경로로 설정한 후 확장 → 분석으로 진행합니다. - 사용자가 "새로 빌드"를 선택한 경우: 새
$OUTPUT_DIR을 확인하고 빌드 → 확장 → 분석을 실행합니다.
일반 결정 프롬프트
프롬프트에서 데이터베이스나 워크플로우가 명확하지 않은 경우, AskUserQuestion을 통해 네 워크플로우를 제시하십시오.
...
[번역을 위해 잘렸습니다]