추출기 옵션

참고: 이 문서는 2023년 1월에 CodeQL 설명서 웹 사이트에서 마이그레이션되었습니다.

추출기 정보

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 하위 명령은 YAML 파일(확장자 .yaml 또는 .yml) 또는 JSON 파일(확장자 .json)에 대한 경로의 필수 인수가 있는 --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 추출기 옵션을 여러 번 설정하면 모든 옵션 값이 순서대로 연결됩니다.

추출기 옵션

이 문서의 내용

추출기 정보