CodeQL 쿼리 팩 참조

CodeQL 팩 호환성

쿼리 팩이 게시되면 분석 속도를 높이기 위해 쿼리 팩에 포함된 모든 쿼리의 미리 컴파일된 표현이 포함됩니다. 그러나 분석을 수행하는 CodeQL 버전이 실행된 codeql pack publish버전보다 6개월 이상 최신 버전인 경우 분석 중에 원본에서 쿼리를 컴파일하여 프로세스가 크게 느려질 수 있습니다.

CodeQL의 최신 공개 릴리스에서 게시한 팩은 code scanning 및 GitHub Actions에서 사용되는 약간 더 오래된 버전의 CodeQL에서도 사용할 수 있습니다.

분석에 다음과 같은 줄이 포함된 경우 CodeQL이(가) 미리 컴파일된 쿼리를 성공적으로 사용하고 있습니다.

[42/108] Loaded /long/path/to/query/Filename.qlx.

분석에 다음과 같은 줄이 포함되어 있는 경우, CodeQL이(가) 원본에서 쿼리를 수동으로 다시 컴파일한 것입니다.

Compiling query plan for /long/path/to/query/Filename.ql.
[42/108 comp 25s] Compiled /long/path/to/query/Filename.ql.

쿼리 팩 사용자가 미리 컴파일된 쿼리의 혜택을 최대한 누리도록, CodeQL의 최신 릴리스를 사용하여 팩을 발행할 것을 권장합니다. 또한 6개월마다 CodeQL의 업데이트된 버전을 포함한 새 패키지를 게시해야 합니다.

번들로 묶인 CodeQL 이진 파일을 사용하는 GitHub Enterprise Server 설치에 쿼리 팩을 사용하려는 목적으로 게시하려는 경우 동일한 CodeQL 버전을 사용하여 codeql pack publish를 실행합니다.

          `qlpack.yml` 파일

쿼리 관련 명령을 실행할 때 CodeQL는 먼저 설치 디렉터리(및 해당 하위 디렉터리) qlpack.yml 의 형제에서 파일을 찾은 다음 패키지 캐시에서 다운로드한 CodeQL 팩을 확인합니다. 즉, 설치 디렉터리의 로컬 패키지가 패키지 캐시에서 동일한 이름의 패키지를 재정의하면 로컬 변경 내용을 테스트할 수 있습니다.

각 qlpack.yml 파일의 메타데이터는 CodeQL에게 팩의 쿼리를 컴파일하는 방법, 팩이 의존하는 라이브러리 및 쿼리 도구 모음 정의를 찾을 수 있는 위치를 알려줍니다.

CodeQL 팩의 내용(CodeQL 분석에 사용되는 쿼리 또는 라이브러리)은 qlpack.yml 또는 해당 하위 디렉터리와 동일한 디렉터리에 포함됩니다.

          `qlpack.yml` 파일이 포함된 디렉터리가 CodeQL 팩의 콘텐츠에 대한 루트 디렉터리 역할을 합니다. 즉, 팩의 모든 `.ql` 파일과 `.qll` 파일의 경우 CodeQL은(는) 팩의 루트에 있는 `qlpack.yml` 파일이 포함된 디렉터리를 기준으로 모든 가져오기 문을 확인합니다.

          `qlpack.yml` 속성

다음과 같은 속성이 qlpack.yml 파일에 지원됩니다.

`name`

모든 팩에 필요합니다.
CodeQL 팩이 게시된 팩의 범위와 영숫자 문자 및 하이픈을 사용하여 정의된 팩의 이름을 정의합니다. CodeQL은(는) 이름이 동일한 CodeQL 팩을 구분할 수 없으므로 고유해야 합니다. 팩 이름을 사용하여, database analyze(을)를 사용하여 실행할 쿼리를 지정하고 CodeQL 팩 간에 종속성을 정의합니다(아래 예시 참조). 다음은 그 예입니다.
```
name: octo-org/security-queries
```

`version`

