Korzystanie z interfejsu wiersza polecenia CodeQL

8 minut

Oprócz graficznego interfejsu użytkownika w GitHub.com można również uzyskać dostęp do wielu tych samych podstawowych funkcji CodeQL za pośrednictwem interfejsu wiersza polecenia.

Ta lekcja obejmuje tworzenie baz danych, analizowanie baz danych i przekazywanie wyników do usługi GitHub przy użyciu interfejsu wiersza polecenia CodeQL.

Polecenia interfejsu wiersza polecenia codeQL

Po udostępnieniu interfejsu wiersza polecenia CodeQL serwerom w systemie ciągłej integracji i upewnieniu się, że mogą uwierzytelnić się w usłudze GitHub, możesz przystąpić do generowania danych.

Możesz użyć trzech różnych poleceń, aby wygenerować wyniki i przekazać je do usługi GitHub:

database create aby utworzyć bazę danych CodeQL reprezentującą hierarchiczną strukturę każdego obsługiwanego języka programowania w repozytorium.
database analyze w celu uruchomienia zapytań w celu przeanalizowania każdej bazy danych CodeQL i podsumowania wyników w pliku SARIF.
github upload-results w celu przekazania wynikowych plików SARIF do usługi GitHub, gdzie wyniki są dopasowane do gałęzi lub żądania ściągnięcia i wyświetlane jako alerty skanowania kodu.

Możesz wyświetlić pomoc wiersza polecenia dla dowolnego polecenia przy użyciu polecenia --help option.

Przekazywanie danych SARIF w celu wyświetlenia wyników skanowania kodu w usłudze GitHub jest obsługiwane w przypadku repozytoriów należących do organizacji z włączoną usługą GitHub Advanced Security i repozytoriów publicznych w GitHub.com.

Tworzenie baz danych CodeQL do analizowania

Wykonaj następujące kroki, aby utworzyć bazy danych CodeQL do analizy.

Zapoznaj się z kodem, który chcesz przeanalizować:
- W przypadku gałęzi zapoznaj się z głową gałęzi, którą chcesz przeanalizować.
- W przypadku żądania ściągnięcia zapoznaj się z głównym zatwierdzeniem żądania ściągnięcia lub zapoznaj się z wygenerowanym przez usługę GitHub zatwierdzeniem scalania żądania ściągnięcia.
Skonfiguruj środowisko dla bazy kodu, upewniając się, że wszystkie zależności są dostępne.
Znajdź polecenie kompilacji, jeśli istnieje, dla bazy kodu. Zazwyczaj jest to dostępne w pliku konfiguracji w systemie ciągłej integracji.
Uruchom polecenie codeql database create z katalogu głównego wyewidencjonowania repozytorium i skompiluj bazę kodu:
- Aby utworzyć jedną bazę danych CodeQL dla jednego obsługiwanego języka, użyj następującego polecenia:
```
codeql database create <database> --command <build> --language=<language-identifier>
```
- Aby utworzyć jedną bazę danych CodeQL na język dla wielu obsługiwanych języków, użyj następującego polecenia:
```
codeql database create <database> --command <build> \
  --db-cluster --language=<language-identifier>,<language-identifier>
```

Uwaga

Jeśli używasz konteneryzowanej kompilacji, musisz uruchomić interfejs wiersza polecenia CodeQL wewnątrz kontenera, w którym odbywa się zadanie kompilacji.

Pełna lista parametrów polecenia database create jest wyświetlana w poniższej tabeli:

Opcja	Wymagane użycie
`<database>`	Określ nazwę i lokalizację katalogu do utworzenia dla bazy danych CodeQL. Polecenie zakończy się niepowodzeniem, jeśli spróbujesz zastąpić istniejący katalog. Jeśli określisz `--db-cluster`również wartość , jest to katalog nadrzędny, a podkatalog zostanie utworzony dla każdego przeanalizowanego języka.
`--language`	Określ identyfikator języka, aby utworzyć bazę danych dla jednej z `cpp`, , `csharpgojavajavascriptpython`i `ruby` (użyj języka JavaScript do analizowania kodu TypeScript). W przypadku użycia z opcją `--db-cluster`opcja akceptuje listę rozdzielaną przecinkami lub może być określona więcej niż raz.
`--command`	Zalecane. Służy do określania polecenia kompilacji lub skryptu, który wywołuje proces kompilacji dla bazy kodu. Polecenia są uruchamiane z bieżącego folderu lub, gdzie jest on zdefiniowany, z .`--source-root` Nie jest wymagane do analizy języków Python i JavaScript/TypeScript.
`--db-cluster`	Opcjonalny. Użyj w wielojęzycznych bazach kodu, aby wygenerować jedną bazę danych dla każdego języka określonego przez `--language`.
`--no-run-unnecessary-builds`	Zalecane. Służy do pomijania polecenia kompilacji dla języków, w których interfejs wiersza polecenia CodeQL nie musi monitorować kompilacji (na przykład Python i JavaScript/TypeScript).
`--source-root`	Opcjonalny. Użyj polecenia , jeśli uruchamiasz interfejs wiersza polecenia poza katalogiem głównym wyewidencjonowania repozytorium. Domyślnie polecenie tworzenia bazy danych zakłada, że bieżący katalog jest katalogem głównym plików źródłowych; użyj tej opcji, aby określić inną lokalizację.

