Перейти к основному содержимому
Версия: v1.0.x

Самостоятельное добавление сканеров

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

Добавление собственных сканеров возможно для следующих типов сканеров:

  • Secrets
  • SAST
  • SCA
  • Image Scan
  • IaC
к сведению

Шерлок сохраняет состояние процесса добавления нового сканера после каждого перехода между этапами. Помимо этого, для сохранения состояния можно нажать на кнопку Сохранить и выйти.

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

Создание сканера​

Основное​

Цель этапа: указать общую информацию о добавляемом сканере, предоставить формата отчёта, который он генерирует.

  1. Для самостоятельного добавления сканера необходимо перейти в раздел Настройки системы -> Сканеры.

  2. Выбрать тип сканера, который планируется добавить: Secrets, SAST, SCA, Image Scan или IaC.

    к сведению

    Выбранный тип можно будет поменять в следующем шаге.

  3. Нажать кнопку Добавить:

  4. Заполнить необходимые параметры в открывшемся окне:

    • Название: название добавляемого сканера
    • Тип: проверить, что указан корректный тип сканера: Secrets, SAST, SCA, Image Scan или IaC
    • Логотип: выбрать цветовой индикатор для добавляемого сканера. Данный функционал будет реализован в одном из следующих релизов и в настоящее время недоступен
    • Отчет: файл формата JSON до 10 МБ, генерируемый сканером

  5. Нажать на кнопку Следующий шаг.

Выбор образа (только для Image Scan)​

Цель этапа: указать информацию об анализируемом образе контейнера, доступную из отчета.

  1. Заполнить необходимые параметры в открывшемся окне:

    • Имя образа: путь до имени образа контейнера в отчете (на примере Grype это source.target.userInput)
    • Дайджест: путь до уникального идентификатора образа контейнера (дайджеста) в отчете (на примере Grype это source.target.ImageID)

  2. Нажать на кнопку Следующий шаг.

Путь к ИБ-дефектам​

Цель этапа: указать раздел отчета, в котором собрана информация об ИБ-дефектах.

  1. Заполнить необходимые параметры в открывшемся окне:

    • Путь к ИБ-дефектам: путь в отчете до массива, в котором содержится информация об ИБ-дефектах (на примере SARIF это runs.0.results)

      к сведению

      Записи runs.[0].results и runs.[0].results.[*] являются эквивалентными.

  2. Нажать на кнопку Следующий шаг.

Обогащение данными​

Цель этапа: получить максимально возможное количество информации об ИБ-дефектах для дальнейшей работы с ними.
к сведению

Для примера рассмотрим отчет формата SARIF:

  • Информация об ИБ-дефектах хранится по пути runs.[0].results
  • У каждого ИБ-дефекта есть поле ruleId - идентификатор правила, которое было использовано для его нахождения
  • При этом описание правил хранятся по пути runs.[0].tool.driver.rules
  • У каждого правила есть поле id
  • Шерлок может "связать" runs.[0].results с runs.[0].tool.driver.rules через ruleId и id соответственно, чтобы при дальнейшем соотношении полей отчета и полей ИБ-дефекта в Шерлоке можно было получать информацию не только об ИБ-дефекте, но и о правиле

  1. При необходимости обогащения данных нажать на кнопку Добавить (в противном случае - нажать кнопку Пропустить):

  2. Заполнить необходимые параметры в открывшемся окне:

    • Путь к массиву, откуда забрать информацию: путь в отчете до массива, данные из которого связаны с массивом ИБ-дефектов и потребуются в дальнейшем для соотношения полей отчета и полей ИБ-дефекта в Шерлоке (на примере SARIF это runs.0.tool.driver.rules - в этом массиве указано описание правил, рекомендации, CWE и т.д.):

  3. Нажать на кнопку Подтвердить:

  4. Выбрать поля из массива ИБ-дефектов и массива обогащённого элемента, через которые осуществляется их связь (на примере SARIF это ruleId для массива ИБ-дефектов и id для массива правил - обогащённого элемента):

  5. Нажать на кнопку Связать:

к сведению

При необходимости процедуру обогащения можно повторять несколько раз для разных массивов с нужными данными.

  1. Нажать на кнопку Следующий шаг.

Маппинг полей​

