CodeQL CLI를 사용하여 데이터베이스 분석

CodeQL CLI을(를) 사용하여 데이터베이스 분석 정보

코드베이스를 분석하려면 코드에서 추출된 CodeQL 데이터베이스에 대해 쿼리를 실행합니다.

CodeQL 분석은 소스 코드에서 경고 또는 경로로 표시할 수 있는 해석된 결과를 생성합니다. 를 사용하여 실행할 database analyze쿼리를 작성하는 방법에 대한 자세한 내용은 "CodeQL CLI에서 사용자 지정 쿼리 사용"을 참조하세요.

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

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

실행하는 가장 간단한 방법은 codeql database analyze CodeQL 팩을 사용하는 것입니다. CodeQL 리포지토리의 로컬 체크 아웃에서 쿼리를 사용하여 명령을 실행할 수도 있습니다. CodeQL 핵심 쿼리를 사용자 지정하려는 경우 수행할 수 있습니다.

실행 중 codeql database analyze

를 실행하면 다음을 수행 database analyze합니다.

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

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

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

다음을 지정해야 합니다.

• <database>: 분석하려는 CodeQL 데이터베이스의 경로입니다.
• --format: 분석 중에 생성된 결과 파일의 형식입니다. CSV, SARIF 및 그래프 형식을 포함하여 다양한 형식이 지원됩니다. CSV 및 SARIF에 대한 자세한 내용은 결과를 참조 하세요. 지원되는 다른 결과 형식을 확인하려면 데이터베이스 분석 참조를 참조하세요.
• --output: 분석 중에 생성된 결과 파일의 출력 경로입니다.

다음을 지정할 수도 있습니다.

• <query-specifiers>...: 데이터베이스를 통해 실행할 공간으로 구분된 쿼리 목록입니다. 각 인수는 다음과 같은 인수 목록입니다.

  • 쿼리 파일의 경로
  • 쿼리 파일이 포함된 디렉터리의 경로
  • 쿼리 도구 모음 파일의 경로
  • CodeQL 쿼리 팩의 이름
    • 선택적 버전 범위 사용
    • 팩 내의 쿼리, 디렉터리 또는 쿼리 도구 모음에 대한 선택적 경로

  생략하면 분석된 데이터베이스의 언어에 대한 기본 쿼리 도구 모음이 사용됩니다. 쿼리 지정자의 전체 구문은 "CodeQL 팩에서 실행할 쿼리 지정"을 참조하세요.

• --sarif-category: 결과에 대한 식별 범주입니다. 커밋에 대해 둘 이상의 결과 집합을 업로드하려는 경우에 사용됩니다. 예를 들어 를 사용하여 github upload-results 둘 이상의 언어에 대한 결과를 GitHub 코드 검사 API로 보낼 수 있습니다. 이 사용 사례에 대한 자세한 내용은 CI 시스템에서 CodeQL CLI 구성을 참조하세요.

• --sarif-add-query-help: (버전 2.7.1 이상에서 지원됨)는 분석에 의해 생성된 SARIF 파일(v2.1.0 이상)에 markdown으로 작성된 사용자 지정 쿼리 도움말을 추가합니다. 분석을 실행하기 전에 파일에 저장된 .qhelp 쿼리 도움말을 로 .md 변환해야 합니다. 자세한 내용은 "SARIF 파일에서 사용자 지정 CodeQL 쿼리에 대한 쿼리 도움말 포함"을 참조하세요.

• --download: CLI가 로컬에서 사용할 수 없는 참조된 CodeQL 패키지를 다운로드할 수 있도록 하는 부울 플래그입니다. 이 플래그가 누락되고 참조된 CodeQL 패키지를 로컬로 사용할 수 없는 경우 명령이 실패합니다.

데이터베이스를 분석할 때 사용할 수 있는 모든 옵션에 대한 자세한 내용은 데이터베이스 분석 참조 설명서를 참조하세요.

