Použití rozhraní příkazového řádku CodeQL

Kromě grafického uživatelského rozhraní na GitHub.com můžete také přistupovat k mnoha stejným primárním funkcím CodeQL prostřednictvím rozhraní příkazového řádku.

Tato lekce se zabývá vytvářením databází, analýzou databází a nahráváním výsledků do GitHubu pomocí rozhraní příkazového řádku CodeQL.

Příkazy rozhraní příkazového řádku CodeQL

Jakmile zpřístupníte rozhraní příkazového řádku CodeQL pro servery ve vašem systému CI a zajistíte, že se můžou ověřit pomocí GitHubu, jste připraveni vygenerovat data.

K vygenerování výsledků a jejich nahrání na GitHub můžete použít tři různé příkazy:

• database create vytvoření databáze CodeQL, která představuje hierarchickou strukturu každého podporovaného programovacího jazyka v úložišti.
• database analyze pro spouštění dotazů za účelem analýzy jednotlivých databází CodeQL a shrnutí výsledků v souboru SARIF.
• github upload-results nahrajte výsledné soubory SARIF na GitHub, kde jsou výsledky svázány s větví nebo pull requestem a zobrazí se jako výstrahy kontroly kódu.

Nápovědu k příkazovému řádku můžete zobrazit pro libovolný příkaz pomocí příkazu --help option.

Nahrání dat SARIF tak, aby se zobrazovala jako výsledky kontroly kódu na GitHubu, se podporuje pro úložiště vlastněná organizací s povoleným GitHub Advanced Security a veřejnými úložišti na GitHub.com.

Vytvoření databází CodeQL pro analýzu

Následujícím postupem vytvoříte databáze CodeQL k analýze.

1. Podívejte se na kód, který chcete analyzovat:
   • Pro větev se podívejte na hlavu větve, kterou chcete analyzovat.
   • U žádosti o přijetí změn se podívejte buď na hlavní potvrzení žádosti o přijetí změn, nebo si prohlédněte potvrzení žádosti o přijetí změn vygenerované GitHubem.
2. Nastavte prostředí pro základ kódu a ujistěte se, že jsou k dispozici všechny závislosti.
3. Vyhledejte příkaz sestavení, pokud existuje, pro základ kódu. Obvykle je to k dispozici v konfiguračním souboru v systému CI.
4. Spusťte codeql database create z kořenového adresáře vašeho úložiště a sestavte kódovou základnu:

   • Pokud chcete vytvořit jednu databázi CodeQL pro jeden podporovaný jazyk, použijte následující příkaz:

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

   • Pokud chcete vytvořit jednu databázi CodeQL pro každý jazyk pro více podporovaných jazyků, použijte následující příkaz:

     codeql database create <database> --command <build> \
       --db-cluster --language=<language-identifier>,<language-identifier>
     

Úplný seznam parametrů příkazu database create je uvedený v následující tabulce:

Příklad s jedním jazykem

Tento příklad vytvoří databázi CodeQL pro úložiště rezervovanou na adrese /checkouts/example-repo. Pomocí extraktoru JavaScriptu vytvoří hierarchickou reprezentaci kódu JavaScriptu a TypeScriptu v úložišti. Výsledná databáze je uložena v /codeql-dbs/example-reposouboru .

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

Příklad více jazyků

Tento příklad vytvoří dvě databáze CodeQL pro úložiště rezervované na adrese /checkouts/example-repo-multi. Používá:

• --db-cluster požadovat analýzu více než jednoho jazyka.
• --language určit, pro které jazyky se mají vytvářet databáze.
• --command a řekněte nástroji příkaz pro sestavení pro kódovou základnu, zde make.
• --no-run-unnecessary-builds říct nástroji, aby přeskočil příkaz sestavení pro jazyky, ve kterých není potřeba (například Python).

Výsledné databáze jsou uloženy v python podadresářích cpp/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.
$

Analýza databáze CodeQL

Po vytvoření databáze CodeQL ji analyzujte následujícím postupem:

1. Volitelně spusťte codeql pack download <packs> ke stažení libovolných balíčků CodeQL (beta), které chcete spustit během analýzy.
2. Spusťte codeql database analyze v databázi a určete, které balíčky nebo dotazy se mají použít.

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

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

Úplný seznam parametrů příkazu database analyze je uvedený v následující tabulce:

Základní příklad

Tento příklad analyzuje databázi CodeQL uloženou na /codeql-dbs/example-repo a uloží výsledky jako soubor SARIF: /temp/example-repo-js.sarif. Používá se --sarif-category k zahrnutí dalších informací do souboru SARIF, který identifikuje výsledky jako JavaScript. To je nezbytné, pokud máte více než jednu databázi CodeQL k analýze jednoho potvrzení v úložišti.

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

Nahrání výsledků do GitHubu

Nahrávání SARIF podporuje maximálně 25 000 výsledků na nahrání. Zobrazí se však pouze prvních 5 000 výsledků s prioritou podle závažnosti. Pokud nástroj generuje příliš mnoho výsledků, měli byste aktualizovat konfiguraci tak, aby se zaměřila na výsledky pro nejdůležitější pravidla nebo dotazy.

Při každém nahrávání souboru SARIF gzip podporujeme maximální velikost 10 MB. Všechna nahrání nad tímto limitem budou odmítnuta. Pokud je soubor SARIF příliš velký, protože obsahuje příliš mnoho výsledků, měli byste aktualizovat konfiguraci tak, aby se zaměřila na výsledky pro nejdůležitější pravidla nebo dotazy. Další informace o omezeních a validaci souborů SARIF naleznete v dokumentaci^[6].

Než budete moct nahrát výsledky do GitHubu, musíte určit nejlepší způsob předání tokenu aplikace GitHub nebo osobního přístupového tokenu, který jste vytvořili dříve, do rozhraní příkazového řádku CodeQL. Doporučujeme, abyste si prostudovali pokyny k zabezpečenému použití úložiště tajných kódů ve vašem systému CI. Rozhraní příkazového řádku CodeQL podporuje:

• Propojení s úložištěm tajných kódů pomocí možnosti --github-auth-stdin Toto je doporučený způsob ověřování.
• Uložení tajného kódu do proměnné GITHUB_TOKEN prostředí a spuštění rozhraní příkazového řádku bez zahrnutí možnosti --github-auth-stdin .
• Předejte možnost příkazového řádku --github-auth-stdin a zadejte dočasný token prostřednictvím standardního vstupu. To se doporučuje pro účely testování.

Když jste se rozhodli pro nejbezpečnější a nejspolehlivější metodu serveru CI, spusťte codeql github upload-results na každém souboru výsledků SARIF a zahrňte --github-auth-stdin ho, pokud není token k dispozici v proměnné GITHUB_TOKENprostředí .

# 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> 

Úplný seznam parametrů pro github upload-results příkaz se zobrazí v tabulce následujícím způsobem.