Brug CodeQL-kommandolinjegrænsefladen

8 minutter

Ud over den grafiske brugergrænseflade på GitHub.com kan du også få adgang til mange af de samme primære CodeQL-funktioner via en kommandolinjegrænseflade.

Dette undermodul dækker brugen af CodeQL-kommandolinjegrænsefladen til at oprette databaser, analysere databaser og uploade resultaterne til GitHub.

CodeQL CLI-kommandoer

Når du har gjort CodeQL-kommandolinjegrænsefladen tilgængelig for servere i dit CI-system og sikret, at de kan godkendes med GitHub, er du klar til at generere data.

Du kan bruge tre forskellige kommandoer til at generere resultater og uploade dem til GitHub:

database create at oprette en CodeQL-database, der repræsenterer den hierarkiske struktur for hvert understøttet programmeringssprog i lageret.
database analyze til at køre forespørgsler for at analysere hver CodeQL-database og opsummere resultaterne i en SARIF-fil.
github upload-results til at uploade de resulterende SARIF-filer til GitHub, hvor resultaterne matches med en forgrenings- eller pullanmodning og vises som beskeder om kodescanning.

Du kan få vist kommandolinjehjælpen til alle kommandoer ved hjælp af --help option.

Upload af SARIF-data, der skal vises som kodescanningsresultater i GitHub, understøttes for organisationsejede lagre med GitHub Advanced Security aktiveret, og offentlige lagre på GitHub.com.

Opret CodeQL-databaser til analyse

Følg disse trin for at oprette CodeQL-databaser, der skal analyseres.

Se den kode, du vil analysere:
- For en forgrening skal du se lederen af den forgrening, du vil analysere.
- Hvis du vil have en pullanmodning, skal du enten tjekke hovedbekræftelse af pullanmodningen eller tjekke en GitHub-genereret flettebekræftelse for pullanmodningen.
Konfigurer miljøet for kodebasen, og sørg for, at alle afhængigheder er tilgængelige.
Find eventuelt kommandoen build for kodebasen. Dette er typisk tilgængeligt i en konfigurationsfil i CI-systemet.
Kør codeql database create fra lagerets udtjekningsrod, og opret kodebasen:
- Hvis du vil oprette én CodeQL-database til et enkelt understøttet sprog, skal du bruge følgende kommando:
```
codeql database create <database> --command <build> --language=<language-identifier>
```
- Hvis du vil oprette én CodeQL-database pr. sprog for flere understøttede sprog, skal du bruge følgende kommando:
```
codeql database create <database> --command <build> \
  --db-cluster --language=<language-identifier>,<language-identifier>
```

Seddel

Hvis du bruger et objektbeholderbuild, skal du køre CodeQL-kommandolinjegrænsefladen i den objektbeholder, hvor din buildopgave finder sted.

Den komplette liste over parametre for kommandoen database create vises i følgende tabel:

Valgmulighed	Påkrævet brug
`<database>`	Angiv navnet på og placeringen af en mappe, der skal oprettes for CodeQL-databasen. Kommandoen mislykkes, hvis du forsøger at overskrive en eksisterende mappe. Hvis du også angiver `--db-cluster`, er dette den overordnede mappe, og der oprettes en undermappe for hvert sprog, der analyseres.
`--language`	Angiv id'et for det sprog, der skal oprettes en database for `cpp`, `csharp`, `go`, `java`, , `javascript`, `python`og `ruby` (brug JavaScript til at analysere TypeScript-kode). Når indstillingen bruges sammen med `--db-cluster`, accepterer den en kommasepareret liste eller kan angives mere end én gang.
`--command`	Anbefalet. Bruges til at angive den buildkommando eller det script, der aktiverer buildprocessen for kodebasen. Kommandoer køres fra den aktuelle mappe eller fra `--source-root`, hvor den er defineret. Ikke nødvendig til Python- og JavaScript/TypeScript-analyse.
`--db-cluster`	Valgfri. Bruges i kodebaser med flere sprog til at generere én database for hvert sprog, der er angivet af `--language`.
`--no-run-unnecessary-builds`	Anbefalet. Bruges til at undertrykke kommandoen build for sprog, hvor CodeQL-kommandolinjegrænsefladen ikke behøver at overvåge buildet (f.eks. Python og JavaScript/TypeScript).
`--source-root`	Valgfri. Bruges, hvis du kører kommandolinjegrænsefladen uden for lagerets udtjekningsrod. Kommandoen opret database forudsætter som standard, at den aktuelle mappe er rodmappen for kildefilerne. brug denne indstilling til at angive en anden placering.

