CodeQL 쿼리를 사용하여 코드 분석

CodeQL CLI를 이용한 데이터베이스 분석 정보

코드베이스를 분석하기 위해서는 코드에서 추출된 CodeQL 데이터베이스에 쿼리를 실행할 수 있습니다. CodeQL 분석은 코드 검색 경고를 생성하기 위해 GitHub에 업로드할 수 있는 결과를 생성합니다.

필수 조건

분석 시작 전에 다음을 수행해야 합니다.

•           로컬로 명령을 실행하기 위해 [CodeQL CLI](/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli)를 설정합니다.
  

•           [분석하려는 소스 코드에 대해 CodeQL 데이터베이스](/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis)를 생성합니다.
  

가장 간단하기 codeql database analyze를 실행하는 방법은 CodeQL CLI 번들에 포함된 표준 쿼리를 사용하는 것입니다.

codeql database analyze 실행

database analyze를 실행하면 다음과 같이 작동합니다.

1. 로컬에서 이용할 수 없는 참조된 CodeQL 패키지를 선택적으로 다운로드합니다.
2. 하나 이상의 쿼리 파일을 CodeQL 데이터베이스에 실행합니다.
3. 소스 코드 내 올바른 위치에 경고가 표시되도록 특정 쿼리 메타데이터를 기반으로 결과를 해석합니다.
4. 표준 출력으로 진단 및 요약 쿼리 결과를 보고합니다.

다음 명령을 실행하여 데이터베이스를 분석할 수 있습니다.

codeql database analyze <database> --format=<format> --output=<output> <query-specifiers>...

codeql database analyze <database> --format=<format> \
    --sarif-category=<language-specifier> --output=<output> \
    <packs,queries>

