Aktivera kodgenomsökning med verktyg från tredje part

4 minuter

I stället för att köra kodgenomsökning i GitHub kan du utföra analys någon annanstans och sedan ladda upp resultaten. Aviseringar för kodgenomsökning som du kör externt visas på samma sätt som de som du kör i GitHub. Du kan ladda upp SARIF-filer (Static Analysis Results Interchange Format) som genererats utanför GitHub eller med GitHub Actions för att se kodgenomsökningsaviseringar från verktyg från tredje part på lagringsplatsen.

I den här lektionen får du lära dig hur du aktiverar kodgenomsökning med verktyg från tredje part och hur du använder och laddar upp SARIF-filer.

Om SARIF-filuppladdningar för kodgenomsökning

GitHub skapar kodgenomsökningsaviseringar på en lagringsplats med hjälp av information från SARIF-filer. Du kan generera SARIF-filer med hjälp av många testverktyg för statisk analyssäkerhet, inklusive CodeQL. Resultatet måste använda SARIF version 2.1.0.

Du kan ladda upp resultaten med hjälp av kodgenomsöknings-API:et, CodeQL CLI eller GitHub Actions. Den bästa uppladdningsmetoden beror på hur du genererade SARIF-filen.

API för kodgenomsökning

Med kodgenomsöknings-API:et kan du hämta information om kodgenomsökningsaviseringar, analyser, databaser och standardkonfigurationskonfiguration från en lagringsplats. Dessutom kan du uppdatera kodgenomsökningsaviseringar och standardkonfigurationen för konfigurationen. Du kan använda slutpunkterna för att skapa automatiserade rapporter för kodgenomsökningsaviseringar i en organisation eller ladda upp analysresultat som genererats med hjälp av kodgenomsökningsverktyg offline.

Du kan komma åt GitHub API via HTTPS från https://api.github.com. Alla data skickas och tas emot som JSON. API:et använder anpassade medietyper för att låta konsumenterna välja formatet för de data som de vill ta emot. Medietyper är specifika för resurser, så att de kan ändras oberoende av varandra och stödja format som andra resurser inte har.

Det finns en anpassad medietyp som stöds för kodgenomsökningens REST API, application/sarif+json.

Du kan använda den här medietypen med GET-begäranden som skickas /analyses/{analysis_id} till slutpunkten. När du använder den här medietypen med den här åtgärden innehåller svaret en delmängd av de faktiska data som laddades upp för den angivna analysen, i stället för sammanfattningen av analysen som returneras när du använder standardmedietypen. Svaret innehåller även ytterligare data, till exempel github/alertNumber egenskaperna och github/alertUrl . Data formateras som SARIF version 2.1.0.

Följande är ett exempel på ett cURL-kommando som använder API:et för att lista kodgenomsökningsaviseringar för en organisation:

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

Mer information om hur du använder API:et för kodgenomsökning finns i GitHub REST API-dokumenten .

CodeQL CLI

CodeQL CLI är en fristående produkt som du kan använda för att analysera kod. Dess huvudsakliga syfte är att generera en databasrepresentation av en kodbas, en CodeQL-databas. När databasen är klar kan du fråga den interaktivt eller köra en uppsättning frågor för att generera en uppsättning resultat i SARIF-format och ladda upp resultatet till GitHub.com. CodeQL CLI kan användas på offentliga lagringsplatser som underhålls på GitHub.com och kan användas på kundägda privata lagringsplatser med en Advanced Security-licens. Ladda ned CodeQL-paketet från https://github.com/github/codeql-action/releases.

Paketet innehåller:

CodeQL CLI-produkt
En kompatibel version av frågorna och biblioteken från https://github.com/github/codeql
Förkompilerade versioner av alla frågor som ingår i paketet

Du bör alltid använda CodeQL-paketet eftersom detta garanterar kompatibilitet och ger också mycket bättre prestanda än en separat nedladdning av CodeQL CLI och utcheckning av CodeQL-frågorna.

Kodgenomsökningsanalys med GitHub Actions

Om du vill använda GitHub Actions för att ladda upp en SARIF-fil från tredje part till en lagringsplats behöver du ett GitHub Actions-arbetsflöde. Ett GitHub Actions-arbetsflöde är en automatiserad process som består av ett eller flera jobb som konfigurerats som en .yml fil. Arbetsflöden lagras i .github/workflows katalogen för din lagringsplats.

