코드 검색을 위한 워크플로 구성 옵션

참고

사이트 관리자가 먼저 code scanning을 사용하도록 설정해야 이 기능을 사용할 수 있습니다. GitHub Actions를 사용하여 코드를 스캔하려면 사이트 관리자도 GitHub Actions를 사용하도록 설정하고 필요한 인프라를 설정해야 합니다. 자세한 내용은 어플라이언스에 대한 코드 스캐닝 구성을(를) 참조하세요.

참고

이 문서에서는 이 GitHub Enterprise Server 버전의 초기 릴리스에 포함된 CodeQL 작업과 관련 CodeQL CLI 번들의 버전에서 사용할 수 있는 기능을 설명합니다. 엔터프라이즈에서 더 최신 버전의 CodeQL 작업을 사용하는 경우, 최신 기능에 대한 자세한 내용은 이 문서의GitHub Enterprise Cloud 버전을 참조하세요. 최신 버전 사용에 대한 자세한 내용은 어플라이언스에 대한 코드 스캐닝 구성을(를) 참조하세요.

필수 조건

code scanning의 고급 설정을 활용하려면 구성이 정의된 워크플로 파일을 편집할 수 있어야 합니다.

이 문서에 제공된 예제는 CodeQL 분석 워크플로 파일과 관련이 있습니다. 기본적으로 이 파일은 .에서 .github/workflows/codeql-analysis.yml정의됩니다.

스캔 빈도

일정에 따라 또는 리포지토리에서 특정 이벤트가 발생하는 경우에 코드를 검사하도록 CodeQL 분석 워크플로를 구성할 수 있습니다.

누군가가 변경 사항을 푸시할 때 또는 끌어오기 요청을 만들 때마다 코드를 검사하면 개발자가 코드에 새로운 취약성 및 오류를 도입할 수 없습니다. 일정에 따라 코드를 검사하면 개발자가 리포지토리를 적극적으로 유지 관리하지 않는 경우에도 GitHub, 보안 연구원 및 커뮤니티가 발견한 최신 취약성 및 오류에 대해 알 수 있습니다.

푸시할 때 검사

기본 설정에 따라, CodeQL 분석 워크플로는 on:push 이벤트를 사용하여 리포지토리의 기본 분기 및 보호된 분기에 푸시할 때마다 코드 검사를 트리거합니다. 지정된 분기에서 code scanning을 트리거하려면 워크플로가 해당 분기에 있어야 합니다. 자세한 내용은 GitHub Actions에 대한 워크플로 구문을(를) 참조하세요.

푸시할 때 검사하면 리포지토리의 보안 탭에 결과가 표시됩니다. 자세한 내용은 리포지토리에 대한 코드 검사 경고 평가을(를) 참조하세요.

또한 on:push 검사가 열려 있는 끌어오기 요청에 매핑할 수 있는 결과를 반환하면, 이러한 경고는 다른 끌어오기 요청 경고와 동일한 위치의 끌어오기 요청에 자동으로 표시될 것입니다. 경고는 분기 헤드의 기존 분석을 대상 분기에 대한 분석과 비교하여 식별됩니다. 끌어오기 요청에서의 code scanning 경고에 대한 자세한 내용은 끌어오기 요청에서 코드 검사 경고 심사에서 확인할 수 있습니다.

끌어오기 요청 검사

