Help:ServerClient

Работа с сервером

Получение справки

Запустив Svacer без параметров, можно получить информацию о доступных командах. Дополнительная информация о каждой команде доступна при использовании опции --help

   svacer <command name> --help

Общий формат командной строки

   svacer [global options] command [command options] [arguments...]

Глобальные опции относятся ко всем командам. Опции команд имеют префикс «--». Их следует указывать до списка аргументов. Для команд с опцией --password доступна возможность ввода пароля с клавиатуры.

Процесс импорта

Процесс импорта результатов работы статического анализатора Svace состоит из двух шагов:

1. Дедупликация данных, предобработка, конвертирование во внутренний формат и сохранение результатов в промежуточном хранилище (svacer import).
2. Загрузка данных из промежуточного хранилища на сервер (svacer upload).

Промежуточное хранилище

Промежуточное хранилище используется для хранения результатов, подготовленных для загрузки на сервер. При импорте данных в промежуточное хранилище снимкам назначается уникальный ID, задается имя проекта и ветки. Промежуточное хранилище можно использовать для аккумулирования результатов нескольких запусков анализатора, в том числе для различных проектов. По умолчанию, промежуточное хранилище создается в директории .svacer-dir рядом с директорией .svace-dir. Параллельный доступ к хранилищу из разных экземпляров Svacer не допускается. Если необходимо использовать разделяемое хранилище и конкурентный доступ, Svacer следует запускать в режиме удаленного промежуточного хранилища. Процедура импорта c промежуточным хранилищем по умолчанию (размещается в <path to project>/.svacer-dir):

   svacer import --svace <path to svace> [path to project]

где <path to svace> — путь к исполняемому файлу svace из дистрибутива svace, [path to project] — путь к проекту (директории, содержащей .svace-dir). Его можно не указывать, тогда в качестве пути к проекту будет использована текущая директория.

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

   svacer import --store <path to store> --svace <path to svace> <path to project>

Пользовательские атрибуты

При импорте данных можно ассоциировать пользовательские строковые атрибуты со снимком. Значения атрибутов доступно посредством публичного REST API и интерфейса командной строки. Это позволяет связать дополнительные данные с результатами (например commit ID). Пользовательские атрибуты нельзя модифицировать после импорта данных на сервер. Пользовательские атрибуты экспортируются и импортируются как часть информации при использовании функциональности по экспорту и импорту снимков.

Пользовательский атрибут может быть передан при использовании команды import посредством опции --field <name>:<value>. Опция может быть указана несколько раз в командной строке.

   svacer import … --field f1:val1 --field f2:val2 …

Если одно и тоже поле указано несколько раз, то значения поля сохраняются как JSON массив строк. Допустимое имя пользовательского атрибута состоит из латинских букв, цифр, знаков подчеркивание или минуса.

Для получения списка всех пользовательских атрибутов в JSON виде используется следующая команда в командной строке

   svacer access --project <project name>  --branch <branch name> --snapshot <name or id> --user <user name> --password <password> custom_fields

Результат операции выдается как JSON объект в stdout. Объект имеет следующую структуру

   {
   "field name1":"value",
   "field name2": ["value", "value"..]
   } 

Для получения значения конкретного пользовательского атрибута используется следующая команда

   svacer access --project <project name>  --branch <branch name> --snapshot <name or id> --user <user name> --password <password> custom_fields --get <field name>

Значение атрибута выводится в stdout как JSON строка или массив.

Клонирование ветки

При импорте данных возможно клонирование ветки (вместе со снимками, разметкой и комментариями) из того же проекта, куда происходит импорт данных.

Для клонирования ветки следует использовать опцию --if-no-branch <value>

   svacer import ... --if-no-branch <value> ...

Значения, которые может принимать опция --if-no-branch:

• clone-{name|id} — клонировать ветку с заданным именем|id (по умолчанию clone-master)
• create-empty — создает пустую ветку
• return-error — возвращает ошибку, если для опции --branch <branch_name> не существует такой ветки с именем branch_name

Внимание: если не указать данную опцию, то будет автоматически клонироваться ветка master, поэтому для избежания ошибок следует убедиться, что ветка master существует, если данная опция не указана, иначе будет выведена ошибка.

Клонирование разметки и комментариев

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

Для клонирования разметки и комментариев следует использовать опцию --clone-review {name|id}

   svacer import ... --clone-review {name|id} ...

Данная опция принимает имя или id ветки, из которой необходимо склонировать разметку и комментарии.

Приоритет опции --clone-review выше, чем у опции --if-no-branch, поэтому возможно клонировать снимки из одного проекта, а разметку и комментарии из другого.

Если бранч с таким именем или id будет не найден, то возвращается ошибка.

Прикрепление файлов

При импорте данных возможно прикрепление файлов размером до 300Мб к снимку. Файлы будут доступны пользователю в веб-интерфейсе и посредством интерфейса командной строки. Прикрепленные файлы фиксируются в момент операции импорта и не могут быть модифицированы после загрузки на сервер. Удалить файлы может администратор посредством веб интерфейса. Основное назначение данной функциональности прикрепление некоторой иммутабельной информации к результатам анализа для использования в интеграциях со сторонними системами. Прикрепленные файлы являются частью данных, которые экспортируются и импортируются посредством функциональности экспорта и импорта снимков.

Для прикрепления файлов следует использовать опцию --attach <file name>

   svacer import … --attach file1.txt --attach file2.txt …

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

Для получения списка файлов из командной строки следует использовать команду

   svacer access --project <project name> --branch <branch name> --snapshot <name or id> --user <user name> --password <password> attachments --list