게시된 모든 팩에 필요합니다.

        [SemVer v2.0.0 사양](http://semver.org/spec/v2.0.0.html)을 준수해야 하는 이 CodeQL 팩의 의미 체계 버전을 정의합니다. 다음은 그 예입니다.

version: 0.0.0

`dataExtensions`

모델 팩에 필요합니다.
쿼리 팩 또는 라이브러리 팩의 루트를 기준으로 데이터 확장 파일의 위치를 지정하는 GLOB 패턴 목록을 가져옵니다.

`dependencies`

다른 팩에 대한 CodeQL 패키지 종속성을 정의하는 쿼리 및 라이브러리 팩에 필요합니다. 모델 팩은 종속성을 정의하고 extensionTargets를 대신 사용할 수 없습니다.
팩 참조에서 이 팩과 호환되는 의미 체계 버전 범위에 대한 맵을 정의합니다. CodeQL CLI 버전 v2.6.0 이상에서 지원됩니다. 다음은 그 예입니다.
```
dependencies:
  codeql/cpp-all: ^0.0.2
```
어떤 버전을 사용해야 할지 잘 모르거나 사용할 중요하지 않은 경우, 이 종속성의 모든 버전이 이 팩과 호환됨을 나타내는 "*"를 사용할 수 있습니다. 실제로 이 문제는 일반적으로 가장 많이 게시된 종속성 버전으로 해결될 수 있는 경우가 많습니다.

특수 버전 자리 표시자인 ${workspace}가 있으며, 이는 이 CodeQL 팩이 동일한 작업 영역에 있는 종속성의 어떤 버전에 종속되어 있음을 나타냅니다. 자세한 내용은 CodeQL 작업 영역에 대해을(를) 참조하세요.

`defaultSuiteFile`

실행할 기본 쿼리 집합을 내보내는 팩에 필요합니다.
이 팩이 codeql database analyze 명령에 전달될 때 기본적으로 실행되는 모든 쿼리를 포함하는 패키지 루트를 기준으로 쿼리 도구 모음 파일의 경로를 정의합니다. CLI 버전 v2.6.0 이상에서 지원됩니다. defaultSuiteFile 또는 defaultSuite 중 하나만 정의할 수 있습니다. 다음은 그 예입니다.
```
defaultSuiteFile: cpp-code-scanning.qls
```

`defaultSuite`

실행할 기본 쿼리 집합을 내보내는 팩에 필요합니다.
이 팩이 codeql database analyze 명령에 전달될 때 기본적으로 실행되는 모든 쿼리를 포함하는 인라인 쿼리 도구 모음을 정의합니다. CLI 버전 v2.6.0 이상에서 지원됩니다. defaultSuiteFile 또는 defaultSuite 중 하나만 정의할 수 있습니다. 다음은 그 예입니다.
```
defaultSuite:
  queries: .
  exclude:
    precision: medium
```

`extensionTargets`

모델 팩에 필요합니다.
모델 팩의 확장이 적용되는 쿼리 팩을 선언합니다. 확장 팩이 지정된 버전 범위에 속하고 평가에 사용되는 경우, 확장 팩은 extensionTargets 디렉터리에 이름이 지정된 각 팩에 데이터 확장을 삽입합니다.

`groups`

Optional.
CodeQL 작업 영역에서 팩의 논리적 그룹화를 정의합니다. 그룹을 사용하면 작업 영역의 팩 하위 집합에 팩 작업을 적용할 수 있습니다. 예를 들어 다음 팩은 java 및 experimental 그룹의 일부로 정의됩니다.
```
groups:
  - java
  - experimental
```
```
        `codeql pack publish --groups java,-experimental`을 실행하면 `java` 팩을 _제외한_`experimental` 그룹의 모든 팩을 게시합니다. 
        `codeql pack ls --groups [-]<group>[,[-]<group>...]` 명령을 실행하여 지정된 그룹 집합과 일치하는 작업 영역의 팩을 나열할 수 있습니다.
```
다음과 같은 경우 지정된 작업 영역의 CodeQL 팩이 목록에 포함됩니다.
- 마이너스 기호 없이 나열된 그룹 중 하나에 속하며(마이너스 기호 없이 그룹이 나열되지 않은 경우 이 조건은 자동으로 충족됨), 그리고
- 이는 마이너스 기호로 나열된 어떤 그룹에도 속하지 않습니다.

`library`

라이브러리 팩에 필요합니다.
이 팩이 라이브러리 팩인지 여부를 나타내는 부울 값을 정의합니다. 라이브러리 팩은 쿼리를 포함하지 않으며 컴파일되지 않습니다. 쿼리 팩은 이 필드를 무시하거나 명시적으로 false로 설정할 수 있습니다. 다음은 그 예입니다.
```
library: true
```

`suites`

쿼리 도구 모음을 정의하는 팩의 경우 선택 사항입니다. 이를 통해 사용자는 전체 경로를 제공하지 않고 팩 이름을 지정하여 지정된 디렉터리에 저장된 쿼리 도구 모음을 실행할 수 있습니다.
현재 CodeQL CLI 번들에 포함된 표준 쿼리 팩에 대해서만 지원됩니다.
이 옵션은 GitHub 컨테이너 레지스트리에서 다운로드한 CodeQL 팩에는 지원되지 않습니다.

`tests`

CodeQL 테스트를 포함하는 팩의 경우 선택 사항입니다. 테스트가 없는 팩의 경우 무시됩니다.
팩 디렉터리를 기준으로 정의된 테스트를 포함하는 팩 내 디렉터리로의 경로를 정의합니다. 전체 팩을 지정하는 데 .(을)를 사용합니다. 이 디렉터리의 모든 쿼리는 test run 옵션을 사용하여 --strict-test-discovery(이)가 실행되면 테스트로 실행됩니다. 이러한 쿼리는 특정 팩의 모든 쿼리를 요청하는 queries 또는 qlpack 명령을 사용하는 쿼리 도구 모음 정의에서 무시됩니다. 이 속성이 없으면 .(을)를 가정합니다. 다음은 그 예입니다.
```
tests: .
```

`extractor`

CodeQL 테스트를 포함하는 모든 팩에 필요합니다.
팩에서 CodeQL 테스트를 실행할 때 사용할 CodeQL 언어 추출기를 정의합니다. 쿼리 테스트에 대한 자세한 내용은 사용자 지정 쿼리 테스트을(를) 참조하세요. 다음은 그 예입니다.
```
extractor: javascript-typescript
```

`authors`

Optional.
CodeQL 팩이 게시된 계정의 패키지 섹션에 있는 패키징 검색 페이지에 표시될 메타데이터를 정의합니다. 다음은 그 예입니다.
```
authors: author1@github.com,author2@github.com
```

`license`

Optional.
CodeQL 팩이 게시된 계정의 패키지 섹션에 있는 패키징 검색 페이지에 표시될 메타데이터를 정의합니다. 허용되는 라이선스 목록은 SPDX 사양의 SPDX 라이선스 목록을 참조하세요. 다음은 그 예입니다.
```
license: MIT
```

`description`

Optional.
CodeQL 팩이 게시된 계정의 패키지 섹션에 있는 패키징 검색 페이지에 표시될 메타데이터를 정의합니다. 다음은 그 예입니다.
```
description: Human-readable description of the contents of the CodeQL pack.
```

`libraryPathDependencies`

선택 사항으로, 사용되지 않음입니다. 대신 dependencies 속성을 사용합니다.
이전에는 이 CodeQL 팩이 종속된 CodeQL 팩의 이름을 배열로 정의하는 데 사용되었습니다. 이를 통해 팩이 종속성에 정의된 모든 라이브러리, 데이터베이스 스키마 및 쿼리 도구 모음에 액세스할 수 있습니다. 다음은 그 예입니다.
```
libraryPathDependencies: codeql/javascript-all
```

`dbscheme`

핵심 언어 팩에만 필요합니다.
이 CodeQL 언어용으로 작성된 모든 라이브러리 및 쿼리에 대한 데이터베이스 스키마 경로를 정의합니다(아래 예시 참조). 다음은 그 예입니다.
```
dbscheme: semmlecode.python.dbscheme
```

`upgrades`

핵심 언어 팩에만 필요합니다.
팩 디렉터리를 기준으로 정의된 데이터베이스 업그레이드 스크립트를 포함하는 팩 내 디렉터리로의 경로를 정의합니다. 데이터베이스 업그레이드는 다른 버전의 CodeQL CLI(으)로 만든 데이터베이스가 현재 버전의 CLI와 호환되는지 확인하기 위해 내부적으로 사용됩니다. 다음은 그 예입니다.
```
upgrades: .
```

`warnOnImplicitThis`

Optional. false 속성이 정의되지 않은 경우 기본적으로 warnOnImplicitThis로 설정됩니다.
컴파일러가 명시적 수신기 없이 암시적 this 호출 수신기가 있는 멤버 조건자 호출에 대한 경고를 내보내야 하는지 여부를 지정하는 부울을 정의합니다. CodeQL CLI v2.13.2부터 이용할 수 있습니다. 다음은 그 예입니다.
```
warnOnImplicitThis: true
```

          `codeql-pack.lock.yml` 파일

          `codeql-pack.lock.yml` 파일은 CodeQL 팩의 확인된 전이적 종속성의 버전을 저장합니다. 이 파일은 아직 존재하지 않고 버전 제어 시스템에 추가되어야 하는 경우 `codeql pack install` 명령에 의해 만들어집니다. 
          `dependencies` 파일의 `qlpack.yml` 섹션에는 팩과 호환되는 버전 범위가 포함되어 있습니다. 
          `codeql-pack.lock.yml` 파일은 버전을 정확한 종속성으로 잠급니다. 이를 통해 이 팩에서 `codeql pack install`을 실행하면 호환되는 최신 버전이 있더라도 항상 동일한 버전의 종속성을 검색하게 됩니다.

예를 들어 qlpack.yml 파일에 다음 종속성이 포함되어 있는 경우는 다음과 같습니다.

dependencies:
  codeql/cpp-all: ^0.1.2
  my-user/my-lib: ^0.2.3
  other-dependency/from-source: "*"

          `codeql-pack.lock.yml` 파일에는 다음과 같은 내용이 포함됩니다.

dependencies:
  codeql/cpp-all:
    version: 0.1.4
  my-user/my-lib:
    version: 0.2.4
  my-user/transitive-dependency:
    version: 1.2.4

          `codeql/cpp-all` 종속성은 버전 0.1.4로 잠깁니다. 
          `my-user/my-lib` 종속성은 버전 0.2.4로 잠깁니다. 전이적 종속성이며 `my-user/transitive-dependency` 파일에 지정되지 않은 `qlpack.yml`는 버전 1.2.4로 잠깁니다. 원본에서 해결되므로 잠금 파일에 `other-dependency/from-source`가 없습니다. 이 종속성은 팩과 동일한 CodeQL 작업 영역에서 사용할 수 있어야 합니다. CodeQL 작업 영역 및 원본의 종속성 확인에 대한 자세한 내용은 [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces)을(를) 참조하세요.

대부분의 경우 라이브러리 팩은 실행 불가능하며 일반적으로 전이적 종속성을 수정할 필요가 없으므로 codeql-pack.lock.yml 파일은 쿼리 팩과만 관련이 있습니다. 이는 테스트를 포함하는 라이브러리 팩에 대한 예외입니다. 이 경우 codeql-pack.lock.yml 파일은 일치하지 않는 종속성이 있을 때 가짜 오류를 방지하기 위해 항상 동일한 버전의 종속성으로 테스트를 실행하도록 하는 데 사용됩니다.

CodeQL 사용자 지정 패키지 예제

사용자 지정 쿼리 및 테스트용 파일을 별도의 팩에 저장하고 사용자 지정 팩을 각 대상 언어의 특정 폴더로 구성해야 합니다.

사용자 지정 라이브러리용 CodeQL 팩

쿼리 또는 테스트가 없는 사용자 지정 C++ 라이브러리가 포함된 사용자 지정 CodeQL 팩에 다음을 포함한 qlpack.yml 파일이 있을 수도 있습니다.

name: my-github-user/my-custom-libraries
version: 1.2.3
library: true
dependencies:
  codeql/cpp-all: ^0.1.2

여기서 codeql/cpp-all(은)는 CodeQL 리포지토리에 포함된 C/C++ 분석용 CodeQL 팩의 이름입니다. 버전 범위 ^0.1.2(은)는 이 팩이 codeql/cpp-all보다 크거나 같고 0.1.2보다 작은 0.2.0의 모든 버전과 호환됨을 나타냅니다. 이 팩에 정의된 CodeQL 라이브러리 파일(.qll 확장명 파일)은 종속성 블록에 이 팩을 갖고 있는 쿼리 팩에 정의된 쿼리에 사용할 수 있습니다.

          `library` 속성은 이 팩이 라이브러리 팩이며 쿼리를 포함하지 않음을 나타냅니다.

사용자 지정 쿼리용 CodeQL 팩

사용자 지정 C++ 쿼리 및 라이브러리가 포함된 사용자 지정 CodeQL 팩에 다음이 포함된 qlpack.yml 파일이 있을 수도 있습니다.

name: my-github-user/my-custom-queries
version: 1.2.3
dependencies:
  codeql/cpp-all: ^0.1.2
  my-github-user/my-custom-libraries: ^1.2.3

여기서 codeql/cpp-all(은)는 CodeQL 리포지토리에 포함된 C/C++ 분석용 CodeQL 팩의 이름입니다. 버전 범위 ^0.1.2(은)는 이 팩이 codeql/cpp-all보다 크거나 같고 0.1.2보다 작은 0.2.0의 모든 버전과 호환됨을 나타냅니다. my-github-user/my-custom-libraries(은)는 C++용 사용자 지정 CodeQL 라이브러리가 포함된 CodeQL 팩의 이름입니다. 이 팩에 정의된 CodeQL 라이브러리 파일(.qll 확장명 파일)은 my-github-user/my-custom-queries 팩에서 쿼리할 수 있습니다.

사용자 지정 테스트용 CodeQL 팩

테스트 파일이 포함된 사용자 지정 CodeQL 팩의 경우, extractor 명령에서 테스트 데이터베이스를 만드는 방법을 알 수 있도록 test run 속성도 포함해야 합니다. 또한 tests 속성을 지정할 수도 있습니다.

다음 qlpack.yml 파일은 1.2.3보다 크거나 같은 버전과 2.0.0보다 작은 버전에 my-github-user/my-query-tests따라 달라집니다 my-github-user/my-custom-queries . 또한 CLI는 테스트 데이터베이스를 만들 때 Java extractor을(를) 사용해야 한다고 선언합니다. 이 tests: . 줄은 --strict-test-discovery 옵션을 사용하여 실행할 때 팩의 모든 .ql 파일을 테스트로 codeql test run실행해야 한다고 선언합니다. 일반적으로 테스트 팩에는 version 속성이 포함되지 않습니다. 이렇게 하면 실수로 게시되지 않습니다.

name: my-github-user/my-query-tests
dependencies:
  my-github-user/my-custom-queries: ^1.2.3
extractor: java-kotlin
tests: .

테스트 실행에 대한 자세한 내용은 사용자 지정 쿼리 테스트을(를) 참조하세요.

CodeQL 리포지토리의 CodeQL 패키지 예제

CodeQL 리포지토리의 각 언어에는 다음 4개의 기본 CodeQL 팩이 있습니다.

언어에 사용되는 데이터베이스 스키마와 CodeQL 라이브러리 및 쿼리가 포함된 언어용 핵심 라이브러리 팩은 <language>/ql/lib에 있습니다.
언어에 대한 기본 쿼리와 해당 쿼리 도구 모음이 포함된 언어의 핵심 쿼리 팩은 <language>/ql/src에 있습니다.
핵심 언어 라이브러리 및 쿼리에 대한 테스트는 <language>/ql/test에 있습니다.
언어용 예시 쿼리는 <language>/ql/examples에 있습니다.

핵심 라이브러리 팩

다음은 C/C++ 분석 라이브러리 핵심 언어 팩에 대한 예시 qlpack.yml 파일입니다.

name: codeql/cpp-all
version: x.y.z-dev
dbscheme: semmlecode.cpp.dbscheme
library: true
upgrades: upgrades

다음 속성에 대한 몇 가지 추가 정보:

        `library`: 실행 가능한 쿼리가 없는 라이브러리 팩임을 나타냅니다. 이는 다른 팩에 대한 종속성으로만 사용됩니다.

        `dbscheme` 및 `upgrades`: 이러한 속성은 CodeQL CLI의 내부 속성이며 언어의 핵심 CodeQL 쿼리 팩에만 정의되어야 합니다.

핵심 쿼리 팩

다음은 qlpack.yml 파일입니다. 이는 C/C++ 분석 쿼리 핵심 쿼리 팩에 대한 예시입니다.

name: codeql/cpp-queries
version: x.y.z-dev
dependencies:
    codeql/cpp-all: "*"
    codeql/suite-helpers: "*"
suites: codeql-suites
defaultSuiteFile: codeql-suites/cpp-code-scanning.qls

다음 속성에 대한 몇 가지 추가 정보:

        `dependencies`: 이 쿼리 팩은 `codeql/cpp-all` 및 `codeql/suite-helpers`에 의존합니다. 이러한 종속성은 원본에서 확인되므로 호환되는 CodeQL 팩의 버전은 중요하지 않습니다. 원본에서 종속성을 확인하는 방법에 대한 자세한 정보는 [원본 종속성](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces#source-dependencies)을 참조하세요.

        `suites`: "잘 알려진" 쿼리 도구 모음이 포함된 디렉터리를 나타냅니다.

        `defaultSuiteFile`: 쿼리 도구 모음을 지정하지 않을 때 사용되는 기본 쿼리 도구 모음 파일의 이름입니다.

핵심 CodeQL 패키지 테스트

다음은 qlpack.yml 파일의 예시로, C/C++ 분석 테스트 핵심 테스트 팩에 대한 것입니다.

name: codeql/cpp-tests
dependencies:
  codeql/cpp-all: "*"
  codeql/cpp-queries: "*"
extractor: cpp
tests: .

다음 속성에 대한 몇 가지 추가 정보:

        `dependencies`: 이 팩은 핵심 CodeQL 쿼리 및 C++용 라이브러리 팩에 따라 달라집니다.

        `extractor`: 모든 테스트가 동일한 C++ 추출기를 사용하여 테스트용 데이터베이스를 만들도록 지정합니다.

        `tests`: 테스트 위치를 지정합니다. 이 경우 테스트는 팩의 루트 폴더(및 모든 하위 폴더)에 있습니다.

        `version`: 테스트 팩에 대한 `version` 속성이 없습니다. 그러면 테스트 팩이 실수로 게시되지 않습니다.

누가 이 기능을 사용할 수 있나요?

이 문서의 내용

CodeQL 팩 호환성

`name`

`version`

`dataExtensions`

`dependencies`

`defaultSuiteFile`

`defaultSuite`

`extensionTargets`

`groups`

`library`

`suites`

`tests`

`extractor`

`authors`

`license`

`description`

`libraryPathDependencies`

`dbscheme`

`upgrades`

`warnOnImplicitThis`

CodeQL 사용자 지정 패키지 예제

사용자 지정 라이브러리용 CodeQL 팩

사용자 지정 쿼리용 CodeQL 팩

사용자 지정 테스트용 CodeQL 팩

CodeQL 리포지토리의 CodeQL 패키지 예제

핵심 라이브러리 팩

핵심 쿼리 팩

핵심 CodeQL 패키지 테스트