이 버전의 GitHub Enterprise는 다음 날짜에 중단되었습니다. 2026-04-09. 중요한 보안 문제에 대해서도 패치 릴리스가 이루어지지 않습니다. 더 뛰어난 성능, 향상된 보안, 새로운 기능을 위해 최신 버전의 GitHub Enterprise Server로 업그레이드합니다. 업그레이드에 대한 도움말은 GitHub Enterprise 지원에 문의하세요.

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

워크플로 파일을 편집하여 고급 설정이 프로젝트의 코드를 검사하여 취약성 및 오류를 검사하는 방법을 구성합니다.

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

쓰기 권한이 있는 사용자 if advanced setup is already enabled

이 기사에서

참고

사이트 관리자가 먼저 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에 대한 워크플로 구문을(를) 참조하세요.

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

또한 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은 결과를 분기의 기존 끌어오기 요청에 매핑하고 경고를 해당 끌어오기 요청의 주석으로 추가합니다. 자세한 내용은 푸시할 때 검사에서 확인할 수 있습니다.

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

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

YAML
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에 대한 워크플로 구문을(를) 참조하세요.

참고

이 이벤트는 워크플로 파일이 기본 분기에 있는 경우에만 워크플로 실행을 트리거합니다.

예시

다음 예제는 기본 분기 main와 보호된 분기 protected를 가진 특정 리포지토리에 대한 CodeQL 분석 워크플로을(를) 보여 줍니다.

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

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

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

운영 체제

참고

  • Swift 코드의 코드 스캐닝은 기본적으로 macOS 실행기를 사용합니다.
  • ARC 실행기는 Linux만 사용하고 Swift에는 macOS 실행기만 필요하기 때문에 Actions Runner Controller(ARC)의 일부인 실행기에는 Swift 코드의 Code scanning이(가) 지원되지 않습니다. 그러나 ARC 실행기와 자체 호스팅 macOS 실행기를 혼합하여 사용할 수 있습니다. 자세한 내용은 Actions Runner 컨트롤러을(를) 참조하세요.

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

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

          CodeQL
          code scanning 는 최신 버전의 Ubuntu, Windows 및 macOS를 지원합니다. 따라서 이 설정의 일반적인 값은 `ubuntu-latest`, `windows-latest`, `macos-latest`입니다. 자세한 내용은 [AUTOTITLE](/actions/using-jobs/choosing-the-runner-for-a-job) 및 [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners)을(를) 참조하세요.

          Git이 자체 호스팅 실행기에서 PATH 변수에 있는지 확인해야 합니다. 자세한 내용은 [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) 및 [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners)을(를) 참조하세요.

자체 호스팅 컴퓨터에서 분석을CodeQL 실행 을 참조하세요.

          CodeQL 데이터베이스 위치

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

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

제공된 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 에서는 다음 언어 식별자를 사용합니다.
언어식별자선택적 얼터너티브 식별자(있는 경우)
C/C++c-cpp
          `c` 또는 `cpp` |

| C# | csharp | | | Go | go | | Java/Kotlin | java-kotlin | java 또는 kotlin | | JavaScript/TypeScript | javascript-typescript | javascript 또는 typescript | | Python | python | | Ruby | ruby | | | Rust(공개 미리 보기) | rust | | | Swift | swift |

참고

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

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

YAML
- 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) 파일은 분석할 리포지토리의 언어를 나열하는 명명 `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 }}

워크플로에서 행렬을 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

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

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

참고

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

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

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

  • 필수 도구는 규칙 집합에 정의된 심각도 수준에 따라 code scanning 경고를 식별합니다.
  • 필수 도구의 분석은 아직 진행 중입니다.
  • 리포지토리에 필요한 도구가 구성되지 않았습니다.

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

분석 범주

          `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"

워크플로에서 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 모델 팩은 현재 베타 상태이며 변경될 수 있습니다. 모델 팩은 C/C++, C#, Java/Kotlin, Python, 와 Ruby 분석을 위해 지원됩니다.

Visual Studio Code에 대한 CodeQL 확장의 CodeQL 모델 편집기에서 C#, Java/Kotlin, Ruby에 대한 모델링 종속성을 지원합니다.

모델 팩 CodeQL 사용

게시된 CodeQL 모델 팩을 하나 이상 추가하려면 워크플로의 uses: github/codeql-action/init@v4 섹션에 있는 with: packs: 항목에 이들을 지정하십시오. 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

