CodeQL 분석을 위한 코드 준비

분석을 위한 코드 준비 정보

CodeQL을(를) 사용하여 코드를 분석하기 전에 코드에서 쿼리를 실행하는 데 필요한 모든 데이터가 포함된 CodeQL 데이터베이스를 만들어야 합니다. CodeQL CLI를 사용하여 CodeQL을(를) 직접 만들 수 있습니다.

CodeQL 분석은 코드에서 관계형 데이터를 추출하고 이를 사용하여 CodeQL 데이터베이스를 빌드하는 데 의존합니다. CodeQL 데이터베이스에는 코드베이스에 대한 중요한 정보가 모두 포함되어 있으며, 이 정보는 CodeQL 쿼리를 실행하여 분석할 수 있습니다.

CodeQL 데이터베이스를 생성하기 전 다음 작업을 수행해야 합니다.

1. CodeQL CLI(을)를 설치 및 설정합니다. 자세한 내용은 "CodeQL CLI 설정하기"을(를) 참조하세요.
2. 분석하려는 코드를 체크 아웃합니다.
   • 분기의 경우 분석하려는 분기의 헤드를 체크 아웃합니다.
   • 끌어오기 요청의 경우 끌어오기 요청의 헤드 커밋을 체크 아웃하거나, 끌어오기 요청의 GitHub 생성 병합 커밋을 체크 아웃합니다.
3. 모든 종속성을 사용할 수 있도록 코드베이스에 대한 환경을 설정합니다.
4. 컴파일된 언어를 사용하여 최상의 결과를 얻으려면 코드베이스에 대한 빌드 명령(있는 경우)을 찾습니다. 일반적으로 이 명령은 CI 시스템의 구성 파일에서 사용할 수 있습니다.

코드베이스가 준비되면 codeql database create(을)를 실행하여 데이터베이스를 만들 수 있습니다. 자세한 내용은 "컴파일되지 않은 언어에 대한 데이터베이스 만들기" 및 "컴파일된 언어에 대한 데이터베이스 만들기"를 참조하세요.

codeql database create 실행 중

CodeQL 데이터베이스는 프로젝트의 체크 아웃 루트에서 다음 명령을 실행하여 생성됩니다.

codeql database create <database> --language=<language-identifier>

다음 항목을 지정해야 합니다.

• <database>는 생성할 새 데이터베이스의 경로입니다. 명령을 실행하면 이 디렉터리가 만들어집니다. 기존 디렉터리를 지정할 수는 없습니다.

• --language: 데이터베이스 생성에 사용되는 언어의 식별자입니다. --db-cluster와 함께 사용할 경우 옵션은 쉼표로 구분된 목록을 허용하거나 두 번 이상 지정할 수 있습니다. CodeQL(은)는 다음 언어용 데이터베이스 만들기를 지원합니다.

  언어	식별자	선택적 얼터너티브 식별자(있는 경우)
  C/C++	c-cpp	c 또는 cpp
  C#	csharp
  Go	go
  Java/Kotlin	java-kotlin	java 또는 kotlin
  JavaScript/TypeScript	javascript-typescript	javascript 또는 typescript
  Python	python
  Ruby	ruby
  Swift	swift

  노트: 얼터너티브 식별자 중 하나를 지정하는 경우 표준 언어 식별자를 사용하는 것과 같습니다. 예를 들어 javascript 대신 javascript-typescript를 지정해도 TypeScript 코드의 분석은 제외되지 않습니다. --paths-ignore 옵션을 사용하여 고급 설정 워크플로에서 이 작업을 수행할 수 있습니다. 자세한 내용은 "코드 검색을 위한 고급 설정 사용자 지정"을(를) 참조하세요.

코드베이스에 빌드 프로세스를 호출하는 빌드 명령 또는 스크립트가 있는 경우 다음과 같이 지정하는 것이 좋습니다.

   codeql database create <database> --command <build> \
         --language=<language-identifier>

데이터베이스를 만들기 위한 옵션

원본 파일의 위치, 코드를 컴파일해야 하는 경우, 두 개 이상의 언어에 대한 CodeQL 데이터베이스를 생성하려는 경우 추가 옵션을 지정할 수 있습니다.

