Перейти к основному содержимому
Версия: v1.1.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. Нажать кнопку Да. Добавленный сканер отобразится в разделе Подключенные в соответствии с создаваемым типом сканера. У него будет метка Пользовательский сканер.

Продолжение заполнения​

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

Пользовательский сканер, настройки которого не были завершены, будет отображен в блоке Можно подключить на соответствующей вкладке (Secrets, SAST, SCA, Image Scan или IaC) и иметь метку Черновик.

Для продолжения настройки сканера необходимо:

  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);
    • Референсы: не совсем то, но пусть это будет helpUri (из массива rules).

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

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