Przykład pojedynczego języka

W tym przykładzie tworzona jest baza danych CodeQL dla repozytorium wyewidencjonowana pod adresem /checkouts/example-repo. Używa wyodrębniającego kodu JavaScript, aby utworzyć hierarchiczną reprezentację kodu JavaScript i TypeScript w repozytorium. Wynikowa baza danych jest przechowywana w pliku /codeql-dbs/example-repo.

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

Przykład wielu języków

W tym przykładzie są tworzone dwie bazy danych CodeQL dla repozytorium wyewidencjonowane pod adresem /checkouts/example-repo-multi. Procesor zdarzeń korzysta z następujących elementów:

--db-cluster zażądać analizy więcej niż jednego języka.
--language aby określić języki do utworzenia baz danych.
--command aby poinformować narzędzie o poleceniu kompilacji dla bazy kodu, wykonaj polecenie .
--no-run-unnecessary-builds aby nakazać narzędziu pominięcie polecenia kompilacji dla języków, gdzie nie jest to potrzebne (np. Python).

Wynikowe bazy danych są przechowywane w python podkatalogach cppi /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.
$

Analizowanie bazy danych CodeQL

Po utworzeniu bazy danych CodeQL wykonaj następujące kroki, aby je przeanalizować:

Opcjonalnie uruchom polecenie codeql pack download <packs> , aby pobrać wszystkie pakiety CodeQL (beta), które mają być uruchamiane podczas analizy.
Uruchom polecenie codeql database analyze w bazie danych i określ pakiety i/lub zapytania do użycia.

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

Uwaga

Jeśli analizujesz więcej niż jedną bazę danych CodeQL dla pojedynczego zatwierdzenia, musisz określić kategorię SARIF dla każdego zestawu wyników generowanych przez to polecenie. Po przekazaniu wyników do usługi GitHub skanowanie kodu używa tej kategorii do przechowywania wyników dla każdego języka oddzielnie. Jeśli zapomnisz to zrobić, każde przekazanie zastępuje poprzednie wyniki.

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

Pełna lista parametrów polecenia database analyze jest wyświetlana w poniższej tabeli:

Opcja	Wymagane użycie
`<database>`	Określ ścieżkę katalogu zawierającego bazę danych CodeQL do przeanalizowania.
`<packs,queries>`	Określ pakiety CodeQL lub zapytania do uruchomienia. Aby uruchomić standardowe zapytania używane do skanowania kodu, pomiń ten parametr. Inne pakiety zapytań zawarte w pakiecie interfejsu wiersza polecenia CodeQL można znaleźć w pliku `/<extraction-root>/codeql/qlpacks/codeql-<language>/codeql-suites`. Aby uzyskać informacje na temat tworzenia własnego zestawu zapytań, zapoznaj się z tematem Tworzenie zestawów^{zapytań CodeQL[5]} w dokumentacji interfejsu wiersza polecenia CodeQL.
`--format`	Określ format pliku wyników wygenerowanego przez polecenie . W przypadku przekazywania do usługi GitHub powinno to być: `sarif-latest`.
`--output`	Określ miejsce zapisania pliku wyników SARIF.
`--sarif-category`	Opcjonalnie w przypadku analizy pojedynczej bazy danych. Wymagany do zdefiniowania języka podczas analizowania wielu baz danych dla pojedynczego zatwierdzenia w repozytorium. Określ kategorię do uwzględnienia w pliku wyników SARIF na potrzeby tej analizy. Kategoria służy do rozróżniania wielu analiz dla tego samego narzędzia i zatwierdzenia, ale wykonywanych w różnych językach lub różnych częściach kodu.
`--sarif-add-query-help`	Opcjonalny. Użyj polecenia , jeśli chcesz uwzględnić dowolną dostępną pomoc dotyczącą zapytań renderowanych za pomocą języka Markdown dla zapytań niestandardowych używanych w analizie. Każda pomoc dotycząca zapytań niestandardowych uwzględnionych w danych wyjściowych SARIF będzie wyświetlana w interfejsie użytkownika skanowania kodu, jeśli odpowiednie zapytanie generuje alert.
`<packs>`	Opcjonalny. Użyj polecenia , jeśli pobrano pakiety zapytań CodeQL i chcesz uruchamiać domyślne zapytania lub zestawy zapytań określone w pakietach.
`--threads`	Opcjonalny. Użyj polecenia , jeśli chcesz użyć więcej niż jednego wątku do uruchamiania zapytań. Domyślna wartość wynosi 1. Możesz określić więcej wątków, aby przyspieszyć wykonywanie zapytań. Aby ustawić liczbę wątków na liczbę procesorów logicznych, określ wartość 0.
`--verbose`	Opcjonalny. Użyj polecenia , aby uzyskać bardziej szczegółowe informacje na temat procesu analizy i danych diagnostycznych z procesu tworzenia bazy danych.

