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

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

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

필수 조건

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

• CodeQL CLI을(를) 설정하여 명령을 로컬로 실행합니다.
• 분석하려는 소스 코드에 대한 CodeQL 데이터베이스를 만듭니다.

가장 간단한 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을 지정해야 합니다. 수행할 분석에 따라 추가 옵션을 지정할 수 있습니다.

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

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

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

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

예를 들어 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(을)를 지정하면 range 및 path(은)는 선택 사항입니다. 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 쿼리 도구 모음 만들기"을(를) 참조하세요.

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

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 분석 결과 업로드"을(를) 참조하세요.

다음 단계

• CodeQL 분석 결과를 GitHub Enterprise Cloud에 업로드하는 방법을 알아보려면 "GitHub에 CodeQL 분석 결과 업로드"(을)를 참조하세요.