Personalizzare il flusso di lavoro di analisi del codice con CodeQL - Parte 1

Completato

I flussi di lavoro di analisi del codice che usano CodeQL hanno varie opzioni di configurazione che è possibile modificare per soddisfare al meglio le esigenze dell'organizzazione.

Quando si usa CodeQL per analizzare il codice, il motore di analisi di CodeQL genera un database dal codice ed esegue query sul codice. L'analisi di CodeQL usa un set predefinito di query, ma è possibile specificare più query da eseguire, oltre alle query predefinite.

È possibile eseguire query aggiuntive se fanno parte di un pacchetto CodeQL (beta) pubblicato nel registro Contenitori GitHub o in un pacchetto QL archiviato in un repository.

Sono disponibili due opzioni per specificare le query da eseguire con l'analisi del codice di CodeQL:

• Uso del flusso di lavoro di analisi del codice
• Utilizzo di un file di configurazione personalizzato

In questa unità si apprenderà come modificare un file del flusso di lavoro in modo che faccia riferimento a query aggiuntive, come usare query da pacchetti di query e come combinare query da un file del flusso di lavoro e un file di configurazione personalizzato.

Specificare query aggiuntive in un file del flusso di lavoro

Le opzioni disponibili per specificare le query aggiuntive da eseguire sono:

• packs per installare uno o più pacchetti di query di CodeQL query (beta) ed eseguire il gruppo di query predefinito o query per questi pacchetti.
• queries per specificare un singolo file .ql, una directory contenente più file .ql, un file di definizione del gruppo di query .qls o una qualsiasi combinazione.

È possibile usare pacchetti e query nello stesso flusso di lavoro.

Non è consigliabile fare riferimento ai gruppi di query direttamente dal repository github/codeql, ad esempio github/codeql/cpp/ql/src@main. Tali query potrebbero non essere compilate con la stessa versione di CodeQL usata per le altre query e ciò potrebbe causare errori durante l'analisi.

Usare i pacchetti di query di CodeQL

Nota

La funzionalità di gestione dei pacchetti di CodeQL, inclusi i pacchetti di CodeQL, è attualmente disponibile come versione beta e soggetta a modifiche.

Per aggiungere uno o più pacchetti di query di CodeQL (beta), aggiungere una voce with: packs: all'interno della sezione uses: github/codeql-action/init@v1 del flusso di lavoro. All'interno dei pacchetti è possibile specificare uno o più pacchetti da usare e, facoltativamente, quale versione scaricare. Se non si specifica una versione, viene scaricata la versione più recente. Se si vogliono usare pacchetti non disponibili pubblicamente, è necessario impostare la variabile di ambiente GITHUB_TOKEN su un segreto che abbia accesso ai pacchetti.

Nell'esempio seguente l'ambito è l'organizzazione o l'account personale che ha pubblicato il pacchetto. Quando viene eseguito il flusso di lavoro, i tre pacchetti di query di CodeQL vengono scaricati da GitHub e vengono eseguite le query predefinite o il gruppo di query per ogni pacchetto. Nell'esempio seguente, ognuno dei pacchetti nell'elenco verrà scaricato in base alle specifiche:

• Viene scaricata la versione più recente di pack1 e vengono eseguite tutte le query predefinite.
• Viene scaricata la versione 1.2.3 di pack2 e vengono eseguite tutte le query predefinite.
• Viene scaricata la versione più recente di pack3 compatibile con la versione 3.2.1 e vengono eseguite tutte le query.
• Viene scaricata la versione 4.5.6 di pack4 e vengono eseguite solo le query trovate in path/to/queries.

- uses: github/codeql-action/init@v3
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/pack2@1.2.3,scope/pack3@~3.2.1,scope/pack4@4.5.6:path/to/queries

Nota

Per i flussi di lavoro che generano database CodeQL per più linguaggi, è invece necessario specificare i pacchetti di query di CodeQL in un file di configurazione.

Usare query nei pacchetti QL

Per aggiungere una o più query, aggiungere una voce with: queries: all'interno della sezione uses: github/codeql-action/init@v3 del flusso di lavoro. Se le query si trovano in un repository privato, usare il parametro external-repository-token per specificare un token che abbia accesso per controllare il repository privato.

- uses: github/codeql-action/init@v3
  with:
    # Comma-separated list of queries / packs / suites to run.
    # This may include paths or a built in suite, for example:
    # security-extended or security-and-quality.
    queries: security-extended
    # Optional. Provide a token to access queries stored in private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

È anche possibile specificare i gruppi di query nel valore di queries. I gruppi di query sono raccolte di query, in genere raggruppate per scopo o linguaggio.

I gruppi di query seguenti sono integrati nell'analisi del codice di CodeQL e sono disponibili per l'uso:

Gruppo di query	Descrizione
security-extended	Query dalla famiglia di prodotti predefinita, oltre alla gravità inferiore e alle query di precisione
security-and-quality	Query da security-extended, oltre a query relative alla manutenibilità e all'affidabilità

Ognuno di questi gruppi di query contiene un subset diverso delle query incluse nel pacchetto di query CodeQL predefinito per tale linguaggio. I gruppi di query vengono generati automaticamente usando i metadati per ogni query.

Quando si specifica un gruppo di query, il motore di analisi di CodeQL eseguirà automaticamente le query contenute nel gruppo, oltre al set predefinito di query.

Combinare le query da un file del flusso di lavoro e da un file di configurazione personalizzato

Se si usa anche un file di configurazione per le impostazioni personalizzate, vengono usati eventuali query o pacchetti aggiuntivi specificati nel flusso di lavoro anziché quelli specificati nel file di configurazione. Se si vuole eseguire il set combinato di query o pacchetti aggiuntivi, aggiungere un prefisso al valore di packs o queries nel flusso di lavoro con il simbolo +.

Nell'esempio seguente, il simbolo + garantisce che le query e i pacchetti aggiuntivi specificati vengano usati insieme a qualsiasi elemento specificato nel file di configurazione a cui si fa riferimento:

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/pack2@1.2.3,scope/pack3@4.5.6:path/to/queries