Skip to main content

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

코드베이스에서 추출된 CodeQL 데이터베이스에 대해 쿼리를 실행할 수 있습니다.

누가 이 기능을 사용할 수 있는 있나요?

GitHub CodeQL은(는) 설치 시 사용자별로 라이선스가 부여됩니다. 라이선스 제한에 따라 특정 작업에만 CodeQL을(를) 사용할 수 있습니다. 자세한 내용은 "CodeQL CLI 알아보기"을(를) 참조하세요.

GitHub Advanced Security 라이선스가 있는 경우 CodeQL을(를) 사용하여 분석 자동화, 연속 통합 및 지속적인 업데이트를 할 수 있습니다. 자세한 내용은 "GitHub Advanced Security 정보.

CodeQL CLI로 데이터베이스 분석 정보

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

필수 조건

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

가장 간단한 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 데이터베이스를 분석하는 경우 이 명령에서 생성된 각 결과 세트에 대해 SARIF 범주를 지정해야 합니다. GitHub Enterprise Cloud에 결과를 업로드할 때 code scanning에서는 이 범주를 사용하여 각 언어에 대한 결과를 별도로 저장합니다. 이 작업을 수행하지 않으면 각 업로드가 이전 결과를 덮어씁니다.

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

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

옵션필수사용
<database>분석할 CodeQL 데이터베이스가 포함된 디렉터리의 경로를 지정합니다.
<packs,queries>실행할 CodeQL 팩 또는 쿼리를 지정합니다. code scanning에 사용되는 표준 쿼리를 실행하려면 이 매개 변수를 생략합니다. CodeQL CLI 번들에 포함된 다른 쿼리 모음을 보려면 /<extraction-root>/qlpacks/codeql/<language>-queries/codeql-suites를 살펴봅니다. 고유한 쿼리 도구 모음을 만드는 방법에 대한 내용은 CodeQL CLI 설명서에서 "CodeQL 쿼리 도구 모음 만들기"을(를) 참조하세요.
--format분석 중에 생성된 결과 파일의 형식을 지정합니다. CSV, SARIF 및 그래프 형식을 포함하여 다양한 형식이 지원됩니다. GitHub에 업로드하는 경우 sarif-latest여야 합니다. 자세한 내용은 "코드 검사에 대한 SARIF 지원"을(를) 참조하세요.
--output.sarif 확장명을 가진 원하는 파일 이름을 포함하여 SARIF 결과 파일을 저장할 위치를 지정합니다.
--sarif-category단일 데이터베이스 분석의 경우 선택 사항입니다. 리포지토리에서 단일 커밋에 대해 여러 데이터베이스를 분석하는 경우 언어를 정의하는 데 필요합니다.

이 분석을 위해 SARIF 결과 파일에 포함할 범주를 지정합니다. 범주는 다양한 언어 또는 다양한 코드 부분에서 수행되지만 동일한 도구와 커밋을 대상으로 하는 여러 분석을 구분하는 데 사용됩니다.
--sarif-add-baseline-file-info권장. 도구 상태 페이지에 파일 적용 범위 정보를 제출하는 데 사용합니다. 자세한 내용은 "코드 스캔을 위한 도구 상태 페이지 정보"을(를) 참조하세요.
--sarif-include-query-helpSARIF 출력에 쿼리 도움말을 포함할지 여부를 지정합니다. 다음 중 하나: always: 모든 쿼리에 대한 쿼리 도움말을 포함합니다. custom_queries_only (기본값): 사용자 지정 쿼리, 즉, codeql/<lang>-queries 형식이 아닌 쿼리에 대해서만 쿼리 도움말을 포함합니다. never: 쿼리에 대한 쿼리 도움말을 포함하지 않습니다. SARIF 출력에 포함된 사용자 지정 쿼리의 쿼리 도움말은 쿼리에 대한 코드 검색 경고에 표시됩니다. 자세한 내용은 "CodeQL CLI에서 사용자 지정 쿼리 사용하기"을 참조하세요.
<packs>분석에 CodeQL 쿼리 팩을 포함하려는 경우에 사용합니다. 자세한 내용은 "CodeQL 팩 다운로드 및 사용"을 참조하세요.
--downloadCodeQL 쿼리 팩 중 일부가 아직 디스크에 없어서 쿼리를 실행하기 전에 다운로드해야 하는 경우에 사용합니다.
--threads둘 이상의 스레드를 사용하여 쿼리를 실행하려는 경우 사용합니다. 기본값은 1입니다. 더 많은 스레드를 지정하여 쿼리 실행 속도를 높일 수 있습니다. 스레드 수를 논리 프로세서 수로 설정하려면 0을 지정합니다.
--verbose데이터베이스 생성 프로세스에서 분석 프로세스 및 진단 데이터에 관한 더 자세한 정보를 가져오는 데 사용합니다.
--threat-model(베타) 위협 모델을 추가하여 CodeQL 분석에서 추가 원본을 구성하는 데 사용합니다. 베타 중에 위협 모델은 Java 분석에서만 지원됩니다. 자세한 내용은 "데이터베이스 분석"을(를) 참조하세요.

