Preparare un database per CodeQL

Completato

CodeQL considera il codice come i dati. Crei un database utilizzando dati interrogabili estratti dal codice. È quindi possibile eseguire query CodeQL in questo database per identificare vulnerabilità, bug e altri errori di sicurezza. È possibile scrivere query personalizzate o eseguire query CodeQL standard scritte da ricercatori e collaboratori della community di GitHub.

In questa unità si apprenderà come creare un database. Questo passaggio è necessario prima di poter analizzare il codice. È necessario creare un database CodeQL contenente tutti i dati necessari per eseguire query sul codice.

L'analisi CodeQL si basa sull'estrazione di dati relazionali dal codice e sull'uso per compilare un database CodeQL. Questi database contengono tutte le informazioni importanti su una codebase.

È possibile usare il prodotto autonomo dell'interfaccia della riga di comando codeQL per analizzare il codice e generare una rappresentazione del database di una codebase. Dopo aver pronto il database, è possibile eseguire una query sul database o eseguire una suite di query per generare un set di risultati in formato SARIF (Static Analysis Results Interchange Format).

Preparazione del database per CodeQL

Prima di generare un database CodeQL, è necessario installare e configurare l'interfaccia della riga di comando codeQL. È quindi necessario controllare la versione della codebase che si vuole analizzare.

Per i linguaggi compilati, la directory deve essere pronta per la compilazione, con tutte le dipendenze già installate. CodeQL inizia estraendo una singola rappresentazione relazionale di ogni file di origine nella codebase per creare un database. Tu usi questo database per analizzare il tuo codice.

Per i linguaggi interpretati, l'estrattore viene eseguito direttamente nel codice sorgente. Questa funzionalità offre una rappresentazione accurata della codebase e risolve eventuali dipendenze.

L'estrazione di file di origine dalla codebase funziona monitorando il normale processo di compilazione per i linguaggi compilati. CodeQL crea una copia del file di origine ogni volta che si richiama un compilatore per elaborare un file di origine. Raccoglie tutte le informazioni pertinenti sul codice sorgente con ogni file di origine.

Configurazione della CLI

Per configurare l'interfaccia della riga di comando codeQL, seguire questa procedura.

1. Scaricare il pacchetto .zip del bundle CLI di CodeQL

È consigliabile installare l'interfaccia della riga di comando di CodeQL e le query scaricando il pacchetto in bundle. Questo metodo consente di garantire la compatibilità e migliorare le prestazioni, anziché scaricare separatamente l'interfaccia della riga di comando e le query.

Il pacchetto di download dell'interfaccia della riga di comando codeQL è un archivio .zip che contiene strumenti, script e vari file specifici di CodeQL. Il bundle include: l'interfaccia della riga di comando di CodeQL, le versioni compatibili delle query e delle librerie dal repository GitHub CodeQL e le versioni precompilate delle query incluse.

1. Passare alla pagina Versioni del repository pubblico di CodeQL.
2. Scarica il bundle specifico della piattaforma sotto Assets.

Nella pagina Versioni, è inoltre possibile visualizzare i changelog delle versioni, insieme ai download per le versioni precedenti del bundle CodeQL. Se necessario, è possibile scaricare codeql-bundle.tar.gz, che contiene l'interfaccia della riga di comando per tutte le piattaforme supportate.

2. Estrarre l'archivio .zip

Se si usa Linux, Windows o macOS, è possibile estrarre l'archivio .zip nella directory preferita.

Gli utenti di macOS Catalina (o versioni successive) devono eseguire ulteriori passaggi. Per altre informazioni, vedere la documentazione di CodeQL relativa all'introduzione all'interfaccia della riga di comando.

3. Eseguire processi CodeQL

Dopo l'estrazione, eseguire uno dei passaggi seguenti per usare il codeql file eseguibile per eseguire i processi CodeQL:

• Esegui <extraction-root>/codeql/codeql, dove <extraction-root> è la cartella in cui è stato estratto il pacchetto CLI di CodeQL.
• Aggiungere <extraction-root>/codeql alla PATH voce in modo che sia possibile eseguire il file eseguibile come .codeql

