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

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

W tej lekcji dowiesz się, jak odwoływać się do dodatkowych zapytań w niestandardowym pliku konfiguracji.

Dodatkowe zapytania w pliku konfiguracji niestandardowej

Niestandardowy plik konfiguracji to alternatywny sposób określania dodatkowych pakietów i zapytań do uruchomienia. Możesz również użyć pliku, aby wyłączyć zapytania domyślne i określić, które katalogi mają być skanowane podczas analizy.

W pliku przepływu pracy użyj config-file parametru init akcji, aby określić ścieżkę do pliku konfiguracji, którego chcesz użyć. W tym przykładzie ładuje plik ./.github/codeql/codeql-config.ymlkonfiguracji .

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml

Plik konfiguracji może znajdować się w repozytorium, które analizujesz lub w repozytorium zewnętrznym. Użycie repozytorium zewnętrznego umożliwia określenie opcji konfiguracji dla wielu repozytoriów w jednym miejscu. Jeśli odwołujesz się do pliku konfiguracji znajdującego się w repozytorium zewnętrznym, możesz użyć OWNER/REPOSITORY/FILENAME@BRANCH składni. Na przykład: octo-org/shared/codeql-config.yml@main.

Jeśli plik konfiguracji znajduje się w zewnętrznym prywatnym repozytorium, użyj external-repository-token parametru init akcji, aby określić token, który ma dostęp do repozytorium prywatnego.

- uses: github/codeql-action/init@v3
  with:
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

Ustawienia w pliku konfiguracji są zapisywane w formacie YAML.

Określanie pakietów zapytań CodeQL w niestandardowych plikach konfiguracji

Uwaga

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

Pakiety zapytań CodeQL można określić w tablicy. Format różni się od formatu używanego przez plik przepływu pracy.

packs:
packs:
  # Use the latest version of 'pack1' published by 'scope'
  - scope/pack1
  # Use version 1.2.3 of 'pack2'
  - scope/pack2@1.2.3
  # Use the latest version of 'pack3' compatible with 3.2.1
  - scope/pack3@~3.2.1
  # Use pack4 and restrict it to queries found in the 'path/to/queries' directory
  - scope/pack4:path/to/queries
  # Use pack5 and restrict it to the query 'path/to/single/query.ql'
  - scope/pack5:path/to/single/query.ql
  # Use pack6 and restrict it to the query suite 'path/to/suite.qls'
  - scope/pack6:path/to/suite.qls

Pełny format określania pakietu zapytań to scope/name[@version][:path]. Oba version elementy i path są opcjonalne. version to zakres wersji programu semver. Jeśli jej brakuje, zostanie użyta najnowsza wersja.

Jeśli masz przepływ pracy, który generuje więcej niż jedną bazę danych CodeQL, możesz określić dowolne pakiety zapytań CodeQL do uruchomienia w niestandardowym pliku konfiguracji przy użyciu zagnieżdżonej mapy pakietów.

packs:
  # Use these packs for JavaScript and TypeScript analysis
  javascript:
    - scope/js-pack1
    - scope/js-pack2
  # Use these packs for Java and Kotlin analysis
  java:
    - scope/java-pack1
    - scope/java-pack2@v1.0.0

Określanie dodatkowych zapytań w konfiguracji niestandardowej

Możesz określić dodatkowe zapytania w tablicy queries . Każdy element tablicy zawiera uses parametr z wartością, która identyfikuje pojedynczy plik zapytania, katalog zawierający pliki zapytań lub plik definicji zestawu zapytań.

queries:
  - uses: ./my-basic-queries/example-query.ql
  - uses: ./my-advanced-queries
  - uses: ./query-suites/my-security-queries.qls

Opcjonalnie można nadać każdej tablicy nazwę elementu tablicy, jak pokazano w poniższym przykładowym pliku konfiguracji:

name: "My CodeQL config"

disable-default-queries: true

queries:
  - name: Use an in-repository QL pack (run queries in the my-queries directory)
    uses: ./my-queries
  - name: Use an external JavaScript QL pack (run queries from an external repo)
    uses: octo-org/javascript-qlpack@main
  - name: Use an external query (run a single query from an external QL pack)
    uses: octo-org/python-qlpack/show_ifs.ql@main
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-qlpacks/complex-python-qlpack/rootAndBar.qls

paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

Wyłączanie domyślnych zapytań

Jeśli chcesz tylko uruchamiać zapytania niestandardowe, możesz wyłączyć domyślne zapytania zabezpieczeń przy użyciu polecenia disable-default-queries: true. Należy również użyć tej flagi, jeśli próbujesz utworzyć niestandardowy zestaw zapytań, który wyklucza określoną regułę. Pozwala to uniknąć dwukrotnego uruchomienia wszystkich zapytań.

Wykluczanie określonych zapytań z analizy

Możesz dodawać exclude i include filtry do niestandardowego pliku konfiguracji, aby określić zapytania, które chcesz wykluczyć lub uwzględnić w analizie, takie jak:

Określone zapytania z domyślnych zestawów (securityi security-extendedsecurity-and-quality ).
Konkretne zapytania, których wyniki cię nie interesują.
Wszystkie zapytania, które generują ostrzeżenia i zalecenia.

Możesz użyć exclude filtrów podobnych do tych w konfiguracji następującego pliku, aby wykluczyć zapytania, które mają zostać usunięte z analizy domyślnej. W przykładzie pliku konfiguracji, który następuje, zapytania js/redundant-assignment i js/useless-assignment-to-local są wykluczone z analizy.

query-filters:
  - exclude:
      id: js/redundant-assignment
  - exclude:
      id: js/useless-assignment-to-local

Aby znaleźć identyfikator zapytania, możesz kliknąć alert na liście alertów na karcie Zabezpieczenia. Spowoduje to otwarcie strony szczegółów alertu. Pole Identyfikator reguły zawiera identyfikator zapytania.

Kwestie, które należy wziąć pod uwagę podczas pracy z filtrem excludes :

Kolejność filtrów jest ważna. Pierwsza instrukcja filtru wyświetlana po instrukcjach dotyczących zapytań i pakietów zapytań określa, czy zapytania są domyślnie dołączone, czy wykluczone.
Kolejne instrukcje są wykonywane w kolejności, a instrukcje wyświetlane w dalszej części pliku mają pierwszeństwo przed wcześniejszymi instrukcjami.

Określanie katalogów do skanowania

W przypadku języków interpretowanych obsługiwanych przez język CodeQL (Python, Ruby i JavaScript/TypeScript) można ograniczyć skanowanie kodu do plików w określonych katalogach przez dodanie paths tablicy do pliku konfiguracji. Pliki w określonych katalogach można wykluczyć z analizy, dodając tablicę paths-ignore .

paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

Uwaga

Słowa kluczowe paths i paths-ignore, używane w kontekście pliku konfiguracji skanowania kodu, nie powinny być mylone z tymi samymi słowami kluczowymi, gdy są używane dla on.<push|pull_request>.paths w przepływie pracy. Gdy są one używane do modyfikowania on.<push|pull_request> w przepływie pracy, określają, czy akcje będą uruchamiane, gdy ktoś modyfikuje kod w określonych katalogach.
Znaki ?wzorca filtru , , +[, ]i ! nie są obsługiwane i będą dopasowywane dosłownie.
** znaki mogą być tylko na początku lub na końcu wiersza albo otoczone ukośnikami i nie można mieszać ** ani innych znaków. Na przykład: foo/**, **/fooi foo/**/bar są dozwolone składni, ale **foo nie. Można jednak używać pojedynczych gwiazdek wraz z innymi znakami, jak pokazano w przykładzie. Musisz zacytować wszystko, co zawiera * znak.

W przypadku skompilowanych języków, jeśli chcesz ograniczyć skanowanie kodu do określonych katalogów w projekcie, musisz określić odpowiednie kroki kompilacji w przepływie pracy. Polecenia potrzebne do wykluczenia katalogu z kompilacji będą zależeć od systemu kompilacji.

Podczas modyfikowania kodu w określonych katalogach można szybko analizować małe fragmenty monorepo. Musisz wykluczyć katalogi w krokach kompilacji i użyć paths-ignore słów kluczowych i paths w on.<push|pull_request> przepływie pracy.

Opinia

Czy ta strona była pomocna?