추출기 옵션

추출기 정보

CodeQL CLI은(는) 추출기라는 특수 프로그램을 사용하여 소프트웨어 시스템의 소스 코드에서 쿼리할 수 있는 데이터베이스로 정보를 추출합니다. CodeQL CLI를 통해 추출기 구성 옵션을 설정하여 추출기의 동작을 사용자 지정할 수 있습니다.

각 추출기는 고유한 구성 옵션 집합을 정의합니다. 특정 추출기에서 사용할 수 있는 옵션을 확인하려면 --format=betterjson 옵션과 함께 codeql resolve languages 또는 codeql resolve extractor를 실행할 수 있습니다. 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은 [a-z]+와 일치하는 값을 갖는 string 옵션입니다.
group1.option2는 [1-9][0-9]\*와 일치하는 값을 갖는 array 옵션입니다.

CodeQL CLI를 사용하여 추출기 옵션 설정

CodeQL CLI는 추출기를 직접 또는 간접적으로 호출하는 하위 명령의 추출기 옵션 설정을 지원합니다. 해당 명령은 다음과 같습니다.

codeql database create
codeql database start-tracing
codeql database trace-command
codeql database index-files

이러한 하위 명령을 실행할 때 --extractor-option CLI 옵션을 사용하여 추출기 옵션을 설정할 수 있습니다. 예시:

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 ...

추출기 이름을 지정하지 않으면 지정된 이름으로 옵션을 선언하는 모든 추출기에 추출기 옵션 설정이 적용됩니다. 위의 예제에서 첫 번째 명령은 java 추출기 및 옵션 option1가 있는 모든 추출기(예: 해당 추출기에 option1 추출기 옵션이 있는 경우 cpp 추출기)에 대해 추출기 옵션 option1을(를) abc(으)로 설정합니다.

파일에서 추출기 옵션 설정

파일을 통해 추출기 옵션을 설정할 수도 있습니다. --extractor-option을 수락하는 CodeQL CLI 하위 명령은 --extractor-options-file도 수락합니다. 여기에는 YAML 파일(확장자 .yaml 또는 .yml) 또는 JSON 파일(확장자 .json) 경로에 대한 필수 인수가 있습니다. 예시:

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 추출기 옵션을 여러 번 설정하면 모든 옵션 값이 순서대로 연결됩니다.

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

이 문서의 내용

추출기 정보

추출기 옵션 정보

CodeQL CLI를 사용하여 추출기 옵션 설정

파일에서 추출기 옵션 설정