CodeQL 팩을 사용하여 분석 사용자 지정

CodeQL 팩 정보

CodeQL 팩은 CodeQL 쿼리 및 라이브러리를 만들고, 공유하고, 사용하고, 실행하는 데 사용됩니다. CodeQL 팩에는 쿼리, 라이브러리 파일, 쿼리 도구 모음 및 메타데이터가 포함됩니다. 다른 사용자가 만든 팩을 다운로드하고 코드베이스에서 실행하여 CodeQL 분석을 사용자 지정할 수 있습니다.

CodeQL 팩은 세 개 유형이 있습니다. 쿼리 팩, 라이브러리 팩, 그리고 모델 팩입니다.

쿼리 팩에는 CodeQL 데이터베이스에서 평가할 수 있는 미리 컴파일된 쿼리 집합이 포함되어 있습니다. 쿼리 팩은 실행되도록 설계되었습니다. 쿼리 팩이 게시되면 번들에 쿼리 원본 외에도 각 쿼리의 모든 전이적 종속성과 미리 컴파일된 표현이 포함됩니다. 이렇게 하면 팩에서 쿼리를 일관되고 효율적으로 실행할 수 있습니다.
라이브러리 팩은 쿼리 팩(또는 다른 라이브러리 팩)에서 사용하도록 설계되었으며 쿼리 자체를 포함하지 않습니다. 라이브러리는 별도로 컴파일되지 않습니다.
code scanning 분석을 확장하여 기본적으로 지원되지 않는 라이브러리 및 프레임워크를 인식하는 데 모델 팩을 사용할 수 있습니다. 모델 팩은 현재 공개 미리 보기 버전이며 변경될 수 있습니다. 공개 미리 보기에서 모델 팩은 C#, Java/Kotlin, Python, and Ruby 분석에 사용할 수 있습니다. 자체 모델 팩을 만드는 방법에 대한 자세한 내용은 "CodeQL 팩 만들기 및 작업"을 참조하세요.

지원되는 모든 언어에 대한 표준 CodeQL 팩이 Container registry에 게시됩니다. CodeQL CLI를 표준 방식으로 설치한 경우 CodeQL CLI 번들을 사용하여 핵심 쿼리 팩을 이미 다운로드하여 사용할 수 있습니다. 화면은 다음과 같습니다.

codeql/cpp-queries
codeql/csharp-queries
codeql/go-queries
codeql/java-queries
codeql/javascript-queries
codeql/python-queries
codeql/ruby-queries
codeql/swift-queries

CodeQL CLI를 사용하여 자체 CodeQL 팩을 만들고, 팩에 종속성을 추가하고, 종속성을 설치하거나 업데이트할 수도 있습니다. 자세한 내용은 "CodeQL 팩 만들기 및 작업"을(를) 참조하세요.

CodeQL CLI을 사용하여 만든 CodeQL 팩을 게시할 수 있습니다. CodeQL 팩 게시 및 다운로드에 대한 자세한 내용은 "CodeQL 팩 게시 및 사용"을 참조하세요.

CodeQL 쿼리 팩 다운로드 및 사용

CodeQL CLI 번들에는 GitHub 전문가, 보안 연구원 및 커뮤니티 기여자들이 유지 관리하는 쿼리가 포함되어 있습니다. 다른 조직에서 개발한 쿼리를 실행하려는 경우, CodeQL 쿼리 팩을 사용하면 쿼리를 효율적이고 안정적으로 다운로드하고 실행할 수 있으며, 모델 팩(공개 미리 보기)을 사용하면 code scanning 분석을 확장해 기본적으로 지원되지 않는 라이브러리 및 프레임워크를 인식할 수 있습니다. 쿼리 팩에 대한 자세한 내용은 "CodeQL을 사용하는 코드 검사 안내"을 참조하세요. 자체 모델 팩을 작성하는 방법에 대한 자세한 내용은 "CodeQL 팩 만들기 및 작업"을(를) 참조하세요.

CodeQL 쿼리 팩을 사용하여 데이터베이스를 분석하려면 GitHub Container registry에서 필요한 패키지를 다운로드해야 합니다. 이 작업은 codeql database analyze 명령에서 --download 플래그를 사용하거나 codeql pack download를 실행하여 수행할 수 있습니다. 패키지를 공개적으로 사용할 수 없는 경우 GitHub App 또는 personal access token을 사용하여 인증해야 합니다. 자세한 내용과 예제는 "GitHub에 CodeQL 분석 결과 업로드"을(를) 참조하세요.

