GitHub에 SARIF 파일 업로드

타사 분석 도구 또는 CI/CD 시스템을 사용하여 코드에서 취약성을 검사하는 경우 SARIF 파일을 생성하고 GitHub에 업로드할 수 있습니다. 최상의 업로드 방법은 SARIF 파일을 생성하는 방법에 따라 달라집니다.

예를 들어 다음을 사용하는 경우:

• GitHub Actions를 사용하여 CodeQL 작업을 실행한다면 추가 작업이 필요하지 않습니다. CodeQL 작업은 분석이 끝나면 SARIF 파일을 자동으로 업로드합니다.
• GitHub Actions로 SARIF 호환 분석 도구를 실행하는 경우, 결과를 업로드하는 단계를 워크플로에 추가하여 업데이트할 수 있습니다. GitHub Actions를 사용하여 code scanning 업로드 참조하세요.
• CI 시스템에서 CodeQL CLI를 사용하여 code scanning을 실행하면, CLI를 통해 결과를 GitHub에 업로드할 수 있습니다. 사용자의 기존 CI 시스템으로 코드 검색 사용하기을(를) 참조하세요.
• 리포지토리 외부에서 결과를 아티팩트로 생성하는 도구의 경우, code scanning API를 통해 파일을 업로드할 수 있습니다. 코드 검색에 대한 REST API 엔드포인트을(를) 참조하세요.

기본적으로 code scanning은 리포지토리에 대한 분석마다 하나의 SARIF 결과 파일이 있을 것으로 기대합니다. 리포지토리 내 커밋에 대해 2개 이상의 결과 집합을 업로드하고 싶다면, 각 결과 집합을 하나의 고유한 집합으로 식별해야 합니다.

GitHub Actions를 사용하여 code scanning 분석 업로드

GitHub Actions를 사용하여 타사 SARIF 파일을 리포지토리에 업로드하려면 워크플로우가 필요합니다. 자세한 내용은 워크플로 작성을(를) 참조하세요.

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

•         `sarif_file`은 업로드할 SARIF 파일의 파일 또는 디렉터리를 구성합니다. 디렉터리나 파일 경로는 리포지토리의 루트가 기준입니다.
  

•         `category`(선택 사항)는 SARIF 파일의 결과에 대한 범주를 할당합니다. 이렇게 하면 동일한 커밋을 다양한 방법으로 분석하고 GitHub의 code scanning 보기를 사용하여 결과를 검토할 수 있습니다. 예를 들어 다양한 도구를 사용하여 분석할 수 있으며, 모노 리포지토리에서는 변경된 파일의 하위 집합에 따라 리포지토리의 여러 조각을 분석할 수 있습니다.
  

자세한 내용은 upload-sarif작업을 참조하세요.

          `upload-sarif` 및 `push` 이벤트가 발생할 때 실행되도록 `scheduled` 작업을 구성할 수 있습니다. GitHub Actions 이벤트에 대한 자세한 내용은 [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows)을(를) 참조하세요.

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

SARIF 속성이 업로드 시 지원되는 크기 범위 내에 있으며, 파일이 코드 검색과 호환되는지 확인할 수 있습니다. 자세한 내용은 코드 검사에 대한 SARIF 지원을(를) 참조하세요.

리포지토리 외부에서 생성된 SARIF 파일에 대한 예제 워크플로

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

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

이 워크플로는 리포지토리의 루트에 있는 results.sarif 파일을 업로드합니다. 워크플로 파일 만들기에 대한 자세한 내용은 워크플로 작성을(를) 참조하세요.

또는 이 워크플로를 수정하여 SARIF 파일 디렉터리를 업로드할 수도 있습니다. 예를 들어, 모든 SARIF 파일을 sarif-output는 리포지토리의 루트에 있는 디렉터리에 배치하고 작업의 입력 매개 변수 sarif_file를 sarif-output로 설정할 수 있을 것입니다. 디렉터리를 업로드하는 경우 각 SARIF 파일에는 결과의 범주를 정의하는 고유한 runAutomationDetails.id 항목이 포함되어야 합니다. 자세한 내용은 코드 검사에 대한 SARIF 지원을(를) 참조하세요.

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:
      # required for all workflows
      security-events: write
      # only required for workflows in private repositories
      actions: read
      contents: read
    steps:
      # This step checks out a copy of your repository.
      - name: Checkout repository
        uses: actions/checkout@v5
      - name: Upload SARIF file
        uses: github/codeql-action/upload-sarif@v4
        with:
          # Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif
          # Optional category for the results
          # Used to differentiate multiple results for one commit
          category: my-analysis-tool

