Устранение неполадок рабочего процесса CodeQL

Создание подробных журналов для отладки

Чтобы получить более подробные выходные данные журнала, можно включить ведение журнала пошаговой отладки. Дополнительные сведения см. в статье Включение ведения журнала отладки.

Создание артефактов отладки данных CodeQL

Вы можете получить артефакты, которые помогут отлаживать CodeQL. Артефакты отладки передаются в рабочий процесс, выполняемый от имени артефакта под названием debug-artifacts. Данные содержат журналы CodeQL, базы данных CodeQL и все файлы SARIF, созданные рабочим процессом.

Эти артефакты помогут вам устранять проблемы с CodeQL code scanning. Если вы обращаетесь в поддержку GitHub, то могут запросить эти данные.

Создание артефактов отладки CodeQL путем повторного выполнения заданий с включенным ведением журнала отладки

Вы можете создать артефакты отладки CodeQL, включив ведение журнала отладки и повторно выполнив задания. Дополнительные сведения о повторном выполнении рабочих процессов и заданий GitHub Actions см. в статье Повторное выполнение рабочих процессов и заданий.

Необходимо выбрать параметр Включить ведение журнала отладки. Он позволит включить ведение журнала диагностики средства выполнения и ведение журнала отладки шага для выполнения. Затем вы сможете скачать debug-artifacts для дальнейшего изучения. Изменять файл рабочего процесса при создании артефактов отладки CodeQL путем повторного выполнения заданий не требуется.

Создание артефактов отладки данных CodeQL с помощью флага рабочего процесса

Вы можете создать артефакты отладки CodeQL с помощью флага в рабочем процессе. Для этого необходимо изменить init шаг файла CodeQL analysis workflow и задать .debug: true

- name: Initialize CodeQL
  uses: github/codeql-action/init@v2
  with:
    debug: true

Сбой автоматической сборки для скомпилированного языка

Если автоматическая сборка кода для скомпилированного языка в проекте завершается ошибкой, выполните следующие действия по устранению неполадок.

• Удалите шаг autobuild из рабочего процесса code scanning и добавьте конкретные шаги сборки. Сведения об изменении рабочего процесса см. в статье Настройка code scanning. Дополнительные сведения о замене шага autobuild см. в статье Настройка рабочего процесса CodeQL для скомпилированных языков.

• Если рабочий процесс явно не указывает языки для анализа, CodeQL неявно обнаруживает поддерживаемые языки в базе кода. В этой конфигурации из скомпилированных языков C/C++, C#, Go, и Java CodeQL анализирует только язык с наибольшим числом исходных файлов. Измените рабочий процесс и добавьте матрицу, указывающую языки, которые требуется проанализировать. Такую матрицу использует рабочий процесс анализа CodeQL по умолчанию.

  В следующих извлечениях из рабочего процесса показано, как можно использовать матрицу в стратегии задания для указания языков, а затем ссылаться на каждый язык в шаге "Инициализировать CodeQL".

  jobs:
    analyze:
      permissions:
        security-events: write
        actions: read
      ...
      strategy:
        fail-fast: false
        matrix:
          language: ['csharp', 'cpp', 'javascript']
  
      steps:
      ...
        - name: Initialize CodeQL
          uses: github/codeql-action/init@v2
          with:
            languages: ${{ matrix.language }}
  

  Дополнительные сведения об изменении рабочего процесса см. в статье Настройка проверки кода.

Во время сборки не найден код

Если рабочий процесс завершается ошибкой No source code was seen during the build или The process '/opt/hostedtoolcache/CodeQL/0.0.0-20200630/x64/codeql/codeql' failed with exit code 32, это означает, что CodeQL не удалось отследить код. У этого сбоя может быть несколько причин.

1. Репозиторий может не содержать исходный код, написанный на языках, поддерживаемых CodeQL. Проверьте список поддерживаемых языков и, если дело в этом, удалите рабочий процесс CodeQL. Дополнительные сведения см. в статье Сведения о проверке кода с помощью CodeQL.

