데이터베이스 분석하기

참고 항목

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

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

개요

Shell

codeql database analyze --format=<format> --output=<output> [--threads=<num>] [--ram=<MB>] <options>... -- <database> <query|dir|suite|pack>...

codeql database analyze --format=<format> --output=<output> [--threads=<num>] [--ram=<MB>] <options>... -- <database> <query|dir|suite|pack>...

Description

데이터베이스를 분석하고 소스 코드의 컨텍스트에서 의미 있는 결과를 생성합니다.

CodeQL 데이터베이스에 대해 쿼리 스위트(또는 일부 개별 쿼리)를 실행하여, SARIF 또는 다른 해석된 형식으로 알림 또는 경로 형식의 결과를 생성합니다.

이 명령은 codeql 데이터베이스 실행 쿼리 및 codeql 데이터베이스 해석 결과 명령의 효과를 통합합니다. 결과가 소스 코드 경고로 해석되기 위한 요구사항을 충족하지 않는 쿼리를 실행하고 싶다면 codeql 데이터베이스 실행 쿼리 또는 codeql 쿼리 실행을 대신 사용한 후에 codeql bqrs 디코딩하여 원시 결과를 읽을 수 있는 표기법으로 변환합니다.

Options

사용할 모델 팩을 제어하기 위한 옵션

          `--model-packs=<`
          <name@range>>...

평가할 쿼리를 사용자 지정하기 위해 모델 팩으로 사용할 CodeQL 팩 이름 목록입니다(각 항목에 선택적 버전 범위를 포함할 수 있습니다).

사용할 위협 모델을 제어하기 위한 옵션

`--threat-model=<name>...`

사용 여부를 설정할 수 있는 위협 모델 목록.

인수는 위협 모델명이며, 앞에 ‘!’를 붙일 수 있습니다. ‘!’가 없으면, 지정된 위협 모델과 그 하위 항목이 모두 활성화됩니다. ‘!’가 있으면 지정된 위협 모델과 모든 하위 항목이 비활성화됩니다.

'기본' 위협 모델은 기본적으로 활성화되지만 ‘--threat-model !default’ 옵션을 지정하면 비활성화할 수 있습니다.

'전체' 위협 모델은 모든 위협 모델의 활성화 및 비활성화에 사용할 수 있습니다.

--threat-model 옵션은 순차적으로 처리됩니다. 가령, ‘--threat-model local --threat-model !environment’는 ‘환경’ 위협 모델만 제외하고 ‘로컬’ 그룹의 모든 위협 모델을 활성화합니다.

이 옵션은 위협 모델을 지원하는 언어에만 적용됩니다.

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

쿼리 평가기를 제어하기 위한 옵션

`--[no-]tuple-counting`

          \[고급] 각 평가 단계별 튜플 수를 쿼리 평가기 로그에 표시합니다. `--evaluator-log` 옵션이 제공되면, 명령으로 생성된 텍스트 기반 로그와 구조화된 JSON 로그에 튜플 수가 포함됩니다. (이것은 복잡한 QL 코드 성능을 최적화하는 데에 도움이 될 수 있습니다.)

`--timeout=<seconds>`

          \[고급] 쿼리 평가에 대한 시간을 초 단위로 설정합니다.

시간 제한 기능은 복잡한 쿼리 평가가 "영구적으로" 실행되는 것을 방지하기 위해 개발되었습니다. 쿼리 평가에 소요되는 총 시간을 제한하기 위한 목적으로는 효과적이지 않습니다. 별도로 시간 제한이 적용되는 계산의 각 부분이 제한 시간 내에 완료되는 한 평가는 계속 진행하도록 허용됩니다. 현재 별도로 시간 제한이 적용되는 부분은 최적화된 쿼리의 "RA 계층"이지만 향후 변경될 수 있습니다.

시간 제한이 지정되지 않거나 0으로 지정된 경우 시간 제한이 설정되지 않으나, 단, codeql test run의 경우 기본 시간 제한은 5분입니다.

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