옵션	필수	사용
<database>		CodeQL 데이터베이스에 대해 만들 디렉터리의 이름과 위치를 지정합니다. 기존 디렉터리를 덮어쓰려고 하면 명령이 실패합니다. 또한 --db-cluster를 지정하는 경우 이는 부모 디렉터리이며 하위 디렉터리는 분석된 각 언어에 대해 만들어집니다.
--language		데이터베이스를 만들 언어의 식별자를 c-cpp, csharp, go, java-kotlin, javascript-typescript, python, ruby, swift 중 하나로 지정합니다. --db-cluster와 함께 사용할 경우 옵션은 쉼표로 구분된 목록을 허용하거나 두 번 이상 지정할 수 있습니다.
--command		권장. 코드베이스에 대한 빌드 프로세스를 호출하는 빌드 명령 또는 스크립트를 지정하는 데 사용합니다. 명령은 현재 폴더에서 실행되거나 정의된 경우 --source-root에서 실행됩니다. Python 및 JavaScript/TypeScript 분석에는 필요하지 않습니다.
--db-cluster		다국어 코드베이스에서 --language에 의해 지정된 각 언어에 대해 하나의 데이터베이스를 생성하는 데 사용합니다.
--no-run-unnecessary-builds		권장. CodeQL CLI가 빌드를 모니터링할 필요가 없는 언어(예: Python 및 JavaScript/TypeScript)의 빌드 명령을 표시하지 않는 데 사용합니다.
--source-root		리포지토리의 체크 아웃 루트 외부에서 CLI를 실행하는 경우 사용합니다. 기본적으로 database create 명령은 현재 디렉터리가 원본 파일의 루트 디렉터리라고 가정합니다. 이 옵션을 사용하여 다른 위치를 지정합니다.
--codescanning-config		고급. CodeQL 데이터베이스를 만드는 방법과 이후 단계에서 실행할 쿼리를 지정하는 구성 파일이 있는 경우 사용합니다. 자세한 내용은 "코드 검색을 위한 고급 설정 사용자 지정" 및 "데이터베이스 만들기"을(를) 참조하세요.

추출기 옵션을 지정하여 CodeQL 데이터베이스를 만드는 추출기의 동작을 사용자 지정할 수 있습니다. 자세한 내용은 "추출기 옵션"을(를) 참조하세요.

데이터베이스를 만들 때 사용할 수 있는 모든 옵션에 대한 전체 내용은 "데이터베이스 만들기"을(를) 참조하세요.

단일 언어 예시

다음은 /checkouts/example-repo에서 체크 아웃된 리포지토리에 대한 단일 CodeQL 데이터베이스를 만드는 예시입니다. JavaScript 추출기를 사용하여 리포지토리에 JavaScript 및 TypeScript 코드의 계층적 표현을 만듭니다. 결과 데이터베이스는 /codeql-dbs/example-repo에 저장됩니다.

$ codeql database create /codeql-dbs/example-repo --language=javascript-typescript \
    --source-root /checkouts/example-repo

> Initializing database at /codeql-dbs/example-repo.
> Running command [/codeql-home/codeql/javascript/tools/autobuild.cmd]
    in /checkouts/example-repo.
> [build-stdout] Single-threaded extraction.
> [build-stdout] Extracting
...
> Finalizing database at /codeql-dbs/example-repo.
> Successfully created database at /codeql-dbs/example-repo.

다중 언어 예시

다음은 /checkouts/example-repo-multi에서 체크 아웃된 리포지토리에 대한 CodeQL 데이터베이스 2개를 만드는 예시입니다. 이는 다음을 사용합니다.

• --db-cluster - 두 개 이상 언어의 분석을 요청합니다.
• --language - 데이터베이스를 만들 언어를 지정합니다.
• --command - 코드베이스에 대한 빌드 명령을 도구에 알립니다(여기서는 make).
• --no-run-unnecessary-builds - 필요하지 않은 경우 언어(예: Python)의 빌드 명령을 건너뛰도록 도구에 알립니다.

결과 데이터베이스는 /codeql-dbs/example-repo-multi의 python 및 cpp 하위 디렉터리에 저장됩니다.

$ codeql database create /codeql-dbs/example-repo-multi \
    --db-cluster --language python,c-cpp \
    --command make --no-run-unnecessary-builds \
    --source-root /checkouts/example-repo-multi