데이터베이스 업그레이드

CodeQL CLI v2.3.3 이하에서 만든 데이터베이스의 경우 최신 버전의 CodeQL CLI으로 분석을 실행하려면 먼저 데이터베이스를 명시적으로 업그레이드해야 합니다. 이 단계가 필요한 경우 database analyze(을)룰 실행할 때 데이터베이스를 업그레이드가 필요하다는 메시지가 표시됩니다.

CodeQL CLI v2.3.4 이상에서 만든 데이터베이스의 경우 CLI는 필요한 업그레이드를 암시적으로 실행합니다. 업그레이드 명령을 명시적으로 실행할 필요는 없습니다.

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

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=sarif-latest --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.

모니터링을 위해 결과에 파일 적용 범위 정보 추가

필요에 따라 GitHub Enterprise Cloud에 파일 적용 범위 정보를 제출하여 code scanning에 대한 도구 상태 페이지에 표시할 수 있습니다. 파일 적용 범위 정보에 대한 자세한 내용은 "코드 스캔을 위한 도구 상태 페이지 정보"을(를) 참조하세요.

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=sarif-latest \
    --output=/temp/example-repo-js.sarif

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

다음 예제에서는 CodeQL 팩을 사용하여 database analyze(을)를 실행하는 방법과 CodeQL 리포지토리의 로컬 체크아웃을 사용하는 방법을 보여 줍니다. 이 예제에서는 CodeQL 데이터베이스가 CodeQL 리포지토리의 로컬 복사본의 형제인 디렉터리에 만들어졌다고 가정합니다.

CodeQL 쿼리 팩 실행

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

codeql database analyze <database> microsoft/coding-standards@1.0.0 github/security-queries --format=sarifv2.1.0 --output=query-results.sarif --download

이 명령은 두 개의 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 쿼리 중 하나에 해당합니다. 비슷한 경로의 공백으로 구분된 목록을 지정하여 둘 이상의 쿼리를 실행할 수 있습니다.

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

또는 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에서 사용자 지정 쿼리 사용하기”을(를) 참조하세요.

디렉터리에서 모든 쿼리 실행

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

중요

명령과 함께 사용하도록 설계되지 않은 일부 특수 쿼리가 포함될 수 있으므로 database analyze(을)를 실행할 때 핵심 CodeQL 쿼리 팩의 루트를 지정하지 않아야 합니다. 대신 쿼리 팩을 실행하여 팩의 기본 쿼리를 분석에 포함하거나 코드 검색 쿼리 도구 모음 중 하나를 실행합니다.

예를 들어 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(의미론적 버전 관리) 범위입니다.

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

scope/name(을)를 지정하면 rangepath(은)는 선택 사항입니다. range을(를) 생략하면 지정된 팩의 최신 버전이 사용됩니다. path(을)를 생략하면 지정된 팩의 기본 쿼리 도구 모음이 사용됩니다.

path은(는) \*.ql 쿼리 파일, 하나 이상의 쿼리가 포함된 디렉터리 또는 .qls 쿼리 도구 모음 파일 중 하나가 될 수 있습니다. 팩 이름을 생략하면 현재 프로세스의 작업 디렉터리를 기준으로 해석되는 path(을)를 제공해야 합니다.

scope/name(와)과 path(을)를 지정하면 path(은)는 절대값이 될 수 없습니다. CodeQL 팩의 루트를 기준으로 고려됩니다.

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

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

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

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

= 0.0.3 및 < 0.1.0(가장 호환되는 버전이 선택됨)인 codeql/cpp-queries CodeQL 팩의 버전에서 cpp-security-and-quality.qls 쿼리 도구 모음을 사용하여 데이터베이스를 분석하려면 다음을 사용할 수 있습니다.

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 쿼리 도구 모음 만들기"을(를) 참조하세요.

오염된 데이터의 잠재적 원본을 추가하기 위한 모델 팩 포함

참고: 위협 모델은 현재 베타 버전이며 변경될 수 있습니다. 베타 버전에서는 분석에서 위협 모델을 Java/Kotlin 및 C#용으로만 지원합니다.

code scanning 분석에서 위협 모델을 구성할 수 있습니다. 자세한 내용은 CodeQL 설명서의 “Threat models for Java and Kotlin” 및 “Threat models for 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 위협 모델을 사용해야 합니다.

결과

분석 결과를 SARIF 및 CSV를 비롯한 다양한 형식으로 저장할 수 있습니다.

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

CSV 형식의 결과 모습에 대한 자세한 내용은 "CodeQL CLI CSV 출력"(을)를 참조하세요.

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

로그 및 진단 정보 보기

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

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

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

다음 단계