Använda CodeQL CLI

8 minuter

Förutom det grafiska användargränssnittet på GitHub.com kan du också komma åt många av samma primära CodeQL-funktioner via ett kommandoradsgränssnitt.

Den här lektionen beskriver hur du använder CodeQL CLI för att skapa databaser, analysera databaser och ladda upp resultaten till GitHub.

CodeQL CLI-kommandon

När du har gjort CodeQL CLI tillgängligt för servrar i ditt CI-system och sett till att de kan autentiseras med GitHub är du redo att generera data.

Du kan använda tre olika kommandon för att generera resultat och ladda upp dem till GitHub:

database create för att skapa en CodeQL-databas som representerar den hierarkiska strukturen för varje programmeringsspråk som stöds på lagringsplatsen.
database analyze för att köra frågor för att analysera varje CodeQL-databas och sammanfatta resultatet i en SARIF-fil.
github upload-results för att ladda upp de resulterande SARIF-filerna till GitHub där resultatet matchas till en gren eller pull-begäran och visas som kodgenomsökningsaviseringar.

Du kan visa kommandoradshjälpen för alla kommandon med hjälp av --help option.

Överföring av SARIF-data som ska visas som kodgenomsökningsresultat i GitHub stöds för organisationsägda lagringsplatser med GitHub Advanced Security aktiverat och offentliga lagringsplatser på GitHub.com.

Skapa CodeQL-databaser att analysera

Följ de här stegen för att skapa CodeQL-databaser att analysera.

Kolla in koden som du vill analysera:
- För en gren kan du ta en titt på chefen för den gren som du vill analysera.
- För en pull-begäran kan du antingen checka ut huvudincheckningen för pull-begäran eller kolla in en GitHub-genererad sammanslagningsbegäran.
Konfigurera miljön för kodbasen och se till att eventuella beroenden är tillgängliga.
Leta upp kompileringskommandot, om det finns, för kodbasen. Detta är vanligtvis tillgängligt i en konfigurationsfil i CI-systemet.
Kör codeql database create från kassaroten på lagringsplatsen och skapa kodbasen:
- Om du vill skapa en CodeQL-databas för ett enda språk som stöds använder du följande kommando:
```
codeql database create <database> --command <build> --language=<language-identifier>
```
- Om du vill skapa en CodeQL-databas per språk för flera språk som stöds använder du följande kommando:
```
codeql database create <database> --command <build> \
  --db-cluster --language=<language-identifier>,<language-identifier>
```

Kommentar

Om du använder en containerbaserad version måste du köra CodeQL CLI i containern där bygguppgiften äger rum.

Den fullständiga listan med parametrar för database create kommandot visas i följande tabell:

Alternativ	Nödvändig användning
`<database>`	Ange namnet och platsen för en katalog som ska skapas för CodeQL-databasen. Kommandot misslyckas om du försöker skriva över en befintlig katalog. Om du också anger `--db-cluster`är det här den överordnade katalogen och en underkatalog skapas för varje språk som analyseras.
`--language`	Ange identifieraren för språket för att skapa en databas för en av `cpp`, `csharp`, `go`, `java`, `javascript`, , `python`och `ruby` (använd JavaScript för att analysera TypeScript-kod). När det används med `--db-cluster`accepterar alternativet en kommaavgränsad lista eller kan anges mer än en gång.
`--command`	Rekommenderas. Använd för att ange byggkommandot eller skriptet som anropar byggprocessen för kodbasen. Kommandon körs från den aktuella mappen eller, där den har definierats, från `--source-root`. Behövs inte för Python- och JavaScript-/TypeScript-analys.
`--db-cluster`	Valfritt. Använd i kodbaser med flera språk för att generera en databas för varje språk som anges av `--language`.
`--no-run-unnecessary-builds`	Rekommenderas. Använd för att ignorera build-kommandot för språk där CodeQL CLI inte behöver övervaka bygget (till exempel Python och JavaScript/TypeScript).
`--source-root`	Valfritt. Använd om du kör CLI utanför kassaroten på lagringsplatsen. Som standard förutsätter kommandot database create att den aktuella katalogen är rotkatalogen för källfilerna. använd det här alternativet för att ange en annan plats.

Exempel på ett språk

Det här exemplet skapar en CodeQL-databas för den utcheckade lagringsplatsen på /checkouts/example-repo. Den använder JavaScript-extraktorn för att skapa en hierarkisk representation av JavaScript- och TypeScript-koden på lagringsplatsen. Den resulterande databasen lagras i /codeql-dbs/example-repo.

