Usare CodeQL CLI

8 minuti

Oltre all'interfaccia utente grafica in GitHub.com, è anche possibile accedere a molte delle stesse funzionalità principali di CodeQL tramite un'interfaccia della riga di comando.

Questa unità illustrerà l'uso di CodeQL CLI per creare database, analizzare database e caricare i risultati in GitHub.

Comandi di CodeQL CLI

Dopo avere reso disponibile CodeQL CLI ai server nel sistema di integrazione continua e dopo essersi assicurati che possano eseguire l'autenticazione con GitHub, è possibile iniziare a generare dati.

È possibile usare tre comandi diversi per generare risultati e caricarli in GitHub:

database create per creare un database CodeQL per rappresentare la struttura gerarchica di ogni linguaggio di programmazione supportato nel repository.
database analyze per eseguire query per analizzare ogni database CodeQL e riepilogare i risultati in un file SARIF.
github upload-results per caricare i file SARIF risultanti in GitHub, dove i risultati vengono associati a un ramo o a una richiesta pull e visualizzati come avvisi di analisi del codice.

È possibile visualizzare la guida della riga di comando per qualsiasi comando usando --help option.

Il caricamento dei dati SARIF da visualizzare come risultati dell'analisi del codice in GitHub è supportato per i repository di proprietà dell'organizzazione con GitHub Advanced Security abilitato e repository pubblici in GitHub.com.

Creare database CodeQL da analizzare

Seguire questa procedura per creare database CodeQL da analizzare.

Esaminare il codice che si vuole analizzare:
- Per un ramo, estrarre l'head del ramo che si vuole analizzare.
- Per una richiesta pull, estrarre il commit HEAD della richiesta pull o un commit di unione della richiesta pull generato da GitHub.
Configurare l'ambiente per la codebase, assicurandosi che siano disponibili eventuali dipendenze.
Trovare il comando di compilazione, se presente, per la codebase. È in genere disponibile in un file di configurazione nel sistema di integrazione continua.
Eseguire codeql database create dalla radice di checkout del repository e compilare la codebase:
- Per creare un database CodeQL per un singolo linguaggio supportato, usare il comando seguente:
```
codeql database create <database> --command <build> --language=<language-identifier>
```
- Per creare un database CodeQL per ogni linguaggio se sono supportati più linguaggi, usare il comando seguente:
```
codeql database create <database> --command <build> \
  --db-cluster --language=<language-identifier>,<language-identifier>
```

Nota

Se si usa una compilazione in contenitori, è necessario eseguire CodeQL CLI all'interno del contenitore in cui si svolge l'attività di compilazione.

L'elenco completo di parametri per il comando database create viene mostrato nella tabella seguente:

Opzione	Utilizzo obbligatorio
`<database>`	Specificare il nome e il percorso di una directory da creare per il database CodeQL. Il comando avrà esito negativo se si prova a sovrascrivere una directory esistente. Se si specifica anche `--db-cluster`, questa sarà la directory padre e verrà creata una sottodirectory per ogni linguaggio analizzato.
`--language`	Specificare l'identificatore per il linguaggio per creare un database per uno di `cpp`, `csharp`, `go`, `javajavascript`, , `python`e `ruby` (usare JavaScript per analizzare il codice TypeScript). Se usata con `--db-cluster`, l'opzione accetta un elenco delimitato da virgole o può essere specificata più di una volta.
`--command`	Requisiti consigliati. Usare questa opzione per specificare il comando di compilazione o lo script che richiama il processo di compilazione per la codebase. I comandi vengono eseguiti dalla cartella corrente o, in cui è definito, da `--source-root`. Non necessario per l'analisi di Python e JavaScript/TypeScript.
`--db-cluster`	Facoltativo. Usare questa opzione nelle codebase multi-linguaggio per generare un database per ogni linguaggio specificato da `--language`.
`--no-run-unnecessary-builds`	Requisiti consigliati. Usare per eliminare il comando di compilazione per i linguaggi in cui l'interfaccia della riga di comando di CodeQL non deve monitorare la compilazione, ad esempio Python e JavaScript/TypeScript.
`--source-root`	Facoltativo. Usare questa opzione se si esegue l'interfaccia della riga di comando all'esterno della radice di checkout del repository. Per impostazione predefinita, il comando di creazione del database presuppone che la directory corrente sia la directory radice per i file di origine. Usare questa opzione per specificare un percorso diverso.