기본 CodeQL 분석 워크플로는 pull_request 이벤트를 사용하여 기본 분기를 대상으로 하는 끌어오기 요청에 대한 코드 검사를 트리거합니다. 끌어오기 요청이 프라이빗 포크에서 열린 경우 pull_request 이벤트가 트리거되지 않습니다.

          `pull_request` 이벤트에 대한 자세한 내용은 [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#pull_request)에서 확인할 수 있습니다.

끌어오기 요청을 검사하면 결과가 끌어오기 요청 검사에서 경고로 표시됩니다. 자세한 내용은 끌어오기 요청에서 코드 검사 경고 심사을(를) 참조하세요.

끌어오기 요청의 헤드 커밋이 아닌 병합 커밋을 검색하도록 구성된 pull_request 트리거를 사용하면, 각 푸시에서 분기의 헤드를 검사하는 것보다 더 효율적이고 정확한 결과를 생성합니다. 그러나 끌어오기 요청에서 트리거하도록 구성할 수 없는 CI/CD 시스템을 사용하는 경우에도 on:push 트리거를 사용할 수 있으며 code scanning은 결과를 매핑하여 분기에서 끌어오기 요청을 열고 끌어오기 요청에 대한 주석으로 경고를 추가합니다. 자세한 내용은 푸시할 때 검사에서 확인할 수 있습니다.

불필요한 끌어오기 요청 검사 방지

변경된 파일에 관계없이 기본 분기를 대상으로 하는 특정 끌어오기 요청에서 코드 검사가 트리거되지 않도록 할 수 있습니다. code scanning 워크플로에서 on:pull_request:paths-ignore 또는 on:pull_request:paths를 지정하면 이 설정을 구성할 수 있습니다. 예를 들어, 끌어오기 요청의 유일한 변경 사항이 파일 확장자가 .md 또는 .txt인 파일인 경우 다음 paths-ignore 배열을 사용할 수 있습니다.

YAML

on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
    paths-ignore:
      - '**/*.md'
      - '**/*.txt'

on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
    paths-ignore:
      - '**/*.md'
      - '**/*.txt'

참고

          `on:pull_request:paths-ignore` 및 `on:pull_request:paths`는 워크플로에서의 작업이 끌어오기 요청에서 실행될지 여부를 결정하는 조건을 설정합니다.

          _작업이 실행_될 때 분석할 파일을 결정하지 않습니다. 끌어오기 요청에 `on:pull_request:paths-ignore` 또는 `on:pull_request:paths`와 일치하지 않은 파일이 포함된 경우 워크플로는 이러한 파일이 제외되지 않은 한, 작업을 실행하고 끌어오기 요청에서 변경된 모든 파일(`on:pull_request:paths-ignore` 또는 `on:pull_request:paths`와 일치하는 파일 포함)을 검색합니다. 분석에서 파일을 제외하는 자세한 방법은 [검사할 디렉터리 지정](#specifying-directories-to-scan)에서 확인할 수 있습니다.

          `on:pull_request:paths-ignore` 및 `on:pull_request:paths`를 사용하여 끌어오기 요청에 대해 워크플로가 실행되는 시기를 결정하는 방법에 대한 자세한 내용은 [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore)에서 확인할 수 있습니다.

일정에 따라 검사

기본 CodeQL 분석 워크플로를 사용하는 경우, 이 워크플로는 이벤트에 의해 트리거되는 검사 외에도 일주일에 한 번 리포지토리의 코드 검사를 수행합니다. 이 일정을 조정하려면 워크플로에서 cron 이벤트에 대한 on.schedule 값을 편집하세요. 자세한 내용은 GitHub Actions에 대한 워크플로 구문을(를) 참조하세요.

참고

데이터 재사용 가능한.actions.branch-requirement %}

예시

다음 예제에서는 main이라는 기본값 분기 및 protected라는 보호된 분기가 있는 특정한 리포지토리에 대한 CodeQL 분석 워크플로를 확인할 수 있습니다.

YAML

on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
  schedule:
    - cron: '20 14 * * 1'

on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
  schedule:
    - cron: '20 14 * * 1'

이 워크플로는 다음을 검사합니다.

기본 분기 및 보호된 분기에 대한 모든 푸시
기본 분기에 대한 모든 끌어오기 요청
매주 월요일 14:20 UTC의 기본 분기

운영 체제

참고

Swift 코드의 코드 스캐닝은 기본적으로 macOS 실행기를 사용합니다.
데이터 재사용 가능성.코드 스캐닝.기본 설정 스위프트 셀프 호스티드 러너 %}

코드를 컴파일하기 위해 특정 운영 체제가 필요한 경우, 운영 체제를 CodeQL 분석 워크플로에서 구성할 수 있습니다. code scanning 작업을 실행하는 머신의 운영 체제를 지정하려면 jobs.analyze.runs-on 값을 편집합니다. 적절한 레이블을 두 요소 배열에서 self-hosted 다음에 오는 두 번째 요소로 사용하여 운영 체제를 지정합니다.

YAML

jobs:
  analyze:
    name: Analyze
    runs-on: [self-hosted, ubuntu-latest]

jobs:
  analyze:
    name: Analyze
    runs-on: [self-hosted, ubuntu-latest]

CodeQL code scanning는 최신 버전의 Ubuntu, Windows 및 macOS를 지원합니다. 따라서 이 설정의 일반적인 값은 ubuntu-latest, windows-latest, macos-latest입니다. 자세한 내용은 작업에 적합한 러너 선택 및 자체 호스트형 실행기에서 레이블 사용을(를) 참조하세요.

Git가 자체 호스팅 실행기의 PATH 변수에 있는지 확인해야 합니다. 자세한 내용은 자체 호스팅 실행기 및 자체 호스트형 실행기 추가에서 확인할 수 있습니다.

CodeQL 분석을 실행하기 위한 권장 사양(RAM, CPU 코어 및 디스크)에 대해서는 CodeQL을 실행하기 위한 권장 하드웨어 리소스에서 확인할 수 있습니다.

CodeQL 데이터베이스 위치

