CodeQL 쿼리 도구 모음 만들기

CodeQL 쿼리 도구 모음 만들기 정보

CodeQL 쿼리 도구 모음은 파일 이름, 디스크 또는 CodeQL 팩의 위치, 또는 메타데이터 속성에 따라 쿼리를 선택하는 방법을 제공합니다. CodeQL 분석에서 자주 사용하려는 쿼리에 대한 쿼리 도구 모음을 만듭니다.

쿼리 도구 모음을 사용하면 각 쿼리 파일의 경로를 개별적으로 지정하지 않고도 여러 쿼리를 CodeQL에 전달할 수 있습니다. 쿼리 도구 모음 정의는 .qls 확장이 있는 YAML 파일에 저장됩니다. 도구 모음 정의는 명령 시퀀스로, 각 명령은 (일반적으로) 단일 키를 사용하는 YAML 매핑입니다. 명령은 쿼리 도구 모음 정의에 표시되는 순서대로 실행됩니다. 도구 모음 정의의 모든 명령이 실행된 후에는 선택한 쿼리 집합이 생성됩니다.

쿼리 도구 모음에 추가할 쿼리 찾기

쿼리 도구 모음을 만들 때 먼저 선택하려는 쿼리의 위치를 지정해야 합니다. 다음을 사용하여 하나 이상의 쿼리 위치를 정의할 수 있습니다.

• query 명령에서는 CodeQL에 지정된 .ql 파일을 하나 이상 찾도록 지시합니다.

  - query: <path-to-query>
  

  인수는 도구 모음의 정의를 포함하는 CodeQL 팩과 상대적인 하나 이상의 파일 경로여야 합니다.

• queries 명령에서는 CodeQL에 디렉터리에서 .ql 파일을 재귀적으로 검사하도록 지시합니다.

  - queries: <path-to-subdirectory>
  

  디렉터리의 경로는 도구 모음 정의 파일이 포함된 CodeQL 팩의 루트와 상대적이어야 합니다. 다른 CodeQL 팩 관련 쿼리를 찾으려면 from 필드를 추가합니다.

  - queries: <path-to-subdirectory>
    from: <ql-pack-name>
    version: ^x.y.z
  

  이 version 필드는 선택 사항이며 이 CodeQL 팩의 호환되는 버전 범위를 지정합니다. 버전을 지정하지 않는 경우 팩의 최신 버전이 사용됩니다.

• qlpack 명령은 CodeQL에게 CodeQL라는 이름의 팩의 기본 도구 모음에서 쿼리를 확인하도록 지시합니다.

  - qlpack: <qlpack-name>
    version: ^x.y.z
  

  쿼리 팩의 기본 도구 모음에는 해당 쿼리 팩 내에 권장되는 쿼리 집합이 포함되어 있습니다. 모든 쿼리 팩에 기본 도구 모음이 있는 것은 아닙니다. 제공된 쿼리 팩이 기본 도구 모음을 정의하지 않으면 qlpack 명령이 팩 내의 모든 쿼리를 확인합니다.

  이 version 필드는 선택 사항이며 이 CodeQL 팩의 호환되는 버전 범위를 지정합니다. 버전을 지정하지 않는 경우 팩의 최신 버전이 사용됩니다.

하나 이상의 query, queries 또는 qlpack 명령을 도구 모음 정의에 추가해야 합니다. 그렇지 않으면 쿼리가 선택되지 않습니다. 도구 모음에 추가 명령이 없는 경우 파일 목록, 지정된 디렉터리 또는 CodeQL로 명명된 팩에서 찾은 모든 쿼리가 선택됩니다. 추가 필터링 명령이 있는 경우 해당 명령으로 부과된 제약 조건과 일치하는 쿼리만 선택됩니다.

쿼리 도구 모음에서 쿼리 필터링

query, queries, 또는 qlpack 명령을 지정하여 도구 모음에 추가할 초기 쿼리 집합을 정의한 후에는 include 및 exclude 명령을 추가할 수 있습니다. 이러한 명령은 특정 속성에 따라 선택 조건을 정의합니다.

• 쿼리 집합에 대한 include 명령을 실행하면 조건과 일치하는 모든 쿼리가 선택 영역에 유지되고 일치하지 않는 쿼리는 제거됩니다.
• 쿼리 집합에 대한 exclude 명령을 실행하면 조건과 일치하는 모든 쿼리가 선택 영역에 제거되고 일치하지 않는 쿼리는 유지됩니다.

필터 명령의 순서가 중요합니다. 찾기 명령 이후에 표시되는 첫 번째 필터 명령은 쿼리가 기본적으로 포함되는지 아니면 제외되는지를 결정합니다. 첫 번째 필터가 include인 경우, 처음에 찾은 쿼리는 명시적 include 필터와 일치하는 경우에만 도구 모음의 일부가 됩니다. 첫 번째 필터가 exclude인 경우, 명시적으로 제외되지 않는 한 처음에 찾은 쿼리는 도구 모음의 일부입니다.