Esempio di linguaggio singolo

In questo esempio viene creato un database CodeQL per il repository estratto in /checkouts/example-repo. Viene usato l'estrattore JavaScript per creare una rappresentazione gerarchica del codice JavaScript e TypeScript nel repository. Il database risultante viene archiviato in /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.

Esempio di più linguaggi

In questo esempio vengono creati due database CodeQL per il repository estratto in /checkouts/example-repo-multi. Usa:

--db-cluster per richiedere l'analisi di più linguaggi.
--language per specificare i linguaggi per cui devono essere creati database.
--command per comunicare allo strumento il comando di compilazione per la codebase. In questo caso, make.
--no-run-unnecessary-builds per indicare allo strumento di ignorare il comando di compilazione per i linguaggi in cui non è necessario (ad esempio Python).

I database risultanti vengono archiviati nelle sottodirectory python e cpp di /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.
$

Analizzare un database CodeQL

Dopo aver creato il database CodeQL, seguire questa procedura per analizzarlo:

Facoltativamente, eseguire codeql pack download <packs> per scaricare eventuali pacchetti CodeQL (beta) da eseguire durante l'analisi.
Eseguire codeql database analyze nel database e specificare i pacchetti e/o le query da usare.

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

Nota

Se si analizzano più database CodeQL per un singolo commit, è necessario specificare una categoria SARIF per ogni set di risultati generati da questo comando. Quando si caricano i risultati in GitHub, l'analisi del codice usa questa categoria per archiviare separatamente i risultati per ogni linguaggio. Se si dimentica di eseguire questa operazione, ogni caricamento sovrascrive i risultati precedenti.

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

L'elenco completo di parametri per il comando database analyze viene mostrato nella tabella seguente:

Opzione	Utilizzo obbligatorio
`<database>`	Specificare il percorso della directory contenente il database CodeQL da analizzare.
`<packs,queries>`	Specificare i pacchetti o le query CodeQL da eseguire. Per eseguire le query standard usate per l'analisi del codice, omettere questo parametro. Gli altri gruppi di query inclusi nel bundle di CodeQL CLI sono disponibili in `/<extraction-root>/codeql/qlpacks/codeql-<language>/codeql-suites`. Per informazioni sulla creazione di un gruppo di query personalizzato, vedere Creazione di gruppi di query CodeQL^[5] nella documentazione relativa al CodeQL CLI.
`--format`	Specificare il formato per il file dei risultati generato dal comando. Per il caricamento in GitHub deve essere: `sarif-latest`.
`--output`	Specificare il percorso in cui salvare il file di risultati SARIF.
`--sarif-category`	Facoltativo per l'analisi del database singolo. Necessario per definire il linguaggio quando si analizzano più database per un singolo commit in un repository. Specificare una categoria da includere nel file di risultati SARIF per questa analisi. Una categoria viene usata per distinguere più analisi per lo stesso strumento e commit, ma eseguite su linguaggi diversi o parti diverse del codice.
`--sarif-add-query-help`	Facoltativo. Usare questa opzione se si vuole includere qualsiasi guida per la query di cui è stato eseguito il rendering markdown disponibile per le query personalizzate usate nell'analisi. Qualsiasi guida alla query personalizzata inclusa nell'output SARIF verrà visualizzata nell'interfaccia utente di analisi del codice se la query pertinente genera un avviso.
`<packs>`	Facoltativo. Usare questa opzione se i pacchetti di query di CodeQL sono stati scaricati e si vuole eseguire le query predefinite o i gruppi di query specificati nei pacchetti.
`--threads`	Facoltativo. Usare questa opzione se si vogliono usare più thread per eseguire query. Il valore predefinito è 1. È possibile specificare più thread per velocizzare l'esecuzione di query. Per impostare il numero di thread sul numero di processori logici, specificare 0.
`--verbose`	Facoltativo. Usare questa opzione per ottenere informazioni più dettagliate sul processo di analisi e i dati di diagnostica del processo di creazione del database.