È ora possibile eseguire i comandi CodeQL.

Verifica della configurazione dell'interfaccia della riga di comando

È possibile eseguire sottocomandi dell'interfaccia della riga di comando codeQL per verificare di aver configurato correttamente l'interfaccia della riga di comando e di analizzare i database:

• Eseguire codeql resolve packs (se è stato aggiunto codeql a PATH) per visualizzare i pacchetti codeQL che l'interfaccia della riga di comando può trovare. In caso contrario, usare /<extraction-root>/codeql/codeql resolve packs. Questo comando visualizza i nomi dei pacchetti CodeQL inclusi nel bundle dell'interfaccia della riga di comando codeQL, illustrati nei passaggi precedenti come <extraction-root>.

  Se l'interfaccia della riga di comando di CodeQL non riesce a trovare i pacchetti CodeQL per le lingue previste, verificare che sia stato scaricato il bundle CodeQL e non una copia autonoma dell'interfaccia della riga di comando di CodeQL.

• Eseguire codeql resolve languages per visualizzare i linguaggi supportati dal pacchetto CLI CodeQL per impostazione predefinita.

Creazione del database

Creare un database CodeQL eseguendo il seguente comando dalla radice del checkout del progetto:

codeql database create <database> --language=<language-identifier>

Nel comando :

• Sostituire <database> con il percorso del nuovo database da creare.
• Sostituire <language-identifier> con l'identificatore per la lingua in uso per creare il database. È possibile usare questo identificatore con --db-cluster per accettare elenchi delimitati da virgole oppure specificarlo più volte.

È anche possibile specificare le opzioni seguenti. Queste opzioni dipendono dal percorso del file di origine, dal fatto che il codice debba essere compilato o se si desidera creare database CodeQL per più di un linguaggio.

• Usare --source-root per identificare la cartella radice per i file di origine primari per la creazione del database.
• Usare --db-cluster per codebase in più lingue quando si desidera creare database per più lingue.
• Usare --command quando si crea un database per uno o più linguaggi compilati. Questa opzione non è necessaria se si usa solo Python e JavaScript.
• Usare --no-run-unnecessary-builds insieme a --db-cluster per eliminare il comando di compilazione per le lingue in cui l'interfaccia della riga di comando di CodeQL non deve monitorare la compilazione.

Dopo aver creato correttamente il database, nel comando viene visualizzata una nuova directory nel percorso specificato. Se è stata usata l'opzione --db-cluster per creare più database, viene creata una sottodirectory per ogni lingua.

Ogni directory di database CodeQL contiene più sottodirectory, inclusi i dati relazionali usati per l'analisi e un archivio di origine. L'archivio di origine è una copia dei file di origine creati al momento della creazione del database. CodeQL lo usa per visualizzare i risultati dell'analisi.

Estrattori

Un estrattore è uno strumento che produce i dati relazionali e il riferimento di origine per ogni file di input, da cui è possibile creare un database CodeQL. Ogni linguaggio supportato da CodeQL ha un estrattore. Questa struttura garantisce che il processo di estrazione sia il più accurato possibile.

Ogni estrattore definisce il proprio set di opzioni di configurazione. L'immissione di codeql resolve extractor --format=betterjson risulta in dati formattati come nel seguente esempio:

{
    "extractor_root" : "/home/user/codeql/java",
    "extractor_options" : {
        "option1" : {
            "title" : "Java extractor option 1",
            "description" : "An example string option for the Java extractor.",
            "type" : "string",
            "pattern" : "[a-z]+"
        },
        "group1" : {
            "title" : "Java extractor group 1",
            "description" : "An example option group for the Java extractor.",
            "type" : "object",
            "properties" : {
                "option2" : {
                    "title" : "Java extractor option 2",
                    "description" : "An example array option for the Java extractor",
                    "type" : "array",
                    "pattern" : "[1-9][0-9]*"
                }
            }
        }
    }
}

