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.

  --quality-gate value            Specify a quality gate. Format: stat_1:severity_1:N_1:[statuses_1],...,stat_k:severity_k:N_k:[statuses_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; statuses - an optional field, specified in square brackets with a separator ";" possible values - confirmed, false_positive, wont_fix, unclear, undecided, when specifying statuses, the quality gate will be searched only for markers that have exactly these statuses, for example [confirmed;wont_fix;undecided]. 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.

Флаг принимает на вход тип предупреждений (stat), severity, их количество (N) и их статусы (statuses).

• stat задает тип предупреждений. Возможные значения:
  • new (присутствует в новом снимке, но отсутствует в старом)
  • missing (присутствует в старом снимке, но отсутствует в новом)
  • matched (присутствуют изменения в файлах не повлиявшие на выданное предупреждение)
  • same (одинаковые)
  • total (сумма всех вышеперечисленных)
• severity задается либо непосредственным его указанием (critical, major, normal, minor, undefined), либо all (все severity), либо частью имени детектора в формате postgres ILIKE https://www.postgresql.org/docs/current/functions-matching.html
• N - порог, после которого вызывается срабатывание. Не включает данное число (т.е. если указать 5, то при нахождении 6 и более вызывается срабатывание quality-gate)
• statuses - опциональное поле, в котором можно указать какие статусы (разметку) учитывать при нахождении предупреждений. Возможные значения confirmed, false_positive, wont_fix, unclear, undecided. Задаются в квадратных скобках с разделителем ";". Например, [confirmed;wont_fix]. Если не указать данное поле, то будут учитываться все статусы. Принципы учета статусов:
  • Если предупреждение размечено в новом снимке (значение не undecided), разметка берется из нового предупреждения
  • Если в новом снимке нет разметки у данного предупреждения, а в старом есть, то берется разметка из старого предупреждения
  • В остальных случаях у данного предупреждения разметка равна undecided.

Пример:

--quality-gate "total:critical:0:[confirmed;wont_fix],new:all:10"

Тогда опция сработает, если либо:

1) статическим анализатором будут найдены общее количество предупреждений (новых, пропущенных, одинаковых, измененных) с severity:critical и статусами confirmed и won't fix

2) статическим анализатором будут найдены новые предупреждения с любым статусом и severity

Пример вывода:

Quality gate exceed:
Previous snapshot   : Snapshot 2025-06-16 15:37:09 +0300
Current snapshot    : Snapshot 2025-06-16 15:37:39 +0300
Stat                : total
Severity            : Critical
Severity Statuses   : confirmed wont_fix
Severity Threshold  : 0
Found Severity      : 3

Также quality-gate можно задать файлом в формате json или yaml (не yml).

Пример json файла:

["total:all:1", "total:proc:1"]

Пример yaml файла:

 - "total:all:1"
 - "total:proc:1"

Флаг --quality-gate-exit-code

В случае срабатывания quality gate можно указать какой exit code будет возвращен

--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.

Принимает значения от 0 до 125 (по умолчанию 0)

Флаг --quality-gate-verbose

Если необходимо выводить информацию и об успешно прошедших quality gate, то нужно добавить флаг --quality-gate-verbose, тогда в конце будет вывод успешно прошедших quality gate

Пример вывода:

Quality gate exceed:
Previous snapshot   : Snapshot 2025-06-16 15:37:39 +0300
Current snapshot    : Snapshot 2025-06-16 16:10:33 +0300
Stat                : total
Severity            : Critical
Severity Statuses   : confirmed wont_fix
Severity Threshold  : 0
Found Severity      : 3
The result of comparison of those who have completed quality gate:
Previous snapshot   : Snapshot 2025-06-16 15:37:39 +0300
Current snapshot    : Snapshot 2025-06-16 16:10:33 +0300
Stat                : new
Severity            : All
Severity Threshold  : 10
Found Severity      : 0

Флаг --baseline

Если сравнение необходимо проводить не с предыдущим снимком в этой же ветке, то можно указать флаг --baseline (также работает для флага --quick-stats)

 --baseline value                                                     A snapshot to compare (--quality-gate and/or --quick-stats). Format: {project}:::{branch}:::{snapshot} or {project}:::{branch} or {project} use UUID or name. By default, snapshot is the last added, branch is master. If the flag is not specified, then the comparison will be with the latest snapshot from the branch where the snapshot is loaded.

Указывается в формате {project}:::{branch}:::{snapshot} или {project}:::{branch} или {project}, используя имена или UUID. По умолчанию используется ветка master (если указан только проект) и последний добавленный снимок (если снимок не указан).

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

• В текстовом формате добавляются строки об имени проекта, ветки и снимка, с которым сравнивался загружаемый снимок.
• В json формате добавляются имена и id проекта,ветки и снимка, с которым сравнивался загружаемый снимок.

Флаг --out-file

Для указания файла, в который необходимо загрузить результаты quality gate, используете опцию --out-file (по умолчанию вывод идет в stdout)

Флаг --out-format

Для указания в каком формате вывести результаты quality gate используйте опцию --out-format. Принимает значения text (человекочитаемый) и json. По умолчанию text

Экспорт

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Мб).