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

  • 8 minuti

I flussi di lavoro di analisi del codice che usano CodeQL hanno varie opzioni di configurazione che possono fare modifiche in base alle esigenze dell'organizzazione.

In questa unità viene illustrato come fare riferimento a query aggiuntive in un file di configurazione personalizzato.

Query aggiuntive in un file di configurazione personalizzato

Un file di configurazione personalizzato è un modo alternativo per specificare pacchetti aggiuntivi e query da eseguire. È anche possibile usare il file per disabilitare le query predefinite e specificare le directory da analizzare durante l'analisi.

Nel file del flusso di lavoro usare il parametro config-file dell'azione init per specificare il percorso del file di configurazione da usare. In questo esempio viene caricato il file di configurazione ./.github/codeql/codeql-config.yml.

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml

Il file di configurazione può trovarsi all'interno del repository che si sta analizzando o in un repository esterno. L'uso di un repository esterno consente di specificare le opzioni di configurazione per più repository in un'unica posizione. Quando si fa riferimento a un file di configurazione che si trova in un repository esterno, è possibile usare la sintassi OWNER/REPOSITORY/FILENAME@BRANCH. Ad esempio: octo-org/shared/codeql-config.yml@main.

Se il file di configurazione si trova in un repository privato esterno, usare il parametro external-repository-token dell'azione init per specificare un token che ha accesso al repository privato.

- uses: github/codeql-action/init@v3
  with:
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

Le impostazioni nel file di configurazione vengono scritte in formato YAML.

Specificare i pacchetti di query CodeQL nei file di configurazione personalizzati

Nota

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

I pacchetti di query CodeQL possono essere specificati in una matrice. Il formato è diverso dal formato usato dal file del flusso di lavoro.

packs:
packs:
  # Use the latest version of 'pack1' published by 'scope'
  - scope/pack1
  # Use version 1.2.3 of 'pack2'
  - scope/pack2@1.2.3
  # Use the latest version of 'pack3' compatible with 3.2.1
  - scope/pack3@~3.2.1
  # Use pack4 and restrict it to queries found in the 'path/to/queries' directory
  - scope/pack4:path/to/queries
  # Use pack5 and restrict it to the query 'path/to/single/query.ql'
  - scope/pack5:path/to/single/query.ql
  # Use pack6 and restrict it to the query suite 'path/to/suite.qls'
  - scope/pack6:path/to/suite.qls

Il formato completo per specificare un pacchetto di query è scope/name[@version][:path]. Sia version che path sono facoltativi. version è l'intervallo di versioni semver. Se manca, viene usata la versione più recente.

Se è presente un flusso di lavoro che genera più di un database CodeQL, è possibile specificare eventuali pacchetti di query di CodeQL da eseguire in un file di configurazione personalizzato usando una mappa annidata di pacchetti.

packs:
  # Use these packs for JavaScript and TypeScript analysis
  javascript:
    - scope/js-pack1
    - scope/js-pack2
  # Use these packs for Java and Kotlin analysis
  java:
    - scope/java-pack1
    - scope/java-pack2@v1.0.0

Specificare query aggiuntive in una configurazione personalizzata

Le query aggiuntive possono essere specificate in una matrice di queries. Ogni elemento della matrice contiene un parametro uses con un valore che identifica un singolo file di query, una directory contenente file di query o un file di definizione del gruppo di query.

queries:
  - uses: ./my-basic-queries/example-query.ql
  - uses: ./my-advanced-queries
  - uses: ./query-suites/my-security-queries.qls

Opzionalmente, è possibile assegnare un nome a ciascun elemento della matrice, come mostrato nel seguente esempio di file di configurazione:

name: "My CodeQL config"

disable-default-queries: true

queries:
  - name: Use an in-repository QL pack (run queries in the my-queries directory)
    uses: ./my-queries
  - name: Use an external JavaScript QL pack (run queries from an external repo)
    uses: octo-org/javascript-qlpack@main
  - name: Use an external query (run a single query from an external QL pack)
    uses: octo-org/python-qlpack/show_ifs.ql@main
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-qlpacks/complex-python-qlpack/rootAndBar.qls

paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

Disabilitare le query predefinite

Se si vogliono eseguire solo query personalizzate, è possibile disabilitare le query di sicurezza predefinite usando disable-default-queries: true. Si dovrebbe usare questo flag anche se si sta cercando di costruire una suite di query personalizzata che escluda una particolare regola. In questo modo si evita l'esecuzione di tutte le query due volte.

Esclusione di query specifiche dall'analisi

È possibile aggiungere i filtri exclude e include al file di configurazione personalizzato, per specificare le query da escludere o includere nell'analisi, ad esempio:

  • Query specifiche dai gruppi predefiniti (security, security-extended e security-and-quality).
  • Query specifiche i cui risultati non interessano l'utente.
  • Tutte le query che generano avvisi e raccomandazioni.

È possibile usare filtri exclude simili a quelli nella configurazione del file seguente per escludere le query da rimuovere dall'analisi predefinita. Nell'esempio di un file di configurazione che segue, sia le js/redundant-assignment query che le query vengono escluse dall'analisi js/useless-assignment-to-local .

query-filters:
  - exclude:
      id: js/redundant-assignment
  - exclude:
      id: js/useless-assignment-to-local

Per trovare l'ID di una query, è possibile fare clic sull'avviso nell'elenco degli avvisi nella scheda Sicurezza. Verrà visualizzata la pagina dei dettagli dell'avviso. Il campo ID regola contiene l'ID query.

Aspetti da tenere presenti quando si lavora con il filtro excludes:

  • L'ordine dei filtri è importante. La prima istruzione di filtro visualizzata dopo le istruzioni sulle query e i pacchetti di query determina se le query vengono incluse o escluse per impostazione predefinita.
  • Le istruzioni successive vengono eseguite in ordine e le istruzioni visualizzate più avanti nel file hanno la precedenza sulle istruzioni precedenti.

Specificare le directory da analizzare

Per i linguaggi interpretati supportati da CodeQL (Python, Ruby e JavaScript/TypeScript), è possibile limitare l'analisi del codice ai file in directory specifiche aggiungendo una matrice di paths al file di configurazione. È possibile escludere i file in directory specifiche dall'analisi aggiungendo una matrice paths-ignore.

paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

Nota

  • Le paths parole chiave e paths-ignore , usate nel contesto del file di configurazione dell'analisi del codice, non devono essere confuse con le stesse parole chiave se usate per on.<push|pull_request>.paths in un flusso di lavoro. Quando vengono usati per modificare on.<push|pull_request> in un flusso di lavoro, determinano se le azioni verranno eseguite quando un utente modifica il codice nelle directory specificate.
  • I caratteri ?, +, [, ] e ! del criterio di filtro non sono supportati e verranno usati per la ricerca di una corrispondenza esatta.
  • I caratteri ** possono trovarsi solo all'inizio o alla fine di una riga oppure racchiusi tra barre e non è possibile combinare ** e altri caratteri. Ad esempio foo/**, **/foo e foo/**/bar sono tutte sintassi corrette, ma **foo non lo è. Tuttavia, è possibile usare singole stelle insieme ad altri caratteri, come illustrato nell'esempio. Sarà necessario racchiudere tra virgolette qualsiasi elemento contenente un carattere *.

Per i linguaggi compilati, se si vuole limitare l'analisi del codice a directory specifiche nel progetto, è necessario specificare i passaggi di compilazione appropriati nel flusso di lavoro. I comandi da usare per escludere una directory dalla compilazione dipendono dal sistema di compilazione.

È possibile analizzare rapidamente piccole parti di un monorepo quando si modifica il codice in directory specifiche. È necessario escludere entrambe le directory nei passaggi di compilazione e usare le parole chiave paths-ignore e paths per on.<push|pull_request> nel flusso di lavoro.