Per scoprire quali opzioni sono disponibili per l'estrattore della lingua, immettere codeql resolve languages --format=betterjson o codeql resolve extractor --format=betterjson. Il formato di output betterjson fornisce anche la radice dell'estrattore e altre opzioni specifiche del linguaggio.

Dati in un database CodeQL

Un database CodeQL è una singola directory che contiene tutti i dati necessari per l'analisi. Questi dati includono dati relazionali, file di origine copiati e uno schema di database specifico del linguaggio che specifica le relazioni reciproche nei dati. CodeQL importa questi dati dopo l'estrazione.

I database CodeQL forniscono uno snapshot dei dati queryable di un linguaggio specifico estratti da una codebase. Questi dati sono una rappresentazione gerarchica completa del codice. Include una rappresentazione dell'albero della sintassi astratta, del grafico del flusso di dati e del grafico del flusso di controllo.

I database vengono generati una lingua alla volta per codebase a più lingue. Ogni linguaggio ha uno schema univoco del database. Lo schema fornisce un'interfaccia tra l'analisi lessicale iniziale durante il processo di estrazione e l'analisi complessa tramite CodeQL.

Un database CodeQL include due tabelle principali:

• La expressions tabella contiene una riga per ogni espressione nel codice sorgente analizzata da CodeQL durante il processo di compilazione.
• La statements tabella contiene una riga per ogni istruzione nel codice sorgente analizzato da CodeQL durante il processo di compilazione.

La libreria CodeQL definisce le classi per fornire un livello di astrazione su ognuna di queste tabelle. Questo livello include le tabelle Expr ausiliarie correlate e Stmt.

Potenziali carenze di CodeQL

La creazione del database nel flusso di lavoro di analisi del codice presenta alcuni potenziali problemi. Questa sezione illustra in modo specifico l'uso dell'azione CodeQL di GitHub.

È necessario utilizzare una matrice di linguaggio, per autobuild, al fine di costruire ciascuno dei linguaggi compilati elencati nella matrice. È possibile usare una matrice per creare processi per più di una versione supportata di un linguaggio di programmazione, un sistema operativo o uno strumento.

Se non si usa una matrice, autobuild prova a compilare il linguaggio compilato supportato con il maggior numero di file di origine nel repository. L'analisi dei linguaggi compilati, diversa da Go, spesso ha esito negativo a meno che non si forniscano comandi espliciti per compilare il codice prima di eseguire il passaggio di analisi.

Il comportamento del autobuild passaggio varia a seconda del sistema operativo in cui viene eseguito l'estrattore di linguaggio. Il autobuild passaggio tenta di rilevare automaticamente un metodo di compilazione appropriato per il linguaggio basato sul sistema operativo. Questo comportamento può causare risultati inaffidabili per i linguaggi compilati e spesso può causare un'esecuzione non riuscita.

È consigliabile configurare una fase di compilazione all'interno del file del flusso di lavoro per l'analisi del codice che viene eseguita prima dell'analisi, piuttosto che lasciare che autobuild tenti di compilare i linguaggi precompilati. In questo modo, il file del flusso di lavoro è personalizzato in base ai requisiti di compilazione del sistema e del progetto per analisi più affidabili.

Per altre informazioni sui linguaggi specifici, vedere la autobuilddocumentazione relativa alla compilazione automatica di CodeQL.

Estensione di Visual Studio Code

È possibile usare Visual Studio Code (VS Code) e l'estensione CodeQL per compilare ed eseguire query, purché si usi VS Code 1.39 o versione successiva. È possibile scaricare l'estensione da Visual Studio Code Marketplace o scaricando il file VSIX CodeQL.

L'estensione usa l'interfaccia della riga di comando installata trovata in PATH, se disponibile. In caso contrario, l'estensione gestisce automaticamente l'accesso al file eseguibile dell'interfaccia della riga di comando (CLI). La gestione automatica garantisce che l'interfaccia della riga di comando sia compatibile con l'estensione CodeQL.