Help:Sarif

Работа с SARIF из CLI

Для импорта и экспорта результатов в формате SARIF Svacer предоставляет набор команд svacer sarif2 import и svacer sarif2 export.

Основные возможности данных команд

Импорт

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-файле или возможности найти файл в процессе импорта):

 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

Использования флага --resolver

В случае, если исходные файлы лежат в иных локациях и простым образом указать --base-dir или --uriBaseId нельзя (допустим, пути Windows-specific а импорт идет на Linux), то пользователь может указать параметр --resolver с путем к файлу, где написана функция конверсии путей. Файл должен содержать Go функцию

func ResolvePath (s string) (string, bool) {
    // пользовательская логика преобразования пути. Возвращать "", false, если надо применить обычные правила
}

Функция обрабатывается в ходе импорта Sarif, для выполнения используется функционал https://github.com/traefik/yaegi Пользователь может использовать пакеты fmt, regexp, strings

Мэппинг severity

Для задания правил отображения checker severity при импорте Sarif, пользователь может использовать флаг --map-severity. Флаг ожидает значение в виде строки в формате <sarif level|*>:<svacer level>,<sarif level>:<svacer level>

Пример:

--map-severity note:minor,error:critical,*:major

Импорт трасс

Конструкции SARIF сodeFlow и relatedLocations импортируются в трассы в концепции Svacer.

Location в исходных конструкциях SARIF должен содержать номер строки. Если location задан через offset, то при импорте может получится некорректная строка.

Использование quality gate

Смотрите секцию про quality gate в документации по импорту.

Экспорт

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 sarif2 import --help
 svacer sarif2 export --help

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

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

Экспорт в SARIF включает дополнительные данные в properties объект у соответствующего SARIF объекта. Дополнительные данные состоят из:

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

Для генерации fingerprints используется invariant маркера. Для генерации partialFingerprints используется поле details у маркера.

Трасса отображается в codeFlows.

В качестве logicalLocations используется поле function.

Оценка размера экспортированного файла

Снимок с примерно 34 тысячами предупреждений, содержащий разметку и комментарии для ядра Linux при экспорте с включением исходного кода производит SARIF файл размером 450Мб (в сжатом виде получается порядка 70Мб).