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

CodeQL 팩 정보

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

CodeQL 팩은 두 개 유형이 있습니다. 쿼리 팩과 라이브러리 팩입니다.

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

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

CodeQL 쿼리 팩 다운로드 및 사용

CodeQL CLI 번들에는 GitHub 전문가, 보안 연구원 및 커뮤니티 기여자들이 유지 관리하는 쿼리가 포함되어 있습니다. 다른 조직에서 개발한 쿼리를 실행하려는 경우, 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 환경 변수에 액세스할 수 있는 경우에는 이 항목이 필요하지 않습니다.

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

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

1. 최신 버전의 octo-org/security-queries 팩을 다운로드합니다.
2. 버전 1.0.1과 _호환_되는 octo-org/optional-security-queries 팩 버전(이 예제에서는 버전 1.0.2)을 다운로드합니다. semver 호환성에 대한 자세한 내용은 npm의 의미 체계 버전 범위 설명서를 참조하세요.
3. octo-org/security-queries에서 모든 기본 쿼리를 실행합니다.
4. 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 파일의 모든 쿼리입니다.