해당하는 수의 스레드를 사용하여 쿼리를 평가합니다.

기본값은 1입니다. 0을 전달하면 머신의 코어당 1개의 스레드를 사용할 수 있고, -_N_을 전달하면 _N_개의 코어를 사용하지 않은 상태로 둘 수 있습니다(단, 최소 한 개의 스레드는 계속 사용됩니다).

`--[no-]save-cache`

          \[사용되지 않음] \[고급] 이 플래그는 아무 작업도 수행하지 않습니다.

`--[no-]expect-discarded-cache`

          \[고급] 쿼리가 실행된 후 캐시가 삭제된다는 사실을 전제로, 평가할 조건자와 디스크 캐시에 작성할 내용을 결정합니다.

`--[no-]keep-full-cache`

          \[고급] 평가가 완료된 후 디스크 캐시를 정리하지 않습니다.

차후에 codeql dataset cleanup 또는 codeql database cleanup을 수행할 경우 시간이 절약됩니다.

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

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

명시적으로 크기를 구성하지 않으면 평가기는 데이터 집합의 크기와 쿼리의 복잡성에 따라 "합리적인" 양의 캐시 공간을 사용하려 할 것입니다. 명시적으로 이러한 기본 사용량보다 높은 한도를 설정하게 되면 추가 캐싱이 가능하므로 이후 쿼리 속도를 높일 수 있습니다.

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

          \[고급] 파일 시스템에 확보할 목표 여유 공간을 설정합니다.

--max-disk-cache가 지정되지 않으면 파일 시스템의 사용 가능한 공간이 해당 값 아래로 떨어지면 평가기에서 디스크 캐시 사용량을 줄이려고 합니다.

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

          \[고급] 파일 시스템에 확보할 여유 공간의 목표 비율을 설정합니다.

--max-disk-cache을 지정하지 않으면, 파일 시스템에 사용 가능한 공간이 이 비율 밑으로 떨어질 때 평가기는 디스크 캐시 사용량을 줄이려고 합니다.

`--external=<pred>=<file.csv>`

외부 조건자 <pred> 의 행을 포함하는 CSV 파일입니다. 여러 개의 --external 옵션을 제공할 수 있습니다.

`--xterm-progress=<mode>`

          \[고급] xterm 제어 시퀀스를 사용하여 QL 평가 중 진행률 추적 표시 여부를 통제합니다. 가능한 값은 다음과 같습니다.

          `no`: 복잡한 진행률을 생성하지 말고, 단순 터미널로 가정합니다.

          `auto`              _(기본값)_: 명령이 적절한 터미널에서 실행 중인지 여부를 자동 검색합니다.

          `yes`: 터미널이 xterm 제어 시퀀스를 이해할 수 있는 것으로 가정합니다. 이 기능은 계속해서 터미널의 _크기_의 자동 검색 가능 여부에 따라 달라지고(Windows에서는 구현되지 않음), `-q`가 지정되면 이 기능은 비활성화됩니다.

          `25x80` (또는 이와 유사): `yes`와 마찬가지로, 터미널 크기를 명시적으로 지정합니다. (`yes`와 달리 이 기능은 Windows에서 작동합니다.)

          `25x80:/dev/pts/17` (또는 이와 유사): stderr가 아닌 _다른_ 터미널에서 복잡한 진행률을 표시합니다. 주로 내부 테스트에 유용합니다.

구조화된 평가기 로그의 출력을 제어하는 옵션

`--evaluator-log=<file>`

          \[고급] 평가기 성능에 대한 구조화된 로그를 지정된 파일에 출력합니다. 이 로그 파일의 형식은 예고 없이 변경될 수 있으나, `--evaluator-log-minify` 옵션이 전달된 경우에는 기본적으로 두 개 또는 하나의 줄 바꿈 문자로 구분된 JSON 개체 스트림입니다. 이 파일에 대한 보다 안정적인 요약을 생성하고 파일의 직접 구문 분석을 피하기 위해 `codeql generate log-summary <file>`을 사용하세요. 파일이 이미 존재하면 덮어쓰기됩니다.