Initializing databases at /codeql-dbs/example-repo-multi.
Running build command: [make]
[build-stdout] Calling python3 /codeql-bundle/codeql/python/tools/get_venv_lib.py
[build-stdout] Calling python3 -S /codeql-bundle/codeql/python/tools/python_tracer.py -v -z all -c /codeql-dbs/example-repo-multi/python/working/trap_cache -p ERROR: 'pip' not installed.
[build-stdout] /usr/local/lib/python3.6/dist-packages -R /checkouts/example-repo-multi
[build-stdout] [INFO] Python version 3.6.9
[build-stdout] [INFO] Python extractor version 5.16
[build-stdout] [INFO] [2] Extracted file /checkouts/example-repo-multi/hello.py in 5ms
[build-stdout] [INFO] Processed 1 modules in 0.15s
[build-stdout] <output from calling 'make' to build the C/C++ code>
Finalizing databases at /codeql-dbs/example-repo-multi.
Successfully created databases at /codeql-dbs/example-repo-multi.
$

진행률 및 결과

지정한 옵션에 문제가 있으면 오류가 보고됩니다. 해석된 언어의 경우 Java에 --build-mode none을 지정하면 추출 진행률이 콘솔에 표시됩니다. 각 원본 파일에 대해 콘솔은 추출에 성공했는지 또는 실패했는지를 표시합니다. 컴파일된 언어가 빌드되면 콘솔에 빌드 시스템의 출력이 표시됩니다.

데이터베이스가 성공적으로 만들어지면 명령에 지정된 경로에서 새 디렉터리를 찾을 수 있습니다. --db-cluster 옵션을 사용하여 둘 이상의 데이터베이스를 만든 경우 각 언어에 대해 하위 디렉터리가 만들어집니다. 각 CodeQL 데이터베이스 디렉터리에는 관계형 데이터(분석에 필요) 및 원본 아카이브(데이터베이스를 만들 때 생성한 원본 파일의 복사본)를 포함하여 분석 결과를 표시하는 데 사용되는 여러 하위 디렉터리가 포함됩니다.

컴파일되지 않은 언어용 데이터베이스 만들기

CodeQL CLI에는 컴파일되지 않은 언어, 특히 JavaScript(및 TypeScript), Python 및 Ruby용 데이터베이스를 만드는 추출기가 포함되어 있습니다. 이러한 추출기는 JavaScript, Python 또는 Ruby를 --language 옵션으로 지정하고 database create(을)를 실행하면 자동으로 호출됩니다. 이들 언어용 데이터베이스를 만들 때는 추가적인 종속성을 모두 사용할 수 있는지 확인해야 합니다.

JavaScript 및 TypeScript

JavaScript용 데이터베이스를 만들 때는 추가 종속성이 필요하지 않지만 프로젝트에 TypeScript 파일이 포함된 경우 Node.js 14 이상이 설치되어 있어야 하며 PATH에서 node로 사용할 수 있어야 합니다. 명령줄에서 JavaScript 및 TypeScript 파일을 모두 추출하도록 --language=javascript-typescript(을)를 지정할 수 있습니다.

codeql database create --language=javascript-typescript --source-root <folder-to-extract> <output-folder>/javascript-database

여기서는 데이터베이스 만들기가 실행되는 위치인 --source-root 경로를 지정했지만 코드베이스의 체크 아웃 루트일 필요는 없습니다.

기본적으로 node_modules 및 bower_components 디렉터리에서의 파일은 추출되지 않습니다.

Python

Python용 데이터베이스를 만들 때는 다음을 확인해야 합니다.

• Python 3이 설치되어 있으며 CodeQL 추출기에서 사용할 수 있습니다.
• 코드에 사용하는 Python 버전이 설치되어 있습니다.

명령줄에서 --language=python(을)를 지정해야 합니다. 예시:

codeql database create --language=python <output-folder>/python-database

그러면 코드의 체크 아웃 루트에서 database create 하위 명령을 실행하여 <output-folder>/python-database에서 새 Python 데이터베이스를 생성합니다.

Ruby