Przykład podstawowy

W tym przykładzie analizuje bazę danych CodeQL przechowywaną w /codeql-dbs/example-repo lokalizacji i zapisuje wyniki jako plik SARIF: /temp/example-repo-js.sarif. Służy --sarif-category do uwzględnienia dodatkowych informacji w pliku SARIF, który identyfikuje wyniki jako JavaScript. Jest to niezbędne, gdy masz więcej niż jedną bazę danych CodeQL do przeanalizowania pod kątem pojedynczego zatwierdzenia w repozytorium.

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

Przekazywanie wyników do usługi GitHub

Przekazywanie SARIF obsługuje maksymalnie 25 000 wyników na jedno przesłanie. Jednak wyświetlane są tylko 5000 pierwszych wyników z priorytetem według ważności. Jeśli narzędzie generuje zbyt wiele wyników, należy zaktualizować konfigurację, aby skoncentrować się na wynikach najważniejszych reguł lub zapytań.

W przypadku każdego przekazywania przekazywanie SARIF obsługuje maksymalny rozmiar 10 MB dla skompresowanego pliku SARIF gzip. Wszelkie przekazywanie przez ten limit zostanie odrzucone. Jeśli plik SARIF jest zbyt duży, ponieważ zawiera zbyt wiele wyników, należy zaktualizować konfigurację, aby skoncentrować się na wynikach najważniejszych reguł lub zapytań. Aby uzyskać więcej informacji na temat ograniczeń i sprawdzania poprawności plików SARIF, zobacz dokumentację^[6].

Przed przekazaniem wyników do usługi GitHub należy określić najlepszy sposób przekazania aplikacji GitHub lub osobistego tokenu dostępu utworzonego wcześniej do interfejsu wiersza polecenia CodeQL. Zalecamy zapoznanie się ze wskazówkami systemu ciągłej integracji dotyczącymi bezpiecznego korzystania z magazynu wpisów tajnych. Interfejs wiersza polecenia CodeQL obsługuje:

Łączenie się z magazynem wpisów tajnych przy użyciu opcji --github-auth-stdin. Jest to zalecany sposób uwierzytelniania.
Zapisanie wpisu tajnego w zmiennej GITHUB_TOKEN środowiskowej i uruchomienie interfejsu wiersza polecenia bez uwzględniania --github-auth-stdin opcji.
Przekaż opcję wiersza polecenia --github-auth-stdin i podaj token tymczasowy za pośrednictwem standardowych danych wejściowych. Jest to zalecane do celów testowych.

Po wybraniu najbezpieczniejszej i niezawodnej metody dla serwera ciągłej integracji uruchom codeql github upload-results polecenie w każdym pliku wyników SARIF i dołącz --github-auth-stdin , chyba że token jest dostępny w zmiennej środowiskowej GITHUB_TOKEN.

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

Pełna lista parametrów polecenia github upload-results jest wyświetlana w poniższej tabeli.

Opcja	Wymagane użycie
`--repository`	Określ właściciela/nazwę repozytorium, do którego mają być przekazywane dane. Właściciel musi być organizacją w przedsiębiorstwie, która ma licencję usługi GitHub Advanced Security, a usługa GitHub Advanced Security musi być włączona dla repozytorium, chyba że repozytorium jest publiczne.
`--ref`	Określ nazwę wyewidencjonowanego i przeanalizowanego odwołania, aby wyniki mogły być dopasowane do poprawnego kodu. W przypadku gałęzi użyj polecenia `refs/heads/BRANCH-NAME`; w przypadku zatwierdzenia głównego żądania ściągnięcia użyj polecenia `refs/pulls/NUMBER/head`; lub w przypadku zatwierdzenia scalania wygenerowanego przez usługę GitHub żądania ściągnięcia użyj polecenia `refs/pulls/NUMBER/merge`.
`--commit`	Określ pełny algorytm SHA przeanalizowanego zatwierdzenia.
`--sarif`	Określ plik SARIF do załadowania.
`--github-auth-stdin`	Opcjonalny. Użyj polecenia , aby przekazać interfejs wiersza polecenia aplikację GitHub lub osobisty token dostępu utworzony do uwierzytelniania za pomocą interfejsu API REST usługi GitHub za pośrednictwem standardowych danych wejściowych. Nie jest to konieczne, jeśli polecenie ma dostęp do zmiennej środowiskowej ustawionej `GITHUB_TOKEN` przy użyciu tego tokenu.

Opinia

Czy ta strona była pomocna?