<database>, --format, --output을 지정해야 합니다. 실시하려는 분석에 따라 추가 옵션을 지정할 수 있습니다.

          **권장**. 파일 커버리지 정보를 도구 상태 페이지로 제출하는 데 사용합니다. 자세한 내용은 [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/about-the-tool-status-page#how-codeql-defines-scanned-files)을(를) 참조하세요. |

| --sarif-include-query-help | | 쿼리 도움말을 SARIF 출력에 포함시킬지 여부를 지정합니다. always 중 하나: 모든 쿼리에 대해 쿼리 도움말을 포함합니다. custom_queries_only (기본값): 쿼리 스위트에서 codeql/<lang>-queries 형태가 아닌 사용자 지정 쿼리에 대해서만 쿼리 도움말을 포함시킵니다. never: 어떤 쿼리도 도움말에 포함하지 않습니다. SARIF 출력에 포함된 사용자 지정 쿼리에 대한 쿼리 도움말은 쿼리에 대한 코드 스캐닝 경고에 표시됩니다. 자세한 내용은 CodeQL CLI에서 사용자 지정 쿼리 사용을(를) 참조하세요. | | <packs> | | 분석에 CodeQL 쿼리 팩을 포함시키고 싶은 경우에 사용합니다. 상세한 정보는 CodeQL 팩 다운로드 및 사용을 참조하세요. | | --download | | 사용자의 CodeQL 쿼리 팩 중 일부가 아직 디스크에 없어서 쿼리 실행 전에 다운로드해야 하는 경우에 사용합니다. | | --threads | | 둘 이상의 스레드를 사용하여 쿼리를 실행하려는 경우 사용합니다. 기본값은 1입니다. 더 많은 스레드를 지정하여 쿼리 실행 속도를 높일 수 있습니다. 스레드 수를 논리 프로세서 수로 설정하려면 0을 지정합니다. | | --verbose | | 데이터베이스 생성 프로세스에서 분석 프로세스 및 진단 데이터에 관한 더 자세한 정보를 가져오는 데 사용합니다. | | --threat-model | | (공개 미리 보기) CodeQL 분석에 추가 원본을 구성하기 위해 위협 모델을 추가합니다. 공개 미리 보기 중에 Java 분석에서만 위협 모델을 지원합니다. 자세한 내용은 데이터베이스 분석하기을(를) 참조하세요. |

데이터베이스를 분석 시 사용 가능한 모든 옵션에 대한 전체 내용은 데이터베이스 분석하기을 참조하세요.

CodeQL 데이터베이스의 기본 분석 예시

이 예제에서는 /codeql-dbs/example-repo에 저장된 CodeQL 데이터베이스를 분석하고 그 결과를 SARIF 파일 /temp/example-repo-js.sarif로 저장합니다. --sarif-category를 사용하여 결과를 JavaScript로 식별하는 SARIF 파일에 추가 정보를 포함합니다. 리포지토리의 단일 커밋에 대해 분석할 CodeQL 데이터베이스가 여러 개 있는 경우 반드시 이렇게 해야 합니다.

$ codeql database analyze /codeql-dbs/example-repo \
    javascript-code-scanning.qls --sarif-category=javascript-typescript \
    --format=sarifv2.1.0 --output=/temp/example-repo-js.sarif

> Running queries.
> Compiling query plan for /codeql-home/codeql/qlpacks/codeql-javascript/AngularJS/DisablingSce.ql.
...
> Shutting down query evaluator.
> Interpreting results.

결과에 모니터링용 파일 커버리지 정보 추가하기

code scanning에 대한 도구 상태 페이지에 표시하도록 GitHub에 파일 커버리지 정보를 제출하는 선택안도 있습니다. 파일 커버리지 정보에 대한 자세한 내용은 코드 검사 도구 상태 페이지 정보을(를) 참조하세요.

파일 커버리지 정보를 code scanning 결과에 포함시키기 위해서는 다음과 같이 CI 시스템 내 --sarif-add-baseline-file-info 플래그를 codeql database analyze 호출에 추가합니다.

$ codeql database analyze /codeql-dbs/example-repo \
    javascript-code-scanning.qls --sarif-category=javascript-typescript \
    --sarif-add-baseline-file-info \ --format=sarifv2.1.0 \
    --output=/temp/example-repo-js.sarif

데이터베이스 분석 실행의 예시

다음 예시에서는 CodeQL 팩을 사용하여 database analyze를 실행하는 방법과 CodeQL 리포지토리의 로컬 체크아웃을 사용하는 방법을 보여줍니다. 이러한 예시에서는 사용자의 CodeQL 데이터베이스가 CodeQL 리포지토리의 로컬 복사본과 같은 상위 디렉터리에 생성된 것으로 가정합니다.

CodeQL 쿼리 팩 실행

GitHub Container registry에서 기존 CodeQL 쿼리 팩을 실행하기 위해 1개 이상의 팩 이름을 지정할 수 있습니다.

codeql database analyze <database> microsoft/[email protected] github/security-queries --format=sarifv2.1.0 --output=query-results.sarif --download

이 명령은 지정된 데이터베이스에서 2개의 CodeQL 쿼리 팩 중 기본 쿼리 스위트를 실행합니다(microsoft/coding-standards 버전 1.0.0 및 github/security-queries 최신 버전). 기본 스위트에 대한 상세한 정보는 CodeQL 팩 게시 및 사용을 참조하세요.

--download 플래그는 선택 사항입니다. 이것을 사용하면 로컬에서 쿼리 팩을 이용할 수 없는 경우 다운로드합니다.

단일 쿼리 실행

JavaScript 코드베이스용으로 CodeQL 데이터베이스에 대해 단일 쿼리를 실행하기 위해서는 데이터베이스가 포함된 디렉터리에서 다음 명령을 사용할 수 있습니다.

codeql database analyze --download <javascript-database> codeql/javascript-queries:Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv

이 명령은 미사용 변수, 가져오기, 함수 또는 클래스와 관련된 잠재적인 버그를 찾는 간단한 쿼리를 실행하며, 이것은 CodeQL 리포지토리에 포함된 JavaScript 쿼리 중 하나에 해당합니다. 공백으로 구분된 비슷한 경로의 목록을 지정하여 2개 이상의 쿼리를 실행할 수 있습니다.

분석은 CSV 파일(js-results.csv)을 새 디렉터리(js-analysis)에 생성합니다.

또는 CodeQL 리포지토리가 체크 아웃된 경우, 쿼리 경로를 직접 지정함으로써 동일한 쿼리를 실행할 수 있습니다.

codeql database analyze <javascript-database> ../ql/javascript/ql/src/Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv

database analyze 명령을 이용해 사용자 지정 쿼리를 실행할 수도 있습니다. CodeQL CLI과 함께 사용할 쿼리 준비에 대한 자세한 내용은 CodeQL CLI에서 사용자 지정 쿼리 사용을 참조하세요.

디렉터리의 모든 쿼리 실행

개별 쿼리 파일을 모두 나열하는 대신 디렉터리 경로를 제공하면 디렉터리에 포함된 모든 쿼리를 실행할 수 있습니다. 경로는 재귀적으로 검색되므로 하위 폴더에 포함된 모든 쿼리도 실행됩니다.

예를 들어, codeql/python-queries 쿼리 팩에서 Functions 디렉터리에 포함된 모든 Python 쿼리를 실행하기 위해서는 다음을 실행합니다.

codeql database analyze <python-database> codeql/python-queries:Functions --format=sarif-latest --output=python-analysis/python-results.sarif --download

또는, CodeQL 리포지토리를 체크아웃해둔 경우, 디렉터리 경로를 직접 지정하여 동일한 쿼리를 실행할 수 있습니다.

codeql database analyze <python-database> ../ql/python/ql/src/Functions/ --format=sarif-latest --output=python-analysis/python-results.sarif

분석이 끝나면 SARIF 결과 파일이 생성됩니다. --format=sarif-latest를 지정하면 CodeQL가 지원하는 최신 SARIF 사양에 따라 결과가 포맷팅됩니다.

CodeQL 팩에서 쿼리 하위 집합 실행하기

CodeQL CLI v2.8.1 이상 버전을 사용하는 경우, 팩 내에서 쿼리의 하위 집합을 실행하기 위해 팩 지정자 끝에 경로를 포함시킬 수 있습니다. 이는 팩 내에서 쿼리의 위치를 찾거나 실행하는 모든 명령에 적용됩니다.

쿼리 집합을 지정하는 방법은 scope/name@range:path 양식으로 되어 있습니다.

•           `scope/name`는 정규화된 CodeQL 팩 이름입니다.
  

•           `range`는 [semver 범위](https://docs.npmjs.com/cli/v6/using-npm/semver#ranges)입니다.
  

•           `path`는 단일 쿼리, 또는 쿼리가 포함된 디렉터리, 또는 쿼리 스위트 파일에 대한 파일 시스템 경로입니다.
  

scope/name를 지정할 때 range 및 path는 선택 사항입니다. range를 생략할 경우, 지정된 팩의 최신 버전이 사용됩니다. path를 생략하면 지정된 팩의 기본 쿼리 스위트가 사용됩니다.

path은 \*.ql 쿼리 파일, 하나 이상의 쿼리를 포함하는 디렉터리, 또는 .qls 쿼리 스위트 파일 중 하나일 수 있습니다. 팩 이름을 생략할 경우, path를 제공해야 하며, 이는 현재 프로세스의 작업 디렉터리를 기준으로 해석됩니다.

scope/name 및 path를 지정할 경우, path는 절대 경로일 수 없습니다. CodeQL 팩의 루트를 기준으로 고려합니다.

experimental/Security CodeQL 팩 내에 codeql/cpp-queries 폴더의 모든 쿼리를 이용하여 데이터베이스를 분석하기 위해 다음을 사용할 수 있습니다.

codeql database analyze --format=sarif-latest --output=results <db> \
    codeql/cpp-queries:experimental/Security

RedundantNullCheckParam.ql CodeQL 팩에서 codeql/cpp-queries 쿼리를 실행하기 위해서는 다음을 사용합니다.

codeql database analyze --format=sarif-latest --output=results <db> \
    'codeql/cpp-queries:experimental/Likely Bugs/RedundantNullCheckParam.ql'

= 0.0.3 및 < 0.1.0(호환성이 가장 높은 버전이 선택됨)에 해당하는 버전의 cpp-security-and-quality.qls CodeQL 팩에서 codeql/cpp-queries 쿼리 스위트를 사용하여 데이터베이스를 분석하기 위해서는 다음을 사용할 수 있습니다.

codeql database analyze --format=sarif-latest --output=results <db> \
   'codeql/cpp-queries@~0.0.3:codeql-suites/cpp-security-and-quality.qls'

리터럴 @ 또는 :이 경로에 포함된 쿼리 파일, 디렉터리 또는 스위트를 참조해야 하는 경우, 다음과 같이 쿼리 지정자 앞에 path:를 붙일 수 있습니다.

codeql database analyze --format=sarif-latest --output=results <db> \
    path:C:/Users/ci/workspace@2/security/query.ql

CodeQL에 대한 추가 정보는 CodeQL 팩을 사용하여 분석 사용자 지정을 참조하세요.

쿼리 스위트 실행

C/C++ 코드베이스용 CodeQL 데이터베이스에서 쿼리 스위트를 실행하기 위해서는 사용자의 데이터베이스를 포함한 디렉터리에서 다음 명령을 사용할 수 있습니다.

codeql database analyze <cpp-database> codeql/cpp-queries:codeql-suites/cpp-code-scanning.qls --format=sarifv2.1.0 --output=cpp-results.sarif --download

이 명령은 codeql/cpp-queries CodeQL 쿼리 팩을 다운로드하고, 분석을 실행하며, GitHub의 모든 버전에서 지원하는 SARIF 버전 2.1.0 형식으로 파일을 생성합니다. codeql github upload-results를 실행하거나 코드 검색 API를 통해 이 파일을 GitHub로 업로드할 수 있습니다. 자세한 내용은 GitHub에 CodeQL 분석 결과 업로드하기 또는 코드 검색에 대한 REST API 엔드포인트을(를) 참조하세요.

CodeQL 쿼리 스위트는 특정 메타데이터 속성을 바탕으로 실행할 쿼리를 선택하기 위해 지시문을 사용하는 .qls 파일입니다. 표준 CodeQL 팩에는 코드 스캐닝에서 사용하는 쿼리 스위트의 위치를 지정하는 메타데이터가 있기 때문에 CodeQL CLI는 이러한 도구 스위트 파일을 자동으로 찾을 곳을 알고 있으며 명령줄에서 전체 경로를 지정할 필요가 없습니다. 자세한 내용은 CodeQL 쿼리 도구 모음 만들기을(를) 참조하세요.

사용자 지정 쿼리 스위트 생성에 관한 내용은 CodeQL 쿼리 도구 모음 만들기을 참조하세요.

오염된 데이터의 잠재적 출처를 추가하기 위한 모델 팩 포함

위협 모델을 code scanning 분석에 구성할 수 있습니다. 자세한 내용은 CodeQL 설명 문서의 Java 및 Kotlin용 위협 모형 및 C#용 위협 모형을 참조하세요.

$ codeql database analyze /codeql-dbs/my-company --format=sarif-latest \
  --threat-model=local \
  --output=/temp/my-company.sarif codeql/java-queries

이 예시에서, 표준 쿼리 팩 codeql/java-queries 내에 관련 쿼리는 remote 데이터플로우 소스에 대한 기본 위협 모형을 비롯해 local 위협 모델도 사용합니다. 로컬 소스(예: 파일 시스템, 명령줄 인수, 데이터베이스 및 환경 변수)의 데이터를 코드베이스에 대한 오염 데이터의 잠재적 출처로 간주하는 경우, local 위협 모델을 사용해야 합니다.

Results

분석 결과는 SARIF, CSV 등 다양한 형식으로 저장할 수 있습니다.

SARIF 형식은 정적 분석 도구의 광범위한 출력을 나타내도록 설계되었습니다. 자세한 내용은 CodeQL CLI SARIF 출력을(를) 참조하세요.

결과가 CSV 형식으로 어떤 모습인지에 대한 자세한 내용은 CodeQL CLI CSV 출력을 참조하세요.

결과 파일은 사용자 고유의 코드 검토 또는 디버깅 인프라로 통합할 수 있습니다. 가령, IDE용 SARIF 뷰어 플러그인을 사용하여 소스 코드의 올바른 위치에서 경고를 강조표시하기 위해 SARIF 파일 출력을 사용할 수 있습니다.

로그 및 진단 정보 보기

code scanning 쿼리 모음을 사용하여 CodeQL 데이터베이스를 분석할 때, CLI는 경고에 대한 상세 정보를 생성하는 것 외에도 데이터베이스 생성 단계 및 요약 메트릭의 진단 데이터를 보고합니다. SARIF 출력을 생성하기로 선택하는 경우, SARIF 파일에 추가 데이터도 포함됩니다. 경고가 거의 없는 리포지토리의 경우 이 정보는 코드에 문제가 거의 없는지 또는 CodeQL 데이터베이스를 생성하는 동안 오류가 없었는지 확인하는 데 유용할 수 있습니다. codeql database analyze에서 보다 자세한 출력을 얻으려면 --verbose 옵션을 사용합니다.

사용 가능한 유형의 진단 정보에 대한 자세한 내용은 코드 검사 로그 보기을 참조하세요.

CodeQL 분석이 실패하더라도 진단 정보를 내보내고 GitHub에 업로드하는 것을 선택할 수 있습니다. 자세한 내용은 GitHub에 CodeQL 분석 결과 업로드하기을(를) 참조하세요.

다음 단계

• CodeQL 분석 결과를 GitHub로 업로드하는 방법은 GitHub에 CodeQL 분석 결과 업로드하기을 참조하세요.