$ codeql database create /codeql-dbs/example-repo --language=javascript \
    --source-root /checkouts/example-repo

> Initializing database at /codeql-dbs/example-repo.
> Running command [/codeql-home/codeql/javascript/tools/autobuild.cmd]
    in /checkouts/example-repo.
> [build-stdout] Single-threaded extraction.
> [build-stdout] Extracting
...
> Finalizing database at /codeql-dbs/example-repo.
> Successfully created database at /codeql-dbs/example-repo.

Exempel på flera språk

Det här exemplet skapar två CodeQL-databaser för den utcheckade lagringsplatsen på /checkouts/example-repo-multi. Den använder:

--db-cluster för att begära analys av fler än ett språk.
--language för att ange vilka språk du vill skapa databaser för.
--command för att berätta för verktyget build-kommandot för kodbasen gör du här.
--no-run-unnecessary-builds för att tala om för verktyget att hoppa över build-kommandot för språk där det inte behövs (till exempel Python).

De resulterande databaserna lagras i python och cpp underkataloger till /codeql-dbs/example-repo-multi.

$ codeql database create /codeql-dbs/example-repo-multi \
    --db-cluster --language python,cpp \
    --command make --no-run-unnecessary-builds \
    --source-root /checkouts/example-repo-multi
Initializing databases at /codeql-dbs/example-repo-multi.
Running build command: [make]
[build-stdout] Calling python3 /codeql-bundle/codeql/python/tools/get_venv_lib.py
[build-stdout] Calling python3 -S /codeql-bundle/codeql/python/tools/python_tracer.py -v -z all -c /codeql-dbs/example-repo-multi/python/working/trap_cache -p ERROR: 'pip' not installed.
[build-stdout] /usr/local/lib/python3.6/dist-packages -R /checkouts/example-repo-multi
[build-stdout] [INFO] Python version 3.6.9
[build-stdout] [INFO] Python extractor version 5.16
[build-stdout] [INFO] [2] Extracted file /checkouts/example-repo-multi/hello.py in 5ms
[build-stdout] [INFO] Processed 1 modules in 0.15s
[build-stdout] <output from calling 'make' to build the C/C++ code>
Finalizing databases at /codeql-dbs/example-repo-multi.
Successfully created databases at /codeql-dbs/example-repo-multi.
$

Analysera en CodeQL-databas

När du har skapat din CodeQL-databas följer du dessa steg för att analysera den:

Du kan också köra codeql pack download <packs> för att ladda ned alla CodeQL-paket (beta) som du vill köra under analysen.
Kör codeql database analyze i databasen och ange vilka paket och/eller frågor som ska användas.

codeql database analyze <database> --format=<format> \
    --output=<output>  <packs,queries>

Kommentar

Om du analyserar mer än en CodeQL-databas för en enda incheckning måste du ange en SARIF-kategori för varje uppsättning resultat som det här kommandot genererar. När du laddar upp resultatet till GitHub använder kodgenomsökning den här kategorin för att lagra resultaten för varje språk separat. Om du glömmer att göra detta skriver varje uppladdning över de tidigare resultaten.

codeql database analyze <database> --format=<format> \
    --sarif-category=<language-specifier> --output=<output> \
    <packs,queries>

Den fullständiga listan med parametrar för database analyze kommandot visas i följande tabell:

Alternativ	Nödvändig användning
`<database>`	Ange sökvägen för katalogen som innehåller CodeQL-databasen som ska analyseras.
`<packs,queries>`	Ange CodeQL-paket eller frågor som ska köras. Om du vill köra standardfrågor som används för kodgenomsökning utelämnar du den här parametern. Du hittar de andra frågesviterna som ingår i CodeQL CLI-paketet i `/<extraction-root>/codeql/qlpacks/codeql-<language>/codeql-suites`. Information om hur du skapar en egen frågesvit finns i Skapa CodeQL-frågesviter^[5] i dokumentationen för CodeQL CLI.
`--format`	Ange formatet för resultatfilen som genereras av kommandot. För uppladdning till GitHub bör detta vara: `sarif-latest`.
`--output`	Ange var SARIF-resultatfilen ska sparas.
`--sarif-category`	Valfritt för enkel databasanalys. Krävs för att definiera språket när du analyserar flera databaser för en enda incheckning på en lagringsplats. Ange en kategori som ska inkluderas i SARIF-resultatfilen för den här analysen. En kategori används för att särskilja flera analyser för samma verktyg och incheckning, men utförs på olika språk eller olika delar av koden.
`--sarif-add-query-help`	Valfritt. Använd om du vill inkludera tillgänglig markdown-renderad frågehjälp för anpassade frågor som används i analysen. All frågehjälp för anpassade frågor som ingår i SARIF-utdata visas i kodgenomsökningsgränssnittet om den relevanta frågan genererar en avisering.
`<packs>`	Valfritt. Använd om du har laddat ned CodeQL-frågepaket och vill köra standardfrågor eller frågesviter som anges i paketen.
`--threads`	Valfritt. Använd om du vill använda mer än en tråd för att köra frågor. Standardvärdet är 1. Du kan ange fler trådar för att påskynda frågekörningen. Om du vill ange antalet trådar till antalet logiska processorer anger du 0.
`--verbose`	Valfritt. Använd för att få mer detaljerad information om analysprocessen och diagnostikdata från processen för att skapa databasen.