Esempio di base

Questo esempio analizza un database CodeQL archiviato in /codeql-dbs/example-repo e salva i risultati come file SARIF: /temp/example-repo-js.sarif. Usa --sarif-category per includere informazioni aggiuntive nel file SARIF che identificano i risultati come JavaScript. Questo è essenziale quando sono presenti più database CodeQL da analizzare per un singolo commit in un repository.

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

Caricare i risultati in GitHub

Il caricamento SARIF supporta un massimo di 25.000 risultati per caricamento. Tuttavia, vengono visualizzati solo i primi 5.000 risultati, classificati in ordine di priorità per gravità. Se uno strumento genera troppi risultati, è necessario aggiornare la configurazione in modo da concentrarsi sui risultati per le regole o le query più importanti.

Per ogni caricamento, il caricamento SARIF supporta una dimensione massima di 10 MB per il file SARIF con compressione gzip. Eventuali caricamenti oltre questo limite verranno rifiutati. Se il file SARIF è troppo grande perché contiene troppi risultati, è necessario aggiornare la configurazione in modo da concentrarsi sui risultati per le regole o le query più importanti. Per altre informazioni sulle limitazioni e sulla convalida dei file SARIF, vedere la documentazione ^[6].

Prima di poter caricare i risultati in GitHub, è necessario determinare il modo migliore per passare l'app GitHub o il token di accesso personale creato in precedenza a CodeQL CLI. È consigliabile esaminare le indicazioni del sistema di integrazione continua sull'uso sicuro di un archivio di segreti. CodeQL CLI supporta:

Interfacciamento con un archivio segreto usando l'opzione --github-auth-stdin. Questo è il modo consigliato per l'autenticazione.
Salvataggio del segreto nella variabile di ambiente GITHUB_TOKEN ed esecuzione dell'interfaccia della riga di comando senza includere l'opzione --github-auth-stdin.
Passare l'opzione della riga di comando --github-auth-stdin e fornire un token temporaneo tramite input standard. Ti consigliamo di eseguire questa opzione a scopo di test.

Quando si è scelto il metodo più sicuro e affidabile per il server di integrazione continua, eseguire codeql github upload-results in ogni file di risultati SARIF e includere --github-auth-stdin, a meno che non sia disponibile il token nella variabile di ambiente 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>

L'elenco completo dei parametri per il github upload-results comando viene visualizzato nella tabella come indicato di seguito.

Opzione	Utilizzo obbligatorio
`--repository`	Specificare il PROPRIETARIO/NOME del repository in cui caricare i dati. Il proprietario deve essere un'organizzazione all'interno di un'azienda che ha una licenza per GitHub Advanced Security ed è necessario che la funzionalità GitHub Advanced Security sia abilitata per il repository, a meno che il repository non sia pubblico.
`--ref`	Specificare il nome del riferimento estratto e analizzato in modo che i risultati possano essere associati al codice corretto. Per un ramo usare `refs/heads/BRANCH-NAME`, per il commit di intestazione di una richiesta pull usare `refs/pulls/NUMBER/head` oppure per il commit di merge generato da GitHub di una richiesta pull usare `refs/pulls/NUMBER/merge`.
`--commit`	Specificare il valore SHA completo del commit analizzato.
`--sarif`	Specificare il file SARIF da caricare.
`--github-auth-stdin`	Facoltativo. Usare questa opzione per passare all'interfaccia della riga di comando l'app GitHub o il token di accesso personale creato per l'autenticazione con l'API REST di GitHub tramite input standard. Questa operazione non è necessaria se il comando può accedere a una variabile di ambiente `GITHUB_TOKEN` impostata con questo token.

Commenti e suggerimenti

Questa pagina è stata utile?