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/swift-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 파일의 모든 쿼리입니다.

게시된 팩 정보

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

• 쿼리 팩의 경우 해당 쿼리 팩이 개발된 정확한 버전의 각 라이브러리 팩의 복사본입니다. 쿼리 팩 사용자는 이러한 라이브러리 팩을 별도로 다운로드할 필요가 없습니다.

• 쿼리 팩의 경우 각 쿼리를 미리 컴파일한 표현입니다. 각 분석에서 쿼리에 대한 QL 원본을 컴파일하는 것보다 실행하는 것이 더 빠릅니다.

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