일반적으로 이전 단계에서 생성한 데이터베이스는 이후 단계에서 자동으로 찾아 주므로, CodeQL 분석 워크플로가 CodeQL 데이터베이스를 어디에 배치하는지는 걱정하지 않아도 됩니다. 그러나 CodeQL 데이터베이스가 특정 디스크 위치에 있어야 하는 사용자 지정 워크플로 단계를 작성하는 경우(예: 데이터베이스를 워크플로 아티팩트로 업로드하는 경우)에는 db-location 작업에서 init 매개 변수를 사용하여 해당 위치를 지정할 수 있습니다.

YAML

- uses: github/codeql-action/init@v4
  with:
    db-location: '${{ github.runner_temp }}/my_location'

- uses: github/codeql-action/init@v4
  with:
    db-location: '${{ github.runner_temp }}/my_location'

CodeQL 분석 워크플로에서는 db-location에 제공된 경로가 쓰기 가능하며, 존재하지 않거나 또는 빈 디렉터리일 것으로 예상합니다. 자체 호스팅 실행기에서 실행 중이거나 Docker 컨테이너를 사용하는 작업에서 이 매개 변수를 사용하는 경우, 사용자는 선택된 디렉터리가 다음 실행 전에 지워지거나 필요 없어진 데이터베이스가 제거되는지 확인해야 합니다. 이것은 실행할 때마다 새 인스턴스와 정리된 파일 시스템을 얻는 GitHub 호스팅 실행기에서 실행 중인 작업에는 필요하지 않습니다. 자세한 내용은 GitHub 호스팅 실행기을(를) 참조하세요.

이 매개 변수를 사용하지 않는 경우, CodeQL 분석 워크플로는 자체적으로 선택한 임시 위치에 데이터베이스를 생성합니다. 현재의 기본값은 ${{ github.runner_temp }}/codeql_databases입니다.

분석할 언어

CodeQL code scanning은 다음 언어로 작성된 코드를 지원합니다.

C/C++
C#
Go
Java/Kotlin
JavaScript/TypeScript
Python
루비
Rust(공개 미리 보기)
Swift

참고

Java, Kotlin 또는 둘 다로 작성된 코드를 분석하는 데 java-kotlin을 사용합니다.
JavaScript, TypeScript 또는 둘 다로 작성된 코드를 분석하는 데 javascript-typescript을(를) 사용합니다.

자세한 내용은 CodeQL 웹 사이트의 설명서의 지원되는 언어와 프레임워크를 참조하세요.

CodeQL은 다음 언어 식별자를 사용합니다.

데이터 재사용.코드-스캐닝.CodeQL-언어-식별자-테이블 %}

참고

대체 식별자 중 하나를 지정하는 경우 표준 언어 식별자를 사용하는 것과 같습니다. 예를 들어 javascript 대신 javascript-typescript를 지정해도 TypeScript 코드의 분석은 제외되지 않습니다. 대신, 사용자 지정 구성 파일을 사용하여 paths-ignore 설정으로 분석에서 파일을 제외할 수 있습니다. 자세한 내용은 사용자 지정 구성 파일 사용 및 검사할 디렉터리 지정을 참조하세요.

이러한 언어 식별자는 languages 작업의 init 입력에 대한 인수로 사용할 수 있습니다. 인수로 하나의 언어만 제공하는 것이 좋습니다.

YAML

- uses: github/codeql-action/init@v4
  with:
    languages: javascript-typescript

- uses: github/codeql-action/init@v4
  with:
    languages: javascript-typescript

          [CodeQL을 사용하는 코드 검사를 위한 고급 설정을 구성하면,](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning#configuring-advanced-setup-for-code-scanning-with-codeql) 기본 CodeQL 분석 워크플로 파일이 생성됩니다. 이 파일은 `language`라는 속성을 포함한 행렬형을 정의하며, 여기에는 리포지토리에서 분석할 언어가 나열됩니다. 이 행렬형은 리포지토리에서 자동으로 감지된 지원 언어로 미리 채워집니다. 
          `language` 행렬형을 사용하면 CodeQL이 각 언어 분석을 병렬로 실행할 수 있고, 각 언어별로 분석을 사용자 지정할 수 있습니다. 개별 분석에서는 행렬형의 언어 이름이 `init` 입력의 인수로 `languages` 작업에 제공됩니다. 모든 워크플로에서 이 구성을 채택하는 것이 좋습니다. 행렬에 대한 자세한 내용은 [AUTOTITLE](/actions/using-jobs/using-a-matrix-for-your-jobs)을(를) 참조하세요.

YAML

- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}

- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}

