CodeQL 팩 만들기 및 작업

CodeQL팩 및 CodeQL CLI에 대해

CodeQL 팩을 사용하면 CodeQL 쿼리와 라이브러리를 작성하고 공유할 수 있으며, 이를 실행하여 다양하게 활용할 수 있습니다.

CodeQL CLI의 pack 명령어를 사용하여 독자적인 CodeQL 팩을 만들고, 필요한 종속성을 추가한 후 설치 또는 업데이트할 수 있습니다. pack 명령어를 통해 CodeQL 팩의 게시와 다운로드를 수행할 수 있습니다.

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 모델 편집기 사용을 참고하시기 바랍니다.

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

모델 팩 제작을 완료했다면, 이제 다른 CodeQL 팩과 마찬가지로 동일한 절차를 거쳐 게시할 수 있습니다. 자세한 내용은 CodeQL 팩 게시 및 사용을(를) 참조하세요. 그런 다음 code scanning 분석에 게시된 모델 팩을 --model-packs 옵션과 함께 사용할 수 있습니다. 자세한 내용은 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 팩의 디렉터리 구조를 구성하기

CodeQL 팩의 루트 디렉터리에는 qlpack.yml 라는 파일이 반드시 존재해야 합니다. qlpack.yml 파일 내 name: 필드에는 <scope>/<pack> 형식을 따르는 값을 입력해야 합니다. 이때 <scope>는 팩이 게시될 GitHub 조직 또는 사용자 계정을 의미하며, <pack> 는 팩의 이름입니다.

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

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

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

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

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

원본 리포지토리에 접근할 수 없거나 Container registry에서 다운로드한 팩을 기본적으로 수정해야 하는 경우, 이러한 팩은 다운로드 후 수정하거나 사용자 지정할 수 없으며 향후 해당 형식이 변경될 수 있습니다. 콘텐츠 수정이 필요하다면, 팩을 다운로드한 뒤 아래 절차를 따르시기 바랍니다.

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

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