CodeQL 팩 만들기 및 작업

          CodeQL 팩 및CodeQL CLI

          CodeQL 팩은 CodeQL 쿼리 및 라이브러리를 만들고 공유하며, 의존하고 실행하는 데 사용됩니다.

이 pack 명령을 CodeQL CLI 사용하여 팩을 만들고 CodeQL , 팩에 종속성을 추가하고, 종속성을 설치하거나 업데이트할 수 있습니다. CodeQL 팩을 pack 명령을 사용하여 게시하고 다운로드할 수도 있습니다.

          CodeQL 팩 만들기

프로젝트의 체크아웃 루트에서 다음 명령을 실행하여 CodeQL 팩을 만들 수 있습니다.

codeql pack init <scope>/<pack>

다음을 지정해야 합니다.

•         `<scope>`: 게시할 조직 또는 사용자 계정의 GitHub 이름입니다.
  

•         `<pack>`: 만들 팩의 이름입니다.
  

이 codeql pack init 명령은 팩에 대한 CodeQL 디렉터리 구조 및 구성 파일을 만듭니다. 이 명령어는 기본적으로 쿼리 팩을 생성합니다. 라이브러리 팩을 생성하기 위해서는 qlpack.yml 파일을 편집하여 library:true 속성을 포함한 파일을 라이브러리 팩으로 명시적으로 선언해야 합니다.

          CodeQL 모델 팩 만들기

모델 팩을 사용하여 분석을 확장 code scanning 하여 기본적으로 지원되지 않는 라이브러리 및 프레임워크를 인식할 수 있습니다. 모델 팩은 YAML 기반의 데이터 확장 프로그램을 활용하며, 새로운 종속성을 위한 데이터를 추가하는 방법을 제시합니다. 모델 팩을 지정하면 해당 팩의 데이터 확장이 분석에 자동으로 추가 code scanning 됩니다. 모델 팩 및 데이터 확장 프로그램에 대한 CodeQL 자세한 내용은 CodeQL 모델 편집기 사용을 참조하세요.

모델 팩은 CodeQL 파일 내의 qlpack.yml 파일에서 다음과 같은 특성을 가진 팩입니다.

•         `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/**/의 모든 데이터 확장 프로그램을 codeql/java-all부터 1.2.3까지의 버전인 1.3.0 쿼리 팩 및 codeql/util부터 4.5.6까지의 버전인 4.6.0 쿼리 팩에 삽입합니다. 보다 자세한 정보는 npm 공식 문서의 시맨틱 버저닝 사용 가이드와 시맨틱 버저닝 명세를 확인하시기 바랍니다.

모델 팩을 만든 후에는 다른 CodeQL 팩과 동일한 방식으로 게시할 수 있습니다. 자세한 내용은 CodeQL 팩 게시 및 사용을(를) 참조하세요. 그런 다음, --model-packs 옵션을 사용하여 code scanning 분석에서 게시된 모델 팩을 활용할 수 있습니다. 자세한 내용은 CodeQL 팩을 사용하여 분석 사용자 지정을(를) 참조하세요.

팩에 CodeQL 종속성 추가 및 설치

명령을 CodeQL사용하여 팩에 codeql pack add 종속성을 추가할 수 있습니다. 범위, 이름, 그리고 호환되는 버전 범위(선택 사항)를 명시해야 합니다.

codeql pack add <scope>/<name>@x.x.x <scope>/<other-name>

특정 버전을 명시하지 않을 경우, 자동으로 가장 최신 버전이 적용됩니다. 요청 범위에 부합하는 최신 버전이 자동으로 추가됩니다.

이 명령은 요청된 종속성을 기반으로 qlpack.yml 파일을 업데이트하며, 동시에 패키지를 캐시에 다운로드합니다. 이 명령은 파일의 형식을 재설정하면서 포함된 모든 주석을 삭제합니다.

수동으로 qlpack.yml 파일을 수정하여 의존성을 직접 추가한 뒤, 명령어를 실행해 설치하는 방법도 가능합니다.

codeql pack install

이 명령은 모든 종속성을 로컬 디스크의 공유 캐시로 다운로드합니다.

          CodeQL 팩의 디렉터리 구조 구성

팩은 루트 디렉터리에 qlpack.yml라는 파일을 포함해야 합니다. qlpack.yml 파일의 name: 필드에는 <scope>/<pack> 형식을 따라야 하는 값이 있어야 하며, 여기서 <scope>는 팩이 게시될 조직 또는 사용자 계정이고, <pack>는 팩의 이름입니다.

또한 CodeQL 테스트가 포함된 쿼리 팩과 라이브러리 팩에는 팩의 해결된 종속성이 포함된 파일이 codeql-pack.lock.yml 있습니다. 이 파일은 codeql pack install 명령 실행 중에 자동으로 생성되므로 직접 수정할 수 없으며, 반드시 버전 제어 시스템에 포함시켜야 합니다.

팩 내의 다른 파일 및 디렉터리를 논리적으로 구성해야 합니다. 예를 들어, 일반적으로:

• 쿼리는 특정 범주에 대한 디렉터리로 구성됩니다.
• 특정 제품, 라이브러리 및 프레임워크에 대한 쿼리는 자체 최상위 디렉터리로 구성됩니다.

다운로드한 CodeQL 팩 사용자 지정

팩의 변경 사항을 검증하기 위해서는 소스 코드가 담긴 리포지토리를 복제하여 실험하는 것이 가장 좋은 방법입니다.

사용할 수 있는 원본 리포지토리가 없고 Container registry에서 다운로드한 팩을 기반으로 수정을 해야 하는 경우, 이러한 팩은 다운로드 후 수정하거나 사용자 지정을 염두에 두고 설계된 것이 아니므로, 이후 형식이 예고 없이 변경될 수 있습니다. 콘텐츠 수정이 필요하다면, 팩을 다운로드한 뒤 아래 절차를 따르시기 바랍니다.

• 수정되지 않은 팩의 결과와 혼동을 피하기 위해 팩의 이름 을 qlpack.yml 로 변경합니다.

• 압축 해제된 디렉터리 내에서 *.qlx 라는 이름을 가진 모든 파일을 삭제합니다. 이러한 파일에는 미리 컴파일된 버전의 쿼리가 포함되어 있으며, 경우에 따라 CodeQL 수정한 QL 원본을 기본 설정으로 사용합니다.