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

8분

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

이 단원에서는 사용자 지정 구성 파일에서 추가 쿼리를 참조하는 방법을 검토합니다.

사용자 지정 구성 파일의 추가 쿼리

사용자 지정 구성 파일은 실행할 추가 팩 및 쿼리를 지정하는 다른 방법입니다. 이 파일을 사용하여 기본 쿼리를 사용하지 않도록 설정하고 분석 중에 검사할 디렉터리를 지정할 수도 있습니다.

워크플로 파일에서 config-file 작업의 init 매개 변수를 사용하여 이후 사용하려는 구성 파일의 경로를 지정합니다. 이 예제에서는 ./.github/codeql/codeql-config.yml 구성 파일을 로드합니다.

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml

구성 파일은 분석 중인 리포지토리나 외부 리포지토리에 있을 수 있습니다. 외부 리포지토리를 사용하면 한 곳에서 여러 리포지토리에 대한 구성 옵션을 지정할 수 있습니다. 외부 리포지토리에 있는 구성 파일을 참조하는 경우 OWNER/REPOSITORY/FILENAME@BRANCH 구문을 사용할 수 있습니다. 예: octo-org/shared/codeql-config.yml@main

구성 파일이 외부 프라이빗 리포지토리에 있는 경우 external-repository-token 작업의 init 매개 변수를 사용하여 프라이빗 리포지토리에 대한 액세스 권한이 있는 토큰을 지정합니다.

- uses: github/codeql-action/init@v3
  with:
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

구성 파일의 설정은 YAML 형식으로 작성됩니다.

사용자 지정 구성 파일에서 CodeQL 쿼리 팩 지정

참고

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

CodeQL 쿼리 팩은 배열에 지정할 수 있습니다. 형식은 워크플로 파일에서 사용하는 형식과 다릅니다.

packs:
packs:
  # Use the latest version of 'pack1' published by 'scope'
  - scope/pack1
  # Use version 1.2.3 of 'pack2'
  - scope/pack2@1.2.3
  # Use the latest version of 'pack3' compatible with 3.2.1
  - scope/pack3@~3.2.1
  # Use pack4 and restrict it to queries found in the 'path/to/queries' directory
  - scope/pack4:path/to/queries
  # Use pack5 and restrict it to the query 'path/to/single/query.ql'
  - scope/pack5:path/to/single/query.ql
  # Use pack6 and restrict it to the query suite 'path/to/suite.qls'
  - scope/pack6:path/to/suite.qls

쿼리 팩을 지정하기 위한 전체 형식은 scope/name[@version][:path]입니다. version 및 path는 모두 선택 사항입니다. version은 semver 버전 범위입니다. 누락된 경우 최신 버전이 사용됩니다.

둘 이상의 CodeQL 데이터베이스를 생성하는 워크플로가 있는 경우 중첩된 팩 맵을 사용하여 사용자 지정 구성 파일에서 실행할 CodeQL 쿼리 팩을 지정할 수 있습니다.

packs:
  # Use these packs for JavaScript and TypeScript analysis
  javascript:
    - scope/js-pack1
    - scope/js-pack2
  # Use these packs for Java and Kotlin analysis
  java:
    - scope/java-pack1
    - scope/java-pack2@v1.0.0

사용자 지정 구성의 추가 쿼리 지정

queries 배열에 추가 쿼리를 지정할 수 있습니다. 배열의 각 요소에는 단일 쿼리 파일, 쿼리 파일이 포함된 디렉터리 또는 쿼리 도구 모음 정의 파일을 식별하는 값이 있는 uses 매개 변수가 포함되어 있습니다.

queries:
  - uses: ./my-basic-queries/example-query.ql
  - uses: ./my-advanced-queries
  - uses: ./query-suites/my-security-queries.qls

필요에 따라 아래 샘플 구성 파일에 나와 있는 것처럼 각 배열 요소에 이름을 지정할 수 있습니다.

name: "My CodeQL config"

disable-default-queries: true

queries:
  - name: Use an in-repository QL pack (run queries in the my-queries directory)
    uses: ./my-queries
  - name: Use an external JavaScript QL pack (run queries from an external repo)
    uses: octo-org/javascript-qlpack@main
  - name: Use an external query (run a single query from an external QL pack)
    uses: octo-org/python-qlpack/show_ifs.ql@main
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-qlpacks/complex-python-qlpack/rootAndBar.qls

paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

기본 쿼리 사용 안 함

사용자 지정 쿼리만 실행하려면 disable-default-queries: true를 사용하여 기본 보안 쿼리를 사용하지 않도록 설정할 수 있습니다. 특정 규칙을 제외하는 사용자 지정 쿼리 도구 모음을 생성하려는 경우에도 이 플래그를 사용해야 합니다. 이는 모든 쿼리가 두 번 실행되지 않도록 하기 위한 것입니다.

분석에서 특정 쿼리 제외

사용자 지정 구성 파일에 exclude 및 include 필터를 추가하여 다음과 같이 분석에 제외하거나 포함할 쿼리를 지정할 수 있습니다.

기본 도구 모음(security, security-extended 및 security-and-quality)의 특정 쿼리입니다.
결과에 관심이 없는 특정 쿼리.
경고 및 권장 사항을 생성하는 모든 쿼리입니다.

다음 파일에서 구성의 필터와 유사한 exclude 필터를 사용하여 기본 분석에서 제거하려는 쿼리를 제외할 수 있습니다. 예시의 구성 파일에서는 js/redundant-assignment 및 js/useless-assignment-to-local 쿼리가 분석에서 제외됩니다.

query-filters:
  - exclude:
      id: js/redundant-assignment
  - exclude:
      id: js/useless-assignment-to-local

쿼리의 ID를 찾으려면 보안 탭의 경고 목록에서 경고를 클릭할 수 있습니다. 그러면 경고 세부 정보 페이지가 열립니다. 규칙 ID 필드에는 쿼리 ID가 포함됩니다.

excludes 필터를 사용할 때 유의해야 할 사항:

필터의 순서가 중요합니다. 쿼리 및 쿼리 팩에 대한 지침 이후에 표시되는 첫 번째 필터 명령은 쿼리가 기본값으로 포함되는지 아니면 제외되는지를 결정합니다.
후속 지침은 순서대로 실행되며 파일의 뒷부분에 표시되는 지침이 이전 지침보다 우선합니다.

검사할 디렉터리 지정

CodeQL에서 지원하는 해석된 언어(Python, Ruby 및 JavaScript/TypeScript)의 경우 구성 파일에 paths 배열을 추가하여 특정 디렉터리의 파일로 코드 검사를 제한할 수 있습니다. paths-ignore 배열을 추가하여 분석에서 특정 디렉터리에 있는 파일을 제외할 수 있습니다.

paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

참고

코드 검색 구성 파일의 컨텍스트에서 사용되는 paths 및 paths-ignore 키워드는 워크플로의 on.<push|pull_request>.paths에 사용되는 동일한 키워드와 혼동해서는 안 됩니다. 이 키워드가 워크플로에서 on.<push|pull_request>를 수정하는 데 사용된 경우, 누군가가 지정된 디렉터리에서 코드를 수정할 때 작업이 실행될지 여부가 이 키워드에 의해 결정됩니다.
?, +, [, ], ! 필터 패턴 문자는 지원되지 않으며 문자 그대로 일치하게 처리됩니다.
** 문자는 줄의 시작 또는 끝에만 있거나 슬래시로 둘러싸일 수 있으며 ** 및 다른 문자와 혼합할 수 없습니다. 예를 들어 foo/**, **/foo, foo/**/bar는 모두 허용되는 구문이지만 **foo는 허용되지 않습니다. 그러나 예제와 같이 별 하나만 다른 문자와 함께 사용할 수 있습니다. * 문자가 포함된 모든 항목을 인용해야 합니다.

컴파일된 언어의 경우 코드 검사를 프로젝트의 특정 디렉터리로 제한하려면 워크플로에서 적절한 빌드 단계를 지정해야 합니다. 빌드에서 디렉터리를 제외하는 데 사용해야 하는 명령은 빌드 시스템에 따라 달라집니다.

특정 디렉터리에서 코드를 수정할 때 monorepo의 작은 부분을 빠르게 분석할 수 있습니다. 빌드 단계에서 디렉터리를 제외하고, 워크플로에서 paths-ignore에 대해 paths 및 on.<push|pull_request> 키워드를 모두 사용해야 합니다.

피드백

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