참고: 이 문서는 2023년 1월에 CodeQL 설명서 웹 사이트에서 마이그레이션되었습니다.
CodeQL 쿼리 도구 모음 만들기 정보
참고: 이 문서에서는 GitHub Enterprise Server 3.4의 초기 릴리스에 포함된 CodeQL CLI 2.7.6 번들에서 사용할 수 있는 기능에 대해 설명합니다.
사이트 관리자가 CodeQL CLI 버전을 최신 릴리스로 업데이트한 경우 최신 기능에 대한 자세한 내용은 이 문서의 GitHub Enterprise Cloud 버전을 참조하세요.
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
참고: 명령을 사용하여 codeql resolve queries /path/to/suite.qls
쿼리 도구 모음 정의에서 선택한 쿼리를 확인할 수 있습니다. 자세한 내용은 쿼리 확인 참조 설명서를 참조하세요.
기존 쿼리 도구 모음 정의 다시 사용
기존 쿼리 도구 모음 정의는 다음을 지정하여 재사용할 수 있습니다.
-
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를 사용하여 데이터베이스 분석"을 참조하세요.