Цель этапа: соотнести данные из отчета сканера с полями, необходимыми Шерлоку для отображения их в таблице и карточке ИБ-дефекта.

  1. Реализовать соотношение полей из отчета с полями ИБ-дефектов в Шерлоке. Наборы полей будут варьироваться в зависимости от типа добавляемого сканера.

    к сведению

    После каждого завершенного соотношения полей необходимо нажать на кнопку Подтвердить.

    При необходимости можно воспользоваться регулярными выражениями.

    Например, информация о CWE в Шерлоке хранится в числовом формате. Некоторые сканеры возвращают строку вида CWE-777. Использование регулярных выражений позволит преобразовать ее в 777.

    Для добавления сканера типа Secrets необходимо реализовать соотношение полей отчета со следующими полями ИБ-дефекта в Шерлоке:

    • Уязвимый файл (обязательное поле): файл, в котором был найден ИБ-дефект
    • Строка с ИБ-дефектом (обязательное поле): номер строки, где был найден ИБ-дефект
    • Фрагмент кода: исходный текст, где был найден ИБ-дефект
    • CWE: перечень CWE
    • Критичность: уровень критичности ИБ-дефекта. После выбора поля отчета, в котором указан уровень критичности ИБ-дефекта потребуется соотнести данные с уровнями критичности, доступными в Шерлоке:
      • По умолчанию Шерлок сам найдет все уровни критичности из предоставленного отчета для соотношения данных. Они будут доступны в выпадающем списке
      • Рекомендуется уточнить полный набор доступных значений уровней критичности сканера и в ручном режиме соотнести их с уровнями критичности Шерлока
      • В противном случае можно указать уровень критичности "по умолчанию" (если отсутствует явное соответствие с уровнями критичности Шерлока)
    • Правило: правило сканера, которое идентифицировало ИБ-дефект
    • Описание: описание ИБ-дефекта, получаемое от сканера
    • Как исправить: рекомендации по устранению ИБ-дефекта, получаемые от сканера
    • Референсы: дополнительная информация об ИБ-дефекте, получаемая от сканера

  2. Нажать на кнопку Следующий шаг.

Предпросмотр​

Цель этапа: убедиться в том, что все настроено корректно и получить пример того, как будут отображаться результаты работы добавленного сканера в Шерлоке.
  1. Нажать на кнопку Обновить данные:
к сведению

Таблица предварительного просмотра результатов является интерактивной. При нажатии на ИБ-дефект будет открыта его карточка.

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

  1. Нажать на кнопку Завершить. В случае успеха, Шерлок предложит подключить добавленный сканер:

  2. Нажать на кнопку Да. Добавленный сканер отобразится в разделе Подключенные в соответствии с создаваемым типом сканера. У него будет метка Пользовательский сканер.

Изменение сканера​

  1. Для изменения сканера необходимо нажать на иконку редактирования (), расположенную рядом со сканером, который необходимо изменить.

    к сведению

    Редактирование сканера полностью аналогично процессу его создания.

    внимание

    После редактирования сканера в обязательном порядке необходимо нажать на кнопку Завершить на этапе предварительного просмотра.

    В противном случае все реализованные изменения не будут сохранены.

Удаление сканера​

  1. Для удаления сканера необходимо нажать на иконку удаления (), расположенную рядом со сканером, который необходимо удалить.

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

    внимание

    Восстановить удаленный сканер невозможно.

Пример добавления сканера​

Для примера возьмем отчет от Semgrep в формате SARIF. Да, Semgrep поддерживается Шерлоком "из коробки", но:

  • по умолчанию Шерлок использует JSON-отчет Semgrep (т.к. в нем больше данных)
  • SARIF-вариант Semgrep содержит много информации (с точки зрения полей) и отлично подходит для примера

Основное​

  1. Укажем необходимые данные:
    • Название: SemgrepSARIF
    • Тип: SAST
    • Логотип: почему бы и нет?
    • Отчет: произвольный отчет Semgrep формата SARIF

Путь к ИБ-дефектам​

  1. В качестве пути к ИБ-дефектам укажем: runs.0.results.[*]

Обогащение данными​

  1. В качестве массива, откуда забирать информацию, укажем runs.0.tool.driver.rules.[*], т.к. в нем есть описание, рекомендации, информация по классификациям и т.д.
  1. Свяжем поля через ruleID (в массиве runs.0.results.[*] - ИБ-дефект) и id (в массиве runs.0.tool.driver.rules.[*] - Обогащённый элемент)
  1. Теперь можно использовать данные обоих массивов (runs.0.results.[*] и runs.0.tool.driver.rules.[*]) для соотношения полей отчета и ИБ-дефектов в Шерлоке.

Маппинг полей​

  1. Настроим следующее соотношение полей:

    • Уязвимый файл (обязательное поле): locations.0.physicalLocation.artifactLocation.uri
    • Строка с ИБ-дефектом (обязательное поле): locations.0.physicalLocation.region.startLine
    • Фрагмент кода: locations.0.physicalLocation.region.snippet.text
    • CWE: properties.tags.0 (данные из массива rules). CWE хранятся в строке вида "CWE-548: Exposure of Information Through Directory Listing", поэтому добавляем регулярное выражение \d+

    • Критичность: defaultConfiguration.level (данные из массива rules). По умолчанию в отчете были найдены уровни критичности: error, warning, note:

      Однако, в SARIF доступен еще один уровень критичности - none. Добавляем его "вручную":

    • Правило": ruleId

    • Описание: fullDescription.text (данные из массива rules)
    • Как исправить: help.text (данные из массива rules)
    • Референсы: массив с данными отсутствует в отчете в качестве отдельного поля

Предпросмотр​

  1. Нажимаем на кнопку "Обновить данные" и смотрим на результаты
  1. Нажимаем на кнопку Завершить и сканер готов к работе!