워크플로에서 language 행렬형을 사용하는 경우, CodeQL은 행렬형의 언어만 분석합니다. 분석할 언어를 변경하려면 행렬형 구성을 편집하면 됩니다. 특정 언어가 분석되지 않도록 해당 언어를 제거할 수도 있습니다. 언어가 분석되지 않게 해야 하는 몇 가지 이유가 있습니다. 예를 들어, 프로젝트에 코드의 본문과 다른 언어로 종속성이 있을 수 있는데 이러한 종속성에 대한 경고를 표시하고 싶지 않을 수 있습니다. code scanning을 구성할 때 리포지토리에 없었던 언어를 추가할 수도 있습니다. 예를 들어 처음 code scanning가 구성될 때 리포지토리에 JavaScript만 포함되어 있었고 나중에 Python 코드를 추가한 경우, 설정 행렬에 python을 추가해야 합니다.

YAML

jobs:
  analyze:
    name: Analyze
    ...
    strategy:
      fail-fast: false
      matrix:
        include:
          - language: javascript-typescript
            build-mode: none
          - language: python
            build-mode: none

jobs:
  analyze:
    name: Analyze
    ...
    strategy:
      fail-fast: false
      matrix:
        include:
          - language: javascript-typescript
            build-mode: none
          - language: python
            build-mode: none

컴파일된 언어의 경우, 행렬형을 사용하여 분석에 사용할 build-mode 속성 값을 변경함으로써 어떤 빌드 모드를 사용할지 구성할 수도 있습니다. 빌드 모드에 대한 자세한 내용은 컴파일된 언어에 CodeQL 코드 스캐닝을(를) 참조하세요.

워크플로가 languages 작업의 init 입력에 인수를 제공하지 않으면, CodeQL은 순차적으로 분석을 실행하도록 구성됩니다. 이 경우, CodeQL은 리포지토리에서 지원되는 모든 언어를 자동으로 감지하고 분석을 시도합니다. 리포지토리의 크기와 언어 수에 따라 시간이 오래 걸릴 수 있습니다. 이 모드에서 한 언어의 분석이 실패하면, 모든 언어의 분석이 함께 실패하게 됩니다. 따라서 이 구성은 권장하지 않습니다.

참고

언어를 순차적으로 분석할 때, 각 언어의 기본 빌드 모드가 사용됩니다. 다만, 명시적으로 autobuild 단계를 제공하는 경우, autobuild 모드를 지원하는 모든 언어는 이 모드를 사용하고 나머지 언어는 기본 모드를 계속 사용합니다. 이보다 더 복잡한 빌드 모드 구성이 필요한 경우에는 행렬형을 구성해야 합니다.

검사 실패에 대한 경고 심각도

다음 조건 중 하나가 충족될 경우 규칙 집합을 사용하여 끌어오기 요청이 병합되지 않도록 할 수 있습니다.

(여기에서 실제로 변역할 텍스트 필요)

자세한 내용은 코드 검사 병합 보호 설정을(를) 참조하세요. 규칙 집합에 대한 일반적인 정보는 규칙 세트에 대한 정보을 참조하세요.

분석 범주

          `category`는 다양한 언어 또는 다양한 코드 부분에서 수행되지만 동일한 도구와 커밋을 대상으로 하는 여러 분석을 구분하는 데 사용합니다. 워크플로에 지정한 범주는 SARIF 결과 파일에 포함됩니다.

이 매개 변수는 단일 리포지토리로 작업하고 단일 리포지토리의 여러 구성 요소에 대한 여러 SARIF 파일이 있을 때 특히 유용합니다.

YAML

    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v4
      with:
        # Optional. Specify a category to distinguish between multiple analyses
        # for the same tool and ref. If you don't use `category` in your workflow,
        # GitHub will generate a default category name for you
        category: "my_category"

    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v4
      with:
        # Optional. Specify a category to distinguish between multiple analyses
        # for the same tool and ref. If you don't use `category` in your workflow,
        # GitHub will generate a default category name for you
        category: "my_category"