Eksempel på et enkelt sprog

I dette eksempel oprettes en CodeQL-database for lageret, der er tjekket ud på /checkouts/example-repo. Den bruger JavaScript-udtrækningen til at oprette en hierarkisk repræsentation af JavaScript- og TypeScript-koden i lageret. Den resulterende database gemmes 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.

Eksempel på flere sprog

I dette eksempel oprettes der to CodeQL-databaser for det lager, der er tjekket ud på /checkouts/example-repo-multi. Den bruger:

--db-cluster til at anmode om analyse af mere end ét sprog.
--language til at angive, hvilke sprog der skal oprettes databaser for.
--command til at fortælle værktøjet kommandoen build for kodebasen, skal du gøre dette.
--no-run-unnecessary-builds for at bede værktøjet om at springe kommandoen build over for de sprog, hvor det ikke er nødvendigt (f.eks. Python).

De resulterende databaser gemmes i python og cpp undermapper til /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.
$

Analysér en CodeQL-database

Når du har oprettet din CodeQL-database, skal du følge disse trin for at analysere den:

Du kan eventuelt køre codeql pack download <packs> for at downloade alle CodeQL-pakker (beta), som du vil køre under analysen.
Kør codeql database analyze på databasen, og angiv, hvilke pakker og/eller forespørgsler der skal bruges.

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

Seddel

Hvis du analyserer mere end én CodeQL-database for en enkelt bekræftelse, skal du angive en SARIF-kategori for hvert sæt resultater, som denne kommando genererer. Når du uploader resultaterne til GitHub, bruger kodescanning denne kategori til at gemme resultaterne for hvert sprog separat. Hvis du glemmer at gøre dette, overskriver hver upload de forrige resultater.

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

Den komplette liste over parametre for kommandoen database analyze vises i følgende tabel:

Valgmulighed	Påkrævet brug
`<database>`	Angiv stien til den mappe, der indeholder den CodeQL-database, der skal analyseres.
`<packs,queries>`	Angiv CodeQL-pakker eller -forespørgsler, der skal køres. Hvis du vil køre de standardforespørgsler, der bruges til kodescanning, skal du udelade denne parameter. Du kan finde de andre forespørgselspakker, der er inkluderet i CodeQL CLI-pakken i `/<extraction-root>/codeql/qlpacks/codeql-<language>/codeql-suites`. Du kan finde oplysninger om, hvordan du opretter din egen forespørgselspakke, i Oprettelse af CodeQL-forespørgselspakker^[5] i dokumentationen til CodeQL-kommandolinjegrænsefladen.
`--format`	Angiv formatet for den resultatfil, der genereres af kommandoen. For upload til GitHub skal dette være: `sarif-latest`.
`--output`	Angiv, hvor SARIF-resultatfilen skal gemmes.
`--sarif-category`	Valgfrit til analyse af en enkelt database. Kræves for at definere sproget, når du analyserer flere databaser for en enkelt bekræftelse i et lager. Angiv en kategori, der skal medtages i SARIF-resultatfilen til denne analyse. En kategori bruges til at skelne mellem flere analyser for det samme værktøj og den samme bekræftelse, men udføres på forskellige sprog eller forskellige dele af koden.
`--sarif-add-query-help`	Valgfri. Bruges, hvis du vil inkludere en tilgængelig markdown-gengivet forespørgselshjælp til brugerdefinerede forespørgsler, der bruges i din analyse. Al forespørgselshjælp til brugerdefinerede forespørgsler, der er inkluderet i SARIF-outputtet, vises i brugergrænsefladen til kodescanning, hvis den relevante forespørgsel genererer en besked.
`<packs>`	Valgfri. Bruges, hvis du har downloadet CodeQL-forespørgselspakker og vil køre de standardforespørgsler eller forespørgselspakker, der er angivet i pakkerne.
`--threads`	Valgfri. Bruges, hvis du vil bruge mere end én tråd til at køre forespørgsler. Standardværdien er 1. Du kan angive flere tråde for at fremskynde udførelse af forespørgsler. Hvis du vil angive antallet af tråde til antallet af logiske processorer, skal du angive 0.
`--verbose`	Valgfri. Bruges til at få mere detaljerede oplysninger om analyseprocessen og diagnosticeringsdata fra databaseoprettelsesprocessen.