Ruby용 데이터베이스를 만들려면 추가 종속성이 필요하지 않습니다. 명령줄에서 --language=ruby(을)를 지정해야 합니다. 예시:

codeql database create --language=ruby --source-root <folder-to-extract> <output-folder>/ruby-database

여기서는 데이터베이스 만들기가 실행되는 위치인 --source-root 경로를 지정했지만 코드베이스의 체크 아웃 루트일 필요는 없습니다.

컴파일된 언어용 데이터베이스 만들기

컴파일된 언어의 경우 CodeQL은(는) 데이터베이스를 생성하는 데 필요한 빌드 시스템을 호출해야 하므로 CLI에서 빌드 메서드를 사용할 수 있어야 합니다. 이 방법은 생성된 코드를 포함하는 데이터베이스를 만듭니다. CodeQL에는 코드베이스를 빌드하는 두 가지 방법이 있습니다.

• "자동 빌드 검색(자동 빌드)"
• "사용자가 지정한 빌드 명령"

빌드 시스템 자동 검색

CodeQL CLI에는 C/C++, C#, Go, Java, Kotlin, and Swift 코드용 자동 빌드기가 포함되어 있습니다. CodeQL 자동 빌드기를 사용하면 빌드 명령을 지정하지 않고도 컴파일된 언어용 프로젝트를 빌드할 수 있습니다. 자동 빌드기가 호출될 때 CodeQL에서는 원본을 검사하여 빌드 시스템의 근거를 확인하고 데이터베이스 추출에 필요한 최적의 명령 집합을 실행하려고 시도합니다. 자세한 내용은 "컴파일된 언어에 대한 CodeQL 코드 검사하기"을(를) 참조하세요.

컴파일된 언어에 대해 codeql database create을 실행할 때 --command 옵션을 설정하지 않으면 자동 빌더가 자동으로 호출됩니다. 예를 들어 C/C++ 코드베이스의 경우 다음을 실행하기만 하면 됩니다.

codeql database create --language=cpp <output-folder>/cpp-database

코드베이스에서 표준 빌드 시스템을 사용하는 경우 자동 빌드기를 사용하는 것이 데이터베이스를 만드는 가장 간단한 방법입니다. 비표준 빌드 단계가 필요한 원본의 경우 명령줄에서 각 단계를 명시적으로 정의해야 할 수 있습니다.

빌드 명령 지정

다음 예시는 컴파일된 언어용으로 지정할 수 있는 빌드 명령 중 일부에 대한 아이디어를 제공하도록 설계되었습니다.

• make를 사용하여 빌드된 C/C++ 프로젝트:

  codeql database create cpp-database --language=c-cpp --command=make
  

• dotnet build를 사용하여 빌드된 C# 프로젝트:

  모든 코드가 빌드되도록 /t:rebuild를 추가하거나 이전 dotnet clean을 수행하는 것이 좋습니다(빌드되지 않은 코드는 CodeQL 데이터베이스에 포함되지 않음).

  codeql database create csharp-database --language=csharp --command='dotnet build /t:rebuild'
  

• CODEQL_EXTRACTOR_GO_BUILD_TRACING=on 환경 변수를 사용하여 빌드된 Go 프로젝트:

  CODEQL_EXTRACTOR_GO_BUILD_TRACING=on codeql database create go-database --language=go
  

• 사용자 지정 빌드 스크립트를 사용하여 빌드된 Go 프로젝트:

  codeql database create go-database --language=go --command='./scripts/build.sh'
  

• Gradle을 사용하여 빌드된 Java 프로젝트:

  # Use `--no-daemon` because a build delegated to an existing daemon cannot be detected by CodeQL.
  # To ensure isolated builds without caching, add `--no-build-cache` on persistent machines.
  codeql database create java-database --language=java-kotlin --command='gradle --no-daemon clean test'
  

• Maven을 사용하여 빌드된 Java 프로젝트:

  codeql database create java-database --language=java-kotlin --command='mvn clean install'
  

• Ant를 사용하여 빌드된 Java 프로젝트:

  codeql database create java-database --language=java-kotlin --command='ant -f build.xml'
  

