GitHub에 SARIF 파일 업로드

code scanning에 대한 SARIF 파일 업로드 정보

GitHub은 SARIF(정적 분석 결과 교환 형식) 파일의 정보를 사용하여 리포지토리에 code scanning 경고를 만듭니다. API 또는 GitHub Actions를 사용하여 리포지토리에 SARIF 파일을 업로드할 수 있습니다. 자세한 내용은 "기존 CI 시스템에서 코드 검색 사용하기"을(를) 참조하세요.

CodeQL을 포함한 많은 정적 분석 보안 테스트 도구를 사용하여 SARIF 파일을 생성할 수 있습니다. 그 결과에서 SARIF 버전 2.1.0을 사용해야 합니다. 자세한 내용은 "코드 검사에 대한 SARIF 지원"을(를) 참조하세요.

GitHub Actions, code scanning API 또는 CodeQL CLI을(를) 사용하여 결과를 업로드할 수 있습니다. 최상의 업로드 방법은 SARIF 파일을 생성하는 방법에 따라 달라집니다. 다음 예를 참고하세요.

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

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

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

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

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

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

push 및 scheduled 이벤트가 발생할 때 실행되도록 upload-sarif 작업을 구성할 수 있습니다. GitHub Actions 이벤트에 대한 자세한 내용은 "워크플로를 트리거하는 이벤트"을(를) 참조하세요.

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@v4
      - name: Upload SARIF file
        uses: github/codeql-action/upload-sarif@v2
        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 파일을 출력합니다. 그런 다음 워크플로는 upload-sarif 작업을 사용하여 GitHub에 results.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@v4
      - 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@v2
        with:
          # Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif

추가 참고 자료

• "SARIF 업로드 문제 해결"
• "GitHub Actions에 대한 워크플로 구문"
• "워크플로 실행 기록 보기"
• "기존 CI 시스템에서 코드 검색 사용하기"
• "코드 검색에 대한 REST API 엔드포인트"