Włączanie skanowania kodu za pomocą narzędzi innych firm

4 minut

Zamiast uruchamiać skanowanie kodu w usłudze GitHub, możesz wykonać analizę w innym miejscu, a następnie przekazać wyniki. Alerty dotyczące skanowania kodu uruchamianego zewnętrznie są wyświetlane w taki sam sposób, jak te uruchamiane w usłudze GitHub. Możesz przekazać pliki formatu SARIF (Static Analysis Results Interchange Format) wygenerowane poza usługą GitHub lub za pomocą funkcji GitHub Actions, aby wyświetlić alerty skanowania kodu z narzędzi innych firm w repozytorium.

W tej lekcji dowiesz się, jak włączyć skanowanie kodu za pomocą narzędzi innych firm oraz jak używać i przekazywać pliki SARIF.

Informacje o przekazach plików SARIF na potrzeby skanowania kodu

Usługa GitHub tworzy alerty skanowania kodu w repozytorium przy użyciu informacji z plików SARIF. Pliki SARIF można wygenerować przy użyciu wielu statycznych narzędzi do testowania zabezpieczeń analizy, w tym CodeQL. Wyniki muszą używać programu SARIF w wersji 2.1.0.

Wyniki można przekazać przy użyciu interfejsu API skanowania kodu, interfejsu wiersza polecenia CodeQL lub funkcji GitHub Actions. Najlepsza metoda przekazywania zależy od sposobu wygenerowania pliku SARIF.

Interfejs API skanowania kodu

Interfejs API skanowania kodu umożliwia pobieranie informacji na temat alertów skanowania kodu, analiz, baz danych i domyślnej konfiguracji konfiguracji z repozytorium. Ponadto można aktualizować alerty skanowania kodu i domyślną konfigurację konfiguracji. Za pomocą punktów końcowych można tworzyć automatyczne raporty dla alertów skanowania kodu w organizacji lub przekazywać wyniki analizy wygenerowane przy użyciu narzędzi do skanowania kodu w trybie offline.

Dostęp do interfejsu API usługi GitHub można uzyskać za pośrednictwem protokołu HTTPS z witryny https://api.github.com. Wszystkie dane są wysyłane i odbierane jako dane JSON. Interfejs API używa niestandardowych typów multimediów, aby umożliwić konsumentom wybranie formatu danych, które mają zostać odebrane. Typy multimediów są specyficzne dla zasobów, dzięki czemu mogą zmieniać się niezależnie i obsługiwać formaty, których nie mają inne zasoby.

Istnieje jeden obsługiwany typ nośnika niestandardowego dla interfejsu API REST skanowania kodu. application/sarif+json

Tego typu nośnika można używać z żądaniami GET wysyłanymi do punktu końcowego /analyses/{analysis_id} . W przypadku użycia tego typu nośnika z tą operacją odpowiedź zawiera podzbiór rzeczywistych danych przekazanych do określonej analizy, a nie podsumowanie analizy zwracanej podczas korzystania z domyślnego typu nośnika. Odpowiedź zawiera również dodatkowe dane, takie jak github/alertNumber właściwości i github/alertUrl . Dane są formatowane jako SARIF w wersji 2.1.0.

Poniżej przedstawiono przykładowe polecenie cURL używające interfejsu API do wyświetlania listy alertów skanowania kodu dla organizacji:

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

Zapoznaj się z dokumentami interfejsu API REST usługi GitHub , aby uzyskać więcej informacji na temat korzystania z interfejsu API skanowania kodu.

Interfejs wiersza polecenia CodeQL

Interfejs wiersza polecenia CodeQL to autonomiczny produkt, którego można użyć do analizowania kodu. Jej głównym celem jest wygenerowanie reprezentacji bazy danych kodu, bazy danych CodeQL. Gdy baza danych będzie gotowa, możesz wykonać zapytanie interakcyjne lub uruchomić zestaw zapytań, aby wygenerować zestaw wyników w formacie SARIF i przekazać wyniki do GitHub.com. Interfejs wiersza polecenia CodeQL jest bezpłatny do użycia w repozytoriach publicznych przechowywanych w GitHub.com i jest dostępny do użycia w repozytoriach prywatnych należących do klienta z licencją usługi Advanced Security. Pobierz pakiet CodeQL z witryny https://github.com/github/codeql-action/releases.

Pakiet zawiera:

Produkt interfejsu wiersza polecenia CodeQL
Zgodna wersja zapytań i bibliotek z https://github.com/github/codeql
Wstępnie skompilowane wersje wszystkich zapytań zawartych w pakiecie

Zawsze należy używać pakietu CodeQL, ponieważ zapewnia to zgodność, a także zapewnia znacznie lepszą wydajność niż oddzielne pobieranie interfejsu wiersza polecenia CodeQL i wyewidencjonowanie zapytań CodeQL.

Analiza skanowania kodu za pomocą funkcji GitHub Actions