Результат работы команды представляет собой JSON массив объектов вида

   [{
       "id": 11,
       "snapshot_id": "d99c23f7-9fb9-4f4e-85ac-2539328947e0",
       "lid": 122885,
       "short_name": "Makefile",
       "description": "/home/ruseer/static-analysis/svacer/Makefile",
       "created_by": "importer",
       "updated_by": null,
       "create_ts": "2022-10-18T06:41:54.532925Z",
       "update_ts": null,
       "checksum": "9b1e02a276e810829ac2e38fb775c4ff8d269d0f44fd0fbae40f79a0320389ad"
   }]
   

Для получения содержимого файла из командной строки следует использовать команду

   svacer access --project <project name>  --branch <branch name> --snapshot <name or id> --user <user name> --password <password> attachments --get <id> <output file>

• Если <output file> не указан, то результат будет напечатан в stdout;
• Если <branch> не указан, то будет использован ветка master;
• Если <snapshot> не указан, то будет использован последний снимок на указанной ветке.

Загрузка данных на сервер

ВНИМАНИЕ: при загрузке данных на сервер, а также при прочих взаимодействиях клиента Svacer с сервером Svacer, крайне рекомендуется, чтобы версия клиента совпадала с версией сервера. В случае несовпадения версий возможны непредсказуемые ошибки.

Для загрузки данных из промежуточного хранилища на сервер используется команда upload:

   svacer upload --user <user> --password <pwd> --host <host> --port <rest_port> --grpc <grpc_port> <path_to_store>

Если отсутствуют параметры:

• --user и --password, то используется специальный системный пользователь importer — он предназначен для импорта данных на сервер;
• --host, то используется locahost;
• --port и --grpc, то используются их значения по умолчанию;

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

В случае если Svacer запущен с поддержкой SSL/TLS или работает за reverse proxy и доступен по протоколу HTTPS, то для загрузки требуется явно указать протокол в параметре --host, либо добавить опцию --ssl.

   svacer upload --host https://<url_without_port> <path_to_store>
   svacer upload --ssl --host <url_without_port> <path_to_store>

При этом grpc порт (по умолчанию — 3002), по которому идет загрузка данных, на сервере должен быть доступен.

Для информации о загрузке данных на сервер с авторизацией в LDAP см. Использование CLI сервера Svacer с поддержкой LDAP

При загрузке данных на сервер можно включить печать краткой статистики по загруженным результатам. Данная статистика включает информацию о новых и пропущенных предупреждениях, по сравнению с последним ранее загруженным снимком. Выдача краткой статистики возможно в текстовом или JSON виде. Результаты печатаются в stdout.

   svacer upload ... --quickStats --quickStatsFormat=text ...

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

   Quick Stats:
   Previous snapshot   : Snapshot 2022-11-16 10:11:37 +0300
   Current snapshot    : Snapshot 2022-11-16 10:23:08 +0300
   New                 : 1
   Missing             : 0
   Matched             : 1
   Same                : 0

   svacer upload ... --quickStats --quickStatsFormat=json ...

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

   {"branch":"391f21d1-2173-449c-9d1a-dd846d2a6471","snapshot":"34a1125d-86a3-45d3-9b41-cb5da24ab96e","snapshotName":"Snapshot 2022-11-21 10:19:06 +0300","lastSnapshot":"59657ae8-c3b6-48bc-b586-a6c0580cdb50","lastSnapshotName":"Snapshot 2022-11-21 10:18:09 +0300","same":2}

Формат JSON определяется protobuf3 схемой:

   message ImportSummaryContext {
     string branch = 1;
     string snapshot = 2;
     string snapshotName = 9;
     string lastSnapshot = 3;  
     string lastSnapshotName = 4;  
     int64 new = 5;
     int64 missing = 6;
     int64 matched = 7;
     int64 same = 8; 
   }

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

Переименование снимка после импорта

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

  svacer container snapshot rename --host <host> --port <port> --user <user name> --password <pwd> --id <snapshot id> --name <snapshot name>

Идентификатор снимка можно посмотреть в веб-интерфейсе или получить посредством public API.

Модификация путей в Review (разметке) при импорте

Обычное поведение

По умолчанию пути к файлам не меняются, за исключением пути к папки .svace-dir, он будет заменён на .build. Эту информацию можно увидеть при импорте проекта:

   svacer import --clean .svacer-dir
   ...
   info    The path prefix of .svace-dir 'C:\work\generate_files\gen_exp' will be trimmed when converting file paths
   ...

После этого все маркеры из этой папки и дочерних будут в Review показывать путь вида /.build/test500_1.c вместо полного пути для файла C:\work\generate_files\gen_exp\test500_1.c.

Использование --pathPrefix

При необходимости модификацию по умолчанию можно заменить через --pathPrefix. Значения опции передаются в виде:

   --pathPrefix "prefix_for_replace1:value1;prefix_for_replace2:value2…"

Поддерживается как передача данных сразу в опцию, так и через указание файла содержащего значения. Разумно делать замены для унификации вида проекта, собранного на разных машинах (или из разных папок). При использовании файла допустимо размещать каждую замену на отдельную строчку.

Префиксы путей заменяются только при полном совпадении (включая регистр, даже на Windows). Для указания двоеточия в префиксе пути используется удвоенное двоеточие, к примеру (для показа преобразований добавлено --debug):

   svacer --debug import --clean --upload --pathPrefix "C::\work:work" .svacer-dir
   ...
   INFO    Creating regular object store
   DEBUG   Creating path mapping rule 'C:\work' => 'work'
   DEBUG   Creating path mapping rule 'C:/work' => 'work'
   DEBUG   Creating path mapping rule '/C_/work' => 'work'
   ...