워크플로에서 category 매개 변수를 지정하지 않은 경우, GitHub는 작업을 트리거하는 워크플로 파일의 이름, 작업 이름 및 행렬 변수를 기준으로 범주 이름을 생성할 것입니다. 다음은 그 예입니다. * .github/workflows/codeql-analysis.yml 워크플로와 analyze 작업은 .github/workflows/codeql.yml:analyze 범주를 생성합니다. * .github/workflows/codeql-analysis.yml 워크플로, analyze 작업과 {language: javascript-typescript, os: linux} 행렬 변수는 .github/workflows/codeql-analysis.yml:analyze/language:javascript-typescript/os:linux 범주를 생성합니다.

          `category` 값은 SARIF v2.1.0의 `<run>.automationDetails.id` 속성에 표시됩니다. 자세한 내용은 [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#runautomationdetails-object)을(를) 참조하세요.

지정된 범주는 SARIF 파일(포함된 경우)에 있는 runAutomationDetails 개체의 세부 정보를 덮어쓰지 않습니다.

CodeQL 모델 팩

코드베이스가 CodeQL의 표준 쿼리에서 인식되지 않는 라이브러리 또는 프레임워크에 종속된 경우, 게시된 CodeQL 모델 팩을 지정하여 code scanning 워크플로에서 CodeQL 적용 범위를 확장할 수 있습니다. 자신만의 모델 팩을 만드는 자세한 내용은 CodeQL 팩 만들기 및 작업에서 확인합니다.

CodeQL 모델 팩 사용하기

하나 이상의 게시된 CodeQL 모델 팩을 추가하려면, 해당 워크플로의 with: packs: 섹션 내에 있는 uses: github/codeql-action/init@v4 항목 내에 해당 모델 팩을 지정합니다. packs 내에서 사용할 패키지를 하나 이상 지정하고, 필요하다면 다운로드할 버전을 지정합니다. 버전을 지정하지 않으면 최신 버전이 다운로드됩니다. 공개적으로 사용할 수 없는 패키지를 사용하려면 GITHUB_TOKEN 환경 변수를 패키지에 액세스할 수 있는 비밀로 설정해야 합니다. 자세한 내용은 워크플로에서 인증에 GITHUB_TOKEN 사용 및 GitHub Actions에서 비밀 사용을(를) 참조하세요.

YAML

- uses: github/codeql-action/init@v4
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: security-extended
    packs: my-company/my-java-queries@~7.8.9,my-repo/my-java-model-pack

- uses: github/codeql-action/init@v4
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: security-extended
    packs: my-company/my-java-queries@~7.8.9,my-repo/my-java-model-pack

이 예제에서는 기본 쿼리가 Java에 대해 실행되며, 쿼리 팩 7.8.9의 버전 중 7.9.0 이상이고 my-company/my-java-queries 미만인 경우의 쿼리도 실행됩니다. 모델 팩 my-repo/my-java-model-pack의 최신 버전에서 모델링된 종속성은 기본값 쿼리와 my-company/my-java-queries의 해당 쿼리 모두에서 사용할 수 있습니다.

기본이 아닌 쿼리

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

팁

분석에서 제외하거나 분석에 포함할 쿼리를 지정할 수도 있습니다. 이를 위해서는 사용자 지정 구성 파일을 사용해야 합니다. 자세한 내용은 사용자 지정 구성 파일 및 아래 분석에서 특정 쿼리 제외를 참조하세요 .

GitHub Container registry에 게시되었거나 리포지토리에 저장된 CodeQL 팩의 일부인 경우 추가 쿼리를 실행할 수 있습니다. 자세한 내용은 CodeQL을 사용하는 코드 검사 안내을(를) 참조하세요.

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

        `packs`: 하나 이상의 CodeQL 쿼리 팩을 설치하고 해당 팩에 대한 기본 쿼리 도구 모음 또는 쿼리를 실행합니다.

        `queries`: 단일 _.ql_ 파일, 여러 _.ql_ 파일이 포함된 디렉터리, _.qls_ 쿼리 도구 모음 정의 파일 또는 임의 조합을 지정합니다. 쿼리 도구 모음 정의에 대한 자세한 내용은 [CodeQL 쿼리 도구 모음 만들기](https://codeql.github.com/docs/codeql-cli/creating-codeql-query-suites/)를 참조하세요.

동일한 워크플로에서 packs 및 queries를 모두 사용할 수 있습니다.

쿼리 팩 사용하기

하나 이상의 CodeQL 쿼리 팩을 추가하려면, 워크플로의 with: packs: 섹션 내에 uses: github/codeql-action/init@v4 항목을 추가합니다. packs 내에서 사용할 패키지를 하나 이상 지정하고, 필요하다면 다운로드할 버전을 지정합니다. 버전을 지정하지 않으면 최신 버전이 다운로드됩니다. 공개적으로 사용할 수 없는 패키지를 사용하려면 GITHUB_TOKEN 환경 변수를 패키지에 액세스할 수 있는 비밀로 설정해야 합니다. 자세한 내용은 워크플로에서 인증에 GITHUB_TOKEN 사용 및 GitHub Actions에서 비밀 사용을(를) 참조하세요.

참고

여러 언어에 대한 CodeQL 데이터베이스를 생성하는 워크플로의 경우, 대신에 사용자가 구성 파일에서 CodeQL 쿼리 팩을 지정해야 합니다. 자세한 내용은 아래의 CodeQL 쿼리 팩 지정하기에서 확인할 수 있습니다.

아래 예제에서 scope는 패키지를 게시한 조직 또는 개인 계정입니다. 해당 워크플로가 실행되면, CodeQL 쿼리 팩 4개가 GitHub에서 다운로드되고 각 팩 실행에 대한 기본 쿼리 또는 쿼리 도구 모음이 실행됩니다.

최신 버전의 pack1이 다운로드되고 모든 기본 쿼리가 실행됩니다.

        `pack2` 버전 1.2.3이 다운로드되고 모든 기본 쿼리가 실행됩니다.

버전 3.2.1과 호환되는 최신 버전의 pack3이 다운로드되고 모든 기본 쿼리가 실행됩니다.

        `pack4` 버전 4.5.6이 다운로드되고 `path/to/queries`에서 찾은 쿼리만 실행됩니다.

YAML

- uses: github/codeql-action/init@v4
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/[email protected],scope/pack3@~3.2.1,scope/[email protected]:path/to/queries

- uses: github/codeql-action/init@v4
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/[email protected],scope/pack3@~3.2.1,scope/[email protected]:path/to/queries

참고

사용할 쿼리 팩의 특정 버전을 지정하면, 지정한 버전이 너무 오래되어 CodeQL 작업에서 사용되는 기본 CodeQL 엔진에서 효율적으로 사용하지 못하게 될 수 있으므로 유의하세요. 정확한 쿼리 팩 버전을 지정해야 하는 경우, 최적의 성능을 보장하기 위해서는 고정된 버전의 쿼리 팩을 업그레이드해야 하는지 정기적으로 검토해야 합니다.

팩 호환성에 대한 자세한 내용은 CodeQL 쿼리 팩 참조을(를) 참조하세요.

GitHub Enterprise Server에서 CodeQL 팩 다운로드하기

워크플로가 게시된 팩을 GitHub Enterprise Server 설치에 사용하는 경우, 워크플로에 해당 팩을 찾을 위치를 알려 주어야 합니다. 이 작업은 github/codeql-action/init@v4 작업의 registries 입력을 사용하여 수행할 수 있습니다. 이 입력은 아래와 같이 url, packages 및 token 속성의 목록을 수락합니다.

YAML

- uses: github/codeql-action/init@v4
  with:
    registries: |
      # URL to the container registry, usually in this format
      - url: https://containers.GHEHOSTNAME1/v2/

        # List of package glob patterns to be found at this registry
        packages:
          - my-company/*
          - my-company2/*

        # Token, which should be stored as a secret
        token: ${{ secrets.GHEHOSTNAME1_TOKEN }}

      # URL to the default container registry
      - url: https://ghcr.io/v2/
        # Packages can also be a string
        packages: "*/*"
        token: ${{ secrets.GHCR_TOKEN }}

- uses: github/codeql-action/init@v4
  with:
    registries: |
      # URL to the container registry, usually in this format
      - url: https://containers.GHEHOSTNAME1/v2/

        # List of package glob patterns to be found at this registry
        packages:
          - my-company/*
          - my-company2/*

        # Token, which should be stored as a secret
        token: ${{ secrets.GHEHOSTNAME1_TOKEN }}

      # URL to the default container registry
      - url: https://ghcr.io/v2/
        # Packages can also be a string
        packages: "*/*"
        token: ${{ secrets.GHCR_TOKEN }}

레지스트리 목록에 있는 패키지 패턴은 순서대로 검사되므로, 일반적으로 가장 구체적인 패키지 패턴을 먼저 배치해야 합니다. token 값은 GitHub 인스턴스에서 read:packages 권한으로 다운로드할 때 생성된 personal access token (classic)여야 합니다.

          `|` 속성 이름 다음에 `registries`를 통지합니다. 이것이 중요한 이유는 GitHub Actions 입력은 문자열만 수락할 수 있기 때문입니다. 이 `|`를 사용하면 이후의 텍스트를 문자열로 변환하며, 이 문자열은 나중에 github/codeql-action/init@v4 작업에 의해 구문 분석됩니다.

QL 팩에서 쿼리 사용

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

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

YAML

- uses: github/codeql-action/init@v4
  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 }}