옵션	필수	사용
`<scope/name@version:path>`		쉼표로 구분된 목록을 사용하여 다운로드할 하나 이상의 CodeQL 쿼리 팩의 범위와 이름을 지정합니다. 필요에 따라 다운로드하고 압축을 풀 버전을 포함시킵니다. 기본적으로 이 팩의 최신 버전이 다운로드됩니다. 필요에 따라 실행할 쿼리, 디렉터리 또는 쿼리 모음의 경로를 포함시킵니다. 경로가 없으면 이 팩의 기본 쿼리를 실행합니다.
`--github-auth-stdin`		표준 입력을 통해 비밀 저장소에서 GitHub의 REST API를 사용하여 인증을 위해 만든 GitHub App 또는 personal access token을(를) CLI에 전달합니다. 명령이 이 토큰을 사용하여 설정된 `GITHUB_TOKEN` 환경 변수에 액세스할 수 있는 경우에는 이 항목이 필요하지 않습니다.

Note

사용할 특정 버전의 쿼리 팩을 지정하는 경우 지정한 버전이 너무 오래되어 최신 버전의 CodeQL을 효율적으로 사용할 수 없게 될 수 있습니다. 최적의 성능을 보장하려면 정확한 쿼리 팩 버전을 지정해야 하는 경우 사용 중인 CodeQL CLI를 업그레이드할 때마다 고정할 버전을 다시 평가해야 합니다.

팩 호환성에 대한 자세한 정보는 "CodeQL 팩 게시 및 사용"을(를) 참조하세요.

쿼리 팩 다운로드 및 사용의 기본 예

이 예제에서는 codeql database analyze 명령을 실행하고 --download 옵션을 선택하여 다음을 수행합니다.

최신 버전의 octo-org/security-queries 팩을 다운로드합니다.
버전 1.0.1과 _호환_되는 octo-org/optional-security-queries 팩 버전(이 예제에서는 버전 1.0.2)을 다운로드합니다. semver 호환성에 대한 자세한 내용은 npm의 의미 체계 버전 범위 설명서를 참조하세요.
octo-org/security-queries에서 모든 기본 쿼리를 실행합니다.
octo-org/optional-security-queries에서 queries/csrf.ql 쿼리만 실행합니다.

$ echo $OCTO-ORG_ACCESS_TOKEN | codeql database analyze --download /codeql-dbs/example-repo \
    octo-org/security-queries \
    octo-org/optional-security-queries@~1.0.1:queries/csrf.ql \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Download location: /Users/mona/.codeql/packages
> Installed fresh octo-org/security-queries@1.0.0
> Installed fresh octo-org/optional-security-queries@1.0.2
> Running queries.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> [1/2] Found in cache: /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> Starting evaluation of octo-org/security-queries/query1.ql.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> [2/2] Found in cache: /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> Starting evaluation of octo-org/optional-security-queries/queries/csrf.ql.
> [2/2 eval 694ms] Evaluation done; writing results to octo-org/security-queries/query1.bqrs.
> Shutting down query evaluator.
> Interpreting results.

CodeQL 팩 직접 다운로드

CodeQL 팩을 즉시 실행하지 않고 다운로드하려면 codeql pack download 명령을 사용합니다. 이 방법은 인터넷에 액세스하지 않고 CodeQL 쿼리를 실행할 때 유용합니다. CodeQL 분석을 실행하는 경우 이전 예제와 동일한 방식으로 팩, 버전 및 경로를 지정할 수 있습니다.

echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download <scope/name@version:path> <scope/name@version:path> ...

여러 GitHub 컨테이너 레지스트리에서 CodeQL 팩 다운로드

CodeQL 팩이 여러 컨테이너 레지스트리에 있는 경우 CodeQL CLI에 각 팩을 찾을 위치를 지시해야 합니다. 자세한 내용은 "코드 검색을 위한 고급 설정 사용자 지정"을(를) 참조하세요.

CodeQL 팩에서 실행할 쿼리 지정

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

scope/name(은)는 CodeQL 팩의 정규화된 이름입니다.
range(은)는 semver(의미론적 버전 관리) 범위입니다.
path는 단일 쿼리, 쿼리가 포함된 디렉터리 또는 쿼리 도구 모음 파일에 대한 파일 시스템 경로입니다.

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

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

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

