Help:Sarif: Difference between revisions

From Svacer Wiki
VisualWikitext
m (minor fixes)
mNo edit summary
(6 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== Работа с SARIF из CLI ==
[[Category:Help]]
Для импорта и экспорта результатов в формате SARIF Svacer предоставляет набор команд <code>svacer sarif2 import</code> и <code>svacer sarif2 export</code>.
== Работа с SARIF ==


Основные возможности данных команд
=== SARIF2 ===
 
Начиная с релиза 8.0.0 добавлена команда '''sarif2''' с подкомандами '''import''' и '''export'''. Рекомендуется использовать данную функциональность вместо старой команды '''sarif'''. Новый импорт обеспечивает создание детекторов в Svacer из reporting descriptor-ов в sarif, что обеспечивает корректную работу фильтров. Новая функциональность импорта поддерживает большую часть опций, которые могут быть использованы при импорте svres-файлов.
=== Импорт ===
NAME:
    svacer sarif2 import - Import SARIF files to Svacer format
USAGE:
    svacer sarif2 import [command options] <path> <path> ... <path>
OPTIONS:
    --ssl                                            Connect to the server using https protocol (default: false)
    --ssl-ca-certs value                            Trusted CA cert path. Example: /usr/local/certs/* , /usr/local/certs/ca.crt, /usr/local/certs/ca*.crt
    --user value                                    Valid user name
    --password value                                Valid user password
    --host value                                    Valid host name with running svace history server (default: localhost) [$SVACER_HOST_NAME]
    --port value                                    Defines port for REST API (default: 8080) [$SVACER_API_PORT]
    --grpc value                                    Defines port for gRPC API (default: 3002) [$SVACER_GRPC_PORT]
    --ldap_server value                              Server for LDAP authentication [$SVACER_LDAP_SERVER]
    --quick-stats                                    Report quick stats about uploaded snapshots (default: false)
    --out-format value                              Define format of reported information. Values: text|json. Default: text.
    --quality-gate value                            Specify a quality gate. Format: stat_1:severity_1:N_1,...,stat_k:severity_k:N_k, stat takes values: new, missing, matched, same, total; severity takes the following values: all, critical, major, normal, minor, undefined, <detector name part>; N is a natural number. If the severity of the number N is exceeded, it will out a warning. Also, as a value, you can specify a json or yaml file in which the quality gate is specified.
    --quality-gate-exit-code value                  Specify the exit code of the application in the range from 0 to 125, which will be issued when the quality-gate is exceeded. The default is 0.
    --out-file value                                Target to print report information (by default stdout)
    --project-group value [ --project-group value ]  Project group where put new project. To set multiple project groups, use this flag multiple times
    --if-no-group value                              Defines if there is no project group with specified name: no-action (ignore project group with warning), add (add new project group), error (throw an error). The default is no-action
    --if-no-branch name                              Defines if there is no branch: clone-{name|id} (clone the branch with given name|id), create-empty (create a new empty branch), return-error (throw an error), name or `ID` of the branch to be cloned. The default is clone-master
    --attach value [ --attach value ]                Attach file(s) to the snapshot. To add multiple files, use this flag multiple times
    --field value [ --field value ]                  Adds custom field to the snapshot information. Format <field name>:<value>. <value> is treated as JSON string. Multiple occurrences of the same field are processed as array.
    --no-clean                                      Do not clean intermediate directory with pre-processed data before import (default: false)
    --upload                                        Upload data to the server (default: false)
    --project value                                  Set explicit project name. Default value is a name of the directory containing .svace-dir
    --branch value                                  Set branch name (default: master)
    --snapshot value                                Set explicit snapshot name (default: <import time>)
    --path-prefix value                              Defines mapping rule for path prefixes in format <file> or line prefix:replacement;prefix:replacement
    --store value                                    Defines path to directory for pre-processed data. You may share the same directory for multiple projects. You can define remote store here to upload data to another server in a format remote:<host>:<port> (default: <current working dir>/.svacer-dir)
    --pattern value [ --pattern value ]              List of patterns to match files. Pattern is matched against full path
    --uriBaseId value                                Specifies the absolute URI with respect to which that relative reference is interpreted (see 3.4.4 in SARIF spec). Format '<name>=<path>,<name>=<path>,...
    --base-dir value                                Base dir to resolve relative path in artifacts
    --include-contents                              Import/export artifact contents (source code) when it is available (default: false)
    --resolver value                                Defines path to file with custom path resolver.
      User should provide file containing function with signature:
      // Return (<resolved path>, true) if path is resolved. Return ("", false) if default (built-in) path resolver should be used
      // Function can use Go packages regexp, filepath, strings, fmt
      func ResolvePath (s string) (string, bool)
    --map-severity value  Defines relation between SARIF and Svacer checker severity.
      Expected format <sarif level|*>:<svacer level>,<sarif level>:<svacer level>,...
      All values are case-insensitive. Asterisk matches any severity. All rules are applied from left to right
      Example: note:minor,error:critical,*:major
    --autoclean  Remove .svacer-dir after successfull upload (default: false)
    --help      Show help (default: false)


Пример импорта c включением содержимого файлов (при наличии его в самом sarif-файле или возможности найти файл в процессе импорта):
Пример импорта c включением содержимого файлов (при наличии его в самом sarif-файле или возможности найти файл в процессе импорта):
   svacer sarif2 import --store /tmp/sarif --include-contents /path/to/sarif/file.sarif
   svacer sarif2 import --store /tmp/sarif --include-contents /path/to/sarif/file.sarif


Если sarif-файл содержит относительные пути, то можно указать опцию <code>--base-dir</code> для поиска файлов относительно указанной директории.
Если sarif файл содержит относительные пути, то можно указать опцию <code>--base-dir</code> для поиска файлов относительно указанной директории.


Далее полученный intermediate store можно загрузить командой upload как и для импорта svres. Также можно скомбинировать import с upload:
Далее полученный intermediate store можно загрузить командой upload как и для импорта svres. Также можно скомбинировать import с upload:
   svacer sarif2 import --upload --store /tmp/sarif --include-contents /path/to/sarif/file.sarif
   svacer sarif2 import --upload --store /tmp/sarif --include-contents /path/to/sarif/file.sarif


==== Использования флага <code>--resolver</code> ====
Пример экспорта с включением содержимого файлов в артефакты:
В случае, если исходные файлы лежат в иных локациях и простым образом указать <code>--base-dir</code> или <code>--uriBaseId</code> нельзя (допустим, пути Windows-specific а импорт идет на Linux), то пользователь может указать параметр <code>--resolver</code> с путем к файлу, где написана функция конверсии путей. Файл должен содержать Go функцию
  svacer sarif2 export --host localhost --user admin --password admin --include-contents --project bash --out /tmp/out.sarif


func ResolvePath (s string) (string, bool) {
При экспорте включается разметка предупреждений в пользовательские атрибуты (properties). Также включается информация об ID снимка, проекта и прочая дополнительная информация.
    // пользовательская логика преобразования пути. Возвращать "", false, если надо применить обычные правила
}


Функция обрабатывается в ходе импорта Sarif, для выполнения используется функционал https://github.com/traefik/yaegi Пользователь может использовать пакеты <code>fmt, regexp, strings</code>
Полный список опций может быть получен при выполнении команд:
  svacer sarif2 import --help
  svacer sarif2 export --help


==== Мэппинг severity ====
=== Генерация SARIF (deprecated) ===
Для задания правил отображения checker severity при импорте Sarif, пользователь может использовать флаг <code>--map-severity</code>. Флаг ожидает значение в виде строки в формате <code><sarif level|*>:<svacer level>,<sarif level>:<svacer level></code>
Поддерживается генерация файла в формате [https://sarifweb.azurewebsites.net SARIF], который может быть прочитан при помощи расширения Microsoft SARIF Viewer, GitHub или DefectDojo.
Итоговый файл содержит сопоставление внутренних значений критичности маркеров со значениями уровня SARIF по следующему правилу:
* Critical -> error
* Major -> warning
* Minor -> note
* Normal -> none


Пример:
При импорте результатов анализа в SARIF должны быть предоставлены данные для подключения к серверу, так как значения критичности маркеров берутся оттуда.
--map-severity note:minor,error:critical,*:major


==== Импорт трасс ====
Общие параметры для импорта:
Конструкции SARIF <code>сodeFlow</code> и <code>relatedLocations</code> импортируются в трассы в концепции Svacer.
* out-file, o — имя выходного файла или «-» для вывода в stdout
* scheme — печать примера схемы выходного файла SARIF
* include-contents — включать контент файлов, в которых обнаружены предупреждения


Location в исходных конструкциях SARIF должен содержать номер строки. Если location задан через offset, то при импорте может получится некорректная строка.
==== Генерация из .svres (deprecated) ====
При импорте из файла svres используются дополнительные параметры:
* svace — путь к исполняемому файлу svace
* svace-dir — интерпретировать путь, как путь к директории .svace-dir
* path_to_project_or_svace-dir — путь к директории проекта или к .svace-dir. Его можно не указывать, тогда в качестве пути к проекту будет использована текущая директория


=== Экспорт ===
Пример команды для генерации файла SARIF:
NAME:
    svacer sarif2 export - Export snapshot(s) to SARIF format
USAGE:
    svacer sarif2 export [command options] [arguments...]
OPTIONS:
    --ssl                    Connect to the server using https protocol (default: false)
    --ssl-ca-certs value      Trusted CA cert path. Example: /usr/local/certs/* , /usr/local/certs/ca.crt, /usr/local/certs/ca*.crt
    --user value              Valid user name
    --password value          Valid user password
    --host value              Valid host name with running svace history server (default: localhost) [$SVACER_HOST_NAME]
    --port value              Defines port for REST API (default: 8080) [$SVACER_API_PORT]
    --grpc value              Defines port for gRPC API (default: 3002) [$SVACER_GRPC_PORT]
    --ldap_server value      Server for LDAP authentication [$SVACER_LDAP_SERVER]
    --with-viewer-uri        Add hostedViewerUri property to results. Works only if server is running with --public-url option (default: false)
    --project value          Project name or ID. Default value is master
    --branch value            Branch name or ID (default: master)
    --snapshot value          Snapshot name or ID. Default value is latest snapshot (default: <latest>)
    --include-contents        Import/export artifact contents (source code) when it is available (default: false)
    --out value, -o value    Set explicit output filename (or "-" for stdout)
    --comment-template value  [DEPRECATED]Set sarif result comments template
    --single-code-flow        Generate SARIF report with single code flow (default: false)
    --with-taxonomies        Generate SARIF report with taxonomies (default: false)
    --help                    Show help (default: false)


Полный список опций может быть получен при выполнении команд:
    ./svacer sarif -o <path_to_result_file> --svace <path_to_svace> [path_to_project_or_svace-dir]
  svacer sarif2 import --help
  svacer sarif2 export --help


Пример экспорта с включением содержимого файлов в артефакты:
==== Генерация из данных с сервера ====
  svacer sarif2 export --host localhost --user admin --password admin --include-contents --project bash --out /tmp/out.sarif
При импорте из данных с сервера используются следующие дополнительные параметры:
* from-server — опция для получения данных с сервера
* project — имя или id проекта
* branch — имя или id ветки (master по умолчанию)
* snapshot — имя или id снимка (last по умолчанию)


Экспорт в SARIF включает дополнительные данные в <code>properties</code> объект у соответствующего SARIF объекта. Дополнительные данные состоят из:
Также, для корректного получения необходимого проекта, должен быть указан пользователь, у которого есть доступ к этому проекту.


* информация о проекте, ветке и снимке
Пример команды для генерации файла SARIF из данных с сервера:
* информация о разметке (статус, severity, action, кем была выполнена и дата)
* информация о детекторе (severity, reliability, warnClass и прочая информация)
* дополнительные поля от маркера (mtid, invariant, function и т. д.)
* тэги (метки)
* комментарии


Для генерации <code>fingerprints</code> используется <code>invariant</code> маркера. Для генерации <code>partialFingerprints</code> используется поле <code>details</code> у маркера.
    ./svacer sarif -o <path_to_result_file> --from-server --user <user> --password <password> --project <project_name>


Трасса отображается в <code>codeFlows</code>.
=== Загрузка на сервер из SARIF (deprecated) ===
При загрузке данных на сервер используются следующие параметры:
* read-file, r — файл SARIF, из которого необходимо читать данные
* project — название проекта на сервере (по умолчанию совпадает с именем файла)
* branch — название ветки на сервере (по умолчанию master)
* snapshot — название снимка на сервере (по умолчанию время загрузки)
* skip-source — пропускать исходный код файлов с предупреждениями
* path-prefix — заменять префиксы в названии файлов (prefix:replacement)


В качестве <code>logicalLocations</code> используется поле <code>function</code>.
Пример команды для загрузки на сервер:


==== Оценка размера экспортированного файла ====
    ./svacer sarif upload -r <input_file>
Снимок с примерно 34 тысячами предупреждений, содержащий разметку и комментарии для ядра Linux при экспорте с включением исходного кода производит SARIF файл размером 450Мб (в сжатом виде получается порядка 70Мб).

Revision as of 13:09, 4 June 2024

Работа с SARIF

SARIF2

Начиная с релиза 8.0.0 добавлена команда sarif2 с подкомандами import и export. Рекомендуется использовать данную функциональность вместо старой команды sarif. Новый импорт обеспечивает создание детекторов в Svacer из reporting descriptor-ов в sarif, что обеспечивает корректную работу фильтров. Новая функциональность импорта поддерживает большую часть опций, которые могут быть использованы при импорте svres-файлов.

Пример импорта c включением содержимого файлов (при наличии его в самом sarif-файле или возможности найти файл в процессе импорта): 

 svacer sarif2 import --store /tmp/sarif --include-contents /path/to/sarif/file.sarif

Если sarif файл содержит относительные пути, то можно указать опцию --base-dir для поиска файлов относительно указанной директории.

Далее полученный intermediate store можно загрузить командой upload как и для импорта svres. Также можно скомбинировать import с upload: 

 svacer sarif2 import --upload --store /tmp/sarif --include-contents /path/to/sarif/file.sarif

Пример экспорта с включением содержимого файлов в артефакты: 

 svacer sarif2 export --host localhost --user admin --password admin --include-contents --project bash --out /tmp/out.sarif

При экспорте включается разметка предупреждений в пользовательские атрибуты (properties). Также включается информация об ID снимка, проекта и прочая дополнительная информация.

Полный список опций может быть получен при выполнении команд: 

 svacer sarif2 import --help
 svacer sarif2 export --help

Генерация SARIF (deprecated)

Поддерживается генерация файла в формате SARIF, который может быть прочитан при помощи расширения Microsoft SARIF Viewer, GitHub или DefectDojo. Итоговый файл содержит сопоставление внутренних значений критичности маркеров со значениями уровня SARIF по следующему правилу:

  • Critical -> error
  • Major -> warning
  • Minor -> note
  • Normal -> none

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

Общие параметры для импорта:

  • out-file, o — имя выходного файла или «-» для вывода в stdout
  • scheme — печать примера схемы выходного файла SARIF
  • include-contents — включать контент файлов, в которых обнаружены предупреждения

Генерация из .svres (deprecated)

При импорте из файла svres используются дополнительные параметры:

  • svace — путь к исполняемому файлу svace
  • svace-dir — интерпретировать путь, как путь к директории .svace-dir
  • path_to_project_or_svace-dir — путь к директории проекта или к .svace-dir. Его можно не указывать, тогда в качестве пути к проекту будет использована текущая директория

Пример команды для генерации файла SARIF: 

   ./svacer sarif -o <path_to_result_file> --svace <path_to_svace> [path_to_project_or_svace-dir]

Генерация из данных с сервера

При импорте из данных с сервера используются следующие дополнительные параметры:

  • from-server — опция для получения данных с сервера
  • project — имя или id проекта
  • branch — имя или id ветки (master по умолчанию)
  • snapshot — имя или id снимка (last по умолчанию)

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

Пример команды для генерации файла SARIF из данных с сервера: 

   ./svacer sarif -o <path_to_result_file> --from-server --user <user> --password <password> --project <project_name>

Загрузка на сервер из SARIF (deprecated)

При загрузке данных на сервер используются следующие параметры:

  • read-file, r — файл SARIF, из которого необходимо читать данные
  • project — название проекта на сервере (по умолчанию совпадает с именем файла)
  • branch — название ветки на сервере (по умолчанию master)
  • snapshot — название снимка на сервере (по умолчанию время загрузки)
  • skip-source — пропускать исходный код файлов с предупреждениями
  • path-prefix — заменять префиксы в названии файлов (prefix:replacement)

Пример команды для загрузки на сервер: 

   ./svacer sarif upload -r <input_file>
Retrieved from "https://svacer.ispras.ru/mediawiki/index.php?title=Help:Sarif&oldid=1927"