- uses: github/codeql-action/init@v4
  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 }}

다음 쿼리 도구 모음은 CodeQL code scanning에 기본 제공되며 사용할 수 있습니다.

쿼리 도구 모음	설명
`security-extended`	기본 제품군의 쿼리와 낮은 심각도, 정밀도 쿼리
`security-and-quality`	유지 관리 기능 및 안정성 쿼리를 비롯하여 `security-extended`의 쿼리입니다.

자세한 내용은 CodeQL 쿼리 도구 모음을(를) 참조하세요.

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

쿼리 도구 모음을 지정하면 CodeQL 분석 엔진은 기본 쿼리 집합과 추가 쿼리 도구 모음에 정의된 추가 쿼리를 실행합니다.

사용자 지정 구성 파일 작업

또한 사용자 지정 설정에 구성 파일을 사용하는 경우 구성 파일에 지정된 팩이나 쿼리 대신 워크플로에 지정된 추가 팩이나 쿼리가 사용됩니다. 추가 팩 또는 쿼리의 결합된 세트를 실행하려면, 워크플로에서 packs 또는 queries의 값에 + 기호를 접두사로 추가합니다. 자세한 내용은 사용자 지정 구성 파일을 참조하세요.

다음 예제에서 + 기호를 사용하면 지정된 추가 팩 및 쿼리가 참조된 구성 파일에 지정된 모든 팩 및 쿼리와 함께 사용됩니다.