이 예제에서는 기본 쿼리가 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는 패키지를 게시한 조직 또는 개인 계정입니다. 워크플로가 실행되면 4개의 CodeQL 쿼리 팩이 다운로드 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/pack2@1.2.3,scope/pack3@~3.2.1,scope/pack4@4.5.6:path/to/queries

참고

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

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

          CodeQL에서 GitHub Enterprise Server팩을 다운로드 중입니다

워크플로에서 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 }}

레지스트리 목록에 있는 패키지 패턴은 순서대로 검사되므로, 일반적으로 가장 구체적인 패키지 패턴을 먼저 배치해야 합니다. 값 token은 read:packages 권한으로 다운로드하고 있는 GitHub 인스턴스에서 생성된 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 }}

다음 쿼리 도구 모음은 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/pack2@1.2.3,scope/pack3@4.5.6: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

구성 파일은 분석 중인 리포지토리 또는 외부 리포지토리 내에 있을 수 있습니다. 외부 리포지토리를 사용하면 한 곳에서 여러 리포지토리에 대한 구성 옵션을 지정할 수 있습니다. 외부 리포지토리에 있는 구성 파일을 참조하는 경우 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 }}

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

          CodeQL 쿼리 팩 지정

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

YAML
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) 범위입니다. 누락된 경우 최신 버전이 사용됩니다. 유의적 버전 범위에 대한 자세한 내용은 npm의 유의적 버전 문서를 참조하세요.

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

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/java-pack2@v1.0.0

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

참고

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

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

추가 쿼리 지정

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

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

팁

  • 필터의 순서가 중요합니다. 쿼리 및 쿼리 팩에 대한 지침 이후에 표시되는 첫 번째 필터 명령은 쿼리가 기본적으로 포함되는지 아니면 제외되는지를 결정합니다.
  • 후속 지침은 순서대로 실행되며 파일의 뒷부분에 표시되는 지침이 이전 지침보다 우선합니다.
          [예제 구성 파일](#example-configuration-files) 섹션에서 이러한 필터의 사용을 보여 주는 또 다른 예제를 찾을 수 있습니다.

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

검사할 디렉터리 지정

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

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

참고

  • 구성 파일의 paths 컨텍스트에서 사용되는 키워드 및 paths-ignore 키워드는 code scanning 워크플로에서 사용할 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> 키워드를 사용하는 두 가지를 모두 수행해야 합니다.

예제 구성 파일

이 구성 파일은 코드를 스캔할 때 CodeQL에서 실행하는 쿼리 목록에 security-and-quality 쿼리 도구 모음을 추가합니다. 사용할 수 있는 쿼리 도구 모음에 대한 자세한 내용은 기본이 아닌 쿼리를 참조하세요.

name: "My CodeQL config"

queries:
  - uses: security-and-quality

다음 구성 파일은 기본 쿼리를 사용하지 않도록 설정하고 대신 실행할 사용자 지정 쿼리 집합을 지정합니다. 또한 src/node_modules 디렉터리와 이름이 _.test.js_로 끝나는 파일을 제외하고 src 디렉터리(루트를 기준으로)의 파일을 스캔하도록 CodeQL을 구성합니다. 따라서 _src/node_modules_의 파일과 이름이 _.test.js_로 끝나는 파일은 분석에서 제외됩니다.

name: "My CodeQL config"

disable-default-queries: true

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

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

다음 구성 파일은 심각도 오류 경고를 생성하는 쿼리만 실행합니다. 구성은 먼저 모든 기본 쿼리, ./my-queries의 모든 쿼리 및 codeql/java-queries의 기본 도구 모음을 선택한 다음 경고 또는 권장 사항을 생성하는 모든 쿼리를 제외합니다.

queries:
  - name: Use an in-repository CodeQL query pack (run queries in the my-queries directory)
    uses: ./my-queries
packs:
  - codeql/java-queries
query-filters:
- exclude:
    problem.severity:
      - warning
      - recommendation

구성 세부 정보

워크플로 파일에서 추가 구성 세부 정보를 지정하려면 config``init 명령의 CodeQL 작업 입력을 사용할 수 있습니다. 이 입력의 값은 위의 사용자 지정 구성 파일에 문서화된 구성 파일 형식을 따르는 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` 작업을 사용하여 코드 분석 데이터를 업로드할 수 있습니다. 자세한 내용은 [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github)을(를) 참조하세요.