После импорта на сервере можно увидеть файл: /work/generate_files/gen_exp/test500_1.c

Использование --buildObject @auto

При импорте конкретного файла *.svres исходный код может быть загружен, при указании опции --buildObject @auto. В случае, если этот файл лежит в папке .svace-dir, исходный код будет взят из нее. При отсутствии папки .svace-dir файлы будут браться по абсолютным путям из файла *.svres. Для указания конкретных директорий поиска подходящих файлов из *.svres следует использовать опцию --source-tree, которую можно указать несколько раз, чтобы задать несколько корневых директорий. Поиск в этих директориях будет происходить только в случае, когда по путям из файла *.svres были найдены не все файлы. В случае успешного сопоставления, на сервер будут загружены соответствующие файлы из директории source tree.

Использование --fullPaths

Допустимо также полное отключение модификаций путей, для этого импорт надо производить с опцией --fullPaths. Опция блокирует как модификацию по умолчанию .build, так и явные указания через --pathPrefix.

   svacer --debug import --clean --upload --fullPaths .svacer-dir

После загрузки на сервере будет виден только полный путь: /C_/work/generate_files/gen_exp/test500_1.c.

Пути из Windows преобразуются в стиль Linux с небольшим преобразованием символов.

Вход в сервер

Для входа в браузере введите url-адрес сервера. Введите логин и пароль на странице ввода учетных данных. Учётные данные по умолчанию — admin / admin.

Страница ввода учетных данных

В случае конфигурации сервера в режиме поддержки протокола LDAP возможна аутентификация пользователей с помощью внешних серверов. При этом, если настроено более одного LDAP-сервера для авторизации, необходимо выбрать нужный из выпадающего списка.

Страница входа по протоколу LDAP

Примечание: чтобы после применения обновления системы в пользовательском веб-интерфейсе корректно отображались изменения необходимо после авторизации обновить страницу в браузере (нажать F5).

Профиль пользователя

В правом верхнем углу, при нажатии на имя пользователя, в выпадающем меню есть возможность выбрать Profile для редактирования своего профиля.

Переход в профиль пользователя

При нажатии пользователь имеет возможность изменить свои личные данные. В этот диалог также можно попасть через Settings > Profile.

Изменение профиля пользователя

Здесь пользователю доступно 3 вкладки: User profile, UI global settings, и Navigation panel settings.

Во вкладке User profile пользователь может изменить свои данные, все кроме логина. Во вкладке UI global settings предоставляется возможность установить пользовательские настройки. Они нужны, чтобы при обновлении страницы или при выходе и повторном входе под одним аккаунтом некоторые параметры не сбрасывались. Например, при включении Save filters, пользовательские фильтры не будут сбрасываться при обновлении страницы и при переходе с одних проекта/ветки/снимка на другие.

Общие настройки интерфейса

Вкладка Navigation panel settings позволяет настроить отображение файлов и критерий сортировки полей панели навигации Review > Files в левой части экрана. Данная вкладка является аналогом вкладки Navigation panel settings, доступной в панели навигации Review > Files. Данные настройки сохраняются для пользователя и не сбрасываются при новой сессии.

Настройки панели навигации

Настройка панели навигации позволяет указать в каком виде показывать пути к файлам и задать порядок сортировки по умолчанию.

Организации

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

На странице Settings > Organizations в таблице отображаются все организации, которые были добавлены в систему. Доступен поиск по имени организации и сортировка по колонкам Name и Short name.

Чтобы добавить новую организацию в реестр

1. Нажмите кнопку Add organization
2. Заполните поля появившейся формы
3. Нажмите кнопку Add

Чтобы изменить данные существующей организации

1. Нажмите кнопку в столбце Actions
2. В появившейся форме отредактируйте данные организации
3. Нажмите кнопку Save

Чтобы удалить организацию из реестра:

1. Нажмите кнопку в столбце Actions
2. В появившемся диалоге подтвердите удаление, нажав на кнопку Delete

Выбор проекта и снимка

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

Проект, ветка и снимок в интерфейсе

Пример выбранных проекта, ветки и снимка

Виды интерфейса

Сервер историй предоставляет несколько режимов работы интерфейса, каждый из которых предназначен для выполнения определённых действий:

• Review — просмотр и разметка найденных предупреждений, а также сравнение снимков или отдельных предупреждений;
• Browse Code — просмотр снимков исходного кода, связанного с результатами анализатора Svace;
• Reports — формирование отчетов на основе хранимой информации;
• Settings — управление сервером и просмотр его состояния;

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

Элементы управления в режиме разметки

Режим разметки предоставляет следующий набор элементов управления:

1. Левая группа панелей:

1) Панель Checkers — показывает список чекеров Svace, сработавших в выбранном снимке. При нажатии на один из них, будет установлен фильтр таблицы предупреждений на соответствующий checker/severity. Критичность (severity) чекера обозначается цветом при древовидном отображении и иконкой соответствующего цвета при отображении в виде списка.

Кнопкой Unset selection () пользователь может отменить фильтры, примененные из левой группы панелей.

Кнопкой Group by () пользователь может выбрать показ списка чекеров в виде дерева, группирующего чекеры по checker severity.

Панель Checkers. Данные в виде списка

Панель Checkers. Данные в виде дерева

2) Панель Files — показывает список файлов, для которых есть какие-либо предупреждения. Столбец ISSUES показывает число предупреждений в файле.

Панель Files

Действия, доступные на панели Files:

