타사 도구를 사용하여 코드 검사 사용

  • 4분

GitHub에서 코드 검사를 실행하는 대신 다른 곳에서 분석한 다음 결과를 업로드할 수 있습니다. 외부에서 실행하는 코드 검사에 대한 경고는 GitHub 내에서 실행하는 것과 동일한 방식으로 표시됩니다. GitHub 외부에서 또는 GitHub Actions로 생성된 SARIF(정적 분석 결과 교환 형식) 파일을 업로드하여 리포지토리의 타사 도구에서 코드 검사 경고를 볼 수 있습니다.

이 단원에서는 타사 도구를 사용하여 코드 검사를 사용하도록 설정하는 방법과 SARIF 파일을 사용하고 업로드하는 방법을 알아봅니다.

코드 검사를 위한 SARIF 파일 업로드 안내

GitHub는 SARIF 파일의 정보를 사용하여 리포지토리에 코드 검사 경고를 만듭니다. CodeQL을 포함해 많은 정적 분석 보안 테스트 도구를 사용하여 SARIF 파일을 생성할 수 있습니다. 그 결과에서 SARIF 버전 2.1.0을 사용해야 합니다.

코드 검사 API, CodeQL CLI 또는 GitHub Actions를 사용하여 결과를 업로드할 수 있습니다. 최상의 업로드 방법은 SARIF 파일을 생성한 방법에 따라 달라집니다.

코드 검사 API

코드 검사 API를 사용하면 리포지토리에서 코드 검사 경고, 분석, 데이터베이스 및 기본 설정 구성에 대한 정보를 검사할 수 있습니다. 또한 코드 검사 경고 및 기본 설정 구성을 업데이트할 수 있습니다. 엔드포인트를 사용하여 조직의 코드 검사 경고에 대한 자동화된 보고서를 만들거나 오프라인 코드 검사 도구를 사용하여 생성된 분석 결과를 업로드할 수 있습니다.

https://api.github.com에서 HTTPS를 통해 GitHub API에 액세스할 수 있습니다. 모든 데이터가 JSON으로 전송되고 수신됩니다. API는 사용자 지정 미디어 형식을 사용하므로 소비자들이 수신하고자 하는 데이터의 형식을 선택할 수 있습니다. 미디어 유형은 리소스에 따라 다르기 때문에 독립적으로 변경하고 다른 리소스에서 지원하지 않는 형식을 지원할 수 있습니다.

REST API application/sarif+json를 검사하는 코드에 대해 지원되는 사용자 지정 미디어 유형이 하나 있습니다.

/analyses/{analysis_id} 엔드포인트로 전송된 GET 요청과 함께 이 미디어 형식을 사용할 수 있습니다. 이 작업에서 이 미디어 형식을 사용하면 기본 미디어 형식을 사용할 때 반환되는 분석의 요약이 아니라 지정된 분석을 위해 업로드된 실제 데이터의 하위 집합이 응답에 포함됩니다. github/alertNumber 및 github/alertUrl 속성 같은 추가 데이터도 응답에 포함됩니다. 데이터는 SARIF 버전 2.1.0으로 형식이 지정됩니다.

다음은 API를 사용하여 조직에 대한 코드 검사 경고를 나열하는 cURL 명령의 예입니다.

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/code-scanning/alerts

코드 검사 API 사용에 관한 자세한 내용은 GitHub REST API 문서를 참조하세요.

CodeQL 커맨드 라인 인터페이스 (CLI)

CodeQL CLI는 코드 분석에 사용할 수 있는 독립 실행형 제품입니다. 그 주요 목적은 코드베이스, 즉 CodeQL 데이터베이스의 데이터베이스 표현을 생성하는 것입니다. 데이터베이스가 준비되면 대화형으로 쿼리하거나 쿼리 제품군을 실행하여 SARIF 형식으로 결과 집합을 생성하고 결과를 GitHub.com 업로드할 수 있습니다. CodeQL CLI는 GitHub.com 유지 관리되는 공용 리포지토리에서 무료로 사용할 수 있으며 고급 보안 라이선스가 있는 고객 소유의 프라이빗 리포지토리에서 사용할 수 있습니다. https://github.com/github/codeql-action/releases서 CodeQL 번들을 다운로드합니다.