`--evaluator-log-minify`

          \[고급] `--evaluator-log` 옵션을 전달하면, 이 옵션이 전달 시 생성되는 JSON 로그의 크기는 최소화되지만 가독성은 크게 떨어집니다.

RAM 사용량을 제어하는 옵션

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

쿼리 평가기는 총 메모리 사용량을 이 값보다 낮게 유지하려고 합니다. (그러나 대형 데이터베이스의 경우 파일 기반 메모리 맵으로 인해 임계값이 초과할 수 있으며, 메모리 압력 시 디스크로 교환될 수 있습니다.)

값은 최소 2048MB 이상이어야 하고, 이보다 작은 값은 반올림됩니다.

QL 컴파일을 제어하기 위한 옵션

`--warnings=<mode>`

QL 컴파일러에서 발생한 경고를 해결하는 방식. 다음 중 하나입니다.

          `hide`: 경고를 표시하지 않음.

          `show`              _(기본값)_: 경고를 출력하나 계속해서 컴파일을 진행합니다.

          `error`: 경고를 오류로 취급합니다.

`--no-debug-info`

RA에서 디버깅을 위해 원본 위치 정보를 내보내지 않습니다.

`--[no-]fast-compilation`

          \[사용 중단됨] \[고급] 특히 시간이 오래 소요되는 최적화 단계를 생략합니다.

`--no-release-compatibility`

          \[고급] 이식성 저하를 감수하고 최신 컴파일러 기능을 사용합니다.

QL 컴파일러에서 새로운 QL 언어 기능 및 평가기 최적화가 기본적으로 적용되기 전에 수시로 여러 릴리스에 걸쳐 QL 평가기에서 먼저 지원될 예정입니다. 최신 CodeQL 릴리스에서 쿼리를 개발 시 경험하는 성능이 코드 검사 또는 CI 통합에 여전히 사용 중인 이전 버전의 릴리스에서도 동일하게 유지되도록 도와줍니다.

쿼리가 다른(이전 또는 이후) CodeQL 릴리스와의 호환성을 고려할 필요가 없는 경우, 이 플래그를 사용하여 컴파일러의 최신 개선 사항을 조기에 제공하여 성능을 조금씩 향상시킬 수 있습니다.

적용 가능한 최신 개선 사항이 없는 릴리스에서는 이 옵션이 아무런 효과가 없습니다. 따라서 전역 CodeQL 구성 파일에 한 번만 설정하면 안전합니다.

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

`--[no-]local-checking`

사용되는 QL 소스 부분에만 초기 검사를 수행합니다.

`--no-metadata-verification`

QLDoc 주석에 포함된 쿼리 메타데이터에 대해서는 유효성 검사를 수행하지 마십시오.

`--compilation-cache-size=<MB>`

          \[고급] 컴파일 캐시 디렉터리에 설정된 최대 크기 기본값을 재정의합니다.

`--fail-on-ambiguous-relation-name`

          \[고급] 컴파일 중에 모호한 관계명이 생성되는 경우 컴파일이 실패합니다.

컴파일 환경 설정 옵션

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

QL 팩을 찾을 수 있는 디렉터리 목록. 각 디렉터리는 루트에 .codeqlmanifest.json 파일을 포함하는 QL 팩(또는 팩 번들)이거나, 그러한 디렉터리를 하나 이상 포함하는 상위 디렉터리일 수 있습니다.

경로에 하나 이상의 디렉터리가 포함된 경우, 그 순서가 우선순위를 정의하고, 해결해야 하는 팩 이름이 2개 이상의 디렉터리 트리에서 일치하는 경우에는 먼저 지정된 트리가 우선합니다.

오픈 소스 CodeQL 리포지토리의 체크아웃 위치로 지정하면 해당 리포지토리에 있는 언어 중 하나를 쿼리할 때 정상적으로 동작합니다.