CodeQL 팩에서 실행할 쿼리 지정

쿼리 지정자는 및 쿼리 집합에서 작동하는 다른 명령에서 사용됩니다 codeql database analyze . 쿼리 지정자의 전체 형식은 입니다 scope/name@range:path. 여기서:

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

• range 는 셈버 범위입니다.

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

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

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

및 path를 scope/name 모두 지정하는 경우 는 path 절대일 수 없습니다. CodeQL 팩의 루트를 기준으로 간주합니다.

예제 쿼리 지정자

• codeql/python-queries - 팩의 최신 버전의 기본 쿼리 도구 모음에 있는 모든 쿼리입니다 codeql/python-queries .

• codeql/[email protected] - 팩 버전의 1.2.3 기본 쿼리 도구 모음에 있는 모든 쿼리입니다 codeql/python-queries .

• codeql/python-queries@~1.2.3- >= 1.2.3 < 1.3.0팩의 codeql/python-queries 최신 버전의 기본 쿼리 도구 모음에 있는 모든 쿼리입니다.

• codeql/python-queries:Functions - 최신 버전의 팩에 Functions 있는 디렉터리의 모든 쿼리입니다 codeql/python-queries .

• codeql/[email protected]:Functions- 팩 버전 1.2.3의 codeql/python-queries 디렉터리에 있는 모든 쿼리 Functions 입니다.

• codeql/[email protected]:codeql-suites/python-code-scanning.qls- 팩 버전 1.2.3의 codeql/python-queries 디렉터리에 있는 모든 쿼리 codeql-suites/python-code-scanning.qls 입니다.

• suites/my-suite.qls - 현재 작업 디렉터리를 기준으로 하는 파일의 모든 쿼리 suites/my-suite.qls 입니다.

데이터베이스 분석 실행 예제

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

단일 쿼리 실행

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

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

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

분석은 새 디렉터리()에서 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에서 사용자 지정 쿼리 사용"을 참조하세요.

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

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

예를 들어 쿼리 팩의 디렉터리에 포함된 모든 Python 쿼리를 Functions 실행하려면 다음을 codeql/python-queries 실행합니다.

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 사양에 따라 결과의 형식이 지정됩니다.

쿼리 도구 모음 실행

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 쿼리 팩을 다운로드 codeql/cpp-queries 하고, 분석을 실행하고, 모든 버전의 GitHub에서 지원하는 SARIF 버전 2.1.0 형식의 파일을 생성합니다. 이 파일은 또는 코드 검사 API를 codeql github upload-results 실행하여 GitHub에 업로드할 수 있습니다. 자세한 내용은 "CodeQL 데이터베이스 분석" 또는 "코드 검사 API"를 참조하세요.

CodeQL 쿼리 도구 모음은 .qls 지시문을 사용하여 특정 메타데이터 속성에 따라 실행할 쿼리를 선택하는 파일입니다. 표준 CodeQL 팩에는 코드 검사에서 사용하는 쿼리 도구 모음의 위치를 지정하는 메타데이터가 있으므로 CodeQL CLI는 이러한 제품군 파일을 자동으로 찾을 위치를 알고 명령줄에서 전체 경로를 지정할 필요가 없습니다. 자세한 내용은 "CodeQL 쿼리 도구 모음 만들기"를 참조하세요.

사용자 지정 쿼리 도구 모음을 만드는 방법에 대한 자세한 내용은 "CodeQL 쿼리 도구 모음 만들기"를 참조하세요.

진단 및 요약 정보

CodeQL 데이터베이스를 만들 때 추출기는 진단 데이터를 데이터베이스에 저장합니다. 코드 검사 쿼리 도구 모음에는 이 진단 데이터를 보고하고 요약 메트릭을 계산하는 추가 쿼리가 포함됩니다. 명령이 database analyze 완료되면 CLI는 결과 파일을 생성하고 진단 및 요약 데이터를 표준 출력에 보고합니다. SARIF 출력을 생성하도록 선택하면 추가 데이터도 SARIF 파일에 포함됩니다.