• клик на FILES или ISSUES — позволяет отсортировать столбцы по значениям;
• нажатие кнопок и позволяют добавить или удалить соответствующий файл в фильтре для просмотра предупреждений в таблице предупреждений;
• ввод в поле Filter files by full path имени файла или пути к нему — позволяет задать фильтрацию по имени/пути файла, также в этом поле поддерживается фильтрация по регулярным выражениям;
• нажатие кнопки позволяет настроить отображение файлов и критерий сортировки полей панели Files (см. раздел Профиль пользователя).

3) Пользовательские фильтры влияют на левую группу панелей.

2. Центральная группа элементов:

1) Таблица предупреждений [1]:

Панель и таблица предупреждений

Эта таблица является основным элементом для работы с предупреждениями.

Действия, доступные в таблице:

• выбор предупреждений для групповой разметки;
• выбор активного предупреждения — двойной клик на строке в любом столбце или одинарный клик на имени файла в столбце File;

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

2) Панель предупреждений [2]

Информация и действия, доступные на панели:

• число отображаемых в таблице предупреждений;
• фильтрация предупреждений:

• комплексная фильтрация предупреждений — Filters > Custom;
• Отменить пользовательские фильтры — Filters > Unset custom filter

(доступно, если применен пользовательский фильтр);

• Отменить все фильтры — Filters > Unset all filters

(доступно, если применен любой фильтр);

• Применить сохраненный фильтр — Filters > Saved

(выбрать из существующих);

• показ только предупреждений с разметкой — Show markers with non-default status, severity or action;
• выгрузка отображаемых предупреждений в формате .csv и выгрузка отчета отображаемых предупреждений в формате PDF;
• групповая разметка выбранных предупреждений (подробнее в разделе Групповая разметка предупреждений);
• поиск предупреждений — ввод значения в поле query (поддерживается использование метасимволов * и ?).

Фильтры предупреждений

Выгрузка предупреждений

3) Панель с кодом и информацией о снимке:

Панель с кодом и информацией о снимке

Эта панель предоставляет информацию о снимке и показывает положение предупреждения в исходном коде.

Кнопка Hide Table позволяет скрыть таблицу и развернуть панель с кодом на всю среднюю панель.

В части панели с кодом секция с информацией о предупреждении содержит кнопки, которые позволяют разметить открытое предупреждение.

3. Правая группа панелей.

Эта группа предоставляет дополнительную информацию о предупреждении: статус блокировки предупреждения, статус разметки, кто последний размечал предупреждение и многое другое. Здесь пользователю предоставляется возможность разметить предупреждения, добавить комментарии и просмотреть трассу предупреждения.

Правая группа панелей

Доступные действия:

• Отображение исходного кода в панели Source code — доступно по клику на ссылку с именем файла и номером строки; Это позволяет всегда вернуться к нужной точке при навигации по коду;
• Отображение информации (если доступна) о выбранном чекере — доступно по клику на имени чекера в закладке Details;

Информация о чекере

• предпросмотр кода, который соответствует строке трассы предупреждения, в отдельном окне доступно по клику на иконку ;

Окно предпросмотра кода трассы

• разметка предупреждения с помощью кнопок разметки;

Кнопки разметки предупреждения

Разметка предупреждения заключается в установке статуса (Confirmed, Won’t fix, False positive, Unclear) и опциональной установки Severity и Action (доступно только после установки Status).

• просмотр истории изменения разметки предупреждения доступно по нажатию кнопки ;

История изменения разметки предупреждения

Групповая разметка предупреждений

Для групповой разметки:

1. Выделите одно или несколько предупреждений.

2. Нажмите кнопку Review markers group (кнопка становится активной, только если есть выбранные предупреждения).

Кнопка «Review markers group»

Отобразится окно для групповой разметки:

Окно для групповой разметки. Начальное состояние

3. Разметьте выбранные предупреждения. Отображаемые в окне предупреждения окрашиваются в соответствующий цвет. Например, если пользователь поставил статус проверки Confirmed, то все предупреждения окрасятся в красный цвет.

Пример размеченных предупреждений. Установлен статус проверки Confirmed.

4. Добавьте общий комментарий для выбранных предупреждений.

После того, как пользователь разметил и (или) написал комментарий, станут доступными кнопки Reset (Сбросить) и Apply (Применить).

Окно для групповой разметки с кнопками

5. Если требуется отменить изменения, нажмите в правом верхнем углу окна или кнопку Cancel (Отмена). Диалоговое окно закроется и изменения не будут применены.

6. Если требуется сбросить все изменения, нажмите кнопку Reset. Данные в окне вернутся в первоначальное состояние, а кнопки Reset и Apply станут неактивными.

7. Нажмите кнопку Apply, чтобы сохранить изменения разметки и сбросить выбор в таблице предупреждений.

Таблица предупреждений после сохранения групповой разметки

Создание PDF отчета для проекта

Для создания PDF отчета по проекту из интерфейса командной строки используется команда pdfgen. Назначение команды состоит в том, чтобы добиться из консоли результатов (создание PDF файла отчета), аналогичным следующим действиям пользователя в GUI:

1. Выгрузка таблицы маркеров в формате PDF (Рис. 1)
2. Предварительное формирование содержимого таблицы маркеров
   • По режимам сравнения (new, missing, same, matched) с указанием цели и источника сравнения, (Рис. 2)
   • По используемым фильтрам Custom (ограниченный набор из 4 параметров) (Рис. 3)

Ниже приводятся фрагменты GUI, которым соответствует cli команда в различных вариантах ее использования:

Рис. 1 — Отчет без сравнения

Рис. 2 — Отчет со сравнением

Рис. 3 — Отчет со сравнением и фильтрами

