Příprava databáze pro CodeQL

5 min

CodeQL zpracovává kód jako data. Analýza CodeQL spoléhá na extrakci relačních dat z kódu a jeho použití k sestavení databáze CodeQL. Tyto databáze obsahují všechny důležité informace o základu kódu.

Potom můžete spouštět dotazy CodeQL na tuto databázi, abyste identifikovali ohrožení zabezpečení, chyby a další chyby. Můžete napsat vlastní dotazy nebo spouštět standardní dotazy CodeQL napsané výzkumníky a přispěvateli komunity GitHubu.

K vytvoření a analýze databáze CodeQL můžete použít samostatné rozhraní příkazového řádku CodeQL. Analýza databáze generuje výsledky ve formátu SARIF (Static Analysis Results Interchange Format), který se dá nahrát do úložiště GitHub a zobrazit podrobnosti výstrahy.

Architektura skenování CodeQL

Kontrola CodeQL se řídí kanálem, který transformuje zdrojový kód na dotazovatelná data, spouští dotazy zabezpečení a publikuje výsledky jako výstrahy kontroly kódu.

Pracovní postup kontroly je následující:

Zdrojový kód: CodeQL vychází z obsahu repozitáře v analyzovaném commitu.
Extrakce: Extraktor specifický pro jazyk čte kód a shromažďuje fakta o zdrojových souborech, syntaxi, toku řízení a toku dat.
Vytvoření databáze: Extrahovaná fakta jsou uložená v databázi CodeQL. Každá databáze představuje jeden jazyk v základu kódu.
Provádění dotazů: CodeQL spouští GitHub spravované dotazy, dotazy komunity nebo vlastní dotazy na databázi.
Generování SARIF: Výsledky dotazů se zapisují ve formátu SARIF (Static Analysis Results Interchange Format).
GitHub skenování kódu: Výsledky SARIF se nahrají do GitHub a zobrazí se jako výstrahy kontroly kódu.

Tato architektura odděluje extrakci kódu od spouštění dotazů. Po vytvoření databáze můžete pro stejnou databázi spustit různé sady dotazů bez opětovného extrahování kódu.

Strategie jazyků

CodeQL podporuje kompilované i interpretované jazyky, ale strategie extrakce závisí na typu jazyka.

Kompilované jazyky

Pro kompilované jazyky, například:

C/C++
jazyk C#
Java
Kotlin
Rust
Swift
Go

CodeQL často potřebuje pochopit, jak se projekt sestavuje. Během vytváření databáze může CodeQL monitorovat proces sestavení, aby mohl extrahovat zdrojové soubory zpracovávané kompilátorem.

U nejspolehlivějších výsledků nakonfigurujte explicitní příkazy sestavení místo toho, abyste se spoléhali na automatické sestavení nebo na žádné možnosti sestavení .

Interpretované jazyky

Pro interpretované jazyky, například:

Python
JavaScript/TypeScript
Ruby

CodeQL extrahuje informace přímo ze zdrojového kódu bez nutnosti samostatného příkazu sestavení.

Úložiště s více jazyky

Pro úložiště obsahující více podporovaných jazyků:

Vytvořte samostatnou databázi pro každý jazyk.
V GitHub Actions použijte matici jazyka, aby se každý jazyk inicializoval, extrahoval a analyzoval správně.

Příprava databáze pro CodeQL

Před generováním databáze CodeQL:

Nainstalujte a nakonfigurujte rozhraní příkazového řádku CodeQL.
Podívejte se na verzi základu kódu, který chcete analyzovat.

Pro kompilované jazyky:

Ujistěte se, že je projekt připraven k sestavení.
Nainstalujte všechny požadované závislosti předem.
CodeQL extrahuje relační reprezentaci každého zdrojového souboru pro vytvoření databáze.

Pro interpretované jazyky:

Extraktor běží přímo ve zdrojovém kódu.
Závislosti se při extrakci automaticky vyřeší.

V kompilovaných jazycích CodeQL monitoruje normální proces sestavení. Pokaždé, když kompilátor zpracuje zdrojový soubor, CodeQL vytvoří kopii a extrahuje všechny relevantní informace potřebné k analýze.

Nastavení rozhraní příkazového řádku

Pomocí následujícího postupu nainstalujte rozhraní příkazového řádku CodeQL.

1. Stažení sady rozhraní příkazového řádku CodeQL

Doporučená metoda instalace stahuje balíček, který zajišťuje kompatibilitu mezi rozhraním příkazového řádku, knihovnami a balíčky dotazů.

Sada obsahuje:

CodeQL CLI
Kompatibilní dotazy a knihovny CodeQL
Předkompilované balíčky dotazů

Stažení sady:

Přejděte na stránku Vydané verze veřejného úložiště CodeQL.
Stáhněte sadu specifickou pro platformu v části Assets.

Stránka Vydané verze obsahuje také:

Poznámky k vydání
Předchozí verze
codeql-bundle.tar.gz, který podporuje všechny platformy

2. Extrahování archivu