분석 결과 표준 쿼리에 대한 결과가 예상보다 적으면 진단 및 요약 쿼리의 결과를 검토하여 CodeQL 데이터베이스가 분석하려는 코드베이스의 좋은 표현일 가능성이 있는지 확인합니다.

CodeQL 팩을 GitHub의 코드 검사 워크플로에 통합

코드 검사 설정에서 CodeQL 쿼리 팩을 사용할 수 있습니다. 이렇게 하면 다양한 원본에서 게시한 쿼리 팩을 선택하고 이를 사용하여 코드를 분석할 수 있습니다. 자세한 내용은 "CodeQL 작업에서 CodeQL 쿼리 팩 사용" 또는 "CI 시스템에서 CodeQL 쿼리 팩 다운로드 및 사용"을 참조하세요.

SARIF 파일에서 사용자 지정 CodeQL 쿼리에 대한 쿼리 도움말 포함

CodeQL CLI를 사용하여 타사 CI/CD 시스템에서 코드 검사 분석을 실행하는 경우 분석 중에 생성된 SARIF 파일에 사용자 지정 쿼리에 대한 쿼리 도움말을 포함할 수 있습니다. SARIF 파일을 GitHub에 업로드하면 사용자 지정 쿼리에서 생성된 경고에 대한 쿼리 도움말이 코드 검사 UI에 표시됩니다.

CodeQL CLI v2.7.1 이상에서 를 실행할 codeql database analyze때 옵션을 제공하여 SARIF 파일에 markdown 렌더링 쿼리 도움말을 --sarif-add-query-help 포함할 수 있습니다. 자세한 내용은 CI 시스템에서 CodeQL CLI 구성을 참조하세요.

사용자 지정 쿼리에 대한 쿼리 도움말을 markdown 파일에 직접 작성하고 해당 쿼리와 함께 저장할 수 있습니다. 또는 표준 CodeQL 쿼리와의 일관성을 위해 형식으로 쿼리 도움말을 .qhelp 작성할 수 있습니다. 파일에 기록된 .qhelp 쿼리 도움말은 SARIF 파일에 포함될 수 없으며 코드 검사로 처리할 수 없으므로 분석을 실행하기 전에 markdown으로 변환해야 합니다. 자세한 내용은 "쿼리 도움말 파일" 및 "쿼리 도움말 파일 테스트"를 참조하세요.

결과

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

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

CSV 형식으로 결과를 생성하도록 선택하면 출력 파일의 각 줄이 경고에 해당합니다. 각 줄은 다음 정보가 포함된 쉼표로 구분된 목록입니다.

속성	설명	예제
이름	결과를 식별한 쿼리의 이름입니다.	Inefficient regular expression
Description	쿼리에 대한 설명입니다.	A regular expression that requires exponential time to match certain inputs can be a performance bottleneck, and may be vulnerable to denial-of-service attacks.
심각도	쿼리의 심각도입니다.	error
메시지	경고 메시지.	This part of the regular expression may cause exponential backtracking on strings containing many repetitions of '\\\\'.
경로	경고가 포함된 파일의 경로입니다.	/vendor/codemirror/markdown.js
시작 줄	경고를 트리거한 코드가 시작되는 파일의 줄입니다.	617
시작 열	경고 코드의 시작을 표시하는 시작 줄의 열입니다. 1과 같으면 포함되지 않습니다.	32
끝선	경고를 트리거한 코드가 끝나는 파일의 줄입니다. 시작 줄과 동일한 값이 있는 경우에는 포함되지 않습니다.	64
끝 열	사용 가능한 경우 경고 코드의 끝을 표시하는 끝 줄의 열입니다. 그렇지 않으면 끝 줄이 반복됩니다.	617

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

추가 참고 자료

• "VS Code용 CodeQL에서 프로젝트 분석"