Aby przekazać plik SARIF innej firmy do repozytorium przy użyciu funkcji GitHub Actions, potrzebny jest przepływ pracy funkcji GitHub Actions. Przepływ pracy funkcji GitHub Actions to zautomatyzowany proces składający się z co najmniej jednego zadania skonfigurowanego .yml jako plik. Przepływy pracy są przechowywane w .github/workflows katalogu dla repozytorium.

Przepływ pracy używa upload-sarif akcji, która jest częścią github/codeql-action repozytorium. Ten przepływ pracy zawiera parametry wejściowe, których można użyć do skonfigurowania przekazywania.

Głównym parametrem wejściowym jest sarif-file, który konfiguruje plik lub katalog plików SARIF do przekazania. Ścieżka katalogu lub pliku jest względna względem katalogu głównego repozytorium.

upload-sarif Akcję można skonfigurować tak, aby uruchamiała się po wystąpieniu push zdarzenia i .scheduled

W tym przykładzie przedstawiono elementy upload-sarif pliku yml akcji:

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'

Za każdym razem, gdy wyniki nowego skanowania kodu są przekazywane, wyniki są przetwarzane, a alerty są dodawane do repozytorium. Usługa GitHub używa właściwości w pliku SARIF do wyświetlania alertów. Na przykład aby zapobiec zduplikowaniu alertów dla tego samego problemu, skanowanie kodu używa odcisków palców w celu dopasowania wyników do różnych przebiegów, aby były wyświetlane tylko raz w najnowszym uruchomieniu dla wybranej gałęzi. Pliki SARIF utworzone przez przepływ pracy analizy CodeQL zawierają te dane odcisku palca w partialFingerprints polu. Jeśli przekażesz plik SARIF przy użyciu upload-sarif akcji i brakuje tych danych, usługa GitHub spróbuje wypełnić partialFingerprints pole z plików źródłowych.

Jeśli plik SARIF nie zawiera partialFingerprints, upload-sarif akcja obliczy partialFingerprints pole i spróbuje zapobiec zduplikowaniu alertów. Usługa GitHub może tworzyć tylko partialFingerprints wtedy, gdy repozytorium zawiera zarówno plik SARIF, jak i kod źródłowy używany w analizie statycznej.

Przesyłanie SARIF obsługuje maksymalnie 5000 wyników na przesyłkę. Wszystkie wyniki przekroczenia tego limitu są ignorowane. Jeśli narzędzie generuje zbyt wiele wyników, należy zaktualizować konfigurację, aby skoncentrować się na wynikach najważniejszych reguł lub zapytań.

W przypadku każdego przekazywania przekazywanie SARIF obsługuje maksymalny rozmiar 10 MB dla skompresowanego pliku SARIF gzip. Wszelkie przekazywanie przez ten limit zostanie odrzucone. Jeśli plik SARIF jest zbyt duży, ponieważ zawiera zbyt wiele wyników, należy zaktualizować konfigurację, aby skoncentrować się na wynikach najważniejszych reguł lub zapytań.

Przekazywanie plików SARIF wygenerowanych poza repozytorium

Możesz również utworzyć nowy przepływ pracy, który przekazuje pliki SARIF po zatwierdzeniu ich do repozytorium. Jest to przydatne, gdy plik SARIF jest generowany jako artefakt poza repozytorium.

W poniższym przykładzie przepływ pracy jest uruchamiany za każdym razem, gdy zatwierdzenia są wypychane do repozytorium. Akcja używa partialFingerprints właściwości , aby określić, czy zmiany wystąpiły.

Oprócz uruchamiania po wypchnięciu zatwierdzeń przepływ pracy jest uruchamiany raz w tygodniu. Ten przepływ pracy przekazuje results.sarif plik znajdujący się w katalogu głównym repozytorium. Możesz również zmodyfikować ten przepływ pracy, aby przekazać katalog plików SARIF. Można na przykład umieścić wszystkie pliki SARIF w katalogu głównym repozytorium o nazwie sarif-output i ustawić parametr sarif_file wejściowy akcji na 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

Przekazywanie plików SARIF wygenerowanych w ramach przepływu pracy ciągłej integracji

Jeśli w ramach przepływu pracy ciągłej integracji (CI) wygenerujesz plik SARIF innej firmy, możesz dodać upload-sarif akcję jako krok po uruchomieniu testów ciągłej integracji. Jeśli nie masz jeszcze przepływu pracy ciągłej integracji, możesz go utworzyć przy użyciu początkowego https://github.com/actions/starter-workflows przepływu pracy w repozytorium.

W tym przykładzie przepływ pracy jest uruchamiany za każdym razem, gdy zatwierdzenia są wypychane do repozytorium. Akcja używa partialFingerprints właściwości , aby określić, czy zmiany wystąpiły. Oprócz uruchamiania po wypchnięciu zatwierdzeń przepływ pracy jest uruchamiany raz w tygodniu.

W tym przykładzie przedstawiono narzędzie do analizy statycznej ESLint jako krok w przepływie pracy. Krok Run ESLint uruchamia narzędzie ESLint i generuje results.sarif plik. Następnie przepływ pracy przekazuje results.sarif plik do usługi GitHub przy użyciu upload-sarif akcji .

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

Sprzężenie zwrotne

Czy ta strona była pomocna?