Перейти к содержанию

Утилита wave-cli

Описание и параметры

В состав Системы как отдельный Docker-образ входит wave-cli – утилита командной строки, позволяющая:

  • Проводить сканирование проектов, для которых объектом сканирования является репозиторий с исходным кодом.
  • Осуществлять интеграцию сканирования с пайплайнами CI/CD.

Для интеграции с пайплайном CI/CD необходимо добавить вызов wave-cli в пайплайн как отдельную задачу.

Пример пайплайна с вызовом wave-cli - фрагмент файла .gitlab-ci.yml:

stages:
    - cli

CODE:cli:
    stage: cli
    image: ${WAVE_CLI_IMAGE}
    script:
      - |
        python /app/src/wave_cli.py \
        --id "${CLI_PROJECT_ID}" \
        --username "${CLI_USERNAME}" \
        --password "${CLI_PASSWORD}" \
        --wave-url "${WAVE_URL}" \
        --branch "${CI_DEFAULT_BRANCH}" \
        --folder "${CLI_FOLDER}" \
        --repository-name "${CI_PROJECT_NAME}" \
        --repository-link "${CI_PROJECT_URL}" \
        --blocked \
        --report-format json --report-format html --report-format sarif \
        --severity-status error=5 --severity-status critical=1
    tags:
      - wave

Параметры утилиты wave-cli:

  • --id – идентификатор проекта в Системе, для которого проводится сканирование.
  • --username – имя пользователя для авторизации в Системе.
  • --password – пароль пользователя для авторизации в Системе.
  • --wave-url – URL-адрес Системы.
  • --branch – ветка репозитория, для которой проводится сканирование.
  • --folder – опциональный параметр, задающий путь до папки с исходным кодом внутри репозитория. Если параметр не задан, используется значение по умолчанию (текущая папка).
  • --repository-name – опциональный параметр, в котором можно указать имя репозитория. Если этот параметр был задан при сканировании, на странице проекта имя репозитория будет отображено в поле Сканируемый репозиторий.
  • --repository-link – опциональный параметр, в котором можно указать ссылку на репозиторий. Если этот параметр был задан при сканировании, на странице проекта ссылка на репозиторий будет отображена в поле Сканируемый репозиторий.
  • --blocked – опциональный флаг. Если флаг установлен, выполнение пайплайна блокируется до конца сканирования. Если флаг не установлен, сканирование запускается, а задача завершается без ожидания его результатов.
  • --report-format – формат отчета о результатах выполненного сканирования. Возможно множественное использование параметра для разных форматов (json, html, sarif) в любом порядке.
  • --severity-status – минимальное количество уязвимостей определенного уровня при котором происходит остановка пайплайна. Возможно множественное использование параметра для разных уровней (critical, error, warning, info).

Переменная WAVE_CLI_IMAGE в приведенном выше примере – ссылка на актуальную версию wave-cli, например, cr.yandex/abc123/wave/wave-cli:26.2.3, где 26.2.3 – номер версии.

Подготовка к запуску

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

Чтобы определить идентификатор проекта в Системе, откройте страницу проекта и скопируйте идентификатор из адресной строки веб-браузера.

Например, для проекта с адресной строкой, приведенной ниже, идентификатор – 15:

https://wave.demo.appsec.global/project/15

Результаты запуска в CLI

В ходе сканирования wave-cli логирует информацию о ходе выполнения. Конечный результат работы утилиты определяется выводом сообщения:

  • FINISHED – при успешном завершении сканирования.
  • CRASHED – при неуспешном завершении.

Также утилита выводит краткую сводку о результатах сканирования, включающую следующую информацию:

  • id_scan – идентификатор сканирования в Системе.
  • scan_status – конечный результат работы утилиты.

  • scanSummary – статистика завершившегося сканирования:

    • infoVulnerabilityCount – количество найденных уязвимостей уровня критичности Info (информационный).
    • warningVulnerabilityCount – количество найденных уязвимостей уровня критичности Warning (предупреждение).
    • errorVulnerabilityCount – количество найденных уязвимостей уровня критичности Error (ошибка).
    • criticalVulnerabilityCount – количество найденных уязвимостей уровня критичности Critical (критический).

Отчеты в CLI

Утилита wave-cli предоставляет возможность формировать отчеты о результатах сканирования.

Для этого необходимо:

  1. Обновить wave-cli до версии 26.2.3.
  2. При запуске утилиты wave-cli указать параметр --report-format и задать формат отчета - json, html, sarif, см. раздел «Описание и параметры».

При успешном завершении сканирования в консоли после сообщения Reports будут приведены ссылки на сформированные отчеты:

Ссылки на скачивание отчетов действительны 24 часа.

Результаты запуска в Системе

После завершения сканирования, выполненного с помощью wave-cli, на странице проекта вновь завершившееся сканирование будет представлено в виде отдельной строки, детали см. в разделе «Результаты сканирования».

Результаты сканирования проекта, выполненного с помощью wave-cli, полностью идентичны результатам, которые можно получить при сканировании с использованием пользовательского интерфейса Системы.