참고: 이 문서는 2023년 1월에 CodeQL 설명서 웹 사이트에서 마이그레이션되었습니다.
추출기 정보
CodeQL CLI는 추출기라는 특수 프로그램을 사용하여 소프트웨어 시스템의 소스 코드에서 쿼리할 수 있는 데이터베이스로 정보를 추출합니다. CodeQL CLI을 통해 추출기 구성 옵션을 설정하여 추출기의 동작을 사용자 지정할 수 있습니다.
추출기 옵션 정보
각 추출기는 고유한 구성 옵션 집합을 정의합니다. 특정 추출기에서 사용할 수 있는 옵션을 확인하려면 또는 codeql resolve extractor
옵션을 실행 codeql resolve languages
하면 --format=betterjson
됩니다. 출력 형식은 betterjson
추출기의 루트 경로와 추가 정보를 제공합니다. 의 codeql resolve extractor --format=betterjson
출력은 종종 다음 예제와 같이 형식이 지정됩니다.
{
"extractor_root" : "/home/user/codeql/java",
"extractor_options" : {
"option1" : {
"title" : "Java extractor option 1",
"description" : "An example string option for the Java extractor.",
"type" : "string",
"pattern" : "[a-z]+"
},
"group1" : {
"title" : "Java extractor group 1",
"description" : "An example option group for the Java extractor.",
"type" : "object",
"properties" : {
"option2" : {
"title" : "Java extractor option 2",
"description" : "An example array option for the Java extractor",
"type" : "array",
"pattern" : "[1-9][0-9]*"
}
}
}
}
}
추출기 옵션 이름 및 설명은 아래에 extractor_options
나열됩니다. 각 옵션에는 다음 필드가 포함될 수 있습니다.
title
(필수): 옵션의 제목description
(필수): 옵션에 대한 설명입니다.type
(필수): 옵션의 유형입니다.string
: 옵션에 단일 문자열 값이 있을 수 있음을 나타냅니다.array
: 옵션에 문자열 값 시퀀스가 있을 수 있음을 나타냅니다.object
: 옵션 자체가 아니라 다른 옵션 및 옵션 그룹을 포함할 수 있는 그룹화임을 나타냅니다.
pattern
(선택 사항): 옵션의 모든 값이 일치해야 하는 정규식 패턴입니다. 추출기는 이 정규식 패턴에서 표현할 수 없거나 표현할 수 없는 옵션 값에 추가 제약 조건을 적용할 수 있습니다. 이러한 제약 조건이 있는 경우 설명 필드 아래에 설명됩니다.properties
(선택 사항): 옵션 그룹의 추출기 옵션 이름에서 해당 추출기 옵션 설명으로 매핑됩니다. 이 필드는 옵션 그룹에만 존재할 수 있습니다. 예를 들어 형식의 옵션입니다object
.
위의 예제에서 추출기는 다음 두 가지 옵션을 선언합니다.
option1
값이 일치하는 옵션입니다.string``[a-z]+
group1.option2
값이array
일치하는 옵션입니다.[1-9][0-9]\*
CodeQL CLI을(를) 사용하여 추출기 옵션 설정
CodeQL CLI은 추출기를 직접 또는 간접적으로 호출하는 하위 명령에서 추출기 옵션을 설정하는 것을 지원합니다. 이러한 명령은 다음과 같습니다.
codeql database create
codeql database start-tracing
codeql database trace-command
codeql database index-files
이러한 하위 명령을 실행할 때 CLI 옵션을 사용하여 추출기 옵션을 --extractor-option
설정할 수 있습니다. 다음은 그 예입니다.
codeql database create --extractor-option java.option1=abc ...
codeql database start-tracing --extractor-option java.group1.option2=102 ...
--extractor-option
에는 정확히 하나의 형식 extractor_option_name=extractor_option_value
인수가 필요합니다. extractor_option_name
는 추출기의 이름(이 예제에서는 java
)이고 마침표가 뒤에 와 추출기 옵션의 이름(이 예제 option1
에서는 또는 group1.option2
)입니다. extractor_option_value
는 추출기 옵션에 할당되는 값입니다. 값은 추출기 옵션의 정규식 패턴과 일치해야 하며(있는 경우) 줄 바꿈 문자를 포함하면 안 됩니다.
를 사용하여 --extractor-option
존재하지 않는 추출기 옵션을 할당하는 것은 오류입니다.
CodeQL CLI은(는) 동일한 호출에서 여러 --extractor-option
옵션을 허용합니다. 추출기 옵션을 여러 번 설정 string
하면 마지막 옵션 값이 이전의 모든 옵션을 덮어씁니다. 배열 추출기 옵션을 여러 번 설정하면 모든 옵션 값이 순서대로 연결됩니다.
추출기 이름 없이 추출기 옵션 이름을 지정할 수도 있습니다. 다음은 그 예입니다.
codeql database create --extractor-option option1=abc ...
codeql database start-tracing --extractor-option group1.option2=102 ...
추출기 이름을 지정하지 않으면 지정된 이름의 옵션을 선언하는 모든 추출기에 추출기 옵션 설정이 적용됩니다. 위의 예제에서 첫 번째 명령은 추출기 및 의 옵션이 있는 모든 추출기(예: 추출기) option1
abc
option1``java
에 대한 추출기 옵션이 있는 경우 option1
추출기 옵션을 로 설정합니다.cpp
파일에서 추출기 옵션 설정
파일을 통해 추출기 옵션을 설정할 수도 있습니다. 허용하는 CodeQL CLI 하위 명령은 YAML 파일 경로(확장명 또는 ) 또는 .yml
JSON 파일(확장 .yaml
명 .json
포함)에 대한 필수 인수가 있는 을 수락 --extractor-option
--extractor-options-file
합니다. 다음은 그 예입니다.
codeql database create --extractor-options-file options.yml ...
codeql database start-tracing --extractor-options-file options.json ...
각 옵션 파일에는 중첩된 맵의 트리 구조가 포함되어 있습니다. 루트에는 추출기 맵 키가 있으며 그 아래에는 추출기 이름에 해당하는 지도 키가 있습니다. 세 번째 수준부터 추출기 옵션 및 옵션 그룹이 있습니다.
JSON:
{
"extractor" : {
"java": {
"option1" : "abc",
"group1" : {
"option2" : [ 102 ]
}
}
}
}
YAML에서:
extractor:
java:
option1: "abc"
group1:
option2: [ 102 ]
추출기 옵션의 string
값은 문자열 또는 숫자여야 합니다(추가 처리 전에 문자열로 변환됨).
추출기 옵션의 array
값은 문자열 또는 숫자의 배열이어야 합니다.
옵션 그룹(형식 object
)의 값은 중첩된 추출기 옵션 및 옵션 그룹을 포함할 수 있는 맵이어야 합니다.
각 추출기 옵션 값은 추출기 옵션의 정규식 패턴과 일치해야 하며(있는 경우) 줄 바꿈 문자를 포함하면 안 됩니다.
존재하지 않는 추출기 옵션을 할당하는 것은 오류입니다. 특별한 __allow_unknown_properties
부울 필드를 사용하여 CodeQL CLI에서 알 수 없는 추출기 옵션을 무시하게 할 수 있습니다. 예를 들어 다음 옵션 파일은 CodeQL CLI에 있는 group1
모든 알 수 없는 추출기 옵션 및 옵션 그룹을 무시하도록 요청합니다.
extractor:
java:
option1: "abc"
group1:
__allow_unknown_properties: true
option2: [ 102 ]
여러 번 지정할 --extractor-options-file
수 있습니다. 추출기 옵션 할당은 다음 순서로 처리됩니다.
- 에
--extractor-options-file
지정된 모든 추출기 옵션 파일은 명령줄에 표시되는 순서대로 처리됩니다. - 에 지정된
--extractor-option
모든 추출기 옵션 할당은 명령줄에 표시되는 순서대로 처리됩니다.
동일한 규칙은 를 사용하여 --extractor-option``--extractor-options-file
할당을 수행하는지 여부와 관계없이 동일한 추출기 옵션을 여러 번 설정할 때 발생하는 작업을 제어합니다. 추출기 옵션을 여러 번 설정 string
하면 마지막 옵션 값이 모든 이전 값을 덮어씁니다. 추출기 옵션을 여러 번 설정 array
하면 모든 옵션 값이 순서대로 연결됩니다.