데이터베이스 작성하기

참고 항목

이 콘텐츠는 CodeQL CLI의 최신 릴리스에 대해 설명합니다. 이 요소에 대한 자세한 내용은 https://github.com/github/codeql-cli-binaries/releases을(를) 참조하세요.

이전 릴리스에서 이 명령에 사용할 수 있는 옵션의 세부 정보를 보려면 터미널에서 옵션을 사용하여 --help 명령을 실행합니다.

개요

Shell

codeql database create [--language=<lang>[,<lang>...]] [--github-auth-stdin] [--github-url=<url>] [--source-root=<dir>] [--threads=<num>] [--ram=<MB>] [--command=<command>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database>

codeql database create [--language=<lang>[,<lang>...]] [--github-auth-stdin] [--github-url=<url>] [--source-root=<dir>] [--threads=<num>] [--ram=<MB>] [--command=<command>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database>

Description

CodeQL 제품 중 하나를 사용하여 분석할 수 있는 소스 트리에 대해 CodeQL 데이터베이스를 생성하세요.

Options

기본 옵션

`<database>`

          \[필수] 생성할 CodeQL 데이터베이스의 경로를 지정하세요. 이 디렉터리는 새로 생성되며, 이미 존재해서는 _안 됩니다_(단, 상위 디렉터리는 존재해야 합니다).

--db-cluster 옵션을 지정하면, 이는 단일 데이터베이스가 아니라 동일한 소스 루트에서 빌드된 여러 언어용 데이터베이스를 포함하는 디렉터리가 됩니다.

이 디렉터리는 빌드 프로세스가 간섭하지 않는 위치에 있어야 합니다. 예를 들어, Maven 프로젝트의 target 디렉터리는 적합한 선택이 아닙니다.

`--[no-]overwrite`

          \[고급] 데이터베이스가 이미 존재하는 경우, 실패하는 대신 해당 데이터베이스를 삭제하고 이 명령을 계속 실행하세요. 디렉터리가 존재하지만 데이터베이스처럼 보이지 않는 경우 오류가 발생합니다.

`--[no-]force-overwrite`

          \[고급] 데이터베이스가 이미 존재하는 경우, 데이터베이스처럼 보이지 않더라도 해당 디렉터리를 삭제하고 실패하는 대신 이 명령을 계속 실행하세요. 이 옵션은 재귀적으로 데이터베이스 디렉터리 전체를 삭제할 수 있으므로 주의하여 사용해야 합니다.

`--codescanning-config=<file>`

          \[고급] CodeQL 데이터베이스를 생성하는 방법과 이후 단계에서 실행할 쿼리를 지정하는 코드 검사 구성 파일을 읽으세요. 이 구성 파일 형식에 대한 자세한 내용은 [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning)을 참조하세요. 이 파일에 정의된 쿼리를 이후 단계에서 실행하려면, 다른 쿼리를 지정하지 않고 [codeql database analyze](/code-security/codeql-cli/codeql-cli-manual/database-analyze)를 호출하세요.

`--[no-]db-cluster`

단일 데이터베이스를 생성하는 대신, 서로 다른 언어용 데이터베이스들의 “클러스터”를 생성하세요. 각 데이터베이스는 명령줄에서 지정한 디렉터리의 하위 디렉터리로 생성됩니다.

`-l, --language=<lang>[,<lang>...]`

새 데이터베이스가 분석에 사용할 언어를 지정합니다.

검색 경로에서 발견된 플러그형 언어 추출기 목록을 가져오려면 codeql resolve languages를 사용하세요.

--db-cluster 옵션을 지정한 경우, 이 옵션은 여러 번 지정할 수 있으며 값으로는 쉼표로 구분된 언어 목록을 사용할 수도 있습니다.

이 옵션을 생략하고 분석 중인 소스 루트가 GitHub 리포지토리의 체크아웃인 경우, CodeQL CLI는 GitHub API를 호출하여 분석할 언어를 자동으로 결정하려고 시도합니다. 이를 수행하려면 GitHub 개인 액세스 토큰(PAT)을 환경 변수 GITHUB_TOKEN으로 제공하거나, --github-auth-stdin 옵션을 사용하여 표준 입력으로 제공해야 합니다.

`--build-mode=<mode>`

데이터베이스를 생성하는 데 사용할 빌드 모드를 지정합니다.

분석할 언어에 따라 빌드 모드를 선택하세요.

          `none`: 소스 루트를 빌드하지 않고 데이터베이스를 생성합니다.

C#, Java, JavaScript/TypeScript, Python, Ruby에서 사용할 수 있습니다.

          `autobuild`: 소스 루트를 자동으로 빌드하려고 시도하여 데이터베이스를 생성합니다. C/C++, C#, Go, Java/Kotlin, Swift에서 사용할 수 있습니다.

          `manual`: 수동으로 지정한 빌드 명령을 사용하여 소스 루트를 빌드하고 데이터베이스를 생성합니다. C/C++, C#, Go, Java/Kotlin, Swift에서 사용할 수 있습니다.

--command를 사용하여 데이터베이스를 만드는 경우, 추가로 '--build-mode manual'을 지정하지 않아도 됩니다.

v2.16.4부터 사용할 수 있습니다.

`-s, --source-root=<dir>`

          \[기본값: .] 루트 소스 코드 디렉터리입니다. 많은 경우 이는 체크아웃 루트가 됩니다. 이 안에 포함된 파일은 이 데이터베이스의 기본 소스 파일로 간주됩니다. 일부 출력 형식에서는 파일이 이 디렉터리를 기준으로 한 상대 경로로 참조됩니다.

`-j, --threads=<num>`

가져오기 작업에 사용할 스레드 수를 지정하며, 호출되는 모든 빌드 명령에 힌트로 전달합니다.

기본값은 1입니다. 0을 전달하면 머신의 각 코어당 하나의 스레드를 사용하며, -_N_을 전달하면 최소 하나의 스레드는 사용하되 _N_개의 코어를 사용하지 않도록 합니다.

`-M, --ram=<MB>`

가져오기 작업에 사용할 메모리 양을 지정하며, 호출되는 모든 빌드 명령에 힌트로 전달합니다.

`-c, --command=<command>`

컴파일 언어의 경우, 분석할 소스 코드에 대해 컴파일러가 호출되도록 하는 빌드 명령을 지정합니다. 이러한 명령은 생성된 코드와 (일부 경우) 표준 라이브러리를 분석할 수 있도록 하는 계측 환경에서 실행됩니다.

이 명령은 빌드 명령을 지정하지 않으면 선택한 언어 팩의 휴리스틱을 기반으로 소스 트리를 빌드하는 방법을 자동으로 파악하려고 시도합니다.

여러 언어를 조합하려면 명시적 빌드 명령을 _필수_적으로 지정해야 합니다.

`--no-cleanup`

          \[고급] 최종화 이후의 모든 데이터베이스 정리 작업을 삭제합니다. 디버깅 목적에 유용합니다.

`--no-pre-finalize`

          \[고급] 활성 CodeQL 추출기에 지정된 모든 사전 최종화 스크립트를 건너뜁니다.

`--[no-]skip-empty`

          \[고급] 빌드 중 소스 코드가 감지되지 않아 데이터베이스가 비어 있는 경우, 실패하는 대신 경고를 출력합니다. 비어 있는 데이터베이스는 최종화되지 않은 상태로 유지됩니다.

`--[no-]linkage-aware-import`

          \[고급] [codeql dataset import](/code-security/codeql-cli/codeql-cli-manual/dataset-import)의 링크 인식 방식인지 여부를 제어합니다 _(기본값)_. 데이터베이스 생성의 이 부분이 과도한 메모리를 소모하는 프로젝트의 경우, 이 옵션을 비활성화하면 데이터베이스의 완전성을 일부 희생하는 대신 처리가 진행되는 데 도움이 될 수 있습니다.

v2.15.3부터 사용할 수 있습니다.

베이스라인 계산 옵션

`--[no-]calculate-baseline`

          \[고급] 분석 중인 코드에 대한 베이스라인 정보를 계산하여 데이터베이스에 추가합니다. 기본적으로 소스 루트가 파일 시스템의 루트가 아닌 경우 이 기능은 활성화됩니다. 이 플래그를 사용하여 이 동작을 비활성화하거나, 파일 시스템의 루트인 경우에도 강제로 활성화할 수 있습니다.

`--[no-]sublanguage-file-coverage`

          \[GitHub.com 및 GitHub Enterprise Server v3.12.0 이상 전용] 하위 언어 파일 적용 범위 정보를 사용합니다. 이는 C와 C++, Java와 Kotlin, JavaScript와 TypeScript처럼 동일한 CodeQL 추출기를 공유하는 언어에 대해 개별적인 파일 커버리지 정보를 계산하고 표시하며 내보냅니다.

v2.15.2부터 사용할 수 있습니다.

추출기 선택 옵션

`--search-path=<dir>[:<dir>...]`

추출기 팩을 찾을 수 있는 디렉터리 목록입니다. 해당 디렉터리는 추출기 팩 자체이거나, 추출기를 즉시 하위 디렉터리로 포함하는 디렉터리일 수 있습니다.

경로에 여러 디렉터리 트리가 포함된 경우, 그 순서에 따라 우선순위가 결정됩니다. 대상 언어가 둘 이상의 디렉터리 트리에서 일치하는 경우 먼저 지정된 항목이 적용됩니다.

CodeQL 도구 체인 자체에 포함된 추출기는 항상 검색되지만, 별도로 배포된 추출기를 사용해야 하는 경우 이 옵션을 지정해야 합니다. 또는 사용자별 구성 파일에서 --search-path를 설정하는 것이 권장됩니다.

(참고: Windows에서는 경로 구분자가 ;입니다.)

언어 자동 감지를 위해 GitHub API를 호출하는 방식을 구성하는 옵션입니다.

`-a, --github-auth-stdin`

표준 입력을 통해 GitHub Apps 토큰 또는 개인 액세스 토큰을 허용합니다.

이 옵션은 GITHUB_TOKEN 환경 변수를 덮어씁니다.

`-g, --github-url=<url>`

사용할 GitHub 인스턴스의 URL입니다. 이를 생략하면 CLI는 체크아웃 경로를 기반으로 자동 감지를 시도하며, 불가능한 경우 기본값으로 https://github.com/을 사용합니다.

패키지 관리자를 구성하기 위한 옵션입니다.

`--registries-auth-stdin`

쉼표로 구분된 <registry_url>=<token> 쌍 목록을 전달하여 GitHub Enterprise Server 컨테이너 레지스트리에 인증합니다.

예를 들어, https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2을 전달할 수 있습니다. 이는 두 개의 GitHub Enterprise Server 인스턴스에 인증하기 위한 것입니다.

이 옵션은 CODEQL_REGISTRIES_AUTH 및 GITHUB_TOKEN 환경 변수를 덮어씁니다. github.com 컨테이너 레지스트리에만 인증하면 되는 경우, 더 단순한 --github-auth-stdin 옵션을 사용하여 인증할 수 있습니다.

하위 수준 데이터 세트 정리 옵션

`--max-disk-cache=<MB>`

중간 쿼리 결과에 대한 디스크 캐시가 사용할 수 있는 최대 공간을 설정합니다.

이 크기가 명시적으로 구성되지 않은 경우, 평가기는 데이터 세트의 크기와 쿼리의 복잡도를 기반으로 “합리적인” 양의 캐시 공간을 사용하려고 시도합니다. 이 기본 사용량보다 더 높은 한계를 명시적으로 설정하면 추가 캐싱이 활성화되어 이후 쿼리를 더 빠르게 실행할 수 있습니다.

`--min-disk-free=<MB>`

          \[고급] 파일 시스템에서 유지하려는 최소 여유 공간의 절대량을 설정합니다.

--max-disk-cache가 지정되지 않은 경우, 파일 시스템의 여유 공간이 이 값보다 낮아지면 평가기는 디스크 캐시 사용을 최대한 억제하려고 시도합니다.

`--min-disk-free-pct=<pct>`

          \[고급] 파일 시스템에서 유지하려는 여유 공간의 비율을 설정합니다.

--max-disk-cache가 지정되지 않은 경우, 파일 시스템의 여유 공간이 이 비율보다 낮아지면 평가기는 디스크 캐시 사용을 최대한 억제하려고 시도합니다.

`--cache-cleanup=<mode>`

캐시를 얼마나 적극적으로 정리할지 선택합니다. 선택 항목은 다음과 같습니다.

          `clear`: 전체 캐시를 제거하여, 새로 추출된 데이터 세트 상태까지 정리합니다.

          `trim`              _(기본값)_: 명시적으로 “캐시됨”으로 표시된 조건자를 제외한 모든 항목을 정리합니다.

          `fit`: 디스크 캐시에 정의된 크기 제한이 준수되도록 필요한 만큼 중간 결과를 삭제합니다.

          `overlay`: 오버레이를 기준으로 평가할 때 유용한 데이터만 남기도록 정리합니다.

`--cleanup-upgrade-backups`

데이터베이스 업그레이드로 인해 생성된 모든 백업 디렉터리를 삭제합니다.

추적 옵션

`--no-tracing`

          \[고급] 지정된 명령을 추적하지 않고, 대신 해당 명령이 필요한 모든 데이터를 직접 생성하는 것으로 간주합니다.

`--extra-tracing-config=<tracing-config.lua>`

          \[고급] 추적기 구성 파일에 대한 경로를 지정합니다. 이 파일은 빌드 추적기의 동작을 수정하는 데 사용할 수 있습니다. 이 파일은 빌드 명령의 일부로 실행되는 컴파일러 프로세스를 식별하고, 다른 도구의 실행을 트리거하는 데 사용할 수 있습니다. 추출기는 대부분의 상황에서 작동해야 하는 기본 추적기 구성 파일을 제공합니다.

빌드 명령 사용자 지정 옵션

`--working-dir=<dir>`

          \[고급] 지정된 명령을 실행할 디렉터리를 지정합니다. 이 인수가 제공되지 않으면, codeql database create에 전달된 `--source-root` 값이 존재하는 경우 해당 값의 디렉터리에서 명령이 실행됩니다. `--source-root` 인수가 제공되지 않으면, 명령은 현재 작업 디렉터리에서 실행됩니다.

`--no-run-unnecessary-builds`

          \[[고급] 빌드 프로세스 추적에 의존하는 추적기를 사용하는 데이터베이스가 생성 중인 경우에만 지정된 빌드 명령을 실행합니다.

이 옵션이 지정되지 않으면, CodeQL에 필요하지 않은 경우에도 다른 목적을 위한 부수 효과가 필요하다고 가정하여 명령이 실행됩니다.

추출기 동작을 제어하는 옵션

`-O, --extractor-option=<extractor-option-name=value>`

CodeQL 추출기에 대한 옵션을 설정합니다. extractor-option-name는 extractor_name.group1.group2.option_name 또는 group1.group2.option_name 형식이어야 합니다. extractor_option_name가 추출기 이름으로 시작하는 경우, 해당 추출기는 group1.group2.option_name 옵션을 선언해야 합니다. 그렇지 않은 경우, 해당 옵션이 group1.group2.option_name 옵션을 선언하는 모든 추출기에 설정됩니다. value는 줄바꿈 문자를 포함하지 않는 임의의 문자열일 수 있습니다.

이 명령줄 옵션을 반복해서 사용하여 여러 추출기 옵션을 설정할 수 있습니다. 여러 값을 동일한 추출기 옵션에 대해 제공하는 경우, 동작은 추출기 옵션이 기대하는 타입에 따라 달라집니다. 문자열 옵션은 마지막으로 제공된 값을 사용합니다. 배열 옵션은 제공된 모든 값을 순서대로 사용합니다. 이 명령줄 옵션을 사용하여 지정된 추출기 옵션은 --extractor-options-file을 통해 제공된 추출기 옵션 이후에 처리됩니다.

이 옵션을 codeql database init 또는 codeql database begin-tracing에 전달하는 경우, 옵션은 간접 추적 환경에만 적용됩니다. Workflow에서 codeql database trace-command도 호출하는 경우, 필요하다면 해당 옵션도 그 명령에 전달해야 합니다.

각 추출기가 선언한 옵션을 나열하는 방법을 포함하여 CodeQL 추출기 옵션에 대한 자세한 내용은 https://codeql.github.com/docs/codeql-cli/extractor-options을 참조하세요.

          \[고급] 명령을 실행하는 JVM에 옵션을 전달합니다.

(공백을 포함한 옵션은 올바르게 처리되지 않으므로 주의하세요.)

          \[고급] 오류, 경고, progress, progress+, progress++, progress+++ 중 하나로 상세 출력 수준을 명시적으로 설정합니다. 
          `-v` 및 `-q`를 재정의합니다.

`--logdir=<dir>`

          \[고급] 지정된 디렉터리에 하나 이상의 파일로 상세 로그를 기록하며, 생성되는 파일 이름에는 타임스탬프와 실행 중인 하위 명령의 이름이 포함됩니다.

(파일 이름을 완전히 제어하여 로그 파일을 작성하려면 대신 --log-to-stderr를 지정하고 stderr를 원하는 대로 리디렉션하세요.)

`--common-caches=<dir>`

          \[고급] 다운로드된 QL 팩과 컴파일된 쿼리 계획 등 CLI를 여러 번 실행하는 동안 유지되는 디스크상의 캐시 데이터 위치를 제어합니다. 명시적으로 설정하지 않으면 사용자 홈 디렉터리 내의 `.codeql`이라는 디렉터리를 기본값으로 사용하며, 해당 디렉터리가 존재하지 않는 경우 생성합니다.

v2.15.2부터 사용할 수 있습니다.

데이터베이스 작성하기

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

이 문서의 내용