2. Автоматическое определение языка идентифицировало поддерживаемый язык, но в репозитории нет анализируемого кода на этом языке. Типичный пример — служба определения языка находит файл, связанный с определенным языком, например файл .h или .gyp, но в репозитории отсутствует соответствующий исполняемый код. Чтобы решить эту проблему, можно вручную определить языки, которые требуется проанализировать, обновив список языков в матрице language. Например, следующая конфигурация проанализирует только Go и JavaScript.

   strategy:
     fail-fast: false
     matrix:
       # Override automatic language detection by changing the list below.
       # Supported options are listed in a comment in the default workflow.
       language: ['go', 'javascript']
   

   Дополнительные сведения см. в приведенном выше разделе Сбой автоматической сборки для скомпилированного языка.

3. Рабочий процесс code scanning анализирует скомпилированный язык (C, C++, C#, Go, или Java), но код не скомпилирован. По умолчанию рабочий процесс анализа CodeQL содержит шаг autobuild, хотя этот шаг и представляет собой оптимальный процесс, но в зависимости от конкретной среды сборки он может не выполнить сборку кода. Компиляция также может завершиться ошибкой, если вы удалили этот шаг autobuild и не включили шаги сборки вручную. Дополнительные сведения об указании шагов сборки см. в статье Настройка рабочего процесса CodeQL для скомпилированных языков.

4. Рабочий процесс анализирует скомпилированный язык (C, C++, C#, Go, или Java), но части сборки кэшируются для повышения производительности (скорее всего, в системах сборки, таких как Gradle или Bazel). Поскольку CodeQL наблюдает за активностью компилятора, чтобы распознать потоки данных в репозитории, для CodeQL требуется полная сборка для выполнения анализа.

5. Рабочий процесс анализирует скомпилированный язык (C, C++, C#, Go, или Java), но компиляция не выполняется между init шагами и analyze в рабочем процессе. Для CodeQL требуется выполнение сборки между этими двумя шагами, чтобы наблюдать за активностью компилятора и выполнять анализ.

6. Скомпилированный код (в C, C++, C#, Go, или Java) успешно скомпилирован, но CodeQL не удалось обнаружить вызовы компилятора. Ниже перечислены наиболее распространенные из них.

   • Выполнение процесса сборки в отдельном контейнере для CodeQL. Дополнительные сведения см. в статье Выполнение проверки кода CodeQL в контейнере.
   • Создание с помощью распределенной системы сборки, внешней для функции GitHub Actions, использующей процесс управляющей программы.
   • CodeQL не знает об используемом конкретном компиляторе.

   При сборке кода для проектов .NET Framework, а также для проектов C# с помощью dotnet build или msbuild нужно указать /p:UseSharedCompilation=false на шаге run рабочего процесса.

   Например, следующая конфигурация для C# будет передавать флаг на первом шаге сборки.

   - run: |
       dotnet build /p:UseSharedCompilation=false
   

   Если возникла другая проблема с конкретным компилятором или конфигурацией, обратитесь в Поддержка GitHub.

Дополнительные сведения об указании шагов сборки см. в статье Настройка рабочего процесса CodeQL для скомпилированных языков.

Проверенных строк кода меньше, чем ожидалось

Для скомпилированных языков, таких как C/C++, C#, Go и Java CodeQL проверяет только файлы, созданные во время анализа. Поэтому число проверенных строк кода будет меньше, чем ожидалось, если некоторые строки исходного кода компилируются неправильно. Это может произойти по следующим причинам.

1. Функция CodeQL autobuild использует эвристические методы для сборки кода в репозитории. Но иногда такой подход приводит к неполному анализу репозитория. Например, если в одном репозитории существует несколько команд build.sh, анализ может и не завершиться, так как шаг autobuild будет выполняет только одну из команд, поэтому некоторые исходные файлы могут не компилироваться.
2. Некоторые компиляторы не работают с CodeQL и могут вызывать проблемы при анализе кода. Например, Project Lombok использует API-интерфейсы компилятора, не являющиеся открытыми, для изменения поведения компилятора. Допущения, используемые в этих изменениях компилятора, недопустимы для средства извлечения Java для CodeQL, поэтому не удается проанализировать код.

Если анализ CodeQL проверяет меньше строк кода, чем ожидалось, есть несколько подходов, которые вы можете попробовать, чтобы убедиться, что все необходимые исходные файлы скомпилированы.

Замена шага autobuild

Замените шаг autobuild теми же командами сборки, которые будут использоваться в рабочей среде. Это гарантирует, что CodeQL точно знает, как скомпилировать все исходные файлы, которые требуется проверить. Дополнительные сведения см. в статье Настройка рабочего процесса CodeQL для скомпилированных языков.

Проверка копии исходных файлов в базе данных CodeQL

Вы можете понять, почему некоторые исходные файлы не были проанализированы, проверив копию исходного кода, включенную в базу данных CodeQL. Чтобы получить базу данных из рабочего процесса Actions, измените шаг init файла рабочего процесса CodeQL и задайте debug: true.

- name: Initialize CodeQL
  uses: github/codeql-action/init@v2
  with:
    debug: true

При этом база данных передается в виде артефакта действий, который можно скачать на локальный компьютер. Дополнительные сведения см. в статье Хранение артефактов рабочего процесса.

Артефакт будет содержать архивную копию исходных файлов, проверенных с помощью CodeQL под названием src.zip. При сравнении файлов исходного кода в репозитории с файлами в src.zip можно увидеть, какие типы файлов отсутствуют. Узнав, какие типы файлов не анализируются, проще понять, как нужно изменить рабочий процесс для анализа CodeQL.

Оповещения, найденные в созданном коде

Для скомпилированных языков, таких как Java, Kotlin, Go, C, C++, и C#, CodeQL анализирует весь код, созданный во время выполнения рабочего процесса. Чтобы ограничить объем анализируемого кода, создайте код, который требуется проанализировать, указав собственные шаги сборки в блоке run . Можно объединить указание собственных шагов сборки с помощью фильтров paths и paths-ignore в событиях pull_request и push, чтобы рабочий процесс выполнялся только при изменении определенного кода. Дополнительные сведения см. в статье Синтаксис рабочего процесса для GitHub Actions.

Для таких языков, как JavaScript, Python и TypeScript, которые CodeQL анализирует без компиляции исходного кода, можно указать дополнительные параметры конфигурации, чтобы ограничить объем анализируемого кода. Дополнительные сведения см. в разделе Указание каталогов для анализа.

Ошибки извлечения в базе данных

Команда CodeQL постоянно работает над устранением критических ошибок извлечения, чтобы обеспечить проверку всех исходных файлов. Но средства извлечения CodeQL иногда генерируют ошибки во время создания базы данных. CodeQL предоставляет сведения об ошибках извлечения и предупреждениях, сгенерированных во время создания базы данных в файле журнала. Сведения о диагностике извлечения указывают на общую работоспособность базы данных. Большинство ошибок средства извлечения существенно не влияют на анализ. Небольшое количество ошибок средства извлечения является нормальным и обычно указывает на хорошее состояние анализа.

Но если в подавляющем большинстве файлов, скомпилированных во время создания базы данных, возникают ошибки средства извлечения, то следует более подробно их изучить, чтобы понять, почему некоторые исходные файлы не извлечены должным образом.

Сборка занимает слишком много времени

Если сборка с помощью анализа CodeQL занимает слишком много времени, есть несколько подходов, которые вы можете попробовать, чтобы сократить время сборки.

Увеличение объема памяти или числа ядер

Если для запуска анализа CodeQL используются локальные средства выполнения тестов, можно увеличить объем памяти или число ядер в этих средствах выполнения тестов.

Использование матричных сборок для параллелизации анализа

По умолчанию CodeQL analysis workflow использует матрицу языков, которая приводит к параллельному выполнению анализа каждого языка. Если вы указали языки, которые необходимо проанализировать непосредственно на шаге "Инициализировать CodeQL", анализ каждого языка будет выполняться последовательно. Чтобы ускорить анализ нескольких языков, измените рабочий процесс для использования матрицы. Дополнительные сведения см. в приведенном выше разделе Сбой автоматической сборки для скомпилированного языка.

Уменьшение объема кода, анализируемого в одном рабочем процессе

Время анализа обычно пропорционально объему анализируемого кода. Вы можете сократить время анализа, уменьшая объем одновременно анализируемого кода, например путем исключения тестового кода или разбиения анализа на несколько рабочих процессов, которые анализируют только подмножество кода за раз.

Для скомпилированных языков, таких как Java, Kotlin, Go, C, C++, и C#, CodeQL анализирует весь код, созданный во время выполнения рабочего процесса. Чтобы ограничить объем анализируемого кода, создайте код, который требуется проанализировать, указав собственные шаги сборки в блоке run . Можно объединить указание собственных шагов сборки с помощью фильтров paths и paths-ignore в событиях pull_request и push, чтобы рабочий процесс выполнялся только при изменении определенного кода. Дополнительные сведения см. в статье Синтаксис рабочего процесса для GitHub Actions.

Для таких языков, как JavaScript, Python и TypeScript, которые CodeQL анализирует без компиляции исходного кода, можно указать дополнительные параметры конфигурации, чтобы ограничить объем анализируемого кода. Дополнительные сведения см. в разделе Указание каталогов для анализа.

Если вы разделяете анализ на несколько рабочих процессов, как описано выше, мы по-прежнему рекомендуем использовать хотя бы один рабочий процесс, который выполняется при событии schedule, что анализирует весь код в репозитории. Так как CodeQL анализирует потоки данных между компонентами, некоторые сложные расширения функциональности безопасности можно обнаружить только в полной сборке.

Выполнение только во время события schedule

Если во время событий push и pull_request анализ все еще выполняется слишком долго, можно активировать анализ только для события schedule. Дополнительные сведения см. в разделе События.

Определение наборов запросов, выполняемых рабочим процессом

По умолчанию для каждого языка доступно три основных набора запросов. Если вы оптимизировали сборку базы данных CodeQL и процесс все еще слишком долгий, можно уменьшить число выполняемых запросов. Набор запросов по умолчанию выполняется автоматически. Он содержит самые быстрые запросы безопасности с наименьшими показателями ложноположительных результатов.

Вы можете выполнять дополнительные запросы или наборы запросов в добавок к запросам по умолчанию. Проверьте, определяет ли рабочий процесс дополнительный набор запросов или дополнительные запросы для выполнения с помощью элемента queries. Вы можете поэкспериментировать с отключением дополнительных запросов или набора запросов. Дополнительные сведения см. в статье Настройка code scanning.

Между платформами анализа результаты отличаются

При анализе кода, написанного на Python, результаты могут отличаться в зависимости от того, выполняете ли CodeQL analysis workflow в Linux, macOS или Windows.

В средствах выполнения, размещенных на GitHub, использующих Linux, CodeQL analysis workflow пытается установить и проанализировать зависимости Python, что может привести к дополнительным результатам. Чтобы отключить автоматическую установку, добавьте setup-python-dependencies: false на шаге "Инициализация CodeQL" рабочего процесса. Дополнительные сведения о настройке анализа зависимостей Python см. в разделе Анализ зависимостей Python.

Ошибка "Ошибка сервера"

Если выполнение рабочего процесса для code scanning завершается сбоем из-за ошибки сервера, попробуйте запустить рабочий процесс еще раз. Если проблема повторится, обратитесь в Поддержка GitHub.

Ошибка "Недостаточно свободного места на диске" или "Недостаточно памяти"

В очень больших проектах CodeQL может не хватить места на диске или объема памяти для средства выполнения тестов. Если вы столкнулись с этой проблемой в размещенном средстве выполнения тестов GitHub Actions, обратитесь в Поддержка GitHub, чтобы мы могли изучить проблему.

Ошибка 403 "Ресурс недоступен для интеграции" при использовании Dependabot

Dependabot считается недоверенным, когда активирует выполнение рабочего процесса, и рабочий процесс будет выполняться с использованием областей, которые доступны только для чтения. Для отправки результатов code scanning для ветви обычно требуется область security_events: write. Но code scanning всегда позволяет отправить результаты, когда событие pull_request активирует выполнение действия. Поэтому для ветвей Dependabot рекомендуем использовать событие pull_request вместо события push.

Для простоты можно запустить принудительную отправку в ветвь по умолчанию и другие важные ветви длительного выполнения, а также инициировать выполнение запросов на вытягивание, открытых для этого набора ветвей:

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

Альтернативный подход заключается в выполнении всех принудительных отправок, за исключением ветвей Dependabot:

on:
  push:
    branches-ignore:
      - 'dependabot/**'
  pull_request:

Анализ по-прежнему завершается сбоем в ветви по умолчанию

Если CodeQL analysis workflow по-прежнему завершается сбоем при фиксации, выполненной в ветви по умолчанию, необходимо проверить следующее:

• является ли Dependabot автором фиксации;
• был ли объединен запрос на вытягивание, включающий фиксацию, с помощью @dependabot squash and merge.

Этот тип фиксации слияния создан с помощью Dependabot, поэтому все рабочие процессы, выполняемые при фиксации, будут иметь разрешения только для чтения. Если вы включили code scanning и обновления системы безопасности Dependabot или обновления версии в репозитории, рекомендуем не использовать команду Dependabot @dependabot squash and merge. Вместо этого можно включить автоматическое слияние для репозитория. Это означает, что запросы на вытягивание будут автоматически объединены, если будут выполнены все необходимые проверки и пройдена проверка состояния. Дополнительные сведения о включении автоматического слияния см. в статье Автоматическое слияние запроса на вытягивание.

Ошибка: "не является файлом .ql, .qls, каталогом или спецификацией пакета запросов"

Эта ошибка возникает, если CodeQL не может найти именованный запрос, набор запросов или пакет запросов в расположении, запрошенном в рабочем процессе. Эта ошибка возникает по следующим двум причинам.

• В рабочем процессе есть опечатка.
• Ресурс, на который ссылается рабочий процесс по пути, был переименован, удален или перемещен в новое расположение.

После проверки расположения ресурса можно обновить рабочий процесс, чтобы указать правильное расположение.

Предупреждение "git checkout HEAD^2 больше не требуется"

Если вы используете старый рабочий процесс CodeQL, в выходных данных действия "Инициализировать CodeQL" может появиться следующее предупреждение:

Warning: 1 issue was detected with this workflow: git checkout HEAD^2 is no longer 
necessary. Please remove this step as Code Scanning recommends analyzing the merge 
commit for best results.

Исправьте это, удалив указанные строки из рабочего процесса CodeQL. Эти строки были добавлены в раздел steps задания Analyze в начальных версиях рабочего процесса CodeQL.

        with:
          # We must fetch at least the immediate parents so that if this is
          # a pull request then we can checkout the head.
          fetch-depth: 2

      # If this run was triggered by a pull request event, then checkout
      # the head of the pull request instead of the merge commit.
      - run: git checkout HEAD^2
        if: ${{ github.event_name == 'pull_request' }}

Измененный раздел steps рабочего процесса будет выглядеть следующим образом:

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      # Initializes the CodeQL tools for scanning.
      - name: Initialize CodeQL
        uses: github/codeql-action/init@v2

      ...

Дополнительные сведения об изменении файла рабочего процесса CodeQL см. в статье Настройка code scanning.