• Xcode 프로젝트 또는 작업 영역에서 빌드된 Swift 프로젝트입니다. 기본값으로 가장 큰 Swift 대상은 다음과 같이 빌드됩니다.

  프로젝트가 클린 상태이고 사용 가능한 빌드 아티팩트가 없는지 확인하는 것이 좋습니다.

  xcodebuild clean -all
  codeql database create -l swift swift-database
  

• swift build를 사용하여 빌드된 Swift 프로젝트:

  codeql database create -l swift -c "swift build" swift-database
  

• xcodebuild를 사용하여 빌드된 Swift 프로젝트:

  codeql database create -l swift -c "xcodebuild build -target your-target" swift-database
  

  archive 및 test 옵션을 xcodebuild에 전달할 수 있습니다. 그러나 표준 xcodebuild 명령은 가장 빠르며 성공적인 검사를 위해 CodeQL에 필요한 모든 것이기 때문에 권장됩니다.

• 사용자 지정 빌드 스크립트를 사용하여 빌드된 Swift 프로젝트:

  codeql database create -l swift -c "./scripts/build.sh" swift-database
  

• Bazel을 사용하여 빌드된 프로젝트:

  # Navigate to the Bazel workspace.
  
  # Before building, remove cached objects
  # and stop all running Bazel server processes.
  bazel clean --expunge
  
  # Build using the following Bazel flags, to help CodeQL detect the build:
  # `--spawn_strategy=local`: build locally, instead of using a distributed build
  # `--nouse_action_cache`: turn off build caching, which might prevent recompilation of source code
  # `--noremote_accept_cached`, `--noremote_upload_local_results`: avoid using a remote cache
  # `--disk_cache=`: avoid using a disk cache. Note that a disk cache is no longer considered a remote cache as of Bazel 6.
  codeql database create new-database --language=<language> \
  --command='bazel build --spawn_strategy=local --nouse_action_cache --noremote_accept_cached --noremote_upload_local_results --disk_cache= //path/to/package:target'
  
  # After building, stop all running Bazel server processes.
  # This ensures future build commands start in a clean Bazel server process
  # without CodeQL attached.
  bazel shutdown
  

• 사용자 지정 빌드 스크립트를 사용하여 빌드된 프로젝트:

  codeql database create new-database --language=<language> --command='./scripts/build.sh'
  

이 명령은 프로젝트를 빌드하는 데 필요한 모든 명령을 포함하는 사용자 지정 스크립트를 실행합니다.

간접 빌드 추적 사용

컴파일된 언어용 CodeQL CLI 자동 빌드기가 CI 워크플로에서 작동하지 않고 codeql database trace-command로 빌드 명령 호출을 래핑할 수 없는 경우, 간접 빌드 추적을 사용하여 CodeQL 데이터베이스를 만들 수 있습니다. 간접 빌드 추적을 사용하려면 CI 시스템에서 각 빌드 작업에 대한 사용자 지정 환경 변수를 설정할 수 있어야 합니다.

간접 빌드 추적을 사용하여 CodeQL 데이터베이스를 생성하려면 프로젝트의 체크 아웃 루트에서 다음 명령을 실행합니다.

codeql database init ... --begin-tracing <database>

다음 항목을 지정해야 합니다.

• <database>는 생성할 새 데이터베이스의 경로입니다. 명령을 실행하면 이 디렉터리가 만들어집니다. 기존 디렉터리를 지정할 수는 없습니다.
• --begin-tracing은 빌드 명령을 추적할 환경을 설정하는 데 사용할 수 있는 스크립트를 만듭니다.

codeql database init 명령에 대한 다른 옵션을 정상적으로 지정할 수 있습니다.

이 codeql database init 명령은 다음 메시지를 출력합니다.

Created skeleton <database>. This in-progress database is ready to be populated by an extractor. In order to initialise tracing, some environment variables need to be set in the shell your build will run in. A number of scripts to do this have been created in <database>/temp/tracingEnvironment. Please run one of these scripts before invoking your build command.

Based on your operating system, we recommend you run: ...

이 codeql database init 명령은 CodeQL이 빌드 단계 시퀀스를 추적할 수 있도록 하는 환경 변수 및 값이 포함된 파일로 <database>/temp/tracingEnvironment를 만듭니다. 이러한 파일의 이름은 start-tracing.{json,sh,bat,ps1}입니다. 다음 단계에서 환경 변수를 설정하기 위해 CI 시스템의 메커니즘과 함께 이러한 파일 중 하나를 사용합니다. 마케팅 목록의 구성원을 관리할 수 있습니다.