Общий вид команды следующий:

   svacer pdfgen —cmpMode [none|new|missing|matched|same] --project [name|id] -- branch [name|id] --snapshot [name|id] [--targetProject [name|id] --targetBranch [name|id] --targetSnapshot [name|id]] [--file [re_exp] —checker [re_exp] --severity [re_exp] --review [re_exp]] --outFile report_name --tz time_zone --lang report_lang

Описание параметров:

• cmpMode — параметры сравнения. Возможные значения: none — без сравнения, new — новые, missing — отсутствующие, matched — сопоставленные, same — одинаковые
• Project, Branch, Snapshot — параметры, описывающие снимок, отчет для которого требуется создать. В качестве значений могут использоваться как имена, так и идентификаторы соответствующих сущностей. Например: --project zstd --branch "7683ed6a-b838-4090-9945-10e148f94be3" --snapshot zstd_130
• targetProject, targetBranch, targetSnapshot — параметры, описывающие снимок, с которым необходимо провести сравнение (обязательные параметры для режимов cmpMode: new, missing, matched, same).
• File, checker, severity, review — параметры, задающие фильтры, применяемые к списку маркеров. Фильтры задают условия включения маркера в отчет. Значения фильтров задаются в формате регулярных выражений. В случае неверного формата, ошибочный фильтр не будет применяться и операция экспорта будет выполнена, как если бы фильтр не был указан. File — фильтр по пути к файлу, где был обнаружен маркер. Checker — фильтр по чекеру, предупреждение от которого было создано. Severity — серьезность сработавшего чекера. Review — статус разметки (confirmed, unclear и т.д.)
• outFile — имя создаваемого файла отчета. Если не будет указано расширение, будет добавлено расширение pdf
• tz — временная зона в минутах. Используется при формировании записи о комментариях, которые оставил пользователь, производивший разметку
• lang — язык, который будет использован в создаваемом отчете (en — английский, ru — русский)

Для создания отчета без использования режима сравнения, необходимо указать cmpMode в значение none (это значение используется по умолчанию). Для предварительного формирования таблицы маркеров с учетом сравнения, использовать значения cmpMode [new, missing, same, matched]. Названия этих режимов аналогичны названиями в GUI. При этом требуется указание как минимум одного параметра из списка: targetProject, targetBranch, targetSnapshot. Если какие-то параметры target* не указаны, они будут установлены в значение исходных (project → targetProject, branch → targetBranch, …). Сформированные на предварительном этапе маркеры, проходят механизм фильтраций (параметры: severity, file, review, checker), после чего происходит создание отчета.

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

URL — /api/public/exportPDF

Метод — POST

Тело запроса — формат JSON, имеет следующий вид:

   {
   "compare_mode": "new",
   "context":{
     "project": "zstd",
     "branch": "v13",
     "snapshot": "zstd_131"
    },
   "target_context":{
     "project": "zstd",
     "branch": "v13",
     "snapshot": "zstd_132"
    },
    "language": "en",
    "timezone": 180,
    "filters": {
      "checker": "^Z.*$",
      "file": ".*example.*",
      "severity": "Cr.*",
      "review": "Conf.*"
    } 
   }

Данный запрос соответствует запросу на создание отчета, который получается в результате сравнения в рамках проекта zstd и ветки v13 двух снимков zstd_131 и zstd_132. При этом будут выбраны только новые маркеры. Среди выбранных останутся только те, что удовлетворяют условиям фильтров, а именно: чекер начинается с буквы Z, файл содержит слово example, серьезность чекера содержит подстроку Cr (что в силу ограниченного количества значений для данного фильтра соответствует значению Critical) в названии, а состояние разметки содержит подстроку Conf (что в силу ограниченного количества значений для данного фильтра соответствует значению Confirmed). Язык отчета — английский, часовой пояс — 180 минут (3 часа).

Использование регулярных выражений

Использование регулярных выражений для поиска и фильтрации доступно в левой панели на вкладке Files и в Filters > Custom > Files.

Особенности реализации:

• Поиск происходит только по регулярному выражению. При необходимости использования специальных символов как обычных их надо экранировать (например, точку: «\.»)
• Находятся вхождения подстроки в полном пути к файлу (также, как, к примеру, работает grep). При необходимости поиска по полной строке используйте символы начала/конца строки: ^ и $
• Поиск регистронезависимый (case insensitive)

В Filters > Custom > Files существует возможность применить фильтр как для отображения только предупреждений из файлов, подходящих под паттерн, так и для скрытия таких предупреждений. Для переключения между этими режимами нажмите кнопку «+»/«-», которая расположена рядом с полем ввода.

Примеры регулярных выражений:

1. Найти файлы с «sha» или «md5» где-либо в пути или в имени файла

   sha|md5

2. Отобразить только предупреждения из файлов с расширением .c

   .*\.c$

3. Скрыть предупреждения из файлов, имя которых начинается с символа «q» и которые имеют расширения .с или .сс

1) Используйте выражение /q[^/]*\.c$|/q[^/]*\.cc$

2) Нажмите кнопку «+» рядом с полем ввода, чтобы она отобразилась как «-».

4. Показать только предупреждения из файлов, которые имеют «string» в конце имени файла и с расширением из одного символа

   /.*string\..$

5. Скрыть предупреждения из файлов в директориях asn1 и pem

1) Используйте выражение /asn1/|/pem/

2) Нажмите кнопку «+» рядом с полем ввода, чтобы она отобразилась как «-».

6. Показать только предупреждения из файлов, которые имеют в имени три цифры подряд

   .*/.*[0-9]{3}[^/]*$