Arbetsflödet använder åtgärden upload-sarif , som är en del av lagringsplatsen github/codeql-action . Det här arbetsflödet innehåller indataparametrar som du kan använda för att konfigurera uppladdningen.

Den huvudsakliga indataparametern är sarif-file, som konfigurerar filen eller katalogen för SARIF-filer som ska laddas upp. Katalog- eller filsökvägen är relativ till lagringsplatsens rot.

Åtgärden upload-sarif kan konfigureras att köras när push händelsen och scheduled inträffar.

I det här exemplet beskrivs elementen i upload-sarif åtgärdens yml-fil:

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'

Varje gång resultatet av en ny kodgenomsökning laddas upp bearbetas resultaten och aviseringar läggs till på lagringsplatsen. GitHub använder egenskaper i SARIF-filen för att visa aviseringar. För att till exempel förhindra duplicerade aviseringar för samma problem använder kodgenomsökning fingeravtryck för att matcha resultat mellan olika körningar så att de bara visas en gång i den senaste körningen för den valda grenen. SARIF-filer som skapats av CodeQL-analysarbetsflödet innehåller dessa fingeravtrycksdata i fältet partialFingerprints . Om du laddar upp en SARIF-fil med åtgärden upload-sarif och dessa data saknas försöker GitHub fylla i partialFingerprints fältet från källfilerna.

Om SARIF-filen inte innehåller partialFingerprintsupload-sarif beräknar partialFingerprints åtgärden fältet åt dig och försöker förhindra dubbletter av aviseringar. GitHub kan bara skapa partialFingerprints när lagringsplatsen innehåller både SARIF-filen och källkoden som används i den statiska analysen.

SARIF-uppladdning stöder högst 5 000 resultat per uppladdning. Eventuella resultat över den här gränsen ignoreras. Om ett verktyg genererar för många resultat bör du uppdatera konfigurationen för att fokusera på resultat för de viktigaste reglerna eller frågorna.

För varje uppladdning stöder SARIF-uppladdning en maximal storlek på 10 MB för den gzip-komprimerade SARIF-filen. Alla uppladdningar över den här gränsen avvisas. Om SARIF-filen är för stor eftersom den innehåller för många resultat bör du uppdatera konfigurationen så att den fokuserar på resultat för de viktigaste reglerna eller frågorna.

Ladda upp SARIF-filer som genererats utanför lagringsplatsen

Du kan också skapa ett nytt arbetsflöde som laddar upp SARIF-filer när du checkar in dem på lagringsplatsen. Detta är användbart när SARIF-filen genereras som en artefakt utanför lagringsplatsen.

I följande exempel körs arbetsflödet när incheckningar skickas till lagringsplatsen. Åtgärden använder partialFingerprints egenskapen för att avgöra om ändringar har inträffat.

Förutom att köras när incheckningar skickas schemaläggs arbetsflödet att köras en gång i veckan. Det här arbetsflödet laddar upp results.sarif filen som finns i roten på lagringsplatsen. Du kan också ändra arbetsflödet för att ladda upp en katalog med SARIF-filer. Du kan till exempel placera alla SARIF-filer i en katalog i roten på lagringsplatsen som heter sarif-output och ange åtgärdens indataparameter sarif_file till 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

Ladda upp SARIF-filer som genererats som en del av ett CI-arbetsflöde

Om du genererar din SARIF-fil från tredje part som en del av ett arbetsflöde för kontinuerlig integrering (CI) kan du lägga till upload-sarif åtgärden som ett steg när du har kört dina CI-tester. Om du inte redan har ett CI-arbetsflöde kan du skapa ett med hjälp av ett startarbetsflöde på lagringsplatsen https://github.com/actions/starter-workflows .

I det här exemplet körs arbetsflödet när incheckningar skickas till lagringsplatsen. Åtgärden använder partialFingerprints egenskapen för att avgöra om ändringar har inträffat. Förutom att köras när incheckningar skickas schemaläggs arbetsflödet att köras en gång i veckan.

I det här exemplet visas ESLint-verktyget för statisk analys som ett steg i ett arbetsflöde. Steget Run ESLint kör ESLint-verktyget och matar ut results.sarif filen. Arbetsflödet laddar sedan upp results.sarif filen till GitHub med hjälp av åtgärden upload-sarif .

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

Feedback

Var den här sidan till hjälp?