후속 지침은 순서대로 실행되며 파일의 뒷부분에 표시되는 지침이 이전 지침보다 우선합니다. 따라서 동일한 쿼리와 일치하는 이후 exclude 명령으로 include 명령을 재정의할 수 있습니다. 마찬가지로 exclude도 나중에 include로 재정의할 수 있습니다.

두 명령 모두 인수는 제약 조건 블록, 즉 제약 조건을 나타내는 YAML 맵입니다. 각 제약 조건은 맵 항목이며, 키는 일반적으로 쿼리 메타데이터 속성입니다. 다음 항목들이 값이 될 수 있습니다.

• 단일 문자열.
• /(으)로 묶인 정규식.
• 문자열, 정규식 또는 둘 다를 포함하는 목록.

제약 조건과 일치하려면 메타데이터 값이 문자열 또는 정규식 중 하나와 일치해야 합니다. 메타데이터 키가 두 개 이상 있는 경우 각 키를 일치시켜야 합니다. 일치시킬 수 있는 표준 메타데이터 키는 description, id, kind, name, tags, precision, problem.severity과 같습니다. 쿼리 메타데이터 속성에 대한 자세한 내용은 "CodeQL 쿼리에 대한 메타데이터"를 참조하세요.

메타데이터 태그 외에도 제약 조건 블록의 키는 다음과 같을 수 있습니다.

• query filename- 쿼리 파일 이름의 마지막 경로의 구성 요소와 일치합니다.
• query path- CodeQL 팩에 포함된 상대적인 쿼리 파일의 경로와 일치합니다.
• tags contain- 주어진 일치 문자열 중 하나가 @tags 메타데이터 속성 값의 공백으로 구분된 구성 요소 중 하나와 일치해야 합니다.
• tags contain all- 주어진 각 일치 문자열이 @tags 메타데이터 속성 값의 공백으로 구분된 구성 요소 중 하나와 일치해야 합니다.

실행되는 쿼리 필터링의 예

일반적인 사용 사례는 사용자가 실행하지 않으려는 몇 가지 특정 쿼리를 제외하고 CodeQL 팩의 모든 쿼리를 실행하는 쿼리 도구 모음을 만드는 것입니다. 일반적으로 각 쿼리에 대해 고유하고 안정적인 식별자인 쿼리 id를 필터링하는 것이 좋습니다. 다음 세 개의 쿼리 도구 모음 정의는 의미상 동일하며 쿼리 id에 의해 필터링됩니다.

해당 필터는 제외된 식별자가 있는 두 쿼리를 제외하고 codeql/cpp-queries의 기본 도구 모음에 있는 모든 쿼리와 일치합니다.

- qlpack: codeql/cpp-queries
- exclude:
    id:
      - cpp/cleartext-transmission
      - cpp/cleartext-storage-file

이 예제에서는 각 쿼리별로 별도의 exclude 명령이 사용됩니다.

- qlpack: codeql/cpp-queries
- exclude:
    id: cpp/cleartext-transmission
- exclude:
    id: cpp/cleartext-storage-file

이 예제에서 정규식은 동일한 두 쿼리를 제외시킵니다. 또한 cpp/cleartext-로 시작하는 식별자를 사용하여 도구 모음에 추가되는 후속 쿼리는 제외됩니다.

- qlpack: codeql/cpp-queries
- exclude:
    id:
      - /^cpp\/cleartext-.*/

codeql/cpp-queries CodeQL 팩의 기본 도구 모음에서 모든 쿼리를 선택한 다음 보안 쿼리만 포함하도록 구체화하는 도구 모음을 정의하려면 다음을 사용합니다.

- qlpack: codeql/cpp-queries
- include:
    tags contain: security

my-custom-queries 디렉터리에서 @kind problem 및 @precision high를 가진 모든 쿼리를 선택하는 도구 모음을 정의하려면 다음을 사용합니다.

- queries: my-custom-queries
- include:
    kind: problem
    precision: very-high

다음 쿼리 도구 모음 정의는 위의 정의와 다르게 동작합니다. 이 정의는 다음과 같이 @kind problem _ 또는 _ @precision very-high 쿼리를 선택합니다.

- queries: my-custom-queries
- include:
    kind: problem
- include:
    precision: very-high

@problem.severity recommendation을 제외한 my-custom-queries 디렉터리에서 @kind problem이 있는 모든 쿼리를 선택하는 도구 모음을 만들려면 다음을 사용합니다.

- queries: my-custom-queries
- include:
    kind: problem
- exclude:
    problem.severity: recommendation

codeql/cpp-queries CodeQL 팩에서 @tag security 및 @precision high 또는 very-high이 있는 모든 쿼리를 선택하는 도구 모음을 만들려면 다음을 사용합니다.

- queries: .
  from: codeql/cpp-queries
- include:
    tags contain: security
    precision:
    - high
    - very-high

기존 쿼리 도구 모음 정의 재사용

다음을 지정하여 기존 쿼리 도구 모음 정의를 다시 사용할 수 있습니다.