Где конструкция [^/]*$ означает, что после трех цифр и до конца строки может встречаться любой символ кроме /. Это позволяет исключить директории имеющие три цифры в названии.

Блокировка разметки

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

Для блокировки разметки используйте кнопку :

• на панели чекеров;

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

• на панели файлов;

В этом случае блокировка распространяется на все предупреждения в файле в выбранном проекте и ветке (для всех снимков из ветки).

• на панели разметки;

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

Для просмотра всех блокировок используйте панель Settings > Locks:

Панель Locks

Также на этой панели можно удалить свои блокировки. Пользователь admin может удалять любые блокировки.

Экспорт исходных кодов с разметкой (опционально) из снимка

Есть возможность экспортировать с сервера исходный код с разметкой (опционально) из снимка двумя способами:

1) Через UI в панели Snapshot information в строке ID нажать на кнопку Sources export

Экспорт кода с разметкой

Откроется диалоговое окно, где нужно будет выбрать шаблон для экспорта (по умолчанию None, т.е. разметка экспортироваться не будет) и опционально заполнить поля для удаления префиксов и исключения путей.

Диалог экспорта разметки

Пример удаления префиксов путей: "/.build/" чтобы убрать папку .build при экспорте. При экспорте можно исключить файлы, соответствующие регулярным выражениям в поле Exclude paths. В итоге создастся архив со всеми исходниками и, если был выбран шаблон разметки, то в исходном коде будет вставлена актуальная разметка, соответствующая выбранному шаблону.

2) Через консольную команду svacer markup export

Синтаксис команды:

   svacer markup --user <user> --password <password> --project <project id or name> --branch <branch id or name> --snapshot <snapshot id or name> export [--stripPrefixes <prefix1, prefix2, … , prefixN> --excludePaths <path1, path2, … ,pathN> --template <name>]

Где:

• user, password — пользователь и пароль учетной записи на сервере истории
• project — проект на сервере истории, из которого будет произведен экспорт
• branch — ветка в проекте выбранном выше (по умолчанию master), из которой будет произведен экспорт
• snapshot — снимок в выбранных проекте и ветке (по умолчанию последний загруженный), из которого будет произведен экспорт
• stripPrefixes, excludePaths — аналогичны полям «Удалить префиксы» и «Исключить пути» из формы экспорта разметки в UI, описанной выше
• template — определяет имя шаблона для экспорта разметки. Если имя не указано, разметка не экспортируется

Итогом будет либо создание директорий и файлов, соответствующих выбранному проекту на сервере истории и наполнение их исходным кодом, либо, если директории и файлы уже существуют, они будут перезаписаны. Наличие в файлах разметки в виде комментариев зависит от того, был ли выбран шаблон разметки.

Импорт разметки из исходного кода на сервер истории

Импорт разметки из исходного кода на сервер истории возможен с помощью команды svacer markup import.

Синтаксис:

   svacer markup --user <user> --password <password> --project <project id or name> --branch <branch id or name> --snapshot <snapshot id or name> import --template <name> [--excludePaths <path1, path2, … ,pathN> --from-build-object]

Где:

• user, password — пользователь и пароль учетной записи на сервере истории
• project — проект на сервере истории, в который будет произведен импорт разметки
• branch — ветка в проекте выбранном выше (по умолчанию master), в которую будет произведен импорт разметки
• snapshot — снимок в выбранных проекте и ветке (по умолчанию последний загруженный), в который будет произведен импорт разметки
• excludePaths — исключает файлы, соответствующие регулярным выражениям
• template — определяет имя шаблона для импорта разметки (важно: флаг обязательный, в отличие от экспорта)
• from-build-object — при включении этой опции, разметка будет выгружаться из объекта сборки того снимка, который был указан в опциях выше.

После выполнения команды все комментарии оставленные в коде в соответствии с выбранным шаблоном разметки будут разобраны и добавлены на сервер истории в соответствующий проект/ветку/снимок.

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

   //svacer_review: -<warn class>[|-<warn class>]+ 