YAML

- uses: github/codeql-action/init@v4
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/[email protected],scope/[email protected]:path/to/queries

- uses: github/codeql-action/init@v4
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/[email protected],scope/[email protected]:path/to/queries

사용자 지정 구성 파일

사용자 지정 구성 파일은 실행할 추가 팩 및 쿼리를 지정하는 다른 방법입니다. 이 파일을 사용하여 기본 쿼리를 비활성화하고, 특정 쿼리를 포함 또는 제외하고, 분석 중에 검사할 디렉터리를 지정할 수도 있습니다.

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

YAML

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

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

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

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

YAML

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

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

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

CodeQL 쿼리 팩 지정

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

YAML

packs:
  # Use the latest version of 'pack1' published by 'scope'
  - scope/pack1
  # Use version 1.2.3 of 'pack2'
  - scope/[email protected]
  # 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

packs:
  # Use the latest version of 'pack1' published by 'scope'
  - scope/pack1
  # Use version 1.2.3 of 'pack2'
  - scope/[email protected]
  # 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) 범위입니다. 누락된 경우 최신 버전이 사용됩니다. 유의적 버전 범위에 대한 자세한 내용은 npm의 유의적 버전 문서를 참조하세요.

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

YAML

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/[email protected]

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/[email protected]

위협 모델을 사용하여 CodeQL 범위 확장하기

참고

위협 모델은 현재 공개 미리 보기 버전이며 변경될 수 있습니다. 공개 미리 보기 동안, 위협 모델을 Java/Kotlin 및 C#용으로만 지원합니다.

기본 위협 모델에는 신뢰할 수 없는 데이터의 원격 원본이 포함됩니다. 사용자 지정 구성 파일에 threat-models: local을 지정하여 신뢰할 수 없는 데이터의 로컬 소스(예: 명령줄 인수, 환경 변수, 파일 시스템 및 데이터베이스)를 포함하도록 CodeQL 위협 모델을 확장할 수 있습니다. 위협 모델을 확장하면, 기본 위협 모델도 사용될 것입니다.

추가 쿼리 지정

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

YAML

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

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

필요에 따라 아래 예제 구성 파일에 표시된 대로 각 배열 요소에 이름을 지정할 수 있습니다. 추가 쿼리에 대한 자세한 내용은 위의 기본이 아닌 쿼리를 참조하세요 .

기본 쿼리 사용 안 함

사용자 지정 쿼리만 실행하려면 disable-default-queries: true를 사용하여 기본 보안 쿼리를 사용하지 않도록 설정할 수 있습니다.

분석에서 특정 쿼리 제외

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

이 기능은 제외하려는 경우에 유용합니다. 예를 들면 다음과 같습니다.

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

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

YAML

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

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

쿼리의 ID를 찾으려면, 보안 탭의 경고 목록에서 경고를 클릭할 수 있습니다. 그러면 경고 세부 정보 페이지가 열립니다. Rule ID 필드에는 쿼리 ID가 포함됩니다. 경고 정보 페이지에 대한 자세한 내용은 코드 검사 경고 정보에서 확인할 수 있습니다.