번들에는 다음이 포함됩니다.

  • CodeQL CLI 제품
  • https://github.com/github/codeql에서 호환되는 쿼리 및 라이브러리 버전
  • 번들에 포함되는 모든 쿼리의 사전 컴파일 버전

호환성을 보장하고 CodeQL CLI의 별도 다운로드 및 CodeQL 쿼리 체크 아웃보다 훨씬 더 나은 성능을 제공하기 때문에 항상 CodeQL 번들을 사용해야 합니다.

GitHub Actions를 사용하여 코드 검사 분석

GitHub Actions를 사용하여 타사 SARIF 파일을 리포지토리에 업로드하려면 GitHub Actions 워크플로가 필요합니다. GitHub Actions 워크플로는 .yml 파일로 구성된 하나 이상의 작업으로 이루어진 자동화된 프로세스입니다. 워크플로는 리포지토리의 .github/workflows 디렉터리에 저장됩니다.

워크플로는 upload-sarif 리포지토리에 속한 github/codeql-action 작업을 사용합니다. 이 워크플로에는 업로드 구성에 사용할 수 있는 입력 매개 변수가 포함되어 있습니다.

기본 입력 매개 변수는 sarif-file데, 이것은 업로드할 SARIF 파일의 파일 또는 디렉터리를 구성합니다. 디렉터리나 파일 경로는 리포지토리의 루트가 기준입니다.

upload-sarif 및 push 이벤트가 발생할 때 실행되도록 scheduled 작업을 구성할 수 있습니다.

이 예에서는 upload-sarif 작업 yml 파일의 요소를 간략하게 설명합니다.

name: 'Code Scanning : Upload SARIF'
description: 'Upload the analysis results'
author: 'GitHub'
inputs:
  sarif_file:
    description: |
      The SARIF file or directory of SARIF files to be uploaded to GitHub code scanning.
      See https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/
      uploading-a-sarif-file-to-github#uploading-a-code-scanning-analysis-with-github-actions
      for information on the maximum number of results and maximum file size supported by code scanning.
    required: false
    default: '../results'
  checkout_path:
    description: "The path at which the analyzed repository was checked out. 
    Used to relativize any absolute paths in the uploaded SARIF file."
    required: false
    default: ${{ github.workspace }}
  token:
    default: ${{ github.token }}
  matrix:
    default: ${{ toJson(matrix) }}
  category:
    description: String used by Code Scanning for matching the analyses
    required: false
  wait-for-processing:
    description: If true, the Action will wait for the uploaded SARIF to be processed before completing.
    required: true
    default: "false"
runs:
  using: 'node12'
  main: '../lib/upload-sarif-action.js'

새 코드 검사 결과가 업로드될 때마다 결과가 처리되고 경고가 리포지토리에 추가됩니다. GitHub는 SARIF 파일의 속성을 사용하여 경고를 표시합니다. 예를 들어, 동일한 문제에 대한 중복 경고를 방지하기 위해 코드 검사에서 지문을 사용하여 다양한 실행의 결과와 맞춰보기 때문에 선택한 분기에 대한 최신 실행에서 한 번만 표시됩니다. CodeQL 분석 워크플로에서 만든 SARIF 파일에는 이 지문 데이터가 partialFingerprints 필드에 포함됩니다. upload-sarif 작업을 사용하여 SARIF 파일을 업로드할 때 이 데이터가 없는 경우 GitHub가 원본 파일에서 partialFingerprints 필드를 채우려고 시도합니다.

SARIF 파일에 partialFingerprints가 포함되지 않은 경우 upload-sarif 작업이 partialFingerprints 필드를 계산하고 중복 경고를 방지하려고 시도합니다. GitHub는 리포지토리에 SARIF 파일과 정적 분석에 사용되는 소스 코드가 모두 포함된 경우에만 partialFingerprints를 만들 수 있습니다.

SARIF 업로드는 업로드당 최대 5,000개의 결과를 지원합니다. 이 한도를 초과하는 결과는 무시됩니다. 도구에서 너무 많은 결과를 생성하는 경우 가장 중요한 규칙 또는 쿼리의 결과에 초점을 맞추도록 구성을 업데이트해야 합니다.

각 업로드에 대해 SARIF 업로드는 최대 10MB 크기의 gzip 압축 SARIF 파일을 지원합니다. 이 한도를 초과하는 모든 업로드는 거부됩니다. SARIF 파일이 너무 많은 결과를 포함해서 너무 큰 경우 가장 중요한 규칙 또는 쿼리의 결과에 초점을 맞추도록 구성을 업데이트해야 합니다.

리포지토리 외부에서 생성된 SARIF 파일 업로드

리포지토리에 커밋한 후 SARIF 파일을 업로드하는 새 워크플로도 만들 수 있습니다. 이는 SARIF 파일이 리포지토리 외부의 아티팩트로 생성될 때 유용합니다.

다음 예제에서는 커밋이 리포지토리에 푸시될 때마다 워크플로가 실행됩니다. 이 작업은 partialFingerprints 속성을 사용하여 변경이 발생했는지 여부를 확인합니다.

커밋이 푸시될 때 실행되는 것 외에도 이 워크플로는 일주일에 한 번 실행되도록 예약됩니다. 이 워크플로는 리포지토리의 루트에 있는 results.sarif 파일을 업로드합니다. 이 워크플로를 수정하여 SARIF 파일 디렉터리를 업로드할 수도 있습니다. 예를 들어, 모든 SARIF 파일을 sarif-output는 리포지토리의 루트에 있는 디렉터리에 배치하고 작업의 입력 매개 변수 sarif_file를 sarif-output로 설정할 수 있을 것입니다.

name: "Upload SARIF"

// Run workflow each time code is pushed to your repository and on a schedule. 
//The scheduled workflow runs every Thursday at 15:45 UTC.

on:
  push:
  schedule:
    - cron: '45 15 * * 4'

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
  steps:
    # This step checks out a copy of your repository.
    - name: Checkout repository
      uses: actions/checkout@v2
    - name: Upload SARIF file
      uses: github/codeql-action/upload-sarif@v1
      with:
        # Path to SARIF file relative to the root of the repository
        sarif_file: results.sarif

CI 워크플로의 일부로 생성된 SARIF 파일 업로드

CI(연속 통합) 워크플로의 일부로 타사 SARIF 파일을 생성하는 경우 upload-sarif 작업을 CI 테스트 실행 후 단계로 추가할 수 있습니다. CI 워크플로가 아직 없는 경우 https://github.com/actions/starter-workflows 리포지토리에서 시작 워크플로를 사용하여 만들 수 있습니다.

이 예제에서는 커밋이 리포지토리에 푸시될 때마다 워크플로가 실행됩니다. 이 작업은 partialFingerprints 속성을 사용하여 변경이 발생했는지 여부를 확인합니다. 커밋이 푸시될 때 실행되는 것 외에도 이 워크플로는 일주일에 한 번 실행되도록 예약됩니다.

이 예제에서는 워크플로의 단계로 ESLint 정적 분석 도구를 보여줍니다. Run ESLint 단계에서는 ESLint 도구를 실행하고 results.sarif 파일을 출력합니다. 그런 다음 이 워크플로는 results.sarif 작업을 사용하여 upload-sarif 파일을 GitHub로 업로드합니다.

  ```
  name: "ESLint analysis"

// Run workflow each time code is pushed to your repository and on a schedule.
// The scheduled workflow runs every Wednesday at 15:45 UTC.
on:
  push:
  schedule:
    - cron: '45 15 * * 3'

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@v2
      - name: Run npm install
        run: npm install
      // Runs the ESlint code analysis
      - name: Run ESLint
        // eslint exits 1 if it finds anything to report
        run: node_modules/.bin/eslint build docs lib script spec-main -f node_modules/@microsoft/eslint-formatter-sarif/sarif.js -o results.sarif || true
      // Uploads results.sarif to GitHub repository using the upload-sarif action
      - uses: github/codeql-action/upload-sarif@v1
        with:
          // Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif
  ```