Пример:

     if (!strncmp("--filelimit",argv[i],11)) {
       j = 11; //svacer_review: -UNUSED_VALUE
       if (*(argv[i]+11) == '=') {

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

Для импортирования разметки при использовании команд import --upload и upload следует указывать флаг --template <template>. В таком случае разметка будет импортирована из объекта сборки сразу после загрузки его на сервер.

Изменение инвариантов для распространения разметки между снимками, с несовпадающими путями

Если на сервер был загружен снимок, в котором расположение некоторых (или всех) файлов поменялось, а при импорте не был указан флаг --pathPrefix, то разметка с прошлого снимка не распространится на новый снимок. Для решения данной проблемы следует использовать команду svacer markup update.

Синтаксис:

   svacer markup update --user <user> --password <password> --project <project id or name> --branch <branch id or name> --pathPrefix <prefix:replacement; prefix:replacement> [<snapshot id or name>1, <snapshot id or name>2, …, <snapshot id or name>N]

Где:

• user, password — пользователь и пароль учетной записи на сервере истории
• project — проект на сервере истории, в котором будет обновлена разметка
• branch — ветка в проекте выбранном выше (по умолчанию master), в которой будет обновлена разметка
• pathPrefix — правило отображения для префиксов путей в формате: <file> или line prefix:replacement;prefix:replacement

В конце команды опционально могут быть указаны имена или идентификаторы снимков, в которых будет обновлена разметка в соответствии с указанными префиксами путей. Если они указаны не будут, изменения будут применены ко всей ветке. После запуска команды на сервер будет отправлен асинхронный запрос на обновление разметки, за дальнейшим прогрессом исполнения можно следить в логе сервера (через UI он доступен пользователям с ролью admin в Settings > Server information).

Подавление предупреждений

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

Список подавленных предупреждений (печатает JSON)

   svacer markup [auth/selection] suppress list

Пример:

   svacer markup --user admin --password admin --project tree-command suppress list

Подавить предупреждение

   svacer markup [auth/selection] suppress add id1 id2 id3

Пример:

   svacer markup --user admin --password admin --project tree-command suppress add 29d298cd-752d-4d19-b535-2089a72a96af

Убрать подавление предупреждения

   svacer markup [auth/selection] suppress remove id1 id2 id3 

Пример:

   svacer markup --user admin --password admin --project tree-command suppress remove 29d298cd-752d-4d19-b535-2089a72a96af

Убрать все подавления

   svacer markup [auth/selection] suppress remove

Пример:

   svacer markup --user admin --password admin --project tree-command suppress remove

Список предупреждений с ID доступен посредством public REST API. Функциональность предназначена для интеграции со сторонними инструментами и встраивание в CI/CD pipeline. На текущий момент информация о подавленных предупреждения недоступна в веб-интерфейсе.

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

Публичные REST запросы

Для работы с сервером через различные приложения реализованы публичные запросы, которые не будут меняться при обновлении самого сервера. Если будут происходить значимые изменения, то запрос будет помечаться как deprecated и создаваться новый такой же запрос с пометкой /api/some/request/v2.

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

• Простой способ — POST запрос с basic auth на /api/login, который вернёт JWT-токен в body. Использование данного способа не желательно, так как он может меняться в будущем, а также не всегда правильно обрабатывает спец. символы и кириллицу в логине/пароле. Пример:

curl -X POST -u admin:admin http://svacer.example.com/api/login

• Предпочтительный способ — POST запрос на /api/public/login с передачей данных в теле запроса. Пример:

curl -X POST -d '{"auth_type": "svacer", "login": "admin", "password": "admin"}' http://svacer.example.com/api/public/login

Полученный токен добавляется в заголовок (Header) всех запросов (Authorization: Bearer <token>).

Основные сущности сервера это:

• проекты (project) — идентифицируются по UUID
• ветка (branch) — идентифицируются по UUID
• cнимки (snapshot) — идентифицируются по UUID
• маркеры (markers) — идентифицируются по UUID
• пользователи (users) — идентифицируются по UUID

Публичные запросы

/api/public/projects	GET	Возвращает список всех проектов с веткими
/api/public/projects/{project_id}/branch/{branch_id}/snapshots	GET	Возвращает список всех снимков конкретной ветки. Необходимые ID можно получить из предыдущего запроса.
/api/public/projects/{project_id}/branch/{branch_id}/snapshots/{snapshot_id}/fullmarkers	GET	Возвращает полную информацию обо всех маркерах конкретного снимка. У запроса есть опция ?traces=true (по умолчанию false). Она добавит к каждому маркеру его трассу. Также доступна опция ?checker_info=true (по умолчанию false). Она добавит к каждому маркеру severity и reliability детектора, к которому относится этот маркер. Иногда значение checker_severity в ответе может отсутствовать, это происходит если Svacer не имеет информации об этом детекторе: возможно он был удален из Svace или в данной версии еще не добавлен в Svacer. Для получения полной истории о разметке предупреждения следует использовать опцию ?review_history=true
/api/public/diff?snapshot_v1=<id1>&snapshot_v2=<id2>&level=<number>	GET	Выполняет сравнение снимков с указанными id. Если snapshot_v2 отсутствует или пустой, то сравнение будет проведено с предыдущим снимком. Количество информации определяется переменной level: 0 — только общая информация со статистикой; 1 — статистика и id маркеров; >1 (default) — полная информация.
/api/public/users/current	PUT	Обновляет текущего пользователя. Нужно передать объект с такими же полями, как в запросе на добавление пользователя.
/api/public/snapshots/{snapshot_id}/markers/suppress	POST	Подавление предупреждений. Тело: { ids: ["id1", "id2", ...] rule: { /* any JSON object */ } } Поле ids задает список ID маркеров для подавления. Поле rule задает специфичное для пользователя правило, согласно которому данные маркеры подавляются.
/api/public/snapshots/{snapshot_id}/markers/unsuppress	POST	Отмена подавления предупреждений. Тело: { ids: ["id1", "id2", ...] } Поле ids задает список ID маркеров для отмены подавления.
/api/public/snapshots/{snapshot_id}/markers/suppressed	GET	Отмена подавления предупреждений. Возвращает список подавленных маркеров в виде JSON массива.
/api/public/snapshots/{snapshot_id}/custom_fields/{field_name}	GET	Получение пользовательского атрибута у снимка. Результатом является JSON строка или массив строк.
/api/public/snapshots/{snapshot_id}/custom_fields	GET	Получение всех пользовательских атрибутов у снимка в виде одного JSON объекта.
/api/public/markers?filters={filter_data}&traces={true/false}&checker_info={true/false}&review_history={true/false}	GET	Получение списка маркеров по всем проектам/веткам/снимкам с учетом указанных в фильтре условий. При наличии больших объемов данных желательно максимально конкретизировать запрос во избежание проблем с производительностью. Фильтр передается в base64 кодировке. Общий вид фильтра следующий: { project:{ name:"имя проекта (регулярное выражение)", id:"ID проекта (GUID)" }, branch:{ name:"имя ветки (регулярное выражение)", id:"ID ветки (GUID)" }, snapshot:{ name:"имя снимка (регулярное выражение)", id:"ID снимка (GUID)" }, marker:{ severity:"серьезность маркера (регулярное выражение)", file:"имя файла (регулярное выражение)", review:"статус разметки (возможные значения: Undecided, Confirmed, Won't fix, False Positive, Unclear)", checker:"имя маркера (регулярное выражение)" } } Данный вид фильтра используется также в других запросах, при этом некоторые секции могут не учитываться (исходя из смысла запроса; например, при запросе снимков, фильтр на маркер не используется). Секции project, branch, snapshot игнорируются в случае их явного наличия в адресной строке. При одновременном указании name и id используется всегда id. ID всегда указывается точным значением.
/api/public/snapshots?filters={filter_data}	GET	Получение списка снимков по всем проектам/веткам с учетом указанных в фильтре условий. Формат фильтра см. выше.
/api/public/projects/{project_id}/branch/{branch_id}/fullmarkers?flat={true/other}	GET	Возвращает все маркеры для ветки с заданным branch_id. Если опция flat = true, то результат возвращается как плоский массив маркеров со всеми данными (без структуризации по контейнеру и снимку). Маркеры возвращаются в виде: [ { container_id: "branch id", "snapshot_id": [ {marker data}, ... ] }, ... ]
/api/public/projects/{project_id}/fullmarkers?flat={true/other}	GET	Возвращает все маркеры для проекта с заданным project_id. Если опция flat = true, то результат возвращается как плоский массив маркеров со всеми данными (без структуризации по контейнеру и снимку). Маркеры возвращаются в виде: [ { container_id: "branch id", "snapshot_id": [ {marker data}, ... ] }, ... ]

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

/api/public/users/admin/list	GET	Возвращает список пользователей. У запроса есть опция "roles=true" (по умолчанию false). Она добавит к каждому пользователю его роли.
/api/public/users/admin/add	POST	Добавляет нового пользователя. Нужно передать объект с полями login (обязательное), password (обязательное), firstname, lastname, middlename, email, passChangeRequest.
/api/public/users/admin/{user_id}	PUT	Обновляет пользователя с переданным ID. Нужно передать объект с такими же полями, как в запросе на добавление пользователя.
/api/public/users/admin/{user_id}	DELETE	Удаляет пользователя с переданным ID.
/api/public/users/admin/{user_id}/status	PUT	Устанавливает пользователю с переданным ID статус переданный в объекте вида {status:<int>}, где 0 — архивный, а 1 — активный.
/api/public/roles/admin/list	GET	Возвращает список ролей.
/api/public/roles/admin/add	POST	Добавляет новую роль. Нужно передать объект с полями name (обязательное), permissions (обязательное), где permissions — это массив объектов с полями target (обязательное) и action (обязательное).
/api/public/roles/admin/{role_id}	PUT	Обновляет роль с переданным ID. Нужно передать объект с такими же полями, как в запросе на добавление роли.
/api/public/roles/admin/{role_id}	DELETE	Удаляет роль с переданным ID.
/api/public/users/admin/{user_id}/roles	PUT	Добавляет или убирает роли пользователю с переданным ID. Нужно передать объект с полями user_id (обязательное), roles (обязательное), где roles — это массив объектов с такими же полями, как в запросе на добавление роли. У запроса есть обязательный параметр "action=add/delete". Опция "add" добавит роль пользователю, а "delete" — уберет.
/api/public/users/current	PUT	Обновление профиля текущего пользователя (того, с чьим токеном авторизации мы обращаемся к API). В body передается JSON объект с полями, аналогичными запросу на добавление нового пользователя
/api/public/users/admin/{user_id}/status	PUT	Установка статуса пользователя. Body должно содержать JSON объект вида {status:<int>} где значение статуса 0 или 1. Где 0 — "архивный" пользователь (неактивен, не может зайти в сервер), 1 — активный пользователь.
/api/public/exportPDF	POST	Создание PDF отчета по проекту. См. Создание PDF отчета для проекта.
/api/public/generateURLs	POST	Создание URL для маркера. Принимает JSON объект с полями markers: ["id1", "id2", ...] — список ID маркеров для генерации URL location: "<url>" — базовый URL на каком виден Svacer с точки зрения клиента type: "short|full" — опциональный атрибут для генерации короткого или полного URL. По умолчанию создаются полные URL Результат работы команды — JSON объект с полями urls: ["url1", "url2", ...] — каждый URL соответствует ID маркеру в той же позиции во входных данных type: "short|full" — тип URL
/api/health	GET	Проверка доступности сервера. Возвращает Status 200 OK если сервер работает
/api/public/snaphots/{snapshot_id}/update	PUT	Переименование снимка. Принимает JSON объект с полем name, задающим новое имя для снимка. Возвращает 200 OK в случае успеха.
/api/public/login	POST	Аутентификация пользователя. Тело запроса имеет формат JSON и выглядит следующим образом: { "auth_type": "ldap", "server": "open_ldap", "login": "user", "password": "user", "role": "admin" } auth_type — тип аутентификации ("svacer" или "ldap") server — имя ldap сервера, как он указан в конфигурационном файле ldap (поле name) при старте сервера. Поле можно опустить в случае использования "svacer" аутентифкации role — роль, с которой будет работать пользователь login — имя пользователя password — пароль пользователя
/api/public/help	GET	Дополнительная информация по REST API. Работает без авторизации.

Не публичное API, которое в следующих релизах станет публичным (добавится префикс public)

/api/projects/admin/{container_id}/update

PUT

Метод переименовывает проект или ветку. Body должно содержать JSON объект с полем "name" и "id", где id должно соответствовать container_id, а container_id соответствовать ID ветки или проекта.