팁

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

          [예제 구성 파일](#example-configuration-files) 섹션에서 이러한 필터의 사용을 보여 주는 또 다른 예제를 찾을 수 있습니다.

사용자 지정 구성 파일에서 exclude 및 include 필터를 사용하는 방법에 대한 자세한 내용은 CodeQL 쿼리 도구 모음 만들기에서 확인할 수 있습니다. 필터링할 수 있는 쿼리 메타데이터에 대한 자세한 내용은 CodeQL 쿼리에 대한 메타데이터에서 확인할 수 있습니다.

검사할 디렉터리 지정

코드를 빌드하지 않고 코드베이스를 분석하는 경우, paths 배열을 구성 파일에 추가하여 code scanning을 특정 디렉터리에 있는 파일로 제한할 수 있습니다. 또한 paths-ignore 배열을 추가하여 특정 디렉터리에 있는 파일을 분석에서 제외할 수도 있습니다. 해석된 언어(Python, Ruby 및 JavaScript/TypeScript)에서 CodeQL 작업을 실행하거나 코드를 작성하지 않고 컴파일된 언어를 분석할 때 이 옵션을 사용할 수 있습니다(현재 C# 및 Java에서 지원됨).

YAML

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

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

참고

code scanning 구성 파일의 컨텍스트에서 사용하는 paths 및 paths-ignore 키워드는 워크플로에서 on.<push|pull_request>.paths에 대해 사용할 때 동일한 키워드와 혼동해선 안 됩니다. 워크플로에서 on.<push|pull_request>를 수정하는 데 사용되는 경우 사용자가 지정된 디렉터리에서 코드를 수정할 때 작업이 실행될지 여부를 결정합니다. 자세한 내용은 GitHub Actions에 대한 워크플로 구문을(를) 참조하세요.

          `?`, `+`, `[`, `]`, `!` 필터 패턴 문자는 지원되지 않으며 문자 그대로 일치됩니다.

          `**` 문자는 줄의 시작 또는 끝에만 있거나 슬래시로 둘러싸여야 하며, `**` 및 다른 문자와 혼합하지 않아야 합니다. 예를 들어 `foo/**`, `**/foo`, `foo/**/bar`는 모두 허용되는 구문이지만 `**foo`는 그렇지 않습니다. 그러나 예제와 같이 다른 문자와 함께 별을 하나만 사용할 수 있습니다.

          `*` 문자가 포함된 모든 항목을 인용해야 합니다.

코드가 빌드된 분석의 경우, code scanning을 프로젝트의 특정 디렉터리로 제한하려면 워크플로에서 적절한 빌드 단계를 지정해야 합니다. 빌드에서 디렉터리를 제외하는 데 사용해야 하는 명령은 빌드 시스템에 따라 달라집니다. 자세한 내용은 컴파일된 언어에 CodeQL 코드 스캐닝을(를) 참조하세요.

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

예제 구성 파일

데이터 재사용 가능한 코드-스캐닝 예제-구성-파일 %}

구성 세부 정보

워크플로 파일에 추가적인 구성 세부 정보를 지정하려면, config 입력을 CodeQL 작업의 init 명령에서 사용할 수 있습니다. 이 입력의 값은 위의 사용자 지정 구성 파일에 문서화된 구성 파일 형식을 따르는 YAML 문자열이어야 합니다.

구성 예

GitHub Actions 워크플로 파일의 이 단계에서는 config 입력을 사용하여 기본값 쿼리를 비활성화하고, security-extended 쿼리 도구 모음을 추가하며, cwe-020 태그가 지정된 쿼리를 제외합니다.

- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}
    config: |
      disable-default-queries: true
      threat-models: local
      queries:
        - uses: security-extended
      query-filters:
        - exclude:
            tags: /cwe-020/

동일한 접근법을 사용하여 유효한 구성 옵션을 워크플로 파일에 지정할 수 있습니다.

팁

GitHub Actions 변수를 사용하여 하나의 구성을 여러 리포지토리에서 공유할 수 있습니다. 이 방법의 이점 중 하나는 워크플로 파일을 편집하지 않고 한 곳에서 구성을 업데이트할 수 있다는 것입니다.

다음 예제에서는 vars.CODEQL_CONF가 GitHub Actions 변수입니다. 이 변수의 값은 유효한 구성 파일의 내용일 수 있습니다. 자세한 내용은 변수에 정보 저장을(를) 참조하세요.

- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}
    config: ${{ vars.CODEQL_CONF }}

컴파일된 언어

컴파일된 언어의 경우, CodeQL 작업이 분석을 위하여 CodeQL 데이터베이스를 생성하는 방법을 결정할 수 있습니다. 사용 가능한 빌드 옵션에 대한 자세한 내용은 컴파일된 언어에 CodeQL 코드 스캐닝에서 확인할 수 있습니다.

데이터 업로드

GitHub은 타사 도구를 이용해 외부에서 생성된 코드 분석 데이터를 표시할 수 있습니다. upload-sarif 작업을 사용하여 코드 분석 데이터를 업로드할 수 있습니다. 자세한 내용은 GitHub에 SARIF 파일 업로드을(를) 참조하세요.

누가 이 기능을 사용할 수 있나요?

이 기사에서

필수 조건

스캔 빈도

푸시할 때 검사

끌어오기 요청 검사

불필요한 끌어오기 요청 검사 방지

일정에 따라 검사

예시

운영 체제

CodeQL 데이터베이스 위치

분석할 언어

검사 실패에 대한 경고 심각도

분석 범주

CodeQL 모델 팩

CodeQL 모델 팩 사용하기

기본이 아닌 쿼리

쿼리 팩 사용하기

GitHub Enterprise Server에서 CodeQL 팩 다운로드하기

QL 팩에서 쿼리 사용

사용자 지정 구성 파일 작업

사용자 지정 구성 파일

CodeQL 쿼리 팩 지정

위협 모델을 사용하여 CodeQL 범위 확장하기

추가 쿼리 지정

기본 쿼리 사용 안 함

분석에서 특정 쿼리 제외

검사할 디렉터리 지정

예제 구성 파일

구성 세부 정보

구성 예

컴파일된 언어

데이터 업로드