Dostosowywanie przepływu pracy skanowania kodu za pomocą języka CodeQL — część 1

  • 10 minut

Przepływy pracy skanowania kodu korzystające z języka CodeQL mają różne opcje konfiguracji, które można dostosować do potrzeb organizacji.

Gdy używasz języka CodeQL do skanowania kodu, aparat analizy CodeQL generuje bazę danych na podstawie kodu i uruchamia na nim zapytania. Analiza CodeQL używa domyślnego zestawu zapytań, ale można określić więcej zapytań do uruchomienia oprócz domyślnych zapytań.

Możesz uruchamiać dodatkowe zapytania, jeśli są częścią pakietu CodeQL (beta) opublikowanego w rejestrze kontenerów Usługi GitHub lub pakietu QL przechowywanego w repozytorium.

Istnieją dwie opcje określania zapytań, które mają być uruchamiane przy użyciu skanowania kodu CodeQL:

  • Korzystanie z przepływu pracy skanowania kodu
  • Używanie niestandardowego pliku konfiguracji

W tej lekcji dowiesz się, jak edytować plik przepływu pracy, aby odwoływać się do dodatkowych zapytań, jak używać zapytań z pakietów zapytań oraz jak łączyć zapytania z pliku przepływu pracy i niestandardowego pliku konfiguracji.

Określanie dodatkowych zapytań w pliku przepływu pracy

Dostępne opcje określania dodatkowych zapytań, które chcesz uruchomić, to:

  • packs aby zainstalować co najmniej jeden pakiet zapytań CodeQL (beta) i uruchomić domyślny zestaw zapytań lub zapytania dla tych pakietów.
  • queries aby określić pojedynczy .ql plik, katalog zawierający wiele .ql plików, plik definicji zestawu zapytań lub dowolną kombinację .qls .

W tym samym przepływie pracy można używać zarówno pakietów, jak i zapytań.

Nie zalecamy odwoływania się do zestawów zapytań bezpośrednio z github/codeql repozytorium, takich jak github/codeql/cpp/ql/src@main. Takie zapytania mogą nie być kompilowane przy użyciu tej samej wersji języka CodeQL, co używane dla innych zapytań, co może prowadzić do błędów podczas analizy.

Korzystanie z pakietów zapytań CodeQL

Uwaga

Funkcje zarządzania pakietami CodeQL, w tym pakiety CodeQL, są obecnie dostępne w wersji beta i mogą ulec zmianie.

Aby dodać co najmniej jeden pakiet zapytań CodeQL (beta), dodaj with: packs: wpis w uses: github/codeql-action/init@v1 sekcji przepływu pracy. W ramach pakietów można określić co najmniej jeden pakiet do użycia i, opcjonalnie, która wersja ma być pobierana. Jeśli nie określisz wersji, pobierana jest najnowsza wersja. Jeśli chcesz użyć pakietów, które nie są publicznie dostępne, musisz ustawić GITHUB_TOKEN zmienną środowiskową na wpis tajny, który ma dostęp do pakietów.

W poniższym przykładzie zakres to konto organizacji lub osobiste, które opublikowało pakiet. Po uruchomieniu przepływu pracy trzy pakiety zapytań CodeQL pobierają z usługi GitHub oraz domyślne zapytania lub zestaw zapytań dla każdego uruchomienia pakietu. W poniższym przykładzie każdy z pakietów na liście zostanie pobrany na podstawie ich specyfikacji:

  • Pobrano najnowszą wersję programu pack1 , a wszystkie zapytania domyślne są uruchamiane.
  • Pobrano wersję 1.2.3 pack2 , a wszystkie zapytania domyślne są uruchamiane.
  • Pobrano najnowszą wersję pack3 zgodną z wersją 3.2.1, a wszystkie zapytania są uruchamiane.
  • Pobrano wersję 4.5.6 pack4 programu i są uruchamiane tylko zapytania znalezione w ścieżce/do/zapytaniach.
- uses: github/codeql-action/init@v3
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/pack2@1.2.3,scope/pack3@~3.2.1,scope/pack4@4.5.6:path/to/queries

Uwaga

W przypadku przepływów pracy, które generują bazy danych CodeQL dla wielu języków, należy zamiast tego określić pakiety zapytań CodeQL w pliku konfiguracji.

Korzystanie z zapytań w pakietach QL

Aby dodać co najmniej jedno zapytanie, dodaj with: queries: wpis w uses: github/codeql-action/init@v3 sekcji przepływu pracy. Jeśli zapytania znajdują się w repozytorium prywatnym, użyj parametru external-repository-token , aby określić token, który ma dostęp do wyewidencjonowania repozytorium prywatnego.

- uses: github/codeql-action/init@v3
  with:
    # Comma-separated list of queries / packs / suites to run.
    # This may include paths or a built in suite, for example:
    # security-extended or security-and-quality.
    queries: security-extended
    # Optional. Provide a token to access queries stored in private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

Można również określić zestawy zapytań w wartości queries. Zestawy zapytań to kolekcje zapytań, zwykle pogrupowane według celu lub języka.

Następujące pakiety zapytań są wbudowane w skanowanie kodu CodeQL i są dostępne do użycia:

Pakiet zapytań opis
security-extended Zapytania z pakietu domyślnego oraz zapytania o niższą ważność i precyzję
security-and-quality Zapytania z security-extendedprogramu oraz zapytania dotyczące konserwacji i niezawodności

Każdy z tych zestawów zapytań zawiera inny podzestaw zapytań zawartych w wbudowanym pakiecie zapytań CodeQL dla tego języka. Zestawy zapytań są generowane automatycznie przy użyciu metadanych dla każdego zapytania.

Po określeniu zestawu zapytań aparat analizy CodeQL uruchomi zapytania zawarte w pakiecie oprócz domyślnego zestawu zapytań.

Łączenie zapytań z pliku przepływu pracy i niestandardowego pliku konfiguracji

Jeśli używasz również pliku konfiguracji dla ustawień niestandardowych, wszystkie dodatkowe pakiety lub zapytania określone w przepływie pracy są używane zamiast tych określonych w pliku konfiguracji. Jeśli chcesz uruchomić połączony zestaw dodatkowych pakietów lub zapytań, prefiks wartości packs lub queries w przepływie pracy z symbolem + .

W poniższym przykładzie symbol gwarantuje, + że określone dodatkowe pakiety i zapytania są używane razem z dowolnymi określonymi w odwołaniu pliku konfiguracji:

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/pack2@1.2.3,scope/pack3@4.5.6:path/to/queries