Codescans inschakelen met hulpprogramma's van derden
In plaats van codescans uit te voeren in GitHub, kunt u elders analyses uitvoeren en vervolgens de resultaten uploaden. Waarschuwingen voor codescans die u extern uitvoert, worden op dezelfde manier weergegeven als de waarschuwingen die u uitvoert in GitHub. U kunt SARIF-bestanden (Static Analysis Results Interchange Format) uploaden die buiten GitHub zijn gegenereerd of met GitHub Actions om waarschuwingen voor codescans te bekijken van hulpprogramma's van derden in uw opslagplaats.
In deze les leert u hoe u codescans inschakelt met hulpprogramma's van derden en hoe u SARIF-bestanden gebruikt en uploadt.
Over SARIF-bestandsuploads voor codescans
GitHub maakt waarschuwingen voor codescans in een opslagplaats met behulp van informatie uit SARIF-bestanden. U kunt SARIF-bestanden genereren met behulp van veel hulpprogramma's voor statische analysebeveiliging, waaronder CodeQL. De resultaten moeten SARIF versie 2.1.0 gebruiken.
U kunt de resultaten uploaden met behulp van de codescan-API, de CodeQL CLI of GitHub Actions. De beste uploadmethode is afhankelijk van hoe u het SARIF-bestand hebt gegenereerd.
API voor codescans
Met de API voor codescans kunt u informatie ophalen over waarschuwingen, analyses, databases en standaardconfiguratie voor het scannen van code vanuit een opslagplaats. Daarnaast kunt u waarschuwingen voor codescans en de standaardconfiguratie bijwerken. U kunt de eindpunten gebruiken om geautomatiseerde rapporten te maken voor de waarschuwingen voor codescans in een organisatie of om analyseresultaten te uploaden die zijn gegenereerd met behulp van offline hulpprogramma's voor codescans.
U hebt toegang tot de GitHub-API via HTTPS van https://api.github.com. Alle gegevens worden verzonden en ontvangen als JSON. De API maakt gebruik van aangepaste mediatypen om gebruikers de indeling te laten kiezen van de gegevens die ze willen ontvangen. Mediatypen zijn specifiek voor resources, zodat ze onafhankelijk kunnen worden gewijzigd en indelingen kunnen ondersteunen die andere resources niet gebruiken.
Er is één ondersteund aangepast mediatype voor de REST API voor codescans. application/sarif+json
U kunt dit mediatype gebruiken met GET-aanvragen die naar het /analyses/{analysis_id} eindpunt worden verzonden. Wanneer u dit mediatype met deze bewerking gebruikt, bevat het antwoord een subset van de werkelijke gegevens die zijn geüpload voor de opgegeven analyse, in plaats van de samenvatting van de analyse die wordt geretourneerd wanneer u het standaardmediatype gebruikt. Het antwoord bevat ook aanvullende gegevens, zoals de github/alertNumber en github/alertUrl eigenschappen. De gegevens zijn opgemaakt als SARIF-versie 2.1.0.
Hier volgt een voorbeeld van een cURL-opdracht met behulp van de API om de waarschuwingen voor codescans voor een organisatie weer te geven:
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
Raadpleeg de GitHub REST API-documenten voor meer informatie over het gebruik van de codescan-API.
CodeQL CLI
De CodeQL CLI is een zelfstandig product dat u kunt gebruiken om code te analyseren. Het belangrijkste doel is het genereren van een databaseweergave van een codebase, een CodeQL-database. Zodra de database klaar is, kunt u er interactief query's op uitvoeren of een reeks query's uitvoeren om een set resultaten in SARIF-indeling te genereren en de resultaten te uploaden naar GitHub.com. De CodeQL CLI is gratis te gebruiken voor openbare opslagplaatsen die worden onderhouden op GitHub.com en is beschikbaar voor gebruik op privéopslagplaatsen in eigendom van de klant met een geavanceerde beveiligingslicentie. Download de CodeQL-bundel van https://github.com/github/codeql-action/releases.
De bundel bevat:
- CodeQL CLI-product
- Een compatibele versie van de query's en bibliotheken van https://github.com/github/codeql
- Vooraf gecompileerde versies van alle query's die zijn opgenomen in de bundel
U moet altijd de CodeQL-bundel gebruiken, omdat dit compatibiliteit garandeert en ook veel betere prestaties biedt dan een afzonderlijke download van de CodeQL CLI en het uitchecken van de CodeQL-query's.
Analyse van codescans met GitHub Actions
Als u GitHub Actions wilt gebruiken om een SARIF-bestand van derden te uploaden naar een opslagplaats, hebt u een GitHub Actions-werkstroom nodig. Een GitHub Actions-werkstroom is een geautomatiseerd proces dat bestaat uit een of meer taken, geconfigureerd als een .yml bestand. Werkstromen worden opgeslagen in de .github/workflows map voor uw opslagplaats.
Uw werkstroom maakt gebruik van de upload-sarif actie, die deel uitmaakt van de github/codeql-action opslagplaats. Deze werkstroom bevat invoerparameters die u kunt gebruiken om de upload te configureren.
De belangrijkste invoerparameter is sarif-file, waarmee het bestand of de map van SARIF-bestanden wordt geconfigureerd die moeten worden geüpload. De map of het bestandspad is relatief ten opzichte van de hoofdmap van de opslagplaats.
De upload-sarif actie kan worden geconfigureerd om uit te voeren wanneer de push en scheduled gebeurtenis plaatsvindt.
In dit voorbeeld worden de elementen van het upload-sarif actie-yml-bestand beschreven:
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'
Telkens wanneer de resultaten van een nieuwe codescan worden geüpload, worden de resultaten verwerkt en worden waarschuwingen toegevoegd aan de opslagplaats. GitHub gebruikt eigenschappen in het SARIF-bestand om waarschuwingen weer te geven. Als u bijvoorbeeld dubbele waarschuwingen voor hetzelfde probleem wilt voorkomen, gebruikt codescans vingerafdrukken om resultaten in verschillende uitvoeringen te vinden, zodat ze slechts eenmaal worden weergegeven in de nieuwste uitvoering voor de geselecteerde vertakking. SARIF-bestanden die zijn gemaakt door de CodeQL-analysewerkstroom bevatten deze vingerafdrukgegevens in het partialFingerprints veld. Als u een SARIF-bestand uploadt met behulp van de upload-sarif actie en deze gegevens ontbreken, probeert GitHub het partialFingerprints veld te vullen vanuit de bronbestanden.
Als uw SARIF-bestand niet is opgenomen partialFingerprints, wordt met de upload-sarif actie het partialFingerprints veld voor u berekend en wordt geprobeerd dubbele waarschuwingen te voorkomen. GitHub kan alleen maken partialFingerprints wanneer de opslagplaats zowel het SARIF-bestand als de broncode bevat die in de statische analyse wordt gebruikt.
SARIF-upload ondersteunt maximaal 5000 resultaten per upload. Alle resultaten boven deze limiet worden genegeerd. Als een hulpprogramma te veel resultaten genereert, moet u de configuratie bijwerken om te focussen op resultaten voor de belangrijkste regels of query's.
Voor elke upload ondersteunt SARIF-upload een maximale grootte van 10 MB voor het met gzip gecomprimeerde SARIF-bestand. Uploads boven deze limiet worden geweigerd. Als uw SARIF-bestand te groot is omdat het te veel resultaten bevat, moet u de configuratie bijwerken om te focussen op resultaten voor de belangrijkste regels of query's.
SARIF-bestanden uploaden die buiten uw opslagplaats zijn gegenereerd
U kunt ook een nieuwe werkstroom maken waarmee SARIF-bestanden worden geüpload nadat u ze hebt doorgevoerd in uw opslagplaats. Dit is handig wanneer het SARIF-bestand wordt gegenereerd als een artefact buiten uw opslagplaats.
In het volgende voorbeeld wordt de werkstroom uitgevoerd wanneer doorvoeringen naar de opslagplaats worden gepusht. De actie gebruikt de partialFingerprints eigenschap om te bepalen of er wijzigingen zijn opgetreden.
Naast het uitvoeren wanneer doorvoeringen worden gepusht, wordt de werkstroom één keer per week uitgevoerd. Met deze werkstroom wordt het results.sarif bestand in de hoofdmap van de opslagplaats geüpload. U kunt deze werkstroom ook wijzigen om een map met SARIF-bestanden te uploaden. U kunt bijvoorbeeld alle SARIF-bestanden in een map in de hoofdmap van uw opslagplaats sarif-output plaatsen en de invoerparameter sarif_file van de actie instellen op 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
SARIF-bestanden uploaden die zijn gegenereerd als onderdeel van een CI-werkstroom
Als u uw SARIF-bestand van derden genereert als onderdeel van een ci-werkstroom (continue integratie), kunt u de upload-sarif actie toevoegen als een stap na het uitvoeren van uw CI-tests. Als u nog geen CI-werkstroom hebt, kunt u er een maken met behulp van een starterswerkstroom in de https://github.com/actions/starter-workflows opslagplaats.
In dit voorbeeld wordt de werkstroom uitgevoerd wanneer doorvoeringen naar de opslagplaats worden gepusht. De actie gebruikt de partialFingerprints eigenschap om te bepalen of er wijzigingen zijn opgetreden. Naast het uitvoeren wanneer doorvoeringen worden gepusht, wordt de werkstroom één keer per week uitgevoerd.
In dit voorbeeld ziet u het hulpprogramma voor statische analyse van ESLint als een stap in een werkstroom. De Run ESLint stap voert het hulpprogramma ESLint uit en voert het results.sarif bestand uit. De werkstroom uploadt het results.sarif bestand vervolgens naar GitHub met behulp van de upload-sarif actie.
```
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
```