CodeQL 팩 및 CodeQL CLI 정보
참고: 이 문서에서는 CodeQL CLI 2.14.6 번들에서 사용할 수 있는 기능을 GitHub Enterprise Server 3.11의 초기 릴리스에 포함되어 있습니다.
사이트 관리자가 CodeQL CLI 버전을 최신 릴리스로 업데이트한 경우 최신 기능에 대한 자세한 내용은 이 문서의 GitHub Enterprise Cloud 버전을 참조하세요.
CodeQL 팩은 CodeQL 쿼리 및 라이브러리를 만들고, 공유하고, 사용하고, 실행하는 데 사용됩니다. CodeQL 팩에는 쿼리, 라이브러리 파일, 쿼리 도구 모음 및 메타데이터가 포함됩니다. CodeQL 팩 및 CodeQL CLI의 패키지 관리 명령을 사용하여 사용자 지정 쿼리를 게시하고 코드베이스 분석에 통합할 수 있습니다.
CodeQL 팩은 세 개 유형이 있습니다. 쿼리 팩, 라이브러리 팩, 그리고 모델 팩입니다.
-
쿼리 팩은 실행되도록 설계되었습니다. 쿼리 팩이 게시되면 번들에 쿼리 원본 외에도 각 쿼리의 모든 전이적 종속성과 미리 컴파일된 표현이 포함됩니다. 이렇게 하면 팩에서 쿼리를 일관되고 효율적으로 실행할 수 있습니다.
-
라이브러리 팩은 쿼리 팩(또는 다른 라이브러리 팩)에서 사용하도록 설계되었으며 쿼리 자체를 포함하지 않습니다. 라이브러리는 별도로 컴파일되지 않습니다.
-
모델 팩을 사용하여 기본적으로 지원되지 않는 종속성을 포함하도록 code scanning 분석을 확장할 수 있습니다. 모델 팩은 현재 beta 버전이며 변경될 수 있습니다. beta에서 모델 팩은 Java/Kotlin 분석에 사용할 수 있습니다. 자체 모델 팩을 만드는 방법에 대한 자세한 내용은 "CodeQL 모델 팩 생성"을 참조하세요.
CodeQL CLI의 pack
명령을 사용하여 CodeQL 팩을 만들고, 팩에 종속성을 추가하고, 종속성을 설치하거나 업데이트할 수 있습니다. pack
명령을 사용하여 CodeQL 팩을 게시하고 다운로드할 수도 있습니다. 자세한 내용은 "CodeQL 팩 게시 및 사용"을(를) 참조하세요.
게시된 쿼리 팩과 다른 CodeQL 릴리스 간의 호환성에 대한 자세한 내용은 "CodeQL 팩 게시 및 사용"을 참조하세요.
지원되는 모든 언어에 대한 표준 CodeQL 패키지가 Container registry에 게시됩니다. CodeQL 리포지토리에는 지원되는 모든 언어에 대한 표준 CodeQL 팩에 대한 원본 파일이 포함되어 있습니다. CodeQL CLI 번들에 포함되어 있지만 다운로드할 수 있는 핵심 쿼리 팩은 다음과 같습니다.
codeql/cpp-queries
codeql/csharp-queries
codeql/go-queries
codeql/java-queries
codeql/javascript-queries
codeql/python-queries
codeql/ruby-queries
CodeQL 팩 구조
CodeQL 팩은 루트 디렉터리에 qlpack.yml
이라는 파일이 있어야 합니다. qlpack.yml
파일에서 name:
필드에는 <scope>/<pack>
의 형식을 따르는 값이 있어야 합니다. 여기서 <scope>
는 팩이 게시될 GitHub 조직 또는 사용자 계정이며 <pack>
은 팩의 이름입니다. 또한 CodeQL 테스트가 있는 쿼리 팩 및 라이브러리 팩에는 팩의 확인된 종속성이 들어있는 codeql-pack.lock.yml
파일이 포함되어 있습니다. 이 파일은 codeql pack install
명령을 호출하는 동안 생성되며, 직접 편집할 수 없으며 버전 제어 시스템에 추가해야 합니다.
팩 내의 다른 파일 및 디렉터리를 논리적으로 구성해야 합니다. 예를 들면 다음과 같습니다.
-
쿼리는 특정 범주에 대한 디렉터리로 구성됩니다.
-
특정 제품, 라이브러리 및 프레임워크에 대한 쿼리는 자체 최상위 디렉터리로 구성됩니다.
CodeQL 팩 만들기
프로젝트의 체크 아웃 루트에서 다음 명령을 실행하여 CodeQL 팩을 만들 수 있습니다.
codeql pack init <scope>/<pack>
다음 항목을 지정해야 합니다.
-
<scope>
: 게시할 GitHub 조직 또는 사용자 계정의 이름입니다. -
<pack>
: 만들 팩의 이름입니다.
codeql pack init
명령은 CodeQL 팩에 대한 디렉터리 구조 및 구성 파일을 만듭니다. 기본적으로 이 명령은 쿼리 팩을 만듭니다. 라이브러리 팩을 만들려면 library:true
속성을 포함하여 파일을 라이브러리 팩으로 명시적으로 선언하도록 qlpack.yml
파일을 편집해야 합니다.
CodeQL 모델 팩 만들기
참고: CodeQL 모델 팩 및 CodeQL 모델 편집기는 현재 beta 버전이며 변경될 수 있습니다. 모델 팩은 Java/Kotlin 분석에 의해 지원됩니다.
code scanning 분석을 확장하여 기본적으로 지원되지 않는 라이브러리 및 프레임워크를 인식하는 데 모델 팩을 사용할 수 있습니다. 모델 팩은 YAML로 구현되는 데이터 확장 프로그램을 사용하고 새 종속성에 대한 데이터를 추가하는 방법을 설명합니다. 모델 팩을 지정하면 해당 팩의 데이터 확장 프로그램이 code scanning 분석에 자동으로 추가됩니다. CodeQL 모델 팩 및 데이터 확장 프로그램에 대한 자세한 정보는 “CodeQL 모델 편집기 사용” 섹션을 참조하세요.
모델 팩은 파일에서 qlpack.yml
파일에서 다음과 같은 특성을 가진 CodeQL 팩입니다.
library: true
를 정의합니다.- 종속성이 없습니다.
extensionTargets
가 하나 이상 있습니다.- 하나 이상의 데이터 확장 프로그램 파일을 가리키는
dataExtensions
속성이 있습니다.
모델 팩은 지정된 버전 범위에 속하는 경우 extensionTargets
에 명명된 각 쿼리 팩에 지정된 데이터 확장 프로그램을 삽입합니다. 예시:
name: my-repo/my-java-model-pack
version: 1.2.3
extensionTargets:
codeql/java-all: ~1.2.3
codeql/util: ~4.5.6
dataExtensions:
- models/**/*.yml
이 예제에서 모델 팩은 models/**/
의 모든 데이터 확장 프로그램을 1.2.3
부터 1.3.0
까지의 버전인 codeql/java-all
쿼리 팩 및 4.5.6
부터 4.6.0
까지의 버전인 codeql/util
쿼리 팩에 삽입합니다. 자세한 내용은 npm 설명서의 “의미 체계 버전 관리 사용” 및 “의미 체계 버전 관리 사양”을 참조하세요.
모델 팩을 만든 후에는 다른 CodeQL 팩과 동일한 방식으로 게시할 수 있습니다. 자세한 내용은 "CodeQL 팩 게시 및 사용"을(를) 참조하세요. 그런 당므 code scanning 분석에 게시된 모델 팩을 --model-packs
옵션과 함께 사용할 수 있습니다. 자세한 내용은 "CodeQL 팩을 사용하여 분석 사용자 지정"을(를) 참조하세요.
CodeQL 팩에 종속성 추가 및 설치
참고: 이는 CodeQL 쿼리 및 라이브러리 팩에만 지원됩니다.
codeql pack add
명령을 사용하여 CodeQL 팩에 종속성을 추가할 수 있습니다. 범위, 이름 및 호환되는 버전 범위(선택 사항)를 지정해야 합니다.
codeql pack add <scope>/<name>@x.x.x <scope>/<other-name>
버전 범위를 지정하지 않으면 최신 버전이 추가됩니다. 그렇지 않으면 요청된 범위를 충족하는 최신 버전이 추가됩니다.
이 명령은 요청된 종속성으로 qlpack.yml
파일을 업데이트하고 패키지 캐시에 다운로드합니다. 이 명령은 파일의 서식을 다시 지정하고 모든 주석을 제거합니다.
qlpack.yml
파일을 수동으로 편집하여 종속성을 포함하고 명령을 사용하여 종속성을 설치할 수도 있습니다.
codeql pack install
이 명령은 모든 종속성을 로컬 디스크의 공유 캐시에 다운로드합니다.
참고:
-
codeql pack add
및codeql pack install
명령을 실행하면codeql-pack.lock.yml
파일이 생성되거나 업데이트됩니다. 이 파일은 버전 관리에 체크인되어야 합니다.codeql-pack.lock.yml
파일에는 팩에서 사용하는 정확한 버전 번호가 포함되어 있습니다. 자세한 내용은 "codeql-pack.lock.yml 파일 정보"를 참조하세요. -
기본적으로
codeql pack install
은 GitHub.com의 Container registry에서 종속성을 설치합니다.qlconfig.yml
파일을 만들어 GitHub Enterprise Server Container registry에서 종속성을 설치할 수 있습니다. 자세한 내용은 GitHub Enterprise Server 설명서의 “CodeQL 팩 게시 및 사용”을(를) 참조하세요.
다운로드한 CodeQL 팩 사용자 지정
팩의 변경 내용을 실험하는 권장 방법은 소스 코드가 포함된 리포지토리를 복제하는 것입니다.
원본 리포지토리를 사용할 수 없고 Container registry에서 다운로드한 팩에 대한 기본 수정이 필요한 경우 이러한 팩은 다운로드 후 수정하거나 사용자 지정할 수 없으며 나중에 해당 형식이 변경될 수 있습니다. 콘텐츠를 수정해야 하는 경우 팩을 다운로드한 후 다음 단계를 수행하는 것이 좋습니다.
-
수정하지 않은 팩의 결과와 혼동하지 않도록 팩 _이름_을
qlpack.yml
로 변경합니다. -
압축을 푼 디렉터리 구조에서 이름이
*.qlx
인 모든 파일을 제거합니다. 이러한 파일에는 미리 컴파일된 버전의 쿼리가 포함되어 있으며, 경우에 따라 CodeQL은 수정한 QL 원본을 기본 설정으로 사용합니다.