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 팩에서 찾은 모든 쿼리가 선택됩니다. 추가 필터링 지침이 있는 경우 해당 지침에 의해 부과된 제약 조건과 일치하는 쿼리만 선택됩니다.

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

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

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

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

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

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

• 단일 문자열입니다.
• 묶은 /정규식입니다.
• 문자열, 정규식 또는 둘 다를 포함하는 목록입니다.

제약 조건과 일치하려면 메타데이터 값이 문자열 또는 정규식 중 하나와 일치해야 합니다. 메타데이터 키가 두 개 이상 있는 경우 각 키를 일치시켜야 합니다. 에서 일치시킬 수 있는 표준 메타데이터 키는 , , , kind, , 및 입니다description``problem.severity. precision``tags``name``id 쿼리 메타데이터 속성에 대한 자세한 내용은 "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 팩의 codeql/cpp-queries 기본 제품군에서 모든 쿼리를 선택한 다음 보안 쿼리만 포함하도록 구체화하는 제품군을 정의하려면 다음을 사용합니다.

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

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

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

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

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

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

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

CodeQL 팩에서 또는 very-high @problem.severity high 를 사용하여 모든 쿼리 @tag security 를 codeql/cpp-queries 선택하는 제품군을 만들려면 다음을 사용합니다.

- queries: .
  from: codeql/cpp-queries
- include:
    tags contain: security
    problem.severity:
    - 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>

이 값은 codeql resolve 쿼리를 실행할 때 도구 모음이 "잘 알려진" 디렉터리에 추가되면 표시됩니다. 자세한 내용은 "잘 알려진 쿼리 도구 모음 지정"을 참조하세요.

CodeQL에서 쿼리 도구 모음 사용

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

추가 참고 자료

• "CodeQL 쿼리"