Extrahujte .zip archiv do libovolného adresáře.

Uživatelé macOS Catalina (nebo novější) musí provést další kroky nastavení, jak je popsáno v dokumentaci k rozhraní příkazového řádku CodeQL.

3. Spusťte CodeQL.

Po extrakci platí jedno z následujícího:

Běh:

<extraction-root>/codeql/codeql

nebo

Přidejte:

<extraction-root>/codeql

do vašeho systému PATH, abyste pak mohli CLI jednoduše spustit takto:

codeql

Teď můžete spouštět příkazy CodeQL.

Ověřte nastavení svého CLI

Spuštěním následujících příkazů ověřte, že instalace funguje správně.

Zobrazení nainstalovaných balíčků CodeQL:

codeql resolve packs

Pokud spustitelný soubor není ve vašem PATHsouboru, použijte:

<extraction-root>/codeql/codeql resolve packs

Pokud chybí očekávané jazykové sady, ověřte, že jste stáhli sadu CodeQL, nikoli samostatné rozhraní příkazového řádku.

Podporované jazyky zobrazení:

codeql resolve languages

Vytvoření databáze

Vytvořte databázi CodeQL z kořenového adresáře projektu:

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

Replace:

<database> s cílovým adresářem.
<language-identifier> s identifikátorem jazyka, který se má analyzovat.

Můžete taky použít následující možnosti:

Option	Purpose
`--source-root`	Určuje kořenový adresář obsahující zdrojový kód.
`--db-cluster`	Vytvoří databáze pro více jazyků.
`--command`	Určuje příkaz sestavení pro kompilované jazyky. Pro Python, Ruby nebo JavaScript se nevyžaduje.
`--no-run-unnecessary-builds`	Přeskočí nepotřebné buildy při použití s `--db-cluster`.

Po úspěšném provedení:

Vytvoří se nový adresář databáze.
Při použití --db-clusterse pro každý jazyk vytvoří podadresář.

Každá databáze obsahuje:

Relační analýza dat
Zdrojový archiv
Metadata požadovaná pro analýzu CodeQL

Zdrojový archiv je snímek zdrojových souborů v době vytvoření databáze a používá se při zobrazení výsledků analýzy.

Aspekty generování a výkonu databáze

Po vytvoření databáze CodeQL je důležité pochopit, jak funguje generování databáze a jak ovlivňuje výkon.

Metody generování databáze

Databáze CodeQL můžete vygenerovat pomocí následujících:

CodeQL CLI

Vytvořte databáze a spusťte analýzu ručně.

Tento přístup je užitečný pro:

Místní rozvoj
Odstraňování chyb
Pokročilá konfigurace

Pracovní postupy GitHub Actions

Většina organizací automatizuje generování databází prostřednictvím GitHub Actions.

Typický pracovní postup:

Inicializuje CodeQL.
Vytvoří databáze.
Spouští dotazy.
Nahraje výsledky SARIF do GitHub.

Databáze pro jednotlivé jazyky

CodeQL vytvoří samostatnou databázi pro každý podporovaný jazyk.

Každý jazyk:

Používá vlastní extraktor.
Používá vlastní schéma databáze.
Analyzuje se nezávisle.

V případě úložišť s více jazyky:

Použijte volbu --db-cluster v CLI.
Nakonfigurujte matici jazyka v GitHub Actions.

Jazyková matice umožňuje paralelní analýzu a úplné pokrytí jazyka.

Extrakce na základě sestavení pro kompilované jazyky

Pro kompilované jazyky:

CodeQL monitoruje proces sestavení.
Sestavení se musí úspěšně dokončit.
Automatický autobuild nefunguje spolehlivě u každého projektu.

Nejlepších výsledků dosáhnete tak, že před analýzou definujete explicitní kroky sestavení.

Pro interpretované jazyky CodeQL extrahuje přímo ze zdrojového kódu bez nutnosti sestavení.

Důležité informace o výkonu

Doba vytváření a analýzy databáze závisí na několika faktorech.

Velikost úložiště

Větší úložiště vyžadují větší dobu extrakce a analýzy.

Více jazyků

Pomocí jazykové matice můžete analyzovat jazyky paralelně a snížit celkový běh.

Zdroje CI

Analýza CodeQL může být náročná na prostředky.

Navýšení výkonu CPU nebo paměti u runnerů může výrazně zlepšit výkon.

Rozsah analýzy

Dobu analýzy můžete zkrátit omezením naskenovaného kódu, například vyloučením:

Testovací soubory
Vygenerovaný kód

Obecně platí, že doba analýzy je úměrná množství zpracovávaného zdrojového kódu.

Vytvoření a regenerace databáze

Databáze CodeQL představuje snímek základu kódu v určitém časovém okamžiku.

Pro každé spuštění analýzy se vytvoří nová databáze.
Databáze se neaktualizují přírůstkově.
Jakákoli změna základu kódu vyžaduje novou databázi.

Databáze obvykle znovu vygenerujete v případech, kdy:

Byly odeslány nové commity.
Žádosti o přijetí změn se otevírají nebo aktualizují.
Změny konfigurace sestavení
Změny konfigurace sad dotazů nebo analýzy

Vzhledem k tomu, že generování databáze je součástí každé kontroly, je důležité sladit kontroly se smysluplnými událostmi, jako jsou žádosti o přijetí změn nebo naplánovaná spuštění.

Extraktory

Extraktor je nástroj, který vytvoří relační data a odkaz na zdroj pro každý vstupní soubor, ze kterého lze sestavit databázi CodeQL. Každý jazyk, který CodeQL podporuje, má jeden extraktor. Tato struktura zajišťuje, aby proces extrakce byl co nejpřesnější.

Každý extraktor definuje vlastní sadu možností konfigurace. Zadáním codeql resolve extractor --format=betterjson se zobrazí data formátovaná jako v následujícím příkladu:

{
  "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]*"
        }
      }
    }
  }
}

Pokud chcete zjistit, které možnosti jsou k dispozici pro extraktor vašeho jazyka, zadejte:

codeql resolve languages --format=betterjson, nebo
codeql resolve extractor --format=betterjson.

Výstupní formát betterjson také poskytuje kořenový adresář extraktoru a další jazykové možnosti.

Data v databázi CodeQL

Databáze CodeQL je jeden adresář, který obsahuje všechna data potřebná k analýze. Tato data zahrnují relační data, zkopírované zdrojové soubory a schéma databáze specifické pro jazyk, které určuje vzájemné vztahy v datech. CodeQL importuje tato data po extrakci.

Databáze CodeQL poskytují snímek dotazovatelných dat určitého jazyka, která byla extrahována z základu kódu. Tato data jsou úplná hierarchická reprezentace kódu. Patří mezi ně:

Reprezentace abstraktního stromu syntaxe (AST).
Graf toku dat.
Graf toku řízení

Databáze se generují pro jeden jazyk najednou pro vícejazyčné kódové základny. Každý jazyk má vlastní jedinečné schéma databáze. Schéma poskytuje rozhraní mezi počáteční lexikální analýzou během procesu extrakce a komplexní analýzou prostřednictvím CodeQL.

Databáze CodeQL obsahuje dvě hlavní tabulky:

Tabulka výrazů obsahuje řádek pro každý výraz ve zdrojovém kódu, který CodeQL analyzoval během procesu sestavení.
Tabulka příkazů obsahuje řádek pro každý příkaz ve zdrojovém kódu, který CodeQL analyzoval během procesu sestavení.

Knihovna CodeQL definuje třídy, které poskytují vrstvu abstrakce nad každou z těchto tabulek. Tato vrstva zahrnuje související pomocné tabulky Expr a Stmt.

Potenciální výpadky CodeQL

Vytvoření databáze v pracovním postupu kontroly kódu má několik potenciálních výpadků. Tato část se konkrétně věnuje použití akce GitHub CodeQL.

K sestavení všech zkompilovaných jazyků uvedených v matici musíte použít jazykovou matici pro automatické sestavení. Matici můžete použít k vytvoření úloh pro více než jednu podporovanou verzi programovacího jazyka, operačního systému nebo nástroje.

Pokud matici nepoužíváte, autobuild se pokusí sestavit podporovaný zkompilovaný jazyk s nejvíce zdrojovými soubory v úložišti. Analýza kompilovaných jazyků kromě jazyka Go často selže, pokud před provedením kroku analýzy nezadáte explicitní příkazy pro sestavení kódu.

Chování kroku automatického sestavení se liší v závislosti na operačním systému, na kterém běží extraktor jazyka. Krok automatického sestavení se pokusí automaticky rozpoznat vhodnou metodu sestavení pro jazyk na základě operačního systému. Toto chování může vést k nespolehlivým výsledkům pro kompilované jazyky a často může vést k selhání spuštění.

Doporučujeme nakonfigurovat krok sestavení v souboru pracovního postupu kontroly kódu, který se spouští před analýzou, místo aby se autobuild pokusil sestavit kompilované jazyky. Tímto způsobem je soubor pracovního postupu přizpůsobený požadavkům na sestavení vašeho systému a projektu pro spolehlivější kontroly.

Další informace o konkrétních jazycích a krocích automatickéhobuildu si můžete přečíst v dokumentaci k autobuildu CodeQL.

Rozšíření VS Code

K kompilaci a spouštění dotazů můžete použít Visual Studio Code (VS Code) a rozšíření CodeQL, pokud používáte VS Code 1.39 nebo novější. Rozšíření si můžete stáhnout z webu Visual Studio Code Marketplace nebo stažením souboru CodeQL VSIX.

Rozšíření používá vaše nainstalované CLI nacházející se v PATH, pokud je to možné. Pokud ne, rozšíření automaticky spravuje přístup ke spustitelnému souboru CLI za vás. Automatická správa zajišťuje, že rozhraní příkazového řádku je kompatibilní s rozšířením CodeQL.

Váš názor

Byla tato stránka užitečná?