• JSON 파일을 읽고, 처리하고, CI 시스템에서 예상하는 형식으로 환경 변수를 출력합니다. 예를 들어 Azure DevOps에는 echo "##vso[task.setvariable variable=NAME]VALUE"를 예상합니다.
• 또는 CI 시스템의 환경을 유지하는 경우 적절한 start-tracing 스크립트를 소싱하여 CI 시스템의 셸 환경에서 CodeQL 변수를 설정합니다.

코드를 빌드합니다. 선택적으로 디렉터리의 end-tracing.{json,sh,bat,ps1} 스크립트를 사용하여 start-tracing 스크립트가 저장된 디렉터리에서 환경 변수를 설정 해제한 다음 codeql database finalize <database> 명령을 실행합니다.

간접 빌드 추적을 사용하여 CodeQL 데이터베이스를 만든 후에는 다른 CodeQL 데이터베이스와 마찬가지로 작업할 수 있습니다. 예를 들어 코드 검색을 사용하는 경우 데이터베이스를 분석하고 GitHub에 결과를 업로드합니다.

간접 빌드 추적을 사용한 CodeQL 데이터베이스 생성 예시

다음 예시에서는 Azure DevOps 파이프라인에서 간접 빌드 추적을 사용하여 CodeQL 데이터베이스를 만드는 방법을 보여 줍니다.

steps:
    # Download the CodeQL CLI and query packs...
    # Check out the repository ...

    # Run any pre-build tasks, for example, restore NuGet dependencies...

    # Initialize the CodeQL database.
    # In this example, the CodeQL CLI has been downloaded and placed on the PATH.
    - task: CmdLine@1
       displayName: Initialize CodeQL database
      inputs:
          # Assumes the source code is checked out to the current working directory.
          # Creates a database at `<current working directory>/db`.
          # Running on Windows, so specifies a trace process level.
          script: "codeql database init --language csharp --trace-process-name Agent.Worker.exe --source-root . --begin-tracing db"

    # Read the generated environment variables and values,
    # and set them so they are available for subsequent commands
    # in the build pipeline. This is done in PowerShell in this example.
    - task: PowerShell@1
       displayName: Set CodeQL environment variables
       inputs:
          targetType: inline
          script: >
             $json = Get-Content $(System.DefaultWorkingDirectory)/db/temp/tracingEnvironment/start-tracing.json | ConvertFrom-Json
             $json.PSObject.Properties | ForEach-Object {
                 $template = "##vso[task.setvariable variable="
                 $template += $_.Name
                 $template += "]"
                 $template += $_.Value
                 echo "$template"
             }

    # Execute the pre-defined build step. Note the `msbuildArgs` variable.
    - task: VSBuild@1
        inputs:
          solution: '**/*.sln'
          msbuildArgs: /p:OutDir=$(Build.ArtifactStagingDirectory)
          platform: Any CPU
          configuration: Release
          # Execute a clean build, in order to remove any existing build artifacts prior to the build.
          clean: True
       displayName: Visual Studio Build

    # Read and set the generated environment variables to end build tracing. This is done in PowerShell in this example.
    - task: PowerShell@1
       displayName: Clear CodeQL environment variables
       inputs:
          targetType: inline
          script: >
             $json = Get-Content $(System.DefaultWorkingDirectory)/db/temp/tracingEnvironment/end-tracing.json | ConvertFrom-Json
             $json.PSObject.Properties | ForEach-Object {
                 $template = "##vso[task.setvariable variable="
                 $template += $_.Name
                 $template += "]"
                 $template += $_.Value
                 echo "$template"
             }

    - task: CmdLine@2
       displayName: Finalize CodeQL database
       inputs:
          script: 'codeql database finalize db'

    # Other tasks go here, for example:
    # `codeql database analyze`
    # then `codeql github upload-results` ...

다음 단계

• CodeQL CLI을(를) 사용하여 코드에서 만든 데이터베이스를 분석하는 방법을 알아보려면 "CodeQL 쿼리를 사용하여 코드 분석"(을)를 참조하세요.