CodeQL 팩 만들기 및 작업

참고: CodeQL 팩을 포함한 CodeQL 패키지 관리 기능은 현재 베타 릴리스 상태로 이용 가능하며 변경될 수 있습니다. 베타 릴리스 중에 CodeQL 팩은 GitHub 패키지 (Container registry)을(를) 사용하여만 사용할 수 있습니다. 이 베타 기능을 사용하려면 다음에서 https://github.com/github/codeql-action/releasesCodeQL CLI 번들의 최신 버전을 설치합니다.

CodeQL 팩 및 CodeQL CLI 정보

CodeQL 팩은 CodeQL 쿼리 및 라이브러리를 만들고, 공유하고, 사용하고, 실행하는 데 사용됩니다. CodeQL 팩에는 쿼리, 라이브러리 파일, 쿼리 도구 모음 및 메타데이터가 포함됩니다. CodeQL 팩 및 CodeQL CLI의 패키지 관리 명령을 사용하여 사용자 지정 쿼리를 게시하고 코드베이스 분석에 통합할 수 있습니다.

CodeQL 팩은 세 개 유형이 있습니다. 쿼리 팩, 라이브러리 팩, 그리고 모델 팩입니다.

쿼리 팩은 실행되도록 설계되었습니다. 쿼리 팩이 게시되면 번들에는 모든 전이적 종속성 및 각 쿼리의 미리 컴파일된 표현, 쿼리 원본이 포함됩니다. 이렇게 하면 팩에서 쿼리를 일관되고 효율적으로 실행할 수 있습니다.
라이브러리 팩은 쿼리 팩(또는 다른 라이브러리 팩)에서 사용하도록 설계되었으며 쿼리 자체를 포함하지 않습니다. 라이브러리는 별도로.
모델 팩을 사용하여 기본적으로 지원되지 않는 종속성을 포함하도록 code scanning 분석을 확장할 수 있습니다. 모델 팩은 현재 베타 버전이며 변경될 수 있습니다. 베타 버전에서는 리포지토리 수준에서 Java/Kotlin 및 C# 분석에 모델 팩을 사용할 수 있습니다. 자체 모델 팩을 만드는 방법에 대한 자세한 내용은 "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 모델 팩 만들기

참고: 모델 팩은 현재 베타 버전이며 변경될 수 있습니다. 베타 버전에서는 모델 팩을 Java/Kotlin 및 C# 분석으로만 지원합니다.

code scanning 분석을 확장하여 기본적으로 지원되지 않는 라이브러리 및 프레임워크를 인식하는 데 모델 팩을 사용할 수 있습니다. 모델 팩은 YAML로 구현되는 데이터 확장 프로그램을 사용하고 새 종속성에 대한 데이터를 추가하는 방법을 설명합니다. 모델 팩을 지정하면 해당 팩의 데이터 확장 프로그램이 code scanning 분석에 자동으로 추가됩니다. CodeQL 모델 팩과 데이터 확장 프로그램에 대한 자세한 정보는 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 팩을 사용하여 분석 사용자 지정"을(를) 참조하세요.

기존 레거시 QL 팩을 수정하여 CodeQL 쿼리 팩 만들기

qlpack.yml 파일이 이미 있는 경우 해당 파일을 수동으로 편집하여 CodeQL 팩으로 변환할 수 있습니다.

<scope>/<name> 형식과 일치하도록 name 속성을 편집합니다. 여기서 <scope>는 게시할 GitHub 조직 또는 사용자 계정의 이름입니다.
qlpack.yml 파일에 semver 식별자가 있는 version 속성과 선택적 dependencies 블록을 포함합니다.
libraryPathDependencies의 종속성 목록을 dependencies 블록으로 마이그레이션합니다. 각 종속성의 버전 범위를 지정합니다. 범위가 중요하지 않거나 호환성이 확실하지 않은 경우 "\*"를 지정할 수 있습니다. 이는 모든 버전이 허용되며 codeql pack install 실행 시 기본값이 최신 버전으로 설정됨을 나타냅니다.

속성에 대한 자세한 내용은 "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 원본을 기본 설정으로 사용합니다.