Grundlæggende eksempel

I dette eksempel analyseres en CodeQL-database, der er gemt på /codeql-dbs/example-repo, og resultaterne gemmes som en SARIF-fil: /temp/example-repo-js.sarif. Den bruger --sarif-category til at inkludere ekstra oplysninger i SARIF-filen, der identificerer resultaterne som JavaScript. Dette er vigtigt, når du har mere end én CodeQL-database, der skal analyseres for en enkelt bekræftelse i et lager.

$ 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.

Upload resultater til GitHub

SARIF-upload understøtter maksimalt 25.000 resultater pr. upload. Det er dog kun de øverste 5.000 resultater, der vises, prioriteret efter alvorsgrad. Hvis et værktøj genererer for mange resultater, skal du opdatere konfigurationen for at fokusere på resultaterne for de vigtigste regler eller forespørgsler.

For hver upload understøtter SARIF-upload en maksimumstørrelse på 10 MB for den gzip-komprimerede SARIF-fil. Alle uploads, der overskrider denne grænse, afvises. Hvis SARIF-filen er for stor, fordi den indeholder for mange resultater, skal du opdatere konfigurationen for at fokusere på resultaterne for de vigtigste regler eller forespørgsler. Du kan finde flere oplysninger om begrænsninger og validering af SARIF-filer i dokumentationen^[6].

Før du kan uploade resultater til GitHub, skal du finde den bedste måde at overføre GitHub-appen eller det personlige adgangstoken, du oprettede tidligere, til CodeQL-kommandolinjegrænsefladen. Vi anbefaler, at du gennemser ci-systemets vejledning til sikker brug af et hemmeligt lager. CodeQL-kommandolinjegrænsefladen understøtter:

Grænseflade med en hemmelig butik ved hjælp af --github-auth-stdin-indstillingen. Dette er den anbefalede måde at godkende på.
Lagring af hemmeligheden i miljøvariablen GITHUB_TOKEN og kørsel af kommandolinjegrænsefladen uden at medtage indstillingen --github-auth-stdin.
Overfør kommandolinjeindstillingen --github-auth-stdin, og angiv et midlertidigt token via standardinput. Dette anbefales til testformål.

Når du har besluttet dig for den mest sikre og pålidelige metode for din CI-server, skal du køre codeql github upload-results på hver SARIF-resultatfil og inkludere --github-auth-stdin, medmindre tokenet er tilgængeligt i miljøvariablen 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 komplette liste over parametre for kommandoen github upload-results vises i tabellen på følgende måde.

Valgmulighed	Påkrævet brug
`--repository`	Angiv EJEREN/NAVNET på det lager, som data skal overføres til. Ejeren skal være en organisation i en virksomhed, der har en licens til GitHub Advanced Security, og GitHub Advanced Security skal være aktiveret for lageret, medmindre lageret er offentligt.
`--ref`	Angiv navnet på den reference, du har tjekket ud og analyseret, så resultaterne kan matches med den korrekte kode. For en forgrening skal du bruge `refs/heads/BRANCH-NAME`; for at bekræfte en pullanmodning, skal du bruge `refs/pulls/NUMBER/head`; eller for den GitHub-genererede flettebekræftelse af en pullanmodning skal du bruge `refs/pulls/NUMBER/merge`.
`--commit`	Angiv den fulde SHA for den bekræftelse, du analyserede.
`--sarif`	Angiv den SARIF-fil, der skal indlæses.
`--github-auth-stdin`	Valgfri. Bruges til at overføre kommandolinjegrænsefladen gitHub-appen eller det personlige adgangstoken, der er oprettet til godkendelse med GitHubs REST API, via standardinput. Dette er ikke nødvendigt, hvis kommandoen har adgang til en `GITHUB_TOKEN` miljøvariabel, der er angivet med dette token.

Feedback

Var denne side nyttig?