Grundläggande exempel

Det här exemplet analyserar en CodeQL-databas som lagras på /codeql-dbs/example-repo och sparar resultatet som en SARIF-fil: /temp/example-repo-js.sarif. Den använder --sarif-category för att inkludera extra information i SARIF-filen som identifierar resultatet som JavaScript. Detta är viktigt när du har mer än en CodeQL-databas att analysera för en enda incheckning på en lagringsplats.

$ codeql database analyze /codeql-dbs/example-repo  \
    javascript-code-scanning.qls --sarif-category=javascript
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Running queries.
> Compiling query plan for /codeql-home/codeql/qlpacks/
    codeql-javascript/AngularJS/DisablingSce.ql.
...
> Shutting down query evaluator.
> Interpreting results.

Ladda upp resultat till GitHub

SARIF-uppladdning stöder högst 25 000 resultat per uppladdning. Men endast de 5 000 främsta resultaten visas, prioriterat efter allvarlighetsgrad. 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. Mer information om begränsningar och verifiering av SARIF-filer finns i dokumentationen^[6].

Innan du kan ladda upp resultat till GitHub måste du bestämma det bästa sättet att skicka GitHub-appen eller den personliga åtkomsttoken som du skapade tidigare till CodeQL CLI. Vi rekommenderar att du går igenom ci-systemets vägledning om säker användning av ett hemligt arkiv. CodeQL CLI stöder:

Interagera med ett hemligt arkiv med alternativet --github-auth-stdin. Det här är det rekommenderade sättet att autentisera.
Spara hemligheten i miljövariabeln GITHUB_TOKEN och köra CLI utan att inkludera alternativet --github-auth-stdin .
Skicka kommandoradsalternativet --github-auth-stdin och ange en tillfällig token via standardindata. Detta rekommenderas i testsyfte.

När du har bestämt dig för den säkraste och mest tillförlitliga metoden för din CI-server kör codeql github upload-results du på varje SARIF-resultatfil och inkluderar --github-auth-stdin om inte token är tillgänglig i miljövariabeln GITHUB_TOKEN.

# GitHub App or personal access token available from a secret store
<call-to-retrieve-secret> | codeql github upload-results \
    --repository=<repository-name> \
    --ref=<ref> --commit=<commit> \
    --sarif=<file> --github-auth-stdin

# GitHub App or personal access token available in GITHUB_TOKEN
codeql github upload-results \
    --repository=<repository-name> \
    --ref=<ref> --commit=<commit> \
    --sarif=<file>

Den fullständiga listan över parametrar för github upload-results kommandot visas i tabellen på följande sätt.

Alternativ	Nödvändig användning
`--repository`	Ange ÄGARE/NAMN för den lagringsplats som data ska laddas upp till. Ägaren måste vara en organisation inom ett företag som har en licens för GitHub Advanced Security och GitHub Advanced Security måste vara aktiverat för lagringsplatsen om inte lagringsplatsen är offentlig.
`--ref`	Ange namnet på referensen som du checkade ut och analyserade så att resultatet kan matchas mot rätt kod. För en gren använder du `refs/heads/BRANCH-NAME`; för huvudincheckningen av en pull-begäran använder du `refs/pulls/NUMBER/head`; eller för den GitHub-genererade sammanslagningsincheckningen av en pull-begäran använder du `refs/pulls/NUMBER/merge`.
`--commit`	Ange den fullständiga SHA:en för incheckningen som du analyserade.
`--sarif`	Ange den SARIF-fil som ska läsas in.
`--github-auth-stdin`	Valfritt. Använd för att skicka DEN GitHub-app eller personlig åtkomsttoken som skapats för autentisering med GitHubs REST API via standardindata. Detta behövs inte om kommandot har åtkomst till en `GITHUB_TOKEN` miljövariabeluppsättning med den här token.

Feedback

Var den här sidan till hjälp?