쿼리 지정자 예

codeql/python-queries - codeql/python-queries 팩 최신 버전의 기본 쿼리 도구 모음에 있는 모든 쿼리입니다.
codeql/python-queries@1.2.3 - codeql/python-queries 팩 버전 1.2.3의 기본 쿼리 도구 모음에 있는 모든 쿼리입니다.
codeql/python-queries@~1.2.3 - codeql/python-queries 팩 최신 버전(1.2.3 이상 1.3.0 미만)의 기본 쿼리 도구 모음에 있는 모든 쿼리입니다.
codeql/python-queries:Functions - codeql/python-queries 팩 최신 버전에 있는 Functions 디렉터리의 모든 쿼리입니다.
codeql/python-queries@1.2.3:Functions - codeql/python-queries 팩 버전 1.2.3의 Functions 디렉터리에 있는 모든 쿼리입니다.
codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls - codeql/python-queries 팩 버전 1.2.3의 codeql-suites/python-code-scanning.qls 디렉터리에 있는 모든 쿼리입니다.
suites/my-suite.qls - 현재 작업 디렉터리를 기준으로 하는 suites/my-suite.qls 파일의 모든 쿼리입니다.

Tip

표준 CodeQL 쿼리 팩의 기본 쿼리 도구 모음은 codeql-suites/<lang>-code-scanning.qls입니다. 다른 몇 가지 유용한 쿼리 도구 모음은 각 팩의 codeql-suites 디렉터리에서도 찾을 수 있습니다. 예를 들어 codeql/cpp-queries 팩에는 다음 쿼리 도구 모음이 포함됩니다.

cpp-code-scanning.qls - C++용 표준 코드 검사 쿼리입니다. 이 팩의 기본 쿼리 도구 모음입니다.
cpp-security-extended.qls - C++용 기본 cpp-code-scanning.qls 도구 모음의 쿼리와 낮은 심각도, 정밀도 쿼리입니다.
cpp-security-and-quality.qls - cpp-security-extended.qls의 쿼리와 유지 관리 기능 및 안정성 쿼리입니다.

CodeQL 리포지토리에서 이러한 쿼리 도구 모음의 원본을 볼 수 있습니다. 다른 언어의 쿼리 도구 모음도 비슷합니다.

모델 팩을 사용하여 사용자 지정 종속성 호출 분석

code scanning 분석에 게시된 모델 팩을 --model-packs 옵션과 함께 사용할 수 있습니다. 예시:

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

이 예에서 표준 쿼리 팩 codeql/java-queries의 관련 쿼리는 모델 팩 my-repo/my-java-model-pack의 종속성 정보를 사용하여 해당 종속성을 호출하는 코드의 취약성을 확인합니다.

여러 번 게시된 모델 팩을 분석에서 지정할 수 있습니다.

자체 모델 팩 작성에 대한 자세한 내용은 "CodeQL 팩 만들기 및 작업"을 참조하세요.

게시된 팩 정보

팩이 분석에 사용하기 위해 게시되면 codeql pack create 또는 codeql pack publish 명령은 콘텐츠가 완료되었는지 확인하고 콘텐츠의 일부를 추가합니다.

쿼리 팩의 경우 해당 쿼리 팩이 개발된 정확한 버전의 각 라이브러리 팩의 복사본입니다. 쿼리 팩 사용자는 이러한 라이브러리 팩을 별도로 다운로드할 필요가 없습니다.
쿼리 팩의 경우 각 쿼리를 미리 컴파일한 표현입니다. 각 분석에서 쿼리에 대한 QL 원본을 컴파일하는 것보다 실행하는 것이 더 빠릅니다.

이 데이터의 대부분은 게시된 팩의 .codeql 디렉터리에 있지만 미리 컴파일된 쿼리는 각 쿼리의 .ql 원본 옆에 .qlx 접미사가 있는 파일에 있습니다. 게시된 팩의 쿼리를 사용하여 데이터베이스를 분석할 때 CodeQL은 .ql 원본 대신 이 파일을 로드합니다. 게시된 팩의 콘텐츠를 수정해야 하는 경우 .ql 파일의 수정이 적용되지 않게 할 수 있으므로 .qlx 파일을 모두 제거해야 합니다.