압축해제된 CodeQL 툴체인의 형제 디렉터리로 CodeQL 리포지토리를 체크아웃한 경우에는 이 옵션을 지정할 필요가 없습니다. 이러한 형제 디렉터리는 다른 방법으로는 찾을 수 없는 QL 팩을 검색 시 항상 검색 대상에 포함됩니다. (해당 기본값이 적용되지 않는 경우 사용자별 구성 파일에 --search-path를 한 번만 설정할 것을 권장합니다).

(참고: Windows에서는 경로 구분 기호로 ;을 사용합니다.)

`--additional-packs=<dir>[:<dir>...]`

해당 디렉터리 목록이 지정되는 경우 --search-path에 위치한 디렉터리보다 먼저 검색 대상이 됩니다. 그들 간 순서는 중요하지 않으며, 이 목록에서 2개의 위치에 팩 이름이 발견될 경우 오류가 발생합니다.

이 기능은 기본 경로에서도 표시되는 팩의 새 버전을 일시적으로 개발하는 경우 유용합니다. 반면 이 옵션을 구성 파일에서 재정의하는 것은 권장하지 않으며, 일부 내부 작업에서는 즉시 이 옵션을 추가하여 구성된 값을 재정의합니다.

(참고: Windows에서는 경로 구분 기호로 ;을 사용합니다.)

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

          \[고급] 디렉터리의 선택 목록으로, QL 라이브러리에 대해 기본 가져오기 검색 경로에 추가됩니다. QL 팩으로 패키지되지 않은 QL 라이브러리를 사용 중인 경우에만 사용하도록 합니다.

(참고: Windows에서는 경로 구분 기호로 ;을 사용합니다.)

`--dbscheme=<file>`

          \[고급] 쿼리가 어떤 dbscheme에 컴파일되어야 하는지 명시적으로 정의합니다. 무엇을 하는지 완전히 파악하는 호출자에 한해서만 사용되어야 합니다.

`--compilation-cache=<dir>`

          \[고급] 컴파일 캐시로 사용할 추가 디렉터리를 지정합니다.

`--no-default-compilation-cache`

          \[고급] 쿼리를 포함하는 QL 팩 또는 CodeQL 도구 체인 디렉터리와 같은 표준 위치에서 컴파일 캐시를 사용하지 마십시오.

CodeQL 패키지 관리자를 구성하기 위한 옵션

`--registries-auth-stdin`

콤마로 구분된 <registry_url>=<token> 쌍 목록을 전달하여 GitHub Enterprise Server Container 레지스트리에 인증합니다.

가령, https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2을 전달하면 2개의 GitHub Enterprise Server 인스턴스에 인증할 수 있습니다.

이는 CODEQL_REGISTRIES_AUTH 및 GITHUB_TOKEN 환경 변수를 재정의합니다. github.com 컨테이너 레지스트리 인증만 필요한 경우에는 간단히 --github-auth-stdin 옵션을 사용하여 인증할 수 있습니다.

`--github-auth-stdin`

표준 입력을 통해 github.com GitHub Apps 토큰 또는 개인 액세스 토큰을 전달하여 github.com 컨테이너 레지스트리에 인증합니다.

GitHub Enterprise Server 컨테이너 레지스트리에 인증하기 위해서는 --registries-auth-stdin을 전달하거나 CODEQL_REGISTRIES_AUTH 환경 변수를 이용합니다.

그러면 GITHUB_TOKEN 환경 변수가 재정의됩니다.

          \[고급] 명령을 실행하는 JVM으로 옵션을 제공합니다.

(옵션에 공백이 포함되면 올바로 처리되지 않을 수 있으므로 유의해야 합니다.)

          \[고급] 세부 정보 표시 수준을 오류, 경고, 진행률, 진행률+, 진행률++, 진행률+++ 중 하나로 명시적으로 설정합니다. 
          `-v` 및 `-q`를 재정의합니다.

`--logdir=<dir>`

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

(로그 파일명을 직접 작성하기 위해서는 대신 --log-to-stderr을 사용하고 원하는 곳으로 stderr를 리디렉션합니다.)

`--common-caches=<dir>`

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

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

데이터베이스 분석하기

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

이 문서의 내용