• import 명령은 이전에 정의된 .qls 파일에서 선택한 쿼리를 현재 도구 모음에 추가합니다.

  - import: <path-to-query-suite>
  

  가져온 도구 모음의 경로는 현재 도구 모음의 정의를 포함하는 CodeQL 팩과 상대적이어야 합니다. 가져온 쿼리 도구 모음이 다른 QL 팩에 있는 경우 다음을 사용할 수 있습니다.

  - import: <path-to-query-suite>
    from: <ql-pack>
    version: ^x.y.z
  

  이 version 필드는 선택 사항이며 이 CodeQL 팩의 호환되는 버전 범위를 지정합니다. 버전을 지정하지 않는 경우 팩의 최신 버전이 사용됩니다.

  import 명령을 사용하여 추가된 쿼리는 후속 exclude 명령을 사용하여 필터링할 수 있습니다.

• apply 명령은 이전에 정의된 .qls 파일의 모든 명령을 현재 도구 모음에 추가합니다. .qls 파일에 적용된 명령은 apply 대신에 표시되는 것처럼 실행됩니다. 적용된 도구 모음의 모든 include 및 exclude 명령은 이전 명령에 의해 추가된 쿼리에도 적용됩니다.

  - apply: <path-to-query-suite>
  

  apply 명령은 .yml 파일에 저장된 재사용 가능한 조건 집합을 여러 쿼리 정의에 적용하는 데 사용할 수도 있습니다. 자세한 내용은 아래 예를 참조하십시오.

재사용 가능성 예제

여러 쿼리 도구 모음 정의에서 동일한 조건을 사용하려면 명령이 포함된 별도의 .yml 파일을 만듭니다. 예를 들어 다음을 reusable-instructions.yml이라는 파일에 저장합니다.

- include:
    kind:
    - problem
    - path-problem
    tags contain: security
    precision:
    - high
    - very-high

현재 쿼리 도구 모음과 동일한 CodeQL 팩에 reusable-instructions.yml을 추가합니다. 그런 다음 하나 이상의 쿼리 도구 모음에서 apply 명령을 사용하여 재사용 가능한 명령을 현재 도구 모음에 적용합니다. 예시:

- queries: queries/cpp/custom
- apply: reusable-instructions.yml

queries/cpp/custom에서 다시 사용할 수 있는 조건과 일치하는 쿼리만 포함하도록 쿼리를 필터링합니다.

다른 CodeQL 팩의 쿼리에서 reusable-instructions.yml을 사용하여 도구 모음 정의를 만들 수도 있습니다. .qls 파일이 쿼리와 동일한 CodeQL 팩에 있는 경우 apply 명령 바로 뒤에 from 필드를 추가할 수 있습니다.

# load queries from the default suite of my-org/my-other-custom-queries
- qlpack: my-org/my-other-custom-queries

# apply the reusable instructions from the my-org/my-custom-instructions CodeQL pack
- apply: reusable-instructions.yml
  from: my-org/my-custom-instructions
  version: ^1.2.3 # optional

import 명령의 일반적인 사용 사례는 다른 쿼리 도구 모음의 쿼리에 추가 필터를 적용하는 것입니다. 예를 들어 이 도구 모음은 cpp-security-and-quality 도구 모음을 필터링하여 low 및 medium 정밀도 쿼리를 제외시킵니다.

- import: codeql-suites/cpp-security-and-quality.qls
  from: codeql/cpp-queries
- exclude:
    precision:
      - low
      - medium

다른 도구 모음에서 가져온 쿼리를 include 하려는 경우의 구문은 약간 다릅니다.

- import: codeql-suites/cpp-security-and-quality.qls
  from: codeql/cpp-queries
- exclude: {}
- include:
    precision:
      - very-high
      - high

비어 있는 exclude 명령을 확인합니다. 이는 후속 include 명령이 가져온 도구 모음에서 쿼리를 필터링할 수 있도록 하는 데 필요합니다.

쿼리 도구 모음 이름 지정

다음 description 명령을 지정하여 쿼리 도구 모음의 이름을 제공할 수 있습니다.

- description: <name-of-query-suite>

쿼리 도구 모음 저장

.qls 확장이 있는 파일에 쿼리 도구 모음을 저장하고 CodeQL 팩에 추가합니다. 자세한 내용은 "CodeQL 팩을 사용하여 분석 사용자 지정"을(를) 참조하세요.

CodeQL로 쿼리 도구 모음 사용

.qls 파일을 허용하는 명령에 대해 명령줄에서 쿼리 도구 모음을 지정할 수 있습니다. 예를 들어 query compile을 사용하여 도구 모음 정의에서 선택한 쿼리를 컴파일하거나 database analyze을 사용하여 쿼리를 분석에 사용할 수 있습니다. GitHub Enterprise 데이터베이스 분석에 대한 자세한 내용은 "CodeQL 쿼리를 사용하여 코드 분석"(을)를 참조하세요.

추가 참고 자료

• "CodeQL 쿼리"