ESLint 분석 도구를 실행하는 예제 워크플로

CI(연속 통합) 워크플로의 일부로 타사 SARIF 파일을 생성하는 경우 upload-sarif 작업을 CI 테스트 실행 후 단계로 추가할 수 있습니다. CI 워크플로가 아직 없는 경우 GitHub Actions 템플릿을 사용하여 만들 수 있습니다. 자세한 내용은 GitHub Actions용 빠른 시작을(를) 참조하세요.

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

워크플로는 ESLint 정적 분석 도구를 워크플로의 단계로서 실행하는 예제를 보여 줍니다. Run ESLint 단계에서는 ESLint 도구를 실행하고 results.sarif 파일을 출력합니다. 그런 다음 워크플로는 results.sarif 작업을 사용하여 GitHub에 upload-sarif 파일을 업로드합니다. 워크플로 파일 만들기에 대한 자세한 내용은 GitHub Actions 이해을(를) 참조하세요.

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:
      # required for all workflows
      security-events: write
      # only required for workflows in private repositories
      actions: read
      contents: read
    steps:
      - uses: actions/checkout@v5
      - 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@v4
        with:
          # Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif

단일 커밋에 대해 여러 개의 SARIF 파일을 업로드하는 방법

기본적으로 code scanning은 리포지토리에 대한 분석마다 하나의 SARIF 결과 파일이 있을 것으로 기대합니다. 따라서 커밋에 대한 두 번째 SARIF 결과 파일을 업로드하면 두 번째가 원래 데이터 세트를 대체하는 것으로 처리됩니다. 예를 들어, 분석 도구가 분석하는 각 언어별로 또는 사용하는 각 규칙 세트별로 서로 다른 SARIF 파일을 생성하는 경우, 하나의 분석에 대해 두 개의 다른 SARIF 파일을 업로드할 수 있습니다. 리포지토리 내 커밋에 대해 2개 이상의 결과 집합을 업로드하고 싶다면, 각 결과 집합을 하나의 고유한 집합으로 식별해야 합니다.

커밋에 대한 여러 SARIF 파일을 업로드하는 경우 각 분석의 "범주"를 지정해야 합니다. 다음과 같은 범주 지정 방법이 있으며 분석 방법에 따라 달라집니다.

• 직접 CodeQL CLI 사용 - SARIF 파일을 생성할 때 --sarif-category 인수를 codeql database analyze 명령에 전달합니다. 자세한 내용은 CodeQL CLI에 대해을(를) 참조하세요.
• codeql-action/analyze와 함께 GitHub Actions 사용 - 범주가 워크플로 이름 및 행렬 변수(일반적으로 language)에서 자동으로 설정됩니다. 단일 워크플로 내에서 모노 리포지토리의 여러 섹션을 분석할 때는 작업 category 입력을 지정하여 재정의하는 방법이 유용합니다.
• GitHub Actions를 사용하여 다른 정적 분석 도구의 결과를 업로드한 다음, 한 워크플로에서 동일한 도구에 대해 둘 이상의 결과 파일을 업로드하는 경우 category 입력을 지정해야 합니다. 자세한 내용은 GitHub에 SARIF 파일 업로드을(를) 참조하세요.
• 이러한 방법을 사용하지 않는 경우 업로드할 각 SARIF 파일에서 고유한 runAutomationDetails.id를 지정해야 합니다. 자세한 내용은 아래 runAutomationDetails 객체를 참고하시기 바랍니다.

동일한 도구에서 동일한 범주를 사용하여 커밋에 대한 두 번째 SARIF 파일을 업로드하는 경우 이전 결과를 덮어씁니다. 그러나 단일 GitHub Actions 워크플로 실행에서 동일한 도구 및 범주에 대한 여러 SARIF 파일을 업로드하려고 하면 구성 오류가 감지되고 실행이 실패합니다.

추가 읽기

•         [AUTOTITLE](/code-security/how-tos/scan-code-for-vulnerabilities/troubleshooting/troubleshooting-sarif-uploads)
  

•         [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions)
  

•         [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/viewing-workflow-run-history)
  

•         [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system)
  

•         [AUTOTITLE](/rest/code-scanning/code-scanning#upload-an-analysis-as-sarif-data)