CodeQL을 사용하는 코드 검사 워크플로 사용자 지정 - 1부

10분

CodeQL을 사용하는 코드 검사 워크플로의 다양한 구성 옵션은 조직의 필요에 맞게 조정할 수 있습니다.

CodeQL을 사용하여 코드를 검사하는 경우 CodeQL 분석 엔진은 코드에서 데이터베이스를 생성하고 해당 데이터베이스에서 쿼리를 실행합니다. CodeQL 분석은 기본 쿼리 세트를 사용하지만, 기본 쿼리 외에도 실행할 쿼리를 추가로 지정할 수 있습니다.

GitHub Container 레지스트리에 게시된 CodeQL 팩(베타) 또는 리포지토리에 저장된 QL 팩의 일부인 경우 추가 쿼리를 실행할 수 있습니다.

CodeQL 코드 검사를 사용하여 실행할 쿼리를 지정하는 두 가지 옵션이 있습니다.

코드 검사 워크플로 사용
사용자 지정 구성 파일 사용

이 단원에서는 추가 쿼리를 참조하도록 워크플로 파일을 편집하는 방법, 쿼리 팩의 쿼리를 사용하는 방법, 워크플로 파일과 사용자 지정 구성 파일의 쿼리를 결합하는 방법을 알아봅니다.

워크플로 파일에서 추가 쿼리 지정

실행할 추가 쿼리를 지정하는 데 사용할 수 있는 옵션은 다음과 같습니다.

packs - 하나 이상의 CodeQL 쿼리 팩(베타)을 설치하고 해당 팩에 대한 기본 쿼리 도구 모음 또는 쿼리를 실행합니다.
queries - 단일 .ql 파일, 여러 .ql 파일이 포함된 디렉터리, .qls 쿼리 도구 모음 정의 파일 또는 임의 조합을 지정합니다.

동일한 워크플로에서 팩과 쿼리를 모두 사용할 수 있습니다.

github/codeql 같이 github/codeql/cpp/ql/src@main 리포지토리에서 직접 쿼리 도구 모음을 참조하는 것은 좋지 않습니다. 해당 쿼리는 다른 쿼리에 사용된 것과 동일한 버전의 CodeQL로 컴파일되지 않을 수 있으므로 분석 중에 오류가 발생할 수 있습니다.

CodeQL 쿼리 팩 사용

참고

CodeQL 팩을 포함한 CodeQL 패키지 관리 기능은 현재 베타 버전이며 변경될 수 있습니다.

하나 이상의 CodeQL 쿼리 팩(베타)을 추가하려면 워크플로의 with: packs: 섹션 내에 uses: github/codeql-action/init@v1 항목을 추가합니다. 팩에서 사용하려는 패키지를 하나 이상 지정하고 필요에 따라 다운로드할 버전을 지정할 수 있습니다. 버전을 지정하지 않으면 최신 버전이 다운로드됩니다. 공개되지 않은 패키지를 사용하려면 GITHUB_TOKEN 환경 변수를 해당 패키지에 액세스할 수 있는 비밀로 설정해야 합니다.

아래 예제의 범위는 패키지를 게시한 조직 또는 개인 계정입니다. 워크플로가 실행되면 세 개의 CodeQL 쿼리 팩이 GitHub에서 다운로드되고 각 팩의 기본 쿼리 또는 쿼리 도구 모음이 실행됩니다. 다음 예제에서는 목록의 각 팩이 사양에 따라 다운로드됩니다.

최신 버전 pack1 이 다운로드되고 모든 기본 쿼리가 실행됩니다.
버전 1.2.3 pack2 이 다운로드되고 모든 기본 쿼리가 실행됩니다.
최신 버전은 pack3 버전 3.2.1과 호환되며 모든 쿼리가 실행됩니다.
버전 4.5.6 pack4 이 다운로드되고 경로/쿼리에 있는 쿼리만 실행됩니다.

- uses: github/codeql-action/init@v3
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/pack2@1.2.3,scope/pack3@~3.2.1,scope/pack4@4.5.6:path/to/queries

참고

여러 언어에 대한 CodeQL 데이터베이스를 생성하는 워크플로의 경우 구성 파일에서 CodeQL 쿼리 팩을 대신 지정해야 합니다.

QL 팩에서 쿼리 사용

하나 이상의 쿼리를 추가하려면 워크플로의 with: queries: 섹션 내에 uses: github/codeql-action/init@v3 항목을 추가합니다. 쿼리가 프라이빗 리포지토리에 있는 경우 external-repository-token 매개 변수를 사용하여 프라이빗 리포지토리를 체크 아웃할 액세스 권한이 있는 토큰을 지정합니다.

- uses: github/codeql-action/init@v3
  with:
    # Comma-separated list of queries / packs / suites to run.
    # This may include paths or a built in suite, for example:
    # security-extended or security-and-quality.
    queries: security-extended
    # Optional. Provide a token to access queries stored in private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

queries 값에 쿼리 도구 모음을 지정할 수도 있습니다. 쿼리 도구 모음은 일반적으로 목적 또는 언어별로 그룹화된 쿼리 컬렉션입니다.

다음 쿼리 도구 모음은 CodeQL 코드 검사에 기본 제공되어 있으며 사용할 수 있습니다.

쿼리 도구 모음	설명
`security-extended`	기본 설정 제품군의 쿼리와 낮은 심각도와 정밀도의 쿼리
`security-and-quality`	`security-extended`의 쿼리, 유지 보수 및 신뢰성 관련 쿼리

이러한 각 쿼리 모음에는 해당 언어에 대한 기본 제공 CodeQL 쿼리 팩에 포함된 쿼리의 서로 다른 하위 집합이 포함되어 있습니다. 쿼리 도구 모음은 각 쿼리에 대한 메타데이터를 사용하여 자동으로 생성됩니다.

쿼리 도구 모음을 지정하면 CodeQL 분석 엔진이 기본 쿼리 세트에 더해 해당 도구 모음에 포함된 쿼리를 실행합니다.

워크플로 파일 및 사용자 지정 구성 파일의 쿼리 결합

또한 사용자 지정 설정에 구성 파일을 사용하는 경우 구성 파일에 지정된 팩이나 쿼리 대신 워크플로에 지정된 추가 팩이나 쿼리가 사용됩니다. 결합된 추가 팩 또는 쿼리 집합을 실행하려면 워크플로에서 packs 또는 queries 값 앞에 + 기호를 붙입니다.

다음 예제에서는 + 기호가 추가되었기 때문에 참조된 구성 파일에 지정된 모든 팩 및 쿼리와 함께 지정된 추가 팩과 쿼리가 사용됩니다.

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/pack2@1.2.3,scope/pack3@4.5.6:path/to/queries

피드백

이 페이지가 도움이 되었나요?