Svacer Wiki - User contributions [en]

Help:CLI

2025-11-20T12:36:36Z

Writer: Add Edit_markers

== CLI features ==
=== Перенос снимков ===
Svacer предоставляет возможность по экспорту и импорту снимков посредством интерфейса командной строки и [[Help:UI manual#Работа со снимками|веб-интерфейса]]. Экспорт снимка включает все предупреждения, информацию о снимке, прикрепленные файлы, объект сборки, пользовательские атрибуты, разметку и комментарии. Подавленные предупреждения также включаются в экспортированную информацию и импортируются в статусе подавленных.

Экспорт и импорт снимков из командной строки доступен пользователям с [[Help:UI manual#Описание ролевой модели|соответствующими правами]] для выбранного проекта/ветки.

Экспорт снимков:
svacer server export
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--snapshot <snapshot name or id>
<output file name>

Импорт снимков:
svacer server import
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--name <new name for snapshot>
[--force]
<input file name>

Опция '''--force''' создаст проект и ветку, если их не было на сервере.

=== Создание PDF отчета ===
Для создания PDF отчета по проекту из интерфейса командной строки используется команда '''pdfgen'''.

Общий вид команды следующий:
svacer pdfgen --cmp-mode [none|new|missing|matched|same] --project [name|id] --branch [name|id] --snapshot [name|id] [--target-project [name|id] --target-branch [name|id] --target-snapshot [name|id]] [--file [re_exp] --checker [re_exp] --severity [re_exp] --review [re_exp]] --out-file 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
* '''target-project, target-branch, target-snapshot''' — параметры, описывающие снимок, с которым необходимо провести сравнение (обязательные параметры для режимов cmpMode: new, missing, matched, same).
* '''file, checker, severity, review''' — параметры, задающие фильтры, применяемые к списку маркеров. Фильтры задают условия включения маркера в отчет. Значения фильтров задаются в формате регулярных выражений. В случае неверного формата, ошибочный фильтр не будет применяться и операция экспорта будет выполнена, как если бы фильтр не был указан. File — фильтр по пути к файлу, где был обнаружен маркер. Checker — фильтр по чекеру, предупреждение от которого было создано. Severity — серьезность сработавшего чекера. Review — статус разметки (confirmed, unclear и т. д.)
* '''out-file''' — имя создаваемого файла отчета. Если не указано расширение, будет добавлено расширение pdf
* '''tz''' — временная зона в минутах. Используется при формировании записи о комментариях, которые оставил пользователь, производивший разметку
* '''lang''' — язык, который будет использован в создаваемом отчете (en — английский, ru — русский)

Для создания отчета без использования режима сравнения, необходимо указать cmpMode в значение none (это значение используется по умолчанию).

Для предварительного формирования таблицы маркеров с учетом сравнения, использовать значения cmpMode [new, missing, same, matched]. Названия этих режимов аналогичны названиями в GUI. При этом требуется указание как минимум одного параметра из списка: target-project, target-branch, target-snapshot. Если какие-то параметры target* не указаны, они будут установлены в значение исходных (project -> target-project, branch -> target-branch, ...). Сформированные на предварительном этапе маркеры, проходят механизм фильтраций (параметры: 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 часа).

=== Импорт разметки из исходного кода ===
Импорт разметки из исходного кода на сервер истории возможен с помощью команды '''svacer markup import''', или с помощью CLI/REST API [[Markup2]].

Синтаксис:
svacer markup --user <user> --password <password> --project <project id or name> --branch <branch id or name> --snapshot <snapshot id or name> import --template <name> [--exclude-paths <path1, path2, ..., pathN> --from-build-object]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в который будет произведен импорт разметки
* branch — ветка в проекте выбранном выше (по умолчанию master), в которую будет произведен импорт разметки
* snapshot — снимок в выбранных проекте и ветке (по умолчанию последний загруженный), в который будет произведен импорт разметки
* exclude-paths — исключает файлы, соответствующие регулярным выражениям
* 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>'''. В таком случае разметка будет импортирована из объекта сборки сразу после загрузки его на сервер.

==== Шаблон разметки DEFAULT ====
Сервер позволяет добавить собственные шаблоны разметки, для удобства добавлен неудаляемый шаблон DEFAULT. Список шаблонов можно увидеть в '''Settings > Markup templates''' (при наличии прав доступа).

Шаблон можно использовать как для импорта, так и для экспорта разметки, поэтому можно проверить ожидаемый формат через [[Help:UI manual#Экспорт кода с разметкой|выгрузку кода]] с указанием шаблона.

В шаблоне DEFAULT каждая разметка описывается на отдельной строчке перед маркером, при необходимости можно использовать несколько строчек. Импорт разметки с неправильным статусом или со статусом Undecided не производится, включая комментарии к ней.

Пример:

//svacer_review: FORMAT_STRING.PARAM_EXCESS r:Confirmed|s:Minor|a:Undecided|c:
//svacer_review: UNINIT.LOCAL_VAR r:Confirmed|s:Unspecified|a:Fix required|c:will be fixed
printf("v = %d", fl3(), i);

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

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

Синтаксис:
svacer markup update --user <user> --password <password> --project <project id or name> --branch <branch id or name> --path-prefix <prefix:replacement; prefix:replacement> [<snapshot id or name>1, <snapshot id or name>2, ..., <snapshot id or name>N]

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

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

=== Изменение инвариантов (--edit-markers) ===
При импорте снимка с использованием --edit-markers можно модифицировать маркеры более гибко, см [[Edit markers (command line)]]

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

Список подавленных предупреждений (печатает 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.
На текущий момент информация о подавленных предупреждениях недоступна в веб-интерфейсе.

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

=== Автомиграция разметки ===
В Svacer возможно настроить автомиграцию разметки с ветки на ветку (у пользователя должны быть права на администрирование сервера).

svacer server automigrate [command] [flags]

Существующие command:
* add — добавляет автомиграцию в соответствии с паттерном
* delete — удаляет автомиграцию
* show_config — показывает все заданные миграции (Config Table), их id, время создания и пользователя, который их создал
* show_automigrate — показывает таблицу всех существующих проектов и веток с которых и на которые происходят автоматические миграции (Automigrate Table)
* log — выводит список всех совершенных миграций (Done Automigrate Table)

Флаг '''pattern''', применяется для команд <code><add|delete|show_config|log></code>

* Для '''add''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:regEx — в [https://www.postgresql.org/docs/current/functions-matching.html#FUNCTIONS-SIMILARTO-REGEXP формате как для PostgreSQL]

* Для '''delete''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:Паттерн должен быть точно таким же, как он записан в Config Table

* Для '''show_config''': Паттерн автомиграции. Поиск будет происходить в следующем виде: <code>ILIKE "'%"+pattern+"%'"</code>

* Для '''log''': Флаг в формате <code>srcProjectId/srcBranchId=>receiveProjectId/receiveBranchId</code> или <code>srcProjectName/srcBranchName=>receiveProjectName/receiveBranchName</code> для вывода автомиграций с данным паттерном

Флаг '''id''', применяется для command <code><delete|show_automigrate></code> в формате uuid

* Для '''delete''': id для удаления автомиграции (из Config Table)

* Для '''show_automigrate''': id ветки/проекта или конфигурации для нахождения его в таблице автомиграций (Automigrate Table) и вывода автомиграций, где присутствует данный id

Флаг '''format''' — формат вывода таблицы. Применяется для command <code><show_config|show_automigrate|log></code>

* Для '''show_config''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:* no-id — вывод без config id
:Значения можно перечислить через запятую: <code>json,no-id</code>. По умолчанию — table.

* Для '''show_automigrate|log''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:По умолчанию — table.

Также возможно использовать POST запрос по адресу <code>/api/automigrate</code>. В теле передается json, с полями <code>action(not null), pattern, id</code>. Выполняется по тому же принципу, что и в CLI.

Принцип работы сервиса:
* При запуске сервера запускается сервис automigrate
* При занесении новой миграции, находит все миграции, подходящие под паттерн, и копирует разметку на них
* При удалении миграции, удаляет её из таблицы Config и удаляет из таблицы автомиграций
* '''Может''' копировать разметку с нескольких веток на одну, а также поддерживает цепочки и циклы автомиграций (например 1->2->3->1)

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

* Единственный случай, когда сервис не даёт выполнить действие — загрузка результатов Svace через CLI: upload, либо import с флагом --upload. В этом случае сервис выдает ошибку миграции и отменяет загрузку. Такое может произойти, когда имя данной ветки (в качестве to_branch) подходит под несколько паттернов.
* Копируется последняя примененная разметка

=== Аутентификация из переменных окружения ===
Пользователь может использовать следующие переменные окружения для выполнения аутентификации при использовании CLI
SVACER_AUTH_CREDS=login:password
SVACER_AUTH_TOKEN=token
В качестве токена нужно использовать токен, получаемый через REST endpoint <code>/api/public/login</code>

Также пользователь может задать переменную окружения SVACER_APP_KEY или передать в CLI ключ <code>--app-key</code> для указания ключа подписи выдаваемых сервером Bearer токенов. Это позволит избежать необходимости повторого логина в веб интерфейсе Svacer после его перезапуска. Кроме того, сторонее приложение также сможет выдавать Bearer токены для сервера Svacer, которые сервер будет рассматривать как подлинные.

=== Аутентификация с использование Personal Token ===
Svacer поддерживает работу с Personal Token для аутентификации. Для этого используется команда <code>svacer server token</code>

Команда позволяет:

* Создавать токены. Параметры <code>name</code>, <code>ttl</code> обязательны. TTL указывается в днях
svacer server token create --name token_name --ttl day_to_live --details more_info
* Просмотреть список созданных токенов
svacer server token list
* Удалить токен
svacer server token delete --id token_id
* Управлять токенами других пользователей (требуется наличие прав по управлению пользователями)

svacer server token list --user user_id_or_login — получение списка токенов пользователя
svacer server token admin delete --id token_id — удаление токена

Сейчас наложено единственное ограничение на создаваемые токены — нельзя с помощью такого токена создавать другие токены. Каждый пользователь может создавать токены также через public API: <code>/api/public/personal_token</code>. См. описание swagger.

Созданные токены можно в дальнейшем использовать в качестве значения переменной окружения <code>SVACER_AUTH_TOKEN</code>

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

svacer marker list --host host --user user --password password --project project_name_or_id --branch branch_name_or_id --snapshot snapshot_name_or_id

Вывод:
# warn file line review msg
1000 INVARIANT_RESULT /.build/subst.c 7080 Expression 'tl->word->flags | (1 << 21)' is always
true , which may be caused by a logical error
1001 DEREF_AFTER_NULL.LOOP /.build/execute_cmd.c 3327 After having been compared to NULL value at execut
e_cmd.c:3325, pointer 'l' is dereferenced at execu
te_cmd.c:3327.
1002 DEREF_AFTER_NULL.LOOP /.build/variables.c 2749 After having been compared to NULL value at variab
les.c:2656, pointer 'vc' is dereferenced at variab
les.c:2749.
1003 CHECK_AFTER_PASS_TO_PROC /.build/redir.c 1219 Variable 'redirector' was passed to function at re
dir.c:1215 by calling function 'fcntl' that can't
use negative values is checked for negative value
at redir.c:1219.

При указании флага <code>--out-format=json</code> вывод будет произведен в JSON формате:

[{"id":"e0ec7389-42a0-403c-9ce2-bfaa3bfa0228","file":"/.build/subst.c","function":"WORD_DESC * parameter_brace_expand_rhs()","line":7080,"locID":1000,"lang":"CXX","tool":"CSA","warnClass":"INVARIANT_RESULT","mtid":"CSA.INVARIANT_RESULT.1","msg":"Expression 'tl-\u003eword-\u003eflags | (1 \u003c\u003c 21)' is always true , which may be caused by a logical error","details":"811ed8f680ae9b540707436615348aed6d32ee93","flags":0,"invariant":"TBXA/IYVZKVlH6f19tiGsd3stuI"},{"id":"184b85bf-a63f-4187-b290-25a5950b3353","file":"/.build/execute_cmd.c","function":"select_query","line":3327,"locID":1001,"

=== Слияние снимков из CLI (экспериментальная опция) ===
Пользователь может объединить несколько снимков в один используя команду
svacer container snapshot merge --host host --user user --password password --branch target_branch --name target_snapshot_name --snapshot val1 --snapshot val2 --snapshot val3 ...
При указании снимков для слияния и целевой ветки, пользователь может использовать либо UUID объектов либо формат
целевая ветка: <project name>:::<branch name>
снимок: <project name>:::<branch name>:::<snapshot name>
При слиянии можно использовать снимки из разных проектов и веток. Пользователь должен иметь доступ на чтение ко всем снимкам и на запись для целевой ветки

=== Управление контейнерами ===
См. [[Help:CLI/management/containers]]

=== Управление пользователями и ролями ===
См. [[User Management (command line)]]

=== Автоматическое удаление снимков ===
См. [[Help:CLI/cleanup]]

== Svacer server features ==

=== Запуск с конфиг-файлом ===
svacer-server run --config config.yml

'''--config <value>''' — путь к файлу конфигураций в формате YAML (по умолчанию svacer.cfg)

=== Поддержка сквозной аутентификации ===
Svacer поддерживает сквозную аутентификацию через reverse proxy. Для этого используется опция proxy-mode. При включении этой опции есть возможность проходить аутентификацию (используя HTTP Basic Authentication) на reverse proxy сервере и использовать эти данные для аутентификации на сервере Svacer.

При включенном proxy-mode используется header с прокси '''Authorization Basic ...''', откуда Svacer берет имя пользователя и пароль, проверяет и аутентифицирует пользователя, если аккаунт с таким логином и паролем есть в БД пользователей Svacer.

Пример запуска сервера с поддержкой сквозной аутентификации:

svacer-server run --proxy-mode

=== Хуки ===
Для использования хуков при запуске сервера нужно указать опцию '''--hooks <path to JSON file>'''. Эта опция задаёт файл, содержащий описание хуков, которые пользователь может вызывать из web-интерфейса. Каждый хук соответствует процессу или скрипту, который сервер запускает при вызове соответствующей команды из web-интерфейса.

Формат файла описания хуков следующий:
{
"hooks": [
{
"id": "<id>",
"label": "<label >",
"target": "<target>",
"input": ["<param1>", "<param2>", ...],
"cmd": "<path to executable>",
"args": ["<arg1>", “<arg2>”, ...]
},
...
]
}

'''Параметры хуков '''
{| class="wikitable"
| style="width:100px;" | ''id''
| Идентификатор хука. Должен быть уникальным в файле
|-
| ''label''
| Имя команды, которую пользователь видит в web-интерфейсе
|-
| ''target''
| Место в UI, в которое будет добавлена команда. Сейчас поддерживается только одно значение — default. Оно соответствует вкладке Details на правой панели пользовательского интерфейса
|-
| ''input''
| Параметры, которые можно передать в запускаемый процесс, исходя из контекста вызова команды в web-интерфейсе. 
Поддерживаемые значения:
* markerID — UUID идентификатор маркера;
* branchID — UUID идентификатор ветки;
* snapshotID — UUID идентификатор снимка;
* projectID — UUID идентификатор проекта;
* url — URL маркера в web-интерфейсе, на котором была вызвана команда;
* marker — будет заменен на полное имя временного файла, содержащего сериализованное в JSON представление маркера, который включает в себя его трассу и информацию о разметке
|-
| ''cmd''
| Полный путь к процессу, который будет запущен. Не должен включать аргументы запуска
|-
| ''args''
| Аргументы, передаваемые в запускаемый процесс. Полный список аргументов запускаемого процесса состоит из списка <args> и списка значений, соответствующих полю <input>
|}

Типичный сценарий использования хуков — создание кейсов для выбранного предупреждения в системах отслеживания ошибок, таких как Jira или Gitlab. Примеры скриптов для этого можно найти на странице [[Примеры использования хуков]].

=== Ограничение числа запросов ===
Чтобы ограничить число запросов на сервер Svacer, перед запуском сервера определите переменную окружения со следующими параметрами

SVACER_SERVER_THROTTLE_PARAMS=limit,backlogLimit,timeout

* limit — число одновременных запросов
* backlogLimit — размер бэклога для запросов, которые нельзя обработать сейчас
* timeout — время ожидания запроса в бэклоге (формат 1m12s — duration)

Help:Installation

2025-11-19T08:29:16Z

Writer: /* Механизм интеграции с внешними системами посредством Webhook-ов */

== Установка и запуск ==
Для использования только клиента Svacer достаточно [[Svacer#Релизы|скачать исполняемый файл]] '''svacer''', или установить [[Help:Installation#Svacer|deb/rpm пакет]].

Сервер Svacer можно запустить в [[Help:Installation#docker compose|докере]] или из [[Help:Installation#deb/rpm|deb/rpm пакета]].

=== docker compose ===
Рекомендуемый и самый простой способ деплоя — развернуть сервер Svacer в докер-контейнерах, воспользовавшиcь [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose.yml] файлом:

<nowiki>curl -LO https://svacer.ispras.ru/extra/docker-compose.yml</nowiki>
docker compose up -d

После запуска контейнеров веб-интерфейс Svacer будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.

Для сборки своего докер-образа Svacer можете использовать [[Dockerfile]] в качестве референса.

Для указания других параметров сервера можете [[Help:Installation#Дополнительные параметры при запуске в docker-контейнере|переопределить команду запуска]] в docker-compose файле.

=== deb/rpm ===
==== PostgreSQL ====
{{Note|type=info|text=Disclaimer
* Рекомендуемая версия PostgreSQL — 15 и выше. С более старыми версиями корректная работа Svacer не гарантируется.
* Svacer требует эксклюзивного доступа к базе. Использование одной и той же базы для нескольких экземпляров Svacer может приводить к порче данных.}}

Для работы сервера Svacer установите PostgreSQL, следуя [https://www.postgresql.org/download/linux документации postgres]. Для RedHat-based OS нужно дополнительно установить пакет postgresql-contrib соответствующей версии.

Пример для Ubuntu 22:

sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
sudo apt install -y postgresql-17

Пример для Rocky Linux 9.4:

<nowiki>sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm</nowiki>
sudo dnf -qy module disable postgresql
sudo dnf install -y postgresql17-server postgresql17-contrib
sudo /usr/pgsql-17/bin/postgresql-17-setup initdb
sudo systemctl enable postgresql-17
sudo systemctl start postgresql-17

==== Браузер для PDF-отчетов ====
Для создания PDF-отчетов с использованием нового HTML-генератора установите браузер Google Chrome на машину, где запускается сервер Svacer. Рекомендуется устанавливать из официального репозитория, следуя [https://www.google.com/chrome/?platform=linux инструкции с сайта google].

{{Note|type=info|text=Рекомендуемые системные требования при генерации PDF-отчетов для больших проектов с использованием HTML-генератора: Intel Core i9, 64 GB RAM, SSD, видеокарта Nvidia}}

При запуске Svacer проверит доступность браузера для генерации PDF. Если он не установлен или генерация не работает, будет использован нативный генератор: менее продвинутый, но для него не нужен браузер. Можно явно включить использование нативного генератора, передав опцию <code>--pdf-generator=native</code> при запуске сервера Svacer.

При невозможности установить Google Chrome, например если нет пакета для вашего дистрибутива Linux, можно установить Chromium. Его пакет в репозиториях, в зависимости от вышей ОС, может называться <code>chromium-browser</code> или <code>chromium</code>. В некоторых случаях генерация с Chromium может не работать. Например, если Svacer установлен из deb-пакета, а Сhromium из snap (на Ubuntu он устанавливается именно так даже при использовании apt) и сервер Svacer запускается от отдельного системного пользователя, от которого Chromium не может запуститься. В этом случае установите Google Chrome, с ним генерация работает.

==== Svacer ====
На Debian-based OS добавьте apt-репозиторий и установите Svacer из него.

<nowiki>echo 'deb [signed-by=/usr/share/keyrings/ispras.gpg] https://repo.ispras.ru/apt /' | sudo tee /etc/apt/sources.list.d/ispras.list</nowiki>
<nowiki>curl -fsSL https://repo.ispras.ru/apt/key.asc | sudo gpg --dearmor -o /usr/share/keyrings/ispras.gpg</nowiki>
sudo apt update
sudo apt install -y svacer

На RedHat-based OS добавьте dnf-репозиторий и установите Svacer из него

<nowiki>curl -fsSL https://repo.ispras.ru/rpm/ispras.repo | sudo tee /etc/yum.repos.d/ispras.repo</nowiki>
sudo dnf install -y svacer

Для создания БД PostgreSQL запустите '''psql''' от учетной записи пользователя '''postgres'''

sudo su -l postgres
psql

И выполните следующие запросы:
create database svace;
create user svace with encrypted password 'svace';
grant all privileges on database svace to svace;
alter user svace superuser;

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

При использовании других значений нужно поменять параметры подключения к БД в файле '''/etc/default/svacer'''

SVACER_ARGS="--pg postgres://<user>:<password>@127.0.0.1:5432/<database>"

В этой же строке можно указать прочие аргументы для запуска сервера Svacer.

На Astra Linux необходимо в файле '''/etc/parsec/mswitch.conf''' установить параметр <code>zero_if_notfound: yes</code>, иначе при запуске Svacer будет ошибка подключения к БД вида

error obtaining MAC configuration for user "svace" (SQLSTATE 57P03)

После создания БД и конфигурации сервера Svacer запустить его можно следующими командами

sudo systemctl enable svacer
sudo systemctl start svacer

После чего проверить успешность запуска командой

systemctl status svacer

После запуска сервер будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.

=== Установка и запуск на Windows ===
PostgreSQL нужен только для сервера Svacer, для клиента не требуется.
* Скачайте установщик PostgreSQL для Windows: https://www.postgresql.org/download/windows
* Установите PostgreSQL, выбрав, как минимум, компоненты "PostgreSQL Server" и "Command Line Tools"
* Задайте и запомните пароль на шаге выбора пароля для суперпользователя
* Остальные параметры при установке можно оставить по умолчанию
* После установки PostgreSQL откройте консоль, перейдите в директорию, куда установили PostgreSQL, запустите его клиент с указанием пользователя "postgres" и авторизуйтесь с паролем, заданным во время установки
cd c:\Program Files\PostgreSQL\15\bin
psql -U postgres
* Запустится консоль управления PostgreSQL. Выполните в ней следующие команды, чтобы создать БД и пользователя для Svacer
create database svace;
create user svace with encrypted password 'svace';
grant all privileges on database svace to svace;
alter user svace superuser;
* Выйдите из консоли PostgreSQL
* Запустите '''svacer-server.exe''' из консоли с указанием параметров подключения к БД. Если при создании пользователя и БД PostgreSQL вы использовали для них имя по умолчанию 'svace', как в примере выше, то указывать данные для подключения к БД при запуске сервера не обязательно
svacer-server.exe run
* Если создавали пользователя или БД с другими именами, то при запуске сервера надо указать их явно
svacer-server.exe run --pg postgres://svacer_user:svacer_password@127.0.0.1:5432/svacer_database
* После запуска сервера его веб-интерфейс будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin

== Обновление ==
{{Note|type=reminder|text='''Перед обновлением настоятельно рекомендуется [[Help:Backup|делать резервные копии]]'''}}

Миграции схем БД PostgreSQL и object store происходят автоматически при обновлении на новую версию Svacer. Поэтому для обновления Svacer достаточно остановить сервер старой версии, запустить сервер новой версии, указав ему те же параметры БД и object store, и подождать, пока не пройдет обновление, после чего Svacer запустится как обычно. При больших объемах данных в БД это может занять существенное время, до нескольких часов. Прогресс можно отслеживать по логам сервера.

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

{{Note|type=warn|text=После запуска Svacer при обновлении обязательно дождитесь пока миграция БД завершится. Если прервать процесс во время миграции, принудительно остановив Svacer, база данных может оказаться в неконсистентном состоянии и придется восстанавливать данные из бэкапа.}}

=== Upgrade notes ===
==== 12-x-x ====
Рекомендуем обновить PostgreSQL до версии 15 или выше. С более старыми версиями корректная работа Svacer не гарантируется.

==== 11-x-x ====
Нет специфических рекомендаций по обновлению.

==== 10-x-x ====
Нет специфических рекомендаций по обновлению.

==== 9-0-0 ====
{{Note|type=reminder|text=При обновлении на эту версию рекомендуем не меньше 8GB RAM для корректности миграций}}

Базово, никаких обязательных ручных действий с базой данных или object store при обновлении на 9-0-0 не требуется. Описанные ниже шаги могут помочь увеличить производительность сервера Svacer или решить возможные проблемы.

'''1.'''

В версии 9-0-0 поменялся формат object store, поэтому при обновлении с предыдущих версий Svacer на 9-0-0 или выше будет запущена конвертация object store в новый формат. Конвертация сначала записывает новые данные, а потом, если все прошло успешно, удаляет старые. Из-за этого для конвертации нужно примерно в два раза больше свободного дискового пространства, чем занимает текущий object store. При больших размерах object store и медленном диске конвертация может занять много времени.

Конвертация запустится автоматически при обновлении на 9-0-0, но можно запустить вручную отдельно:

svacer-server kvconvert --from <path> --to <path>

Расположение object store в файловой системе описано в [[Help:Backup#Бэкап object store вручную|разделе про бэкапы]].

'''2.'''

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

delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

Если вы уже выполняли этот запрос при [[Help:Installation#8-0-0|обновлении на 8-0-0]], то второй раз запускать не обязательно.

'''3.'''

После обновления на версию 9-0-0 и завершения всех миграций БД (когда станет доступен веб-интерфейс) рекомендуем выполнить команду <code>VACUUM FULL</code> в PostgreSQL для очистки и оптимизации базы данных.

psql -h <postgres_host> -U <username> <svacer_database_name> -c 'VACUUM FULL;'

Например:

psql -h localhost -U svacer svacer_db -c 'VACUUM FULL;'

==== 8-0-0 ====
Если при обновлении на версию 8-0-0 и выше возникает подобная ошибка
Key (config_id, checker_id, languages, tools)=(4cd178ce-a2b2-4692-a45a-f84b145c807b, FB.ICAST_QUESTIONABLE_UNSIGNED_RIGHT_SHIFT, {JAVA}, {SpotBugs}) is duplicated
Это значит, что в БД есть дубликаты чекеров. Выполните следующий SQL-запрос в PostgreSQL-базе Svacer, чтобы удалить их:
delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

== Расширенная конфигурация ==

=== Настройки аутентификации в Svacer ===
В Svacer возможны три способа аутентификации пользователей

# Встроенный
# С помощью LDAP сервера
# Через утилиту oauth_proxy (по протоколу OIDC)
# Посредством Personal Access Token (PAT)

Ниже рассматривается настройка аутентификации посредством внутреннего механизма аутентификации. Для настройки LDAP, PAT или OIDC аутентификации см соответствующие разделы документации.

==== Настройка внутреннего механизма аутентификации Svacer ====

===== Настройка парольной политики внутреннего механизма аутентификации Svacer =====
Настройки параметров встроенного механизма аутентификации возможны посредством секции '''auth.svacer''' конфигурационного файла Svacer. Ниже приведен пример настроек:<pre class="">auth:
svacer:
password:
min_length: 10
complexity:
- "[a-z]"
- "[A-Z]"
- "[0-9]"
- "[!#]"</pre>Параметр '''min_length''' задает минимальную возможную длину пароля в системе. Данный критерий используется при смене пароля пользователя и не влияет на текущие пароли пользователей.

Параметр '''complexity''' содержит набор регулярных выражений, задающих требования к паролю с точки зрения наличия в нем определенных символов. При задании такого списка выражений Svacer будет проверять задаваемый пользователем новый пароль на предмет удовлетворения всем этим требованиям. Каждое выражение в списке - полноценное выражение, поддерживаемое языком golang.

Указанные выше настройки применяются только к внутренним учетным записям пользователей Svacer. По умолчанию данные настройки отключены (нет требований на минимальную длину и сложность пароля)

===== Задание вкладки по умолчанию на странице входа в GUI Svacer (а также отключение внутренного механизма аутентификации Svacer) =====
В случае интеграции Svacer с LDAP, можно указать Svacer какую вкладку Svacer или LDAP использовать по умолчанию. Для этого используется параметр '''auth.svacer.default'''. Если данный параметр установлен в значение '''true''', то вкладкой по умолчанию - будет вкладка Svacer, иначе - вкладка LDAP.

Также возможно полностью отключить механизм внутренней аутентификации Svacer с помощью параметра '''auth.svacer.enabled'''.

Ниже приведен пример конфигурационного файла Svacer для задания вкладки LDAP по умолчанию (в случае наличие интеграции с LDAP сервером)<pre class="plaintext">auth:
svacer:
enabled: true
default: false</pre>

==== Настройка защиты от перебора паролей пользователей ====
Для случаев аутентификации с помощью LDAP сервера и с помощью встроенного механизма аутентификации реализован механизм блокировки учетных записей пользователей в том, случае если количество неудачных попыток входа превышает заданное в настройках число. По умолчанию защита отключена. Ниже приведен пример секции конфигурационного файла Svacer, задающего правила блокировки:<pre class="plaintext">security:
login:
max_attempts: 5
lock_time: 2m</pre>Время, на которое происходит блокировка учетной записи пользователя, указывается в формате golang/time: (1s,1m,60m и т.д.) .

В случае активации защиты данный механизм также защищает аутентификацию посредством вызовов соответствующих точек входа public API.

Блокировка не влияет на работу уже зарегистрированных пользователей.

Для принудительной разблокировки пользователей можно использовать команды cli (требуются права управления сервером):<pre class="">svacer user-provider unlock --user admin --password admin --login locked_user</pre>

=== Настройка TLS ===
Svacer может быть сконфигурирован для поддержки TLS несколькими способами. Первый способ — использовать reverse proxy с поддержкой HTTPS и проксированием в Svacer по HTTP, второй — запуск Svacer с нативной поддержкой TLS.

==== Reverse proxy ====
Данный способ позволяет обеспечить безопасную передачу данных только по протоколу HTTPS, данные по протоколу gRPC передаются в незащищенном виде.

===== Nginx =====
Создайте конфигурационный файл с подобным содержанием в '''/etc/nginx/sites-enabled/'''
<pre>
server {
listen 443 ssl;
listen [::]:443 ssl;

server_name svacer.ispras.ru;

# for large data transfers and continuous connections
client_max_body_size 0;
proxy_connect_timeout 600;
proxy_send_timeout 600;
proxy_read_timeout 600;
send_timeout 600;

# path to ssl-certificate and key
ssl_certificate /etc/ssl/certs/svacer.ispras.ru.crt;
ssl_certificate_key /etc/ssl/private/svacer.ispras.ru.key;

location / {
include proxy_params;

# to make WebSockets work
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

# svacer HTTP URL
proxy_pass http://127.0.0.1:8080;
}
}

# proxy gRPC port if required
server {
listen 13002 http2;
underscores_in_headers on;

location / {
grpc_pass grpc://127.0.0.1:3002;
}
}
</pre>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Nginx.
systemctl restart nginx

Если ваш сервер виден из интернета и его внешний IP-адрес привязан к доменному имени, можете использовать Let's Encrypt и Certbot для получения валидного SSL-сертификата. См. [https://www.nginx.com/blog/using-free-ssltls-certificates-from-lets-encrypt-with-nginx/ эту инструкцию].

===== Apache =====
Включите нужные модули в Apache
sudo a2enmod ssl proxy proxy_http rewrite

Создайте конфигурационный файл с подобным содержанием в '''/etc/apache2/sites-enabled/'''
<pre>
<VirtualHost *:443>
SSLEngine On
ProxyPreserveHost On
ProxyTimeout 600

# path to ssl-certificate and key
SSLCertificateFile /etc/ssl/certs/svacer.ispras.ru.crt
SSLCertificateKeyFile /etc/ssl/private/svacer.ispras.ru.key

# svacer HTTP URL
ProxyPass / http://127.0.0.1:8080/
ProxyPassReverse / http://127.0.0.1:8080/

# to make WebSockets work
ProxyPass /api/ws/ ws://127.0.0.1:8080/api/ws/
ProxyPassReverse /api/ws/ ws://127.0.0.1:8080/api/ws/
RewriteEngine on
RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC]
RewriteCond %{HTTP:CONNECTION} ^Upgrade$ [NC]
RewriteRule /api/ws/(.*) ws://127.0.0.1:8080%{REQUEST_URI} [P]

ServerName svacer.ispras.ru
ServerAdmin svacer@ispras.ru
</VirtualHost>
</pre>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Apache.
systemctl restart apache2

==== Нативно ====
Этот способ позволяет обеспечить безопасную передачу данных как по протоколу HTTPS, так и по протоколу gRPC. Если сервер запускается с поддержкой TLS, то эта опция относится как к протоколу HTTPS, так и к протоколу gRPC.
По умолчанию сервер запускается без поддержки TLS, при этом в логах отображается информация об этом.
TLS for REST and gRPC DISABLED

Для запуска сервера с поддержкой TLS необходимо указать сертификат сервера и соответствующий закрытый ключ.
svacer-server run --ssl-cert svacer.crt --ssl-key svacer.key

При этом ключ должен быть в незашифрованном виде. Права доступа к файлу должны быть 0600. В файле сертификата можно указывать цепочку сертификатов. В этом случае сервер, при подключении клиента, будет возвращать всю цепочку. Первым сертификатом в цепочке всегда должен идти сертификат сервера Svacer. Формат файла — PEM. TLS соединение активируется и для протокола REST и для протокола gRPC.

Работа сервера по проктолу TLS сопровождается следующей записью в логе:
Using TLS for REST and gRPC protocols

Работа с таким сервером через CLI происходит как обычно. Для указания необходимости подключаться по TLS можно явно указать протокол в параметре '''--host''', либо добавить опцию '''--ssl'''.
<pre>
svacer upload --host https://example.com
svacer upload --ssl --host example.com
</pre>
Также в клиенте можно определить параметр '''--ssl-ca-certs'''. Он позволяет задать доверенные сертификаты корневых центров. Указывается шаблон файлов (с *) или конкретный файл. Путь к директории должен быть абсолютным. В случае отсутствия этого параметра используется TLS, но сертификат сервера не проверяется. Этому случаю соответствует запись в логе клиента:
Using weak TLS configuration, because no CA certificate found

Если сертификаты были загружены, в логе будет строчка:
added 1 ca certs from /home/user/svacer/svacer.crt

Для администрирования сервера в плане используемого сертификата (например, замена при истечении срока действия) добавлена область в CLI svacer admin: '''server:config'''. В данной области есть 3 команды: '''show''', '''reload''', '''update'''. ID в этом случае нужно всегда указывать в значение '''ssl.cert'''.

* '''show''' — отображает текущий используемый сертификат

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action show</pre>

* '''reload''' — заставляет сервер перечитать использованные при старте сервера файлы с сертификатом и ключом

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action reload</pre>

* '''update''' — позволяет переслать на сервер новый сертификат (и ключ, если надо) и записать их в указанные при старте сервера файлы. При использовании этой команды нужно сформировать файл с новым сертификатом и, при необходимости, ключом, в формате PEM (используете '''cat''' для объединения сертификата и ключа в один файл) и указать этот файл в параметре value. Если в файле не будет указан закрытый ключ, то сервером будет использован текущий (тот, что был указан при запуске). Данная команда также изменит файлы сертификата и ключа (если он указан), указанные при старте сервера, на новые значения.

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action update --value svacer.pem</pre>

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

В конфигурационном файле Svacer можно указать минимальную и максимальные версии TLS, поддерживаемые сервером. Для этого необходимо в конфигурационном файле указать параметры <code>minVersion</code> и <code>maxVersion</code> в разделе security.tls.

<pre>
security:
tls:
minVersion: tls11
maxVersion: tls12
</pre>

=== Интеграция с хранилищем секретов Infisical ===
В Svacer реализована поддержка получения секретов из хранилища секретов [https://infisical.com/ Infisical]. Подробную информацию об интеграции см. в статье [[Infisical|Интеграция с хранилищем секретов Infisical]].

=== Механизм интеграции с внешними системами посредством Webhook-ов ===

==== Общий принцип работы ====

Механизм webhook-ов настраивается в конфигурационном файле в секции '''webhook'''. Механизм срабатывает при получении по внутренней шине одного из поддерживаемых событий Svacer. Каждое из внутренних событий преобразуется в событие вызова webhook-а (см. [[Help:Installation#Модель поддерживаемых событий|Модель поддерживаемых событий]]) и отправляется на обработку в каждую из настроенных целей, которыми являются http-обработчики. Отправкой занимаются работники (их количество настраивается в конфигурационном файле в параметре '''workers_count'''). У каждой цели есть общая очередь, размер которой составляет 500 событий. Если очередь переполняется, будет выдаваться соответствующее сообщение в лог-файле Svacer.

Работники поддерживают протокол https (в том числе самоподписанные сертификаты). Для указания корневого сертификата можно использовать параметр '''ca_certs''' конфигурационного файла. Работникам можно указать таймаут соединения с webhook-сервером (в мс, по умолчанию 1000мс, параметр '''timeout''') и количество попыток отправки (по умолчанию - одна попытка, параметр '''retry_count''').

В настройках можно указать фильтр на отправляемые события (параметр '''filter'''). Фильтр указывается посредством задания выражения. В выражениях используется синтаксис go-expr (см https://github.com/expr-lang/expr ). Фильтр возможно указать в количестве одной штуки на одну цель. Если фильтр после вычисления дает значение true, событие будет отправлено в цель.

Также реализован журнал событий отправки webhook-ов, размер которого может быть указан в конфигурационном файле (параметр '''journal_length'''). По умолчанию он равен 86400 записей - по 1 записи на каждую секунду суток. Журнал может быть использован для отладки механизма отправки событий в цель. Содержимое журнала хранится в памяти. При достижении журналом максимального размера, самые старые записи заменяются новыми. Для настройки аутентификации работника можно использовать параметр '''headers''', который представляет собой список значений вида '''key:value'''. Данные пары будут добавлены в заголовки каждого http-запроса, выполняемого работником.

==== Конфигурация ====

Возможный пример конфигурационного файла, в котором указана отправка на сервер test-host.local событий, связанных с разметкой маркера.

webhook:
enabled: true
journal_length: 86400
targets:
- url: "https://test-host.local:8080/webhook"
workers_count: 1
enabled: true
filter: "Type == EventReviewMarker and Payload.Status != 'Undecided'"
ca_certs: "/etc/ssl/certs/ca.crt"
retry_count: 3
timeout: 1000
headers:
- "password:12345"
- "Authorization: Bearer eyJh .... "

==== CLI ====

Для взаимодействия с механизмом webhook реализованы две cli команды:

<pre class="plaintext">svacer server webhook journal
svacer server webhook stat</pre>
Первая команда позволяет посмотреть записи журнала отправки событий. Вторая команда позволяет вывести статистику по работе службы (особенно интересными могут быть поля '''sendError''' и '''skip''')

Пример вывода для первой команды (с флагом '''--humanize'''; если флага нет - то будет вывод в формате json):

<pre class="plaintext">==================== #1 ======================
Time: 2025-07-01 12:25:52.25343534 +0300 MSK
Created by: admin
Error:
Success: true
SvacerKind: UpdateMarkerReview
EventType: EventReviewMarker
TargetURL: https://swarm-mgr.home:8080/webhook
ProcessTime: 6 ms
==================== #2 ======================
Time: 2025-07-01 12:25:54.202850322 +0300 MSK
Created by: admin
Error:
Success: true
SvacerKind: UpdateMarkerReview
EventType: EventReviewMarker
TargetURL: https://swarm-mgr.home:8080/webhook
ProcessTime: 3 ms
[01_07_2025-12:26:13] user@gp-6</pre>
Пример вывода команды статистики:

{
"enabled": true,
"targets": [
{
"enabled": true,
"url": "https://swarm-mgr.home:8080/webhook",
"filtered": 0,
"sendSuccess": 3,
"sentError": 0,
"submitted": 3,
"skip": 0
}
]
}
==== Модель поддерживаемых событий ====
syntax = "proto3";
import "google/protobuf/any.proto";
option go_package="svacer/proto/webhook";
package webhook;

enum EventType {
EventNone = 0;
EventTest = 1;
EventReviewMarker = 2;
EventPurgeReview = 3;
EventGroupReview = 4;
EventImportSnapshot = 5;
EventCopySnapshot = 6;
EventNewComment = 7;
EventUpdateComment = 8;
EventNewContainer = 9;
EventDeleteContainer = 10;
EventUpdateContainer =11;
EventImportMarkup = 12;
EventDeleteSnapshot = 13;
UpdateSnapshot = 14;
}

message MarkerDetails {
string id = 1;
string file = 2;
string line = 3;
string lang = 4;
}

message Event {
uint64 timestamp = 1;
EventType type = 2;
string created_by = 3;
google.protobuf.Any payload = 4;
}

message PayloadMarkerReview {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
repeated MarkerDetails markers = 7;
string comment = 8;
string severity = 9;
string action = 10;
string status = 11;
bool group_review = 12;
string created_by_id = 13;
string created_by_login = 14;
}

message PayloadPurgeReview {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string created_by_id = 5;
string created_by_login = 6;
}

message PayloadImportSnapshot {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
}

message PayloadMarkerComment {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
MarkerDetails marker = 7;
string comment = 8;
string created_by_id = 9;
string created_by_login = 10;
}

message PayloadCopySnapshot {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
string created_by_id = 7;
string created_by_login = 8;
}

message Container {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
Container source = 5;

}

message PayloadNewContainer {
repeated Container containers = 1;
}

message PayloadDeleteContainer {
repeated Container projects = 1;
repeated Container branches = 2;
}

message PayloadUpdateContainer {
Container container = 1;
}

message CopyResult {
uint64 total = 1;
uint64 applied_reviews = 2;
uint64 applied_comments = 3;
uint64 skipped_reviews = 4;
uint64 duplicate_reviews = 5;
uint64 duplicate_comments = 6;
}

message PayloadImportMarkup {
Container source=1;
Container target=2;
CopyResult copy_result =3;

}

message Snapshot {
string snapshot_id = 1;
string snapshot_name = 2;
Container container = 3;
}
message PayloadDeleteSnapshots {
repeated Snapshot snapshots = 1;
}

message PayloadUpdateSnapshot {
string snapshot_id = 1;
string snapshot_name = 2;
Container container = 3;
}

=== Выбор сетевых интерфейсов и портов сервера ===
* По умолчанию web-сервер запускается на всех сетевых интерфейсах, на порту 8080 ('''0.0.0.0:8080'''). Для указания конкретного сетевого интерфейса можно использовать опцию '''--listen <network interface>''', для указания другого порта: '''--port <port_number>.
* Аналогично для grpc-сервера: по умолчанию — '''0.0.0.0:3002''', для выбора конкретного интерфейса: '''--listen-grpc <network_interface>''', для указания другого порта: '''--grpc <port_number>'''.

svacer-server run --listen 127.0.0.1 --port 9090 --listen-grpc 127.0.0.1 --grpc 3004

При попытке запуска на порту < 1024 от непривилегированного пользователя (например, от пользователя svacer при установке из deb/rpm пакета), сервер Svacer не запустится с ошибкой

ERROR: port 443 is privileged, please check current user permissions or set another rest api port

В таком случае надо выдать capabilities на открытие привилегированных портов файлу сервера Svacer. Это нужно будет делать при каждом обновлении версии сервера

sudo setcap 'cap_net_bind_service=+ep' /usr/bin/svacer-server

=== Увеличение лимита открытых файлов ===
Актуально только для Linux.

Если проекты большие, или их много, в object store создается большое количество файлов. Для нормальной работы сервера Svacer при этом рекомендуется увеличивать системный лимит количества одновременно открытых файлов.

В POSIX таких лимита два:
* soft nofiles — текущее максимальное значение
* hard nofiles — общесистемное максимальное значение

В большинстве систем hard значение достаточно большое, а soft обычно маленькое, что и приводит к проблемам. Пример на Debian 11:

$ ulimit -Sn
1024
$ ulimit -Hn
1048576

Начиная с версии 6-0-0 Svacer пытается автоматически увеличить soft limit до значения hard limit при запуске, а начиная с версии 8-0-0 — проверяет, что увеличить удалось и выводит сообщение с текущим лимитом. Если видите в логах подобную запись — у soft и hard одно, достаточно большое значение — значит все в порядке.

Open files limit (soft and hard): 1048576

Для более ранних версий, или если на вашем дистрибутиве Linux это не работает автоматически, можете увеличить лимит вручную одним из следующих способов:

* Перед запуском Svacer выполнить из консоли команду, увеличив лимит для текущей сессии
ulimit -Sn 16384

* Либо один раз увеличить на уровне системы — в файл '''/etc/security/limits.conf''' добавить

* soft nofile 16384

* Если запускаете Svacer как сервис systemd, добавьте параметр '''LimitNOFILE''' в секцию '''[Service]''' файла описания сервиса.
:В файле из deb/rpm пакета релиза Svacer этот параметр уже добавлен

[Service]
LimitNOFILE=16384

После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer

sudo systemctl daemon-reload
sudo systemctl restart svacer.service

=== Установка пути к директории для кэша ===
Если запускаете Svacer под пользователем без домашней директории, рекомендуется установить путь к директории для кэша через переменную окружения SVACER_CACHE_DIR в файле описания сервиса systemd

[Service]
Environment="SVACER_CACHE_DIR=/path/to/some/dir"

После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer

sudo systemctl daemon-reload
sudo systemctl restart svacer.service

=== Дополнительные параметры при запуске в docker-контейнере ===
При запуске в докер-контейнере можно указать дополнительные параметры, к примеру добавить конфиг [[Help:CLI#Хуки|хуков]].

Для этого переопределите команду запуска сервера Svacer в docker-compose файле и допишите туда нужные параметры:

command: /svacer/bin/svacer-server run --store /data/store --pg postgres://svace:svace@postgresql:5432/svace --hooks /svacer/hooks.json

Конфигурационный файл с описанием хуков примонтируйте как volume:

volumes:
- ./hooks.json:/svacer/hooks.json

Можете использовать переменные из секции environment docker-compose файла, тогда в строке запуска их надо экранировать с помощью <code>$$</code> и запускать сервер Svacer как shell-команду, чтобы в контейнере подставились значения переменных

environment:
- SVACER_PG_URL=postgres://svace:svace@postgresql:5432/svace
- STORE=/data/store
- HOOKS_FILE=/svacer/hooks.json
volumes:
- ./hooks.json:/svacer/hooks.json
command: sh -c "/svacer/bin/svacer-server run --store $$STORE --pg $$SVACER_PG_URL --hooks $$HOOKS_FILE"

Для более комплексных сценариев можете собрать свой образ с сервером Svacer, использовав наш [[Dockerfile]] как референс.

== Обновление детекторов ==
После установки новой версии Svace требуется обновить описания детекторов в Svacer. Для этого необходимо выполнить команду:

svacer checkers --upload </path/to/svace>

{{Note}} Обновление описаний детекторов это серьезная операция, которая должна выполняться после предварительного тестирования. Поэтому перед выполнением команды рекомендуется сделать резервную копию базы данных Svacer.

== Генерация PDF на основе HTML ==
В релиз 10.х.х включена генерация PDF на основе рендеринга HTML с последующим запуском headless chrome/chromium для генерации PDF. Этот подход позволяет упростить формирование шаблонов для генерации PDF, но требует существенно больше вычислительных ресурсов. Для тюнинга числа параллельных процессов при генерации используется переменная окружения

SVACER_PDF_GEN_LIMITS=<pdf tool limit>:<chrome limit>

Первое значение <code><pdf tool limit></code> определяет число одновременных процессов pdfmerge для сборки отдельных секций в единый PDF документ; второе значение <code><chrome limit></code> определяет одновременное число процессов chrome/chromium для генерации PDF из HTML. Не рекомендуется ставить значения, сильно превышающие число ядер в сервере.

== Полнотекстовый поиск ==
Для поддержки полнотекстового поиска Svacer строит индекс. По умолчанию директория для индекса создается в <code>$HOME/.cache/svacer</code>, для указания иной директории можно использовать переменную окружения <code>SVACER_SEARCH_INDEX_DIR</code>

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

svacer search --host <nowiki>http://some_host:port</nowiki> --user <login> --password <pwd> --drop-cache

Используемая при этом учетная запись должна быть с правами на <code>Server administration</code>

== Указание public-url ==
В некоторых случаях необходимо явно указывать серверу Svacer его URL-адрес. Например, это нужно для корректной генерации коротких ссылок на предупреждения и ссылок в [[Notifications|уведомлениях]]. Используйте параметр <code>--public-url</code> при запуске сервера
<nowiki>svacer-server run --public-url http://svacer.intra.net:8080</nowiki>

Markup2

2024-12-24T10:58:36Z

Writer:

== Public REST API для экспорта, импорта и копирования разметки ==
Релиз 10.х Svacer включает новый API, предназначенный для экспорта, импорта и копирования разметки. API доступен по endpoint-ам
POST /api/public/markup/import
POST /api/public/markup/export
POST /api/public/markup/copy

Разметка описывается посредством protobuf схемы:

// Represents exported review (review itself + comments)
// Review is associated with invariant and has list of locations
message Review {

// Defines model for concrete location of the review
message Location {
string warnClass = 1;
string file = 2;
uint32 line = 3;
string details = 4;
string mtid = 5;
string function = 10;
bytes content_hash = 6;
bytes trace_hash = 7;
bytes marker_hash = 8;
bytes line_hash = 9;
string tool = 11;
string lang = 12;
}
// Defines model for comment
message Comment {
string text = 1;
optional string format = 2;
google.protobuf.Timestamp create_ts = 3;
optional google.protobuf.Timestamp update_ts = 4;
string createdBy = 5;
string origin_id = 6;
optional uint64 review_id = 7; // refers to Review.id field
optional string created_by_id = 8;
}
// Defines model for review itself
message ReviewData {
string status = 1;
string severity = 2;
string action = 3;
string origin_id = 4;
google.protobuf.Timestamp create_ts = 5;
string created_by = 6;
optional string created_by_id = 7;
optional string created_from = 8;
}
// Invariant of the marker
string invariant = 1;
// Review information associated with markers having given invariant
optional ReviewData review_data = 2;
// List of comments associated with all markers having given invariant
repeated Comment comments = 3;
// List of locations associated with given invariant. Locations can be used to apply fuzzy matching of review with existing data when there is no invariant match
repeated Location locations = 4;
// Export-specific ID, comments can refer to this id if comment is associated with review operation
uint64 id = 5;
// Meta-information about export, when exporting to file field is initialized only for the first element
optional ReviewExportMeta meta = 6;
}

// Defines meta-information about exported review
message ReviewExportMeta {
message Container {
string id = 1;
string name = 2;
}
google.protobuf.Timestamp create_ts = 1; // timestamp when export was produced (UTC)
string created_by = 2; // user who triggered export
string svacer_version = 3; // svacer version
optional Container project = 4; // source container (project)
optional Container branch = 5; // source container (branch)
map<string,string> properties = 6; // extra properties
}

Актуальную версию схемы можно получить из Svacer по API: <code>GET /api/public/markup/schema</code>.

{{Note|type=reminder|text=При сериализации в JSON используются proto-имена полей. При работе с данными из Go рекомендуется использовать [https://pkg.go.dev/google.golang.org/protobuf/encoding/protojson protojson] для сериализации и десериализации.}}

Svacer поддерживает два формата для экспортирования/импортирования разметки:

* JSON с разделением по newline-ам. Каждая строка представляет собой объект типа '''Review''' (указано выше) сериализованный в JSON
* Бинарный формат: последовательность блоков <code>[lenght little endian][proto]</code>, где первый блок содержит длину следующего блока в формате <code>u32 little endian</code>, а второй блок содержит proto-сериализацию объекта '''Review'''

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

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

=== Экспорт разметки ===
POST /api/public/markup/export

* Параметры передаются в '''body''' запроса
* Запрос должен иметь токен аутентификации
* Пользователь должен иметь доступы на Public API и экспорт разметки из ветки, откуда производится экспорт

Формат body:
{
"source": ["<project name>","<branch name>"],
"source_id": "<branch id>",
"skip_comments": <true|false>,
"skip_review": <true|false>,
"format": "<json|proto>",
"export_all": <true|false>
}

* Пользователь должен указать либо '''source''' элемент, либо '''source_id'''
* Опция '''skip_comments''' позволяет игнорировать комментарии при выгрузке разметки
* Опция '''skip_review''' позволяет игнорировать статусы маркеров при выгрузке разметки (т. е. выгружать только комментарии)
* Опция '''export_all''' позволяет выгрузить пустую разметку (т. е. статусы Undecided/Unspecified/Undecided). Это позволяет получить список всех инвариантов для ветки и использовать данные для генерации требуемой разметки для импорта
* Метод возвращает gzipped файл содержащий разметку в указанном формате

=== Импорт разметки ===
POST /api/public/markup/import

* Параметры передаются в '''query''' запроса
* Запрос должен быть формата '''multipart/form-data''', поле '''file''' должно содержать файл с разметкой
* Запрос должен иметь токен аутентификации
* Пользователь должен иметь доступы на Public API, импорт разметки, '''Update any review''' и '''Update any comment''' (для перезаписи разметки и комментарии ревью мастера)

Query параметры:

project — <project name> — имя проекта
branch — <branch name> — имя бранча
target_id — <branch id> — id бранча. Должно быть либо id бранча, либо имя проекта + имя бранча. Приоритет — id бранча
format — <proto|json> — формат импортируемой разметки. Если не указан, будет определяться автоматически
overwrite — <none|force|last - по умолчанию last> — контролирует логику применения разметки к бранчу при импорте
skip_comments — <true|false - по умолчанию false> — игнорировать комментарии
skip_review — <true|false - по умолчанию false> — игнорировать статус разметки (импорт только комментариев)
response_with_result — <true|false> — вернуть детальный список разметок, которые были применены, в формате JSON с newline-разделителями. Если не указан, то возвращается краткий статус
compressed — <true|false> — формат файла с разметкой, если true то подразумевается gzip-compressed файл

Настоятельно рекомендуется явно указывать параметр <code>overwrite</code>. В случае успеха, метод возвращает body со следующими данными:

{"total":<total number of loaded reviews>,"applied_reviews":<applied reviews>,"applied_comments":<applied comments>,"skipped_reviews":<skipped reviews>,"duplicate_reviews":<duplicate reviews>,"duplicate_comments":<duplicate comments}
<json representation of applied review>*

Первая строка body содержит JSON с информацией о выполненных действиях. Если был указан параметр '''response_with_result''', то дальше будут идти newline-separated JSON представления примененных review.

==== Алгоритм импорта ====

* Блокируются операции по разметке и импорту на целевой бранч
* Выгружается текущая разметка бранча с комментариями
* Загруженная разметка сопоставляется с текущей и формируется список разметки для применения. Дублирующая разметка и комментарии игнорируются
* Перезапись разметки контролируется параметром '''overwrite'''. Если значение '''none''', то разметка не перезаписывается при наличии разметки в целевом бранче. Если значение '''force''', то разметка будет перезаписана. Если значение '''last''', то разметка будет перезаписана, если загруженная разметка имеет более новую дату
* Пустая разметка (Undecided/Unspecified/Undecided) явным образом не применяется к инварианту, если разметка отсутствует на бранче
* Сформированный список применяется к бранчу. При выборе маркера, куда добавлять комментарий, выбирается маркер из наиболее раннего снимка, где маркер с соответствующим инвариантом появился

'''Допустимые значения полей разметки:'''

* Status — <code>"Confirmed", "Won't fix", "False Positive", "Unclear", "Undecided"</code>
* Severity — <code>"Unspecified", "Critical", "Major", "Minor"</code>
* Action — <code>"Undecided", "Fix required", "Fix submitted", "Ignore"</code>

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

POST /api/public/markup/copy

* Параметры передаются в '''body''' запроса
* Запрос должен иметь токен аутентификации
* Пользователь должен иметь доступы на Public API, экспорт снимков (для исходной ветки), импорт разметки (для целевой ветки), разрешения '''Update any review''' и '''Update any comment''' (для перезаписи разметки и комментарии ревью мастера)

Формат body:

{
"source": ["<project name>","<branch name>"],
"source_id": "<branch id>",
"target": ["<project name>","<branch name>"],
"target_id": "<branch id>",
"skip_comments": <true|false - по умолчанию false>,
"skip_review": <true|false - по умолчанию false>,
"overwrite": "<none|last|force>",
"response_with_result": <true|false>
}

В случае успеха, метод возвращает body со следующими данными

{"total":<total number of loaded reviews>,"applied_reviews":<applied reviews>,"applied_comments":<applied comments>,"skipped_reviews":<skipped reviews>,"duplicate_reviews":<duplicate reviews>,"duplicate_comments":<duplicate comments}
<json representation of applied review>*

Первая строка body содержит JSON с информацией о выполненных действиях. Если был указан параметр '''response_with_result''', то дальше будут идти newline-separated JSON представления примененных review.

== CLI API для импорта/экспорта/копирования разметки ==

Данное API является '''экспериментальным''' и может меняться. Основные аргументы будут сохранены. По умолчанию, команды под '''markup2''' скрыты. Использовать можно, указывая их явно. Для получения помощи запустить:

svacer markup2 --help
svacer markup2 copy --help
svacer markup2 import --help
svacer markup2 export --help

Описание команд:
NAME:
svacer markup2 - New [experimental] API for review export/import/copy

USAGE:
svacer markup2 command [command options] [arguments...]

COMMANDS:
import Import markup from file and apply to specified branch
export Export markup to file or stdout. Command needs either branch ID or project and branch name. When exporting to file, data is gzipped.
copy Copy markup between branches
help, h Shows a list of commands or help for one command

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
--oidc-client value ClientID for login with OpenID Connect protocol
--oidc-secret value Client's secret for login with OpenID Connect protocol
--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]
--conn_file value Use connection file [$SVACER_CONN_FILE]
--dry-run Do actions but don't commit result to database (default: false)
--help Show help (default: false)

Импорт разметки из файла
NAME:
svacer markup2 import - Import markup from file and apply to specified branch

USAGE:
svacer markup2 import [command options] <file> - path to file to import. If file is not specified, data is loaded from stdin

OPTIONS:
--project value Target project name
--branch value Target branch name
--branch-id value Target branch ID
--skip-review Import comments only (default: false)
--skip-comments Import review only (default: false)
--overwrite value Overwrite mode: none, force, last
--out value Write information about applied reviews to given file (in json format). If not specified, result is printed to stdout
--verbose-out Include information about applied reviews (default: false)
--format value Specify explicit format for data. If not specified, format will be detected from content
--help Show help (default: false)

Экспорт разметки в файл
NAME:
svacer markup2 export - Export markup to file or stdout. Command needs either branch ID or project and branch name. When exporting to file, data is gzipped.

USAGE:
svacer markup2 export [command options] <file name or empty> - if no file name is specified, result is printed to stdout

OPTIONS:
--project value Source project name
--branch value Source branch name. Branch name will be resolved against source project
--branch-id value Source branch ID
--skip-review Export comments only (default: false)
--skip-comments Export review only (default: false)
--format value Format: json or proto. If format is not specified, proto is used. If output file is not specified and format is not specified, json will be used.
--uncompressed Get data in raw format without gzip compression (default: false)
--export-all Export empty (undecided) review (default: false)
--help Show help (default: false)

Копирование разметки
NAME:
svacer markup2 copy - Copy markup between branches

USAGE:
svacer markup2 copy [command options] [arguments...]

OPTIONS:
--target-project value Target project name
--target-branch value Target branch name
--target-branch-id value Target branch ID
--source-project value Source project name
--source-branch value Source branch name
--source-branch-id value Source branch ID
--skip-review Copy comments only (default: false)
--skip-comments Copy review only (default: false)
--overwrite value Overwrite mode: none, force, last
--out value Write information about applied reviews to given file (in json format). If not specified, result is printed to stdout
--verbose-out Include information about applied reviews (default: false)
--help Show help (default: false)

Примеры использования:
svacer markup2 --user admin --password admin copy --overwrite=force --source-project bash --target-project bash --source-branch master --target-branch bash_clone
2024-11-15T13:19:41.735+0300 info Log file location /tmp/svacer-1543671068.log
2024-11-15T13:19:41.735+0300 info Quering server configuration from <nowiki>http://localhost:8080/api/public/server/info</nowiki>
2024-11-15T13:19:41.745+0300 info Server version: [devel]
{"total":771,"applied_reviews":0,"applied_comments":0,"skipped_reviews":771,"duplicate_reviews":771,"duplicate_comments":5}

svacer markup2 --user admin --password admin import --overwrite=force --project bash --branch bash_clone /tmp/out.json
2024-11-15T13:20:17.433+0300 info Log file location /tmp/svacer-1480510331.log
2024-11-15T13:20:17.433+0300 info Quering server configuration from <nowiki>http://localhost:8080/api/public/server/info</nowiki>
2024-11-15T13:20:17.435+0300 info Server version: [devel]
{"total":771,"applied_reviews":0,"applied_comments":0,"skipped_reviews":771,"duplicate_reviews":771,"duplicate_comments":5}

2024-11-15T15:46:06.809+0300 info Log file location /tmp/svacer-1792255677.log
2024-11-15T15:46:06.809+0300 info Quering server configuration from <nowiki>http://localhost:8080/api/public/server/info</nowiki>
2024-11-15T15:46:06.810+0300 info Server version: [devel]
{"invariant":"+1vB4JXkME3AAcbXR7tezA", "review_data":{"status":"Confirmed", "severity":"Unspecified", "action":"Undecided", "create_ts":"2024-10-16T14:44:07.233554Z", "created_by":"admin", "created_from":"1c8cea92-7708-4bb9-9a88-40325f39efe8"}, "locations":[{"warnClass":"PROC_USE.VULNERABLE", "file":"/.build/jobs.c", "line":4207, "details":"b043c5a63bf9d432c816f2cb421c907fe912bf16", "mtid":"SvEng.L.1", "function":"run_sigchld_trap", "content_hash":"s4AMYzKR8Ol8k4OODPpOlPUsSWI=", "marker_hash":"XiVQmRu8HmhzOnq1+XY7AaujT+o=", "tool":"SvEng", "lang":"C_Cpp"}], "id":"699", "meta":{"create_ts":"2024-11-15T12:46:06.835078490Z", "created_by":"admin", "svacer_version":"devel.2024-11-15@15:45:34.a290bc7e", "project":{"id":"0fd645aa-8e70-4a4f-b68b-766c4f337bf2", "name":"bash"}, "branch":{"id":"8925df5a-7a98-4f07-bc88-ee4ea5b43813", "name":"master"}}}

Markup2

2024-12-24T10:55:07Z

Writer:

== Public REST API для экспорта, импорта и копирования разметки ==
Релиз 10.х Svacer включает новый API, предназначенный для экспорта, импорта и копирования разметки. API доступен по endpoint-ам
POST /api/public/markup/import
POST /api/public/markup/export
POST /api/public/markup/copy

Разметка описывается посредством protobuf схемы:

// Represents exported review (review itself + comments)
// Review is associated with invariant and has list of locations
message Review {

// Defines model for concrete location of the review
message Location {
string warnClass = 1;
string file = 2;
uint32 line = 3;
string details = 4;
string mtid = 5;
string function = 10;
bytes content_hash = 6;
bytes trace_hash = 7;
bytes marker_hash = 8;
bytes line_hash = 9;
string tool = 11;
string lang = 12;
}
// Defines model for comment
message Comment {
string text = 1;
optional string format = 2;
google.protobuf.Timestamp create_ts = 3;
optional google.protobuf.Timestamp update_ts = 4;
string createdBy = 5;
string origin_id = 6;
optional uint64 review_id = 7; // refers to Review.id field
optional string created_by_id = 8;
}
// Defines model for review itself
message ReviewData {
string status = 1;
string severity = 2;
string action = 3;
string origin_id = 4;
google.protobuf.Timestamp create_ts = 5;
string created_by = 6;
optional string created_by_id = 7;
optional string created_from = 8;
}
// Invariant of the marker
string invariant = 1;
// Review information associated with markers having given invariant
optional ReviewData review_data = 2;
// List of comments associated with all markers having given invariant
repeated Comment comments = 3;
// List of locations associated with given invariant. Locations can be used to apply fuzzy matching of review with existing data when there is no invariant match
repeated Location locations = 4;
// Export-specific ID, comments can refer to this id if comment is associated with review operation
uint64 id = 5;
// Meta-information about export, when exporting to file field is initialized only for the first element
optional ReviewExportMeta meta = 6;
}

// Defines meta-information about exported review
message ReviewExportMeta {
message Container {
string id = 1;
string name = 2;
}
google.protobuf.Timestamp create_ts = 1; // timestamp when export was produced (UTC)
string created_by = 2; // user who triggered export
string svacer_version = 3; // svacer version
optional Container project = 4; // source container (project)
optional Container branch = 5; // source container (branch)
map<string,string> properties = 6; // extra properties
}

Актуальную версию схемы можно получить из Svacer по API: <code>GET /api/public/markup/schema</code>.

{{Note|type=reminder|text=При сериализации в JSON используются proto-имена полей. При работе с данными из Go рекомендуется использовать [https://pkg.go.dev/google.golang.org/protobuf/encoding/protojson protojson] для сериализации и десериализации.}}

Svacer поддерживает два формата для экспортирования/импортирования разметки:

* JSON с разделением по newline-ам. Каждая строка представляет собой объект типа '''Review''' (указано выше) сериализованный в JSON
* Бинарный формат: последовательность блоков <code>[lenght little endian][proto]</code>, где первый блок содержит длину следующего блока в формате <code>u32 little endian</code>, а второй блок содержит proto-сериализацию объекта '''Review'''

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

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

=== Экспорт разметки ===
POST /api/public/markup/export

* Параметры передаются в '''body''' запроса
* Запрос должен иметь токен аутентификации
* Пользователь должен иметь доступы на Public API и экспорт разметки из ветки, откуда производится экспорт

Формат body:
{
"source": ["<project name>","<branch name>"],
"source_id": "<branch id>",
"skip_comments": <true|false>,
"skip_review": <true|false>,
"format": "<json|proto>",
"export_all": <true|false>
}

* Пользователь должен указать либо '''source''' элемент, либо '''source_id'''
* Опция '''skip_comments''' позволяет игнорировать комментарии при выгрузке разметки
* Опция '''skip_review''' позволяет игнорировать статусы маркеров при выгрузке разметки (т. е. выгружать только комментарии)
* Опция '''export_all''' позволяет выгрузить пустую разметку (т. е. статусы Undecided/Unspecified/Undecided). Это позволяет получить список всех инвариантов для ветки и использовать данные для генерации требуемой разметки для импорта
* Метод возвращает gzipped файл содержащий разметку в указанном формате

=== Импорт разметки ===
POST /api/public/markup/import

* Параметры передаются в '''query''' запроса
* Запрос должен быть формата '''multipart/form-data''', поле '''file''' должно содержать файл с разметкой
* Запрос должен иметь токен аутентификации
* Пользователь должен иметь доступы на Public API, импорт разметки, '''Update any review''' и '''Update any comment''' (для перезаписи разметки и комментарии ревью мастера)

Query параметры:

project — <project name> — имя проекта
branch — <branch name> — имя бранча
target_id — <branch id> — id бранча. Должно быть либо id бранча, либо имя проекта + имя бранча. Приоритет — id бранча
format — <proto|json> — формат импортируемой разметки. Если не указан, будет определяться автоматически
overwrite — <none|force|last - по умолчанию last> — контролирует логику применения разметки к бранчу при импорте
skip_comments — <true|false - по умолчанию false> — игнорировать комментарии
skip_review — <true|false - по умолчанию false> — игнорировать статус разметки (импорт только комментариев)
response_with_result — <true|false> — вернуть детальный список разметок, которые были применены, в формате JSON с newline-разделителями. Если не указан, то возвращается краткий статус
compressed — <true|false> — формат файла с разметкой, если true то подразумевается gzip-compressed файл

Настоятельно рекомендуется явно указывать параметр <code>overwrite</code>. В случае успеха, метод возвращает body со следующими данными:

{"total":<total number of loaded reviews>,"applied_reviews":<applied reviews>,"applied_comments":<applied comments>,"skipped_reviews":<skipped reviews>,"duplicate_reviews":<duplicate reviews>,"duplicate_comments":<duplicate comments}
<json representation of applied review>*

Первая строка body содержит JSON с информацией о выполненных действиях. Если был указан параметр '''response_with_result''', то дальше будут идти newline-separated JSON представления примененных review.

==== Алгоритм импорта ====

* Блокируются операции по разметке и импорту на целевой бранч
* Выгружается текущая разметка бранча с комментариями
* Загруженная разметка сопоставляется с текущей и формируется список разметки для применения. Дублирующая разметка и комментарии игнорируются
* Перезапись разметки контролируется параметром '''overwrite'''. Если значение '''none''', то разметка не перезаписывается при наличии разметки в целевом бранче. Если значение '''force''', то разметка будет перезаписана. Если значение '''last''', то разметка будет перезаписана, если загруженная разметка имеет более новую дату
* Пустая разметка (Undecided/Unspecified/Undecided) явным образом не применяется к инварианту, если разметка отсутствует на бранче
* Сформированный список применяется к бранчу. При выборе маркера, куда добавлять комментарий, выбирается маркер из наиболее раннего снимка, где маркер с соответствующим инвариантом появился

'''Допустимые значения полей разметки:'''

* Status — <code>"Confirmed", "Won't fix", "False Positive", "Unclear", "Undecided"</code>
* Severity — <code>"Unspecified", "Critical", "Major", "Minor"</code>
* Action — <code>"Undecided", "Fix required", "Fix submitted", "Ignore"</code>

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

POST /api/public/markup/copy

* Параметры передаются в '''body''' запроса
* Запрос должен иметь токен аутентификации
* Пользователь должен иметь доступы на Public API, импорт разметки, разрешения '''Update any review''' и '''Update any comment''' (для перезаписи разметки и комментарии ревью мастера)

Формат body:

{
"source": ["<project name>","<branch name>"],
"source_id": "<branch id>",
"target": ["<project name>","<branch name>"],
"target_id": "<branch id>",
"skip_comments": <true|false - по умолчанию false>,
"skip_review": <true|false - по умолчанию false>,
"overwrite": "<none|last|force>",
"response_with_result": <true|false>
}

В случае успеха, метод возвращает body со следующими данными

{"total":<total number of loaded reviews>,"applied_reviews":<applied reviews>,"applied_comments":<applied comments>,"skipped_reviews":<skipped reviews>,"duplicate_reviews":<duplicate reviews>,"duplicate_comments":<duplicate comments}
<json representation of applied review>*

Первая строка body содержит JSON с информацией о выполненных действиях. Если был указан параметр '''response_with_result''', то дальше будут идти newline-separated JSON представления примененных review.

== CLI API для импорта/экспорта/копирования разметки ==

Данное API является '''экспериментальным''' и может меняться. Основные аргументы будут сохранены. По умолчанию, команды под '''markup2''' скрыты. Использовать можно, указывая их явно. Для получения помощи запустить:

svacer markup2 --help
svacer markup2 copy --help
svacer markup2 import --help
svacer markup2 export --help

Описание команд:
NAME:
svacer markup2 - New [experimental] API for review export/import/copy

USAGE:
svacer markup2 command [command options] [arguments...]

COMMANDS:
import Import markup from file and apply to specified branch
export Export markup to file or stdout. Command needs either branch ID or project and branch name. When exporting to file, data is gzipped.
copy Copy markup between branches
help, h Shows a list of commands or help for one command

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
--oidc-client value ClientID for login with OpenID Connect protocol
--oidc-secret value Client's secret for login with OpenID Connect protocol
--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]
--conn_file value Use connection file [$SVACER_CONN_FILE]
--dry-run Do actions but don't commit result to database (default: false)
--help Show help (default: false)

Импорт разметки из файла
NAME:
svacer markup2 import - Import markup from file and apply to specified branch

USAGE:
svacer markup2 import [command options] <file> - path to file to import. If file is not specified, data is loaded from stdin

OPTIONS:
--project value Target project name
--branch value Target branch name
--branch-id value Target branch ID
--skip-review Import comments only (default: false)
--skip-comments Import review only (default: false)
--overwrite value Overwrite mode: none, force, last
--out value Write information about applied reviews to given file (in json format). If not specified, result is printed to stdout
--verbose-out Include information about applied reviews (default: false)
--format value Specify explicit format for data. If not specified, format will be detected from content
--help Show help (default: false)

Экспорт разметки в файл
NAME:
svacer markup2 export - Export markup to file or stdout. Command needs either branch ID or project and branch name. When exporting to file, data is gzipped.

USAGE:
svacer markup2 export [command options] <file name or empty> - if no file name is specified, result is printed to stdout

OPTIONS:
--project value Source project name
--branch value Source branch name. Branch name will be resolved against source project
--branch-id value Source branch ID
--skip-review Export comments only (default: false)
--skip-comments Export review only (default: false)
--format value Format: json or proto. If format is not specified, proto is used. If output file is not specified and format is not specified, json will be used.
--uncompressed Get data in raw format without gzip compression (default: false)
--export-all Export empty (undecided) review (default: false)
--help Show help (default: false)

Копирование разметки
NAME:
svacer markup2 copy - Copy markup between branches

USAGE:
svacer markup2 copy [command options] [arguments...]

OPTIONS:
--target-project value Target project name
--target-branch value Target branch name
--target-branch-id value Target branch ID
--source-project value Source project name
--source-branch value Source branch name
--source-branch-id value Source branch ID
--skip-review Copy comments only (default: false)
--skip-comments Copy review only (default: false)
--overwrite value Overwrite mode: none, force, last
--out value Write information about applied reviews to given file (in json format). If not specified, result is printed to stdout
--verbose-out Include information about applied reviews (default: false)
--help Show help (default: false)

Примеры использования:
svacer markup2 --user admin --password admin copy --overwrite=force --source-project bash --target-project bash --source-branch master --target-branch bash_clone
2024-11-15T13:19:41.735+0300 info Log file location /tmp/svacer-1543671068.log
2024-11-15T13:19:41.735+0300 info Quering server configuration from <nowiki>http://localhost:8080/api/public/server/info</nowiki>
2024-11-15T13:19:41.745+0300 info Server version: [devel]
{"total":771,"applied_reviews":0,"applied_comments":0,"skipped_reviews":771,"duplicate_reviews":771,"duplicate_comments":5}

svacer markup2 --user admin --password admin import --overwrite=force --project bash --branch bash_clone /tmp/out.json
2024-11-15T13:20:17.433+0300 info Log file location /tmp/svacer-1480510331.log
2024-11-15T13:20:17.433+0300 info Quering server configuration from <nowiki>http://localhost:8080/api/public/server/info</nowiki>
2024-11-15T13:20:17.435+0300 info Server version: [devel]
{"total":771,"applied_reviews":0,"applied_comments":0,"skipped_reviews":771,"duplicate_reviews":771,"duplicate_comments":5}

2024-11-15T15:46:06.809+0300 info Log file location /tmp/svacer-1792255677.log
2024-11-15T15:46:06.809+0300 info Quering server configuration from <nowiki>http://localhost:8080/api/public/server/info</nowiki>
2024-11-15T15:46:06.810+0300 info Server version: [devel]
{"invariant":"+1vB4JXkME3AAcbXR7tezA", "review_data":{"status":"Confirmed", "severity":"Unspecified", "action":"Undecided", "create_ts":"2024-10-16T14:44:07.233554Z", "created_by":"admin", "created_from":"1c8cea92-7708-4bb9-9a88-40325f39efe8"}, "locations":[{"warnClass":"PROC_USE.VULNERABLE", "file":"/.build/jobs.c", "line":4207, "details":"b043c5a63bf9d432c816f2cb421c907fe912bf16", "mtid":"SvEng.L.1", "function":"run_sigchld_trap", "content_hash":"s4AMYzKR8Ol8k4OODPpOlPUsSWI=", "marker_hash":"XiVQmRu8HmhzOnq1+XY7AaujT+o=", "tool":"SvEng", "lang":"C_Cpp"}], "id":"699", "meta":{"create_ts":"2024-11-15T12:46:06.835078490Z", "created_by":"admin", "svacer_version":"devel.2024-11-15@15:45:34.a290bc7e", "project":{"id":"0fd645aa-8e70-4a4f-b68b-766c4f337bf2", "name":"bash"}, "branch":{"id":"8925df5a-7a98-4f07-bc88-ee4ea5b43813", "name":"master"}}}

User Management (command line)

2024-12-02T11:14:46Z

Writer: role-provider

== User management ==

=== Управление пользователями ===
Для управления пользователями используется команда '''user-provider''' инструмента Svacer с необходимыми подкомандами. Также требуется аутентификация на сервере для выполнения запросов и необходимые права доступа.

==== Создание пользователя ====
svacer user-provider add
--login <login>
--user_password <pwd>
--firstname <firstname>
--lastname <lastname>
--middlename <middlename>
--email <email>
--change-password <true|false> (используйте для смены пароля при первой авторизации по умолчанию false)
--auth-type <0|1|2> (тип аутентификации, 0 - Svacer, 1 - LDAP, 2 - OIDC_OAUTH, по умолчанию 0)
--role <role id or name> (для установки нескольких ролей использовать флаг несколько раз)
--review-master <true|false> (активировать атрибут Review Master, по умолчанию false)
'''Пример:'''
svacer user-provider add --user admin --password admin --login example --user_password Example123 --review-master true
2024-12-02T13:19:41.366+0300 info Log file location /tmp/svacer-3054598677.log
2024-12-02T13:19:41.366+0300 info Quering server configuration from <nowiki>http://localhost:8080/api/public/server/info</nowiki>
2024-12-02T13:19:41.375+0300 info Server version: [devel]
2024-12-02T13:19:41.380+0300 info Logged by user admin
2024-12-02T13:19:41.401+0300 info User added successfully: ID: e45f2ae5-4e5b-4308-a2f5-0f3461626c18 Password: Example123

==== Удаление пользователя ====
svacer user-provider delete
--username <id or name>
'''Пример:'''
svacer user-provider delete --user admin --password admin --username example321
2024-12-02T13:27:38.731+0300 info Log file location /tmp/svacer-2241911697.log
2024-12-02T13:27:38.731+0300 info Quering server configuration from <nowiki>http://localhost:8080/api/public/server/info</nowiki>
2024-12-02T13:27:38.739+0300 info Server version: [devel]
2024-12-02T13:27:38.759+0300 info User deleted successfully

==== Получение списка пользователей ====
svacer user-provider get
--with-roles <true|false> (к выводу добавляются роли пользователя)
--filter <all|active|archived> (используйте для фильтрации списка пользователей)
'''Пример:'''
svacer user-provider get --user admin --password admin --with-roles true
2024-12-02T13:21:30.392+0300 info Log file location /tmp/svacer-3616394399.log
2024-12-02T13:21:30.393+0300 info Quering server configuration from <nowiki>http://localhost:8080/api/public/server/info</nowiki>
2024-12-02T13:21:30.395+0300 info Server version: [devel]
[
{
"ID": "00000000-0000-0000-0000-000000000000",
"firstName": "admin",
"lastName": "admin",
"login": "admin",
"roles": [
{
"id": "00000000-0000-0000-0000-000000000000",
"name": "admin",
...
]

==== Обновление пользователя ====
svacer user-provider update
--username <id|name> (имя или идентификатор пользователя для обновления (по умолчанию обновляется текущий пользователь, указанный в авторизации)
--login <login>
--user_password <pwd>
--firstname <firstname>
--middlename <middlename>
--email <email>
--add-role <role id or name> (добавляет роль с переданным id или именем)
--delete-role <role id or name> (удаляет роль с переданным id или именем)
--review-master <true|false> (активировать атрибут Review Master)
'''Пример:'''
svacer user-provider update --user admin --password admin --username example --login example321
2024-12-02T13:24:43.052+0300 info Log file location /tmp/svacer-3041843149.log
2024-12-02T13:24:43.052+0300 info Quering server configuration from <nowiki>http://localhost:8080/api/public/server/info</nowiki>
2024-12-02T13:24:43.059+0300 info Server version: [devel]
2024-12-02T13:24:43.096+0300 info User example updated successfully

==== Изменение статуса пользователя ====
svacer user-provider update-status
--username <id|name> (имя или идентификатор пользователя для обновления)
--status <active|archive>
'''Пример:'''
svacer user-provider update-status --user admin --password admin --username example321 --status archive
2024-12-02T13:26:49.444+0300 info Log file location /tmp/svacer-2446325878.log
2024-12-02T13:26:49.444+0300 info Quering server configuration from <nowiki>http://localhost:8080/api/public/server/info</nowiki>
2024-12-02T13:26:49.452+0300 info Server version: [devel]
2024-12-02T13:26:49.479+0300 info User status updated successfully

== Role management ==

=== Управление ролями ===
Для управления пользователями используется команда '''role-provider''' инструмента Svacer с необходимыми подкомандами. Также требуется аутентификация на сервере для выполнения запросов и необходимые права доступа.

==== Создание роли ====
svacer role-provider add
--name <name>
--permissions <permissions> (Укажите права вида "цель1(ALL, идентификатор ветки, идентификатор или имя проекта, имя проекта/имя ветки):правило(чтобы получить список разрешений используй команду list-permissions);цель2:правило; ... ,цельН:правило")
'''Пример:'''
svacer role-provider add --name example --permissions "ALL:Import;test_md:Projects" --user admin --password admin
2024-12-02T13:43:25.542+0300 info Log file location /tmp/svacer-393346587.log
2024-12-02T13:43:25.542+0300 info Quering server configuration from <nowiki>http://localhost:8080/api/public/server/info</nowiki>
2024-12-02T13:43:25.549+0300 info Server version: [devel]
2024-12-02T13:43:25.556+0300 info Logged by user admin
2024-12-02T13:43:25.578+0300 info Role added successfully: example
Id: 4c2eda54-6d3f-409e-b846-63d49752f331
Permission 'ALL': 'Import', 'ReadAction'
Permission 'test_md': 'Branches', 'ExportMarkup', 'GlobalFilters', 'Import', 'ImportMarkup', 'Projects', 'ReadAction'

==== Удаление роли ====
svacer role-provider delete
--role <role name|id>
'''Пример:'''
svacer role-provider delete --role example --user admin --password admin
2024-12-02T14:13:28.664+0300 info Log file location /tmp/svacer-3511168837.log
2024-12-02T14:13:28.665+0300 info Quering server configuration from <nowiki>http://localhost:8080/api/public/server/info</nowiki>
2024-12-02T14:13:28.670+0300 info Server version: [devel]
2024-12-02T14:13:28.695+0300 info Role deleted successfully

==== Изменение роли ====
svacer role-provider update
--role <role name|id>
--permissions <permissions> (Укажите права вида "цель1(ALL, идентификатор ветки, идентификатор или имя проекта, имя проекта/имя ветки):правило(чтобы получить список разрешений используй команду list-permissions);цель2:правило; ... ,цельН:правило")
--force <true|false> (Используйте, чтобы перезаписать правила для роли. По умолчанию указанные правила будут добавлены к уже существующим)
--remove <true|false> (Используйте, чтобы удалить правила для роли. Правила, необходимые для удаления указываются в опции --permissions)
'''Пример:'''
svacer role-provider update --role example --permissions "ALL:Hooks" --user admin --password admin --force
2024-12-02T14:12:49.084+0300 info Log file location /tmp/svacer-2403337357.log
2024-12-02T14:12:49.084+0300 info Quering server configuration from <nowiki>http://localhost:8080/api/public/server/info</nowiki>
2024-12-02T14:12:49.093+0300 info Server version: [devel]
2024-12-02T14:12:49.125+0300 info Role updated successfully: example
Id: 4c2eda54-6d3f-409e-b846-63d49752f331
Permission 'ALL': 'Hooks'

==== Получение списка ролей ====
svacer role-provider get
--target <user id|name> (имя или идентификатор пользователя, чьи роли запрашиваются, если данный флаг не указан, будут выведены все роли)
'''Пример:'''
svacer role-provider get --user admin --password admin --target admin
2024-12-02T14:08:03.735+0300 info Log file location /tmp/svacer-3317672156.log
2024-12-02T14:08:03.737+0300 info Quering server configuration from <nowiki>http://localhost:8080/api/public/server/info</nowiki>
2024-12-02T14:08:03.744+0300 info Server version: [devel]
{
"ID": "00000000-0000-0000-0000-000000000000",
"firstName": "admin",
"lastName": "admin"
...
}

==== Назначение роли пользователю ====
svacer role-provider assign
--username <user name|id>
--role <role name|id>тобы получить список разрешений используй команду list-permissions);цель2:правило; ... ,цельН:правило")
--remove <true|false> (Используйте, чтобы перезаписать правила для роли. По умолчанию указанные правила будут добавлены к уже существующим)
'''Пример:'''
svacer role-provider assign --user admin --password admin --username guest --role example
2024-12-02T14:09:23.509+0300 info Log file location /tmp/svacer-2142876769.log
2024-12-02T14:09:23.509+0300 info Quering server configuration from <nowiki>http://localhost:8080/api/public/server/info</nowiki>
2024-12-02T14:09:23.519+0300 info Server version: [devel]
2024-12-02T14:09:23.543+0300 info Role example assigned successfully

==== Получение списка разрешений ====
svacer role-provider list-permissions
--format <json|table> (Укажите формат вывода json или table (table выводится с применением, названием и описанием разрешения) (по умолчанию: json))
'''Пример:'''
svacer role-provider list-permissions --user admin --password admin --format table
2024-12-02T14:10:46.061+0300 info Log file location /tmp/svacer-3390742125.log
2024-12-02T14:10:46.061+0300 info Quering server configuration from <nowiki>http://localhost:8080/api/public/server/info</nowiki>
2024-12-02T14:10:46.068+0300 info Server version: [devel]
2024-12-02T14:10:46.072+0300 info Logged by user admin
+-------------------------------------------------------------------------------------------------+
| Permission Table |
+------------------+------------------------------+-------------------+---------------------------+
| PERMISSION | SCOPE | NAME | DESCRIPTION |
+------------------+------------------------------+-------------------+---------------------------+
| Hooks | server | Run hooks | Run hooks from Details |
| | | | section of the right |
| | | | panel |
+------------------+------------------------------+-------------------+---------------------------+
| Backups | server | Create backups | Create, view and restore |
| | | | backup using CLI |
+------------------+------------------------------+-------------------+---------------------------+
...

User Management (command line)

2024-12-02T10:33:12Z

Writer: user-provider

User Management (command line)

2024-12-02T10:06:38Z

Writer: role-provider

== User management ==

=== Управление пользователями ===
Для управления пользователями используется команда '''user-provider''' с необходимыми подкомандами.

==== Создание пользователя ====
svacer user-provider add
--login <login>
--user_password <pwd>
--firstname <firstname>
--lastname <lastname>
--middlename <middlename>
--email <email>
--change-password <true|false> (используйте для смены пароля при первой авторизации по умолчанию false)
--auth-type <0|1|2> (тип аутентификации, 0 - Svacer, 1 - LDAP, 2 - OIDC_OAUTH, по умолчанию 0)
--role <role id or name> (для установки нескольких ролей использовать флаг несколько раз)
--review-master <true|false> (активировать атрибут Review Master, по умолчанию false)

==== Удаление пользователя ====
svacer user-provider delete
--username <id or name>

==== Получение списка пользователей ====
svacer user-provider get
--with-roles <true|false> (к выводу добавляются роли пользователя)
--filter <all|active|archived> (используйте для фильтрации списка пользователей)

==== Обновление пользователя ====
svacer user-provider update
--username <id|name> (имя или идентификатор пользователя для обновления (по умолчанию обновляется текущий пользователь, указанный в авторизации)
--login <login>
--user_password <pwd>
--firstname <firstname>
--middlename <middlename>
--email <email>
--add-role <role id or name> (добавляет роль с переданным id или именем)
--delete-role <role id or name> (удаляет роль с переданным id или именем)
--review-master <true|false> (активировать атрибут Review Master)

==== Изменение статуса пользователя ====
svacer user-provider update-status
--username <id|name> (имя или идентификатор пользователя для обновления)
--status <active|archive>

== Role management ==

=== Управление ролями ===
Для управления ролями используется команда '''role-provider''' с необходимыми подкомандами.

==== Создание роли ====
svacer role-provider add
--name <name>
--permissions <permissions> (Укажите права вида "цель1(ALL, идентификатор ветки, идентификатор или имя проекта, имя проекта/имя ветки):правило(чтобы получить список разрешений используй команду list-permissions);цель2:правило; ... ,цельН:правило")

==== Удаление роли ====
svacer role-provider delete
--role <role name|id>

==== Изменение роли ====
svacer role-provider update
--role <role name|id>
--permissions <permissions> (Укажите права вида "цель1(ALL, идентификатор ветки, идентификатор или имя проекта, имя проекта/имя ветки):правило(чтобы получить список разрешений используй команду list-permissions);цель2:правило; ... ,цельН:правило")
--force <true|false> (Используйте, чтобы перезаписать правила для роли. По умолчанию указанные правила будут добавлены к уже существующим)
--remove <true|false> (Используйте, чтобы удалить правила для роли. Правила, необходимые для удаления указываются в опции --permissions)

==== Получение списка ролей ====
svacer role-provider get
--target <user id|name> (имя или идентификатор пользователя, чьи роли запрашиваются, если данный флаг не указан, будут выведены все роли)

==== Назначение роли пользователю ====
svacer role-provider assign
--username <user name|id>
--role <role name|id>тобы получить список разрешений используй команду list-permissions);цель2:правило; ... ,цельН:правило")
--remove <true|false> (Используйте, чтобы перезаписать правила для роли. По умолчанию указанные правила будут добавлены к уже существующим)

==== Получение списка разрешений ====
svacer role-provider list-permissions
--format <json|table> (Укажите формат вывода json или table (table выводится с применением, названием и описанием разрешения) (по умолчанию: json))

User Management (command line)

2024-12-02T09:49:23Z

Writer: add user provider

Markup2

2024-11-18T13:17:18Z

Writer: Убрал лишний --help в примерах кли команд

== Public REST API для экспорта, импорта и копирования разметки ==
Релиз 10.х Svacer включает новый API предназначенный для экспорта, импорта и копирования разметки. API доступен по endpoint-ам
POST /api/public/markup/import
POST /api/public/markup/export
POST /api/public/markup/copy
Разметка описывается посредством protobuf схемы:
// Represents exported review (review itself + comments)
// Review is associated with invariant and has list of locations
message Review {

// Defines model for concrete location of the review
message Location {
string warnClass = 1;
string file = 2;
uint32 line = 3;
string details = 4;
string mtid = 5;
string function = 10;
bytes content_hash = 6;
bytes trace_hash = 7;
bytes marker_hash = 8;
bytes line_hash = 9;
string tool = 11;
string lang = 12;
}
// Defines model for comment
message Comment {
string text = 1;
optional string format = 2;
google.protobuf.Timestamp create_ts = 3;
optional google.protobuf.Timestamp update_ts = 4;
string createdBy = 5;
string origin_id = 6;
optional uint64 review_id = 7; // refers to Review.id field
optional string created_by_id = 8;
}
// Defines model for review itself
message ReviewData {
string status = 1;
string severity = 2;
string action = 3;
string origin_id = 4;
google.protobuf.Timestamp create_ts = 5;
string created_by = 6;
optional string created_by_id = 7;
optional string created_from = 8;
}
// Invariant of the marker
string invariant = 1;
// Review information associated with markers having given invariant
optional ReviewData review_data = 2;
// List of comments associated with all markers having given invariant
repeated Comment comments = 3;
// List of locations associated with given invariant. Locations can be used to apply fuzzy matching of review with existing data when there is no invariant match
repeated Location locations = 4;
// Export-specific ID, comments can refer to this id if comment is associated with review operation
uint64 id = 5;
// Meta-information about export, when exporting to file field is initialized only for the first element
optional ReviewExportMeta meta = 6;
}

// Defines meta-information about exported review
message ReviewExportMeta {
message Container {
string id = 1;
string name = 2;
}
google.protobuf.Timestamp create_ts = 1; // timestamp when export was produced (UTC)
string created_by = 2; // user who triggered export
string svacer_version = 3; // svacer version
optional Container project = 4; // source container (project)
optional Container branch = 5; // source container (branch)
map<string,string> properties = 6; // extra properties
}
Актуальную версию схемы можно получить из Svacer по API: <code>GET /api/public/markup/schema</code>.

'''ВНИМАНИЕ''': При сериализации в JSON используются proto-имена полей. При работе с данными из Go рекомендуется использовать https://pkg.go.dev/google.golang.org/protobuf/encoding/protojson для сериализации и десериализации.

Svacer поддерживает два формата для экспортирования/импортирования разметки:

* <code>json</code> с разделением по newline-ам. Каждая строка представляет собой объект типа <code>Review</code> (указано выше) сериализованный в JSON
* бинарный формат: последовательность блоков <code>[lenght little endian][proto]</code> , где первый блок содержит длину следующего блока в формате <code>u32 little endian</code> , а второй блок содержит proto-сериализацию объекта <code>Review</code>

В обоих случаях при выгрузке разметки первый элемент типа <code>Review</code> будет содержать мета-информацию об исходном контексте, откуда была выгружена разметка

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

=== Экспорт разметки ===
POST /api/public/markup/export

* параметры передаются в body запроса
* запрос должен иметь токен аутентификации
* пользователь должен иметь доступы на Public API и экспорт разметки из ветки, откуда производится экспорт

Формат body:
{
"source": ["<project name>","<branch name>"],
"source_id": "<branch id>",
"skip_comments": <true|false>,
"skip_review": <true|false>,
"format": "<json|proto>"
}
Пользователь должен указать либо <code>source</code> элемент, либо <code>source_id</code>.

Опция <code>skip_comments</code> позволяет игнорировать комментарии при выгрузке разметки.

Опция <code>skip_review</code> позволяет игнорировать статусы маркеров при выгрузке разметки (т.е выгружать только комментарии).

Метод возвращает gzipped файл содержащий разметку в указанном формате.

=== Импорт разметки ===
POST /api/public/markup/import

* параметры передаются в '''query''' запроса
* запрос должен быть формата <code>multipart/form-data</code>, поле <code>file</code> должно содержать файл с разметкой
* запрос должен иметь токен аутентификации
* пользователь должен иметь доступы на Public API, импорт разметки или снэпшота и разрешения <code>Update any review</code>и<code>Update any comment</code>

Query параметры:
project - <project name> - имя проекта
branch - <branch name> - имя бранча
target_id - <branch id> - id бранча. Должно быть либо id бранча, либо имя проекта + имя бранча. Приоритет - id бранча
format - <proto|json> - формат импортируемой разметки, если не указан - будет определяться автоматически
overwrite - <none|force|last> - контролирует логику применения разметки к бранчу при импорте
skip_comments - <true|false> - игнорировать комментарии
skip_review - <true|false> - игнорировать статус разметки (импорт только комментариев)
response_with_result - <true|false> - вернуть детальный список разметок, какие были применены в формате json с newline
разделителями. Если не указан, то возвращается краткий статус
compressed - <true|false> - формат файла с разметкой, если true то файл подразумевается gzip-compressed
В случае успеха, метод возвращает Body со следующими данными
{"total":<total number of loaded reviews>,"applied_reviews":<applied reviews>,"applied_comments":<applied comments>,"skipped_reviews":<skipped reviews>,"duplicate_reviews":<duplicate reviews>,"duplicate_comments":<duplicate comments}
<json representation of applied review>*
Первая строка Body содержит JSON с информацией о выполненных действиях. Если бы указан параметр <code>response_with_result</code>то дальше будут идти newline-separated JSON представления примененных review.

==== Алгоритм импорта ====

* Блокируются операции по разметки и импорту на целевой бранч
* Выгружается текущая разметка бранча с комментариями
* Загруженная разметка сопоставляется с текущей и формируется список разметки для применения. Дублирующая разметка и комментарии игнорируются. Перезапись разметки контролируется параметрами <code>overwrite</code>. Если значение <code>none</code>, то разметка не перезаписывается при наличии разметки в целевом бранче. Если значение <code>force</code>, то разметка будет перезаписана. Если значение <code>last</code>, то разметка будет перезаписана если загруженная разметка имеет более новую дату.
* Сформированный список применяется к бранчу. При выборе маркера, куда добавлять комментарий, выбирается маркер из наиболее раннего снимка, где маркер с соответствующим инвариантом появился.

=== Копирование разметки ===
POST /api/public/markup/copy

*параметры передаются в '''body''' запроса
* запрос должен иметь токен аутентификации
* пользователь должен иметь доступы на Public API, импорт разметки/снимка и разрешения <code>Update any review</code>и<code>Update any comment</code>

Формат body:
{
"source": ["<project name>","<branch name>"],
"source_id": "<branch id>",
"target": ["<project name>","<branch name>"],
"target_id": "<branch id>",
"skip_comments": <true|false>,
"skip_review": <true|false>,
"overwrite": "<none|last|force>",
"response_with_result": <true|false>
}
В случае успеха, метод возвращает Body со следующими данными
{"total":<total number of loaded reviews>,"applied_reviews":<applied reviews>,"applied_comments":<applied comments>,"skipped_reviews":<skipped reviews>,"duplicate_reviews":<duplicate reviews>,"duplicate_comments":<duplicate comments}
<json representation of applied review>*
Первая строка Body содержит JSON с информацией о выполненных действиях. Если бы указан параметр <code>response_with_result</code>то дальше будут идти newline-separated JSON представления примененных review.

== CLI API для импорта/экспорта/копирования разметки ==
Данное API является '''экспериментальным''' и может меняться. Основные аргументы будут сохранены. По умолчанию, команды под <code>markup2</code> скрыты. Использовать можно, указывая их явно. Для получения помощи запустить:
svacer markup2 --help
svacer markup2 copy --help
svacer markup2 import --help
svacer markup2 export --help
Описание команд:
NAME:
svacer markup2 - New [experimental] API for review export/import/copy

USAGE:
svacer markup2 command [command options] [arguments...]

COMMANDS:
import Import markup from file and apply to specified branch
export Export markup to file or stdout. Command needs either branch ID or project and branch name. When exporting to file, data is gzipped.
copy Copy markup between branches
help, h Shows a list of commands or help for one command

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
--oidc-client value ClientID for login with OpenID Connect protocol
--oidc-secret value Client's secret for login with OpenID Connect protocol
--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]
--conn_file value Use connection file [$SVACER_CONN_FILE]
--dry-run Do actions but don't commit result to database (default: false)
--help Show help (default: false)
Импорт разметки из файла
NAME:
svacer markup2 import - Import markup from file and apply to specified branch

USAGE:
svacer markup2 import [command options] <file> - path to file to import. If file is not specified, data is loaded from stdin

OPTIONS:
--project value Target project name
--branch value Target branch name
--branch-id value Target branch ID
--skip-review Import comments only (default: false)
--skip-comments Import review only (default: false)
--overwrite value Overwrite mode: none, force, last
--out value Write information about applied reviews to given file (in json format). If not specified, result is printed to stdout
--verbose-out Include information about applied reviews (default: false)
--format value Specify explicit format for data. If not specified, format will be detected from content
--help Show help (default: false)
Экспорт разметки в файл
NAME:
svacer markup2 export - Export markup to file or stdout. Command needs either branch ID or project and branch name. When exporting to file, data is gzipped.

USAGE:
svacer markup2 export [command options] <file name or empty> - if no file name is specified, result is printed to stdout

OPTIONS:
--project value Source project name
--branch value Source branch name. Branch name will be resolved against source project
--branch-id value Source branch ID
--skip-review Export comments only (default: false)
--skip-comments Export review only (default: false)
--format value Format: json or proto. If format is not specified, proto is used. If output file is not specified and format is not specified, json will be used.
--uncompressed Get data in raw format without gzip compression (default: false)
--help Show help (default: false)
Копирование разметки
NAME:
svacer markup2 copy - Copy markup between branches

USAGE:
svacer markup2 copy [command options] [arguments...]

OPTIONS:
--target-project value Target project name
--target-branch value Target branch name
--target-branch-id value Target branch ID
--source-project value Source project name
--source-branch value Source branch name
--source-branch-id value Source branch ID
--skip-review Copy comments only (default: false)
--skip-comments Copy review only (default: false)
--overwrite value Overwrite mode: none, force, last
--out value Write information about applied reviews to given file (in json format). If not specified, result is printed to stdout
--verbose-out Include information about applied reviews (default: false)
--help Show help (default: false)
Примеры использования:
svacer markup2 --user admin --password admin copy --overwrite=force --source-project bash --target-project bash --source-branch master --target-branch bash_clone
2024-11-15T13:19:41.735+0300 info Log file location /tmp/svacer-1543671068.log
2024-11-15T13:19:41.735+0300 info Quering server configuration from <nowiki>http://localhost:8080/api/public/server/info</nowiki>
2024-11-15T13:19:41.745+0300 info Server version: [devel]
{"total":771,"applied_reviews":0,"applied_comments":0,"skipped_reviews":771,"duplicate_reviews":771,"duplicate_comments":5}

svacer markup2 --user admin --password admin import --overwrite=force --project bash --branch bash_clone /tmp/out.json
2024-11-15T13:20:17.433+0300 info Log file location /tmp/svacer-1480510331.log
2024-11-15T13:20:17.433+0300 info Quering server configuration from <nowiki>http://localhost:8080/api/public/server/info</nowiki>
2024-11-15T13:20:17.435+0300 info Server version: [devel]
{"total":771,"applied_reviews":0,"applied_comments":0,"skipped_reviews":771,"duplicate_reviews":771,"duplicate_comments":5}

2024-11-15T15:46:06.809+0300 info Log file location /tmp/svacer-1792255677.log
2024-11-15T15:46:06.809+0300 info Quering server configuration from <nowiki>http://localhost:8080/api/public/server/info</nowiki>
2024-11-15T15:46:06.810+0300 info Server version: [devel]
{"invariant":"+1vB4JXkME3AAcbXR7tezA", "review_data":{"status":"Confirmed", "severity":"Unspecified", "action":"Undecided", "create_ts":"2024-10-16T14:44:07.233554Z", "created_by":"admin", "created_from":"1c8cea92-7708-4bb9-9a88-40325f39efe8"}, "locations":[{"warnClass":"PROC_USE.VULNERABLE", "file":"/.build/jobs.c", "line":4207, "details":"b043c5a63bf9d432c816f2cb421c907fe912bf16", "mtid":"SvEng.L.1", "function":"run_sigchld_trap", "content_hash":"s4AMYzKR8Ol8k4OODPpOlPUsSWI=", "marker_hash":"XiVQmRu8HmhzOnq1+XY7AaujT+o=", "tool":"SvEng", "lang":"C_Cpp"}], "id":"699", "meta":{"create_ts":"2024-11-15T12:46:06.835078490Z", "created_by":"admin", "svacer_version":"devel.2024-11-15@15:45:34.a290bc7e", "project":{"id":"0fd645aa-8e70-4a4f-b68b-766c4f337bf2", "name":"bash"}, "branch":{"id":"8925df5a-7a98-4f07-bc88-ee4ea5b43813", "name":"master"}}}

Help:CLI/management/containers

2024-10-15T13:04:48Z

Writer: описание команд из svacer container

== Описание и примеры использования управления контейнерами в svacer ==
Управление разными видами контейнеров может осуществлять пользователь при наличии соответствующих доступов через команды <code>svacer container</code>. Команды можно использовать в скриптах, возвращаемые значения обычно выводятся в виде JSON в <code>stdout</code> поток, что позволяет получать и использовать ID объекты в скриптах.

В примерах для краткости не указываются опции доступа к серверу и пользователя и вывод приведён с сокращениями.

Актуальную информацию по командам можно посмотреть напрямую через вызов <code>svacer <command> --help</code>.

=== Добавление ветки, проекта или группы проектов ===
Добавление нового контейнера осуществляется командой <code>svacer container add</code> c указанием названия и типа создаваемого объекта: <code>project</code>, <code>branch</code>, <code>project-group</code>. Например так создаётся пустой проект
svacer container add --name wiki-help --type project
...
2024-10-15T14:23:56.922+0300 info Project добавлен
В терминале так же будет выведен вывод с JSON строкой следующего вида
{"Containers":[{"id":"550eaba9-39e8-48f7-b8b0-7bde24535d95","name":"wiki-help","type":"project"}]}
Для создания ветки надо указать проект в которые её добавлять, для этого используется опция <code>--parent</code>
svacer container add --name wiki-help-branch --type branch --parent 550eaba9-39e8-48f7-b8b0-7bde24535d95
В терминале так же будет выведен вывод с JSON строкой результата действия:
{"Containers":[{"id":"a162cb5b-d09b-4a34-a4a8-818a9a0f32de","name":"wiki-help-branch","type":"branch","parent":"550eaba9-39e8-48f7-b8b0-7bde24535d95"}]}
При создании проекта можно так же указать параметр <code>--review-with-comment</code> для создания проекта с обязательным комментарием при изменении разметки. Если параметр не передавать, проект создаётся без этого требования.

=== Удаление ветки, проекта или группы проектов ===
Удаление контейнера осуществляется командой <code>svacer container remove</code> c указанием ID и типа удаляемого объекта: <code>project</code>, <code>branch</code>, <code>project-group</code>. Например так удаляется проект
svacer container remove --id 550eaba9-39e8-48f7-b8b0-7bde24535d95 --type project
...
2024-10-15T14:34:48.725+0300 info Удаление завершено
В терминале так же будет выведен вывод с JSON строкой следующего вида
{"Containers":[{"id":"550eaba9-39e8-48f7-b8b0-7bde24535d95","name":"wiki-help","type":"project"}]}

=== Список веток, проектов или групп проектов ===
С помощью команды <code>svacer container list</code> можно просмотреть связи между контейнерами. С помощью опции <code>--name</code> можно ограничить возвращаемые значения, например запрос по <code>wiki без указания типа, вернёт все контейнеры с именем содержащим это значение</code>
svacer container list --name wiki

{"Containers":[{"id":"550eaba9-39e8-48f7-b8b0-7bde24535d95","name":"wiki-help","type":"project"},{"id":"a162cb5b-d09b-4a34-a4a8-818a9a0f32de","name":"wiki-help-branch","type":"branch","parent":"550eaba9-39e8-48f7-b8b0-7bde24535d95"}]}
Если добавить опцию <code>--format text</code> то возвращаемое значение будет отформатировано к такому виду:
Id: 550eaba9-39e8-48f7-b8b0-7bde24535d95, Name: wiki-help, Type: project, ReviewWithComment: false
Id: a162cb5b-d09b-4a34-a4a8-818a9a0f32de, Name: wiki-help-branch, Type: branch, Parent: 550eaba9-39e8-48f7-b8b0-7bde24535d95
Если указать тип ветки, то в результате так же вернётся список снимков в данной ветке.
svacer container list --id 6367355f-bcf7-4f3a-a9dc-00ec8b0d7806 --type branch

{"Containers":[{"id":"87193c7b-6fb9-4eb5-bf55-d7e88e2cfc25","name":"snapshotname","type":"snapshot","parent":"6367355f-bcf7-4f3a-a9dc-00ec8b0d7806"}]}

=== Редактирование ветки, проекта или группы проектов ===
Для изменения названия ветки или настроеек проекта существует команда <code>svacer container update</code>. Для изменения надо передать ID объекта, новое имя и опцию для проекта.
svacer container update --name wiki-help_changed --id 550eaba9-39e8-48f7-b8b0-7bde24535d95 --review-with-comment
...

2024-10-15T14:55:20.043+0300 info Редактирование завершено
В <code>stdout</code> результат операции представлен с новыми значениями
{"Containers":[{"id":"550eaba9-39e8-48f7-b8b0-7bde24535d95","name":"wiki-help_changed","type":"project","review_with_comment":true}]}

=== Клонирование ветки или проекта ===
Клонирование осуществляется командой <code>svacer container clone</code> с указанием типа объекта (<code>project</code> или <code>branch</code>), объекта клонирования (через <code>--parent</code>) и имени клонированного объекта с дополнительными параметрами (группы проектов и обязательности комментария) . Клонирование ветки происходит с ожиданием окончания, а завершения клонирование проекта по умолчнию не ожидается. Для ожидания можно использовать параметр <code>--wait</code>.
svacer container clone --name wiki-help_clone --parent 550eaba9-39e8-48f7-b8b0-7bde24535d95 --review-with-comment true --type project
...
2024-10-15T15:09:00.012+0300 info Клонирование проекта запущено
При этом выводится ID задачи клонирования, для большого проекта можно её отменить
{
"id": "7c3fae83-ba42-450f-af71-91400f50c2fc"
}
Проекты клонируются в порядке очерёдности на сервере, два клонирования проектов паралелльно не запускаются.

==== Получение состояния и отмена текущей задачи клонирования ====
Подкомандами <code>status</code> и <code>cancel</code> можно отменить или получить результаты клонирования. Тут надо учесть что параметры соединения с сервером и данные пользователя надо указывать между <code>clone</code> и подкомандой.
svacer container clone {host/user settings} status --id cd143fd6-17df-4259-a020-f54982040e09
Для статуса будет содержать информацию по всем клонированным веткам в проекте.

=== Управление снимками ===
Снимки можно переименовывать и удалять. Создание снимков происходит только при иморте извне.

==== Переименование и удаление снимков ====
Подкомандами <code>rename</code> и <code>remove</code> можно переименовать или удалить снимок. Для переименования достаточно указать текущий ID снимка и новое название. Для удаления можно так же указать только ID снимка, или проект/ветку/снимок.
svacer container snapshot rename --id 87193c7b-6fb9-4eb5-bf55-d7e88e2cfc25 --name hahah
В данном случае результат операции не печатается, но его можно проверить через команду <code>svacer container list</code>.

==== [ЭКСПЕРИМЕНТАЛЬНО] Слияние снимков ====
Слияния снимков позволяет объеденить несколько снимков в один командой <code>svacer container snapshot merge</code>. В неё передаётся список снимков для слияния, названия результирующего снимка и дополнительные опции (типа удалять ли старые снимки).
svacer container snapshot merge --snapshot {snap1_id} --snapshot {snap2_id} --snapshot {snap3_id} --branch {branch_id} --name target_branch

=== Управление группами проектов ===
Группы проектов это опциональный способ группировки проектов, проекты можно добавить в несколько групп, так и не добавлять ни в одну группу. Поэтому управление выделено в отдельный набор команд. Для управления необходимо чтобы объекты уже существовали на сервере.

==== Добавление проекта в группу проектов ====
Можно передавать как ID объектов, так и их названия. Добавление в групп проектов происходит такой командой
svacer container project-groups add --project {prj_id} --project-group {project_group_id}

==== Удалить проект из группы проектов ====
Удаление из группы происходит практически таким же образом, но с помощью команды <code>remove</code>
svacer container project-groups remove --project {prj_id} --project-group {project_group_id}

Help:Utils

2024-08-27T06:56:38Z

Writer:

== Утилиты ==
=== pfixer ===
pfixer -- утилита для исправления путей при экспорте снимков в файл. Замена путей в существующем снимке опасна, поэтому предлагается делать экспорт снимка с заменой путей. При необходимости исходный снимок пользователь может удалить с сервера.

Утилита так же работает со снимками в файлах. pfixer поддерживает версии Svacer начиная с версии 7, но поставляется после 9-0-2. Исполняемый файл находится в bin.

Для работы с утилитой необходимо создать файл содержащий правила замены путей. Это должен быть юниксовый текстовый файл (разделитель строк знак '\n'). Каждая строчка должна содержать заменяемый префикс и значение, разделённый двоеточием. Если префикс должен быть удалён, для замены используется знак '-'. Его указать можно через опцию --map-file или через stdin.

<pre>
<префикс1>:<замена1>
<префикс2>:<замена2>
<префикс3>:<замена3>
<префикс4>:-
</pre>

Так же есть возможность использовать регулярные выражения (в экспериментальной стадии) из языка Golang (https://pkg.go.dev/regexp#Regexp.ReplaceAllString). В этом случае использовать надо знак '@' в начале строки. Так же можно использовать $var для ссылок на группы в регулярном выражении.

<pre>
@<регулярное_выражение1>:<замена>
@<регулярное_выражение2>:-
</pre>

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

Авторизацию на сервере можно передать через опции --credentials вида login:password или --token сразу токен авторизации.

Исходный снимок с сервера можно передать сразу ссылкой с сайта.

Примеры
<pre>
pfixer --source http://svacer/mode/review/project/{project}/branch/{branch}/snapshot/{snapshot} --output updated.snap --credentials login:password --map-file map.txt
pfixer --source input.snap --output updated.snap -map-file map.txt --log-file test.log
pfixer --source input.snap --output updated.snap --log-file test.log | cat map.txt
</pre>

Help:Utils

2024-08-27T06:54:15Z

Writer: ошибка в описании

== Утилиты ==
=== pfixer ===
pfixer -- утилита для исправления путей при экспорте снимков в файл. Замена путей в существующем снимке опасна, поэтому предлагается делать экспорт снимка с заменой путей. При необходимости исходный снимок пользователь может удалить с сервера.

Утилита так же работает со снимками в файлах. pfixer поддерживает версии Svacer начиная с версии 7, но поставляется после 9-0-2. Исполняемый файл находится в bin.

Для работы с утилитой необходимо создать файл содержащий правила замены путей. Это должен быть юниксовый текстовый файл (разделитель строк знак '\n'). Каждая строчка должна содержать заменяемый префикс и значение, разделённый двоеточием. Если префикс должен быть удалён, для замены используется знак '-'. Его указать можно через опцию --map-file или через stdin.

<pre>
<префикс1>:<замена1>
<префикс2>:<замена2>
<префикс3>:<замена3>
<префикс4>:-
</pre>

Так же есть возможность использовать регулярные выражения (в экспериментальной стадии) из языка Golang (https://pkg.go.dev/regexp#Regexp.ReplaceAllString). В этом случае использовать надо знак '@' в начале строки. Так же можно использовать $var для ссылок на группы в регулярном выражении.

<pre>
@<регулярное_выражение1>:<замена>
@<регулярное_выражение2>:-
</pre>

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

Авторизацию на сервере можно передать через опции --credentials вида login:password или --token сразу токен авторизации.

Исходный снимок с сервера можно передать сразу ссылкой с сайта.

Примеры
<pre>
pfixer --source http://svacer/mode/review/project/{project}/branch/{branch}/snapshot/{snapshot} --output updated.snap --credentials login:password --map-file map.txt
pfixer --source input.snap --output updated.snap -map-file map.txt --log-file test.log
pfixer --source input.snap --output updated.snap --log-file test.log | cat map.txt
</pre>

Help:Utils

2024-08-27T06:35:03Z

Writer: Создание страницы для описания pfixer

== Утилиты ==
=== pfixer ===
pfixer -- утилита для исправления путей при экспорте снимков в файл. Замена путей в существующем снимке опасна, поэтому предлагается делать экспорт снимка с заменой путей. При необходимости исходный снимок пользователь может удалить с сервера.

Утилита так же работает со снимками в файлах. pfixer поддерживает версии Svacer начиная с версии 7, но поставляется после 9-0-2. Исполняемый файл находится в bin.

Для работы с утилитой необходимо создать файл содержащий правила замены путей. Это должен быть юниксовый текстовый файл (разделитель строк знак '\n'). Каждая строчка должна содержать заменяемый префикс и значение, разделённый двоеточием. Если префикс должен быть удалён, для замены используется знак '-'. Его указать можно через опцию --map-file или через stdin.

<pre>
<префикс1>:<замена1>
<префикс2>:<замена2>
<префикс3>:<замена3>
<префикс4>:-
</pre>

Так же есть возможность использовать регулярные выражения (в экспериментальной стадии) из языка Golang (https://pkg.go.dev/regexp#Regexp.ReplaceAllString). В этом случае использовать надо знак '@' в начале строки. Так же можно использовать $var для ссылок на группы в регулярном выражении.

<pre>
@<регулярное_выражение1>:<замена>
@<регулярное_выражение2>:-
</pre>

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

Авторизацию на сервере можно передать через опции --credentials вида login:password или --token сразу токен авторизации.

Исходный снимок с сервера можно передать сразу ссылкой с сайта.

Примеры
<pre>
pfixer --source http://svacer/mode/review/project/{project}/branch/{branch}/snapshot/{snapshot} --output updated.snap --credentials login:password --map-file map.txt
pfixer --source input.snap --output updated.snap -map-file map.txt --log-file test.log
pfixer --source input.snap --output updated.snap --log-file test.log | cat map.txt
</pre>

Svacer

2024-08-27T05:43:14Z

Writer:

Svacer — сервер для хранения и обработки результатов статического анализа. Поддерживает импорт результатов анализа из [https://svace.ispras.ru Svace] напрямую и из прочих анализаторов через формат [[Help:Sarif|SARIF]].

=== Техническая документация ===
Version 9.0.x
# [[Help:Introduction|Введение]]
# [[Help:Installation|Установка и обновление]]
# [[Help:Import from Svace|Импорт из Svace]]
# [[Help:Backup|Резервное копирование]]
# [[Help:UI manual|Использование веб-интерфейса]]
# [[Help:Public API|Public REST API]]
# [[Help:CLI|CLI]]
# [[LDAP configuration|LDAP]]
# [[OIDC|OpenID Connect]]
# [[Help:Sarif|SARIF]]
# [[Help:Statistics|Статистика]]
# [[Help:Match|Механизмы сопоставления предупреждений и переноса разметки]]
# [[Help:XSvacer|XSvacer — расширение функциональности Svacer]]
# [[Help:Utils|Утилиты поставляемые с Svacer]]

=== Релизы ===
Также доступны в виде docker-образа на [https://hub.docker.com/r/ispras/svacer docker hub] и как пакеты в [[Help:Installation#.deb|apt-репозитории]]

{| class="wikitable"
! version !! zip !! linux !! windows !! deb/rpm !! doc
|-
| 9.0.2
| [https://svacer.ispras.ru/releases/svacer-9-0-2/svacer-9-0-2.zip svacer-9-0-2.zip]
| [https://svacer.ispras.ru/releases/svacer-9-0-2/svacer svacer] [https://svacer.ispras.ru/releases/svacer-9-0-2/svacer-server svacer-server]
| [https://svacer.ispras.ru/releases/svacer-9-0-2/svacer.exe svacer.exe] [https://svacer.ispras.ru/releases/svacer-9-0-2/svacer-server.exe svacer-server.exe]
| [https://svacer.ispras.ru/releases/svacer-9-0-2/svacer_9.0-2_amd64.deb svacer_9.0-2_amd64.deb] [https://svacer.ispras.ru/releases/svacer-9-0-2/svacer-9.0-2.x86_64.rpm svacer-9.0-2.x86_64.rpm]
| [[Changelog#Release 9-0-2|Changelog]] [[Help:Installation#9-0-0|Upgrade notes]] [[Svacer#Техническая_документация|Documentation 9.x.x]]
|-
| 9.0.1
| [https://svacer.ispras.ru/releases/svacer-9-0-1/svacer-9-0-1.zip svacer-9-0-1.zip]
| [https://svacer.ispras.ru/releases/svacer-9-0-1/svacer svacer] [https://svacer.ispras.ru/releases/svacer-9-0-1/svacer-server svacer-server]
| [https://svacer.ispras.ru/releases/svacer-9-0-1/svacer.exe svacer.exe] [https://svacer.ispras.ru/releases/svacer-9-0-1/svacer-server.exe svacer-server.exe]
| [https://svacer.ispras.ru/releases/svacer-9-0-1/svacer_9.0-1_amd64.deb svacer_9.0-1_amd64.deb] [https://svacer.ispras.ru/releases/svacer-9-0-1/svacer-9.0-1.x86_64.rpm svacer-9.0-1.x86_64.rpm]
| [[Changelog#Release 9-0-1|Changelog]] [[Help:Installation#9-0-0|Upgrade notes]] [[Svacer#Техническая_документация|Documentation 9.x.x]]
|-
| 9.0.0
| [https://svacer.ispras.ru/releases/svacer-9-0-0/svacer-9-0-0.zip svacer-9-0-0.zip]
| [https://svacer.ispras.ru/releases/svacer-9-0-0/svacer svacer] [https://svacer.ispras.ru/releases/svacer-9-0-0/svacer-server svacer-server]
| [https://svacer.ispras.ru/releases/svacer-9-0-0/svacer.exe svacer.exe] [https://svacer.ispras.ru/releases/svacer-9-0-0/svacer-server.exe svacer-server.exe]
| [https://svacer.ispras.ru/releases/svacer-9-0-0/svacer_9.0-0_amd64.deb svacer_9.0-0_amd64.deb] [https://svacer.ispras.ru/releases/svacer-9-0-0/svacer-9.0-0.x86_64.rpm svacer-9.0-0.x86_64.rpm]
| [[Changelog#Release 9-0-0|Changelog]] [[Release notes 9-0-0|Release notes]] [[Help:Installation#9-0-0|Upgrade notes]] [[Svacer#Техническая_документация|Documentation 9.x.x]]
|-
| 8.0.1
| [https://svacer.ispras.ru/releases/svacer-8-0-1/svacer-8-0-1.zip svacer-8-0-1.zip]
| [https://svacer.ispras.ru/releases/svacer-8-0-1/svacer svacer]
| [https://svacer.ispras.ru/releases/svacer-8-0-1/svacer.exe svacer.exe]
| [https://svacer.ispras.ru/releases/svacer-8-0-1/svacer_8.0-1_amd64.deb svacer_8.0-1_amd64.deb] [https://svacer.ispras.ru/releases/svacer-8-0-1/svacer-8.0-1.x86_64.rpm svacer-8.0-1.x86_64.rpm] [https://svacer.ispras.ru/releases/svacer-8-0-1/svacer-8.0.1.msi svacer-8.0.1.msi]
| [[Changelog#Release 8-0-1|Changelog]] [[Documentation 8.x.x|Documentation 8.x.x]]
|-
| 8.0.0
| [https://svacer.ispras.ru/releases/svacer-8-0-0/svacer-8-0-0.zip svacer-8-0-0.zip]
| [https://svacer.ispras.ru/releases/svacer-8-0-0/svacer svacer]
| [https://svacer.ispras.ru/releases/svacer-8-0-0/svacer.exe svacer.exe]
| [https://svacer.ispras.ru/releases/svacer-8-0-0/svacer_8.0-0_amd64.deb svacer_8.0-0_amd64.deb] [https://svacer.ispras.ru/releases/svacer-8-0-0/svacer-8.0-0.x86_64.rpm svacer-8.0-0.x86_64.rpm] [https://svacer.ispras.ru/releases/svacer-8-0-0/svacer-8.0.0.msi svacer-8.0.0.msi]
| [[Changelog#Release 8-0-0|Changelog]] [[Release notes 8-0-0|Release notes]] [[Documentation 8.x.x|Documentation 8.x.x]]
|}

[https://svacer.ispras.ru/releases Предыдущие релизы] | [https://nextcloud.ispras.ru/index.php/s/x4r4cMJAMr5RZtd?path=%2F Еще более старые релизы]

=== FAQ ===
* [https://gitlab.ispras.ru/svace/svace-support/-/wikis/home Документация на статический анализатор Svace]
* [[Help:Introduction#Системные требования|Системные требования]]
* [[Примеры использования хуков#Создание кейсов в системах отслеживания ошибок|Создание из Svacer кейсов в Gitlab, Jira, Redmine]]
* Public REST API
:* [[Help:Public API#Примеры использования public REST API|Примеры использования]]
:* [https://gitlab.ispras.ru/svacer-public Репозитории с примерами на Python и Go]
:* [https://svacer-demo.ispras.ru/api/public/swagger/ Спецификация OpenAPI]
* [https://t.me/+6pvgZ0oveNVhOTc6 Группа технической поддержки в Telegram]

=== Демо ===
Попробуйте Svacer в действии на демо-сервере: https://svacer-demo.ispras.ru
* admin / svacer_admin_31415 — логин / пароль администратора
* user / user — логин / пароль пользователя

Можете делать там что угодно, каждую ночь сервер восстанавливается до изначального состояния.

Help:UI manual

2024-02-20T07:45:24Z

Writer: Добавлен раздел Известные ограничения

На этой странице приведена инструкция по работе в пользовательском интерфейсе сервера Svacer.

== Авторизация в пользовательском интерфейсе сервера Svacer ==

Для авторизации в пользовательском интерфейсе сервера Svacer введите логин и пароль на странице ввода учётных данных. Учётные данные по умолчанию — admin / admin.
[[File:Авторизация 01.png|thumb|none|x300px|alt=AutorizationMain|Страница ввода учетных данных]]

Если на сервере настроена поддержка протокола LDAP, то войти можно с помощью внешних серверов. Для этого:

# На странице ввода учетных данных перейдите на вкладку '''LDAP'''.
# Выберите LDAP-сервер в списке, если настроено больше одного сервера авторизации.
# Введите логин и пароль.

[[File:Авторизация LDAP 02.png|thumb|none|x300px|alt=AutorizationLDAP|Страница входа по протоколу LDAP]]

После успешного входа отобразится пользовательский интерфейс сервера Svacer. При этом, если в прошлой сессии пользователь [[Help:UI manual#Выбор контекста (проекта, ветки и снимка)|выбрал проект, его ветку и снимок]] или [[Help:UI manual#Использование фильтров|применил фильтры]], отобразятся эти проект, ветка и фильтры.

'''''Примечание''': чтобы после обновления системы в пользовательском веб-интерфейсе корректно отображались изменения, после авторизации обновите страницу в браузере – нажмите клавишу F5.''

== Описание основных элементов пользовательского интерфейса ==
Все страницы пользовательского интерфейса сервера Svacer устроены единообразно и состоят из двух частей:
# Верхняя панель – отображается на всех страницах пользовательского интерфейса Содержит:
#* логотип сервера Svacer
#* [[File:04 Кнопки для переключения режимов работы.png|x25px]] – кнопки для переключения режимов работы:
#** '''Разметка''' – [[Help:UI manual#Работа в режиме просмотра кода|просмотр и разметка найденных маркеров]], а также [[Help:UI manual#Сравнение снимков и маркеров|сравнение снимков или отдельных маркеров]];
#** '''Код''' – [[Help:UI manual#Работа в режиме разметки|просмотр снимков исходного кода]], связанного с результатами анализатора Svace;
#** '''Проекты''' – [[Help:UI manual#Управление проектами и группами проектов|управление проектами]] (режим доступен только пользователям с ролью admin);
#** '''Отчеты''' – [[Help:UI manual#Режим формирования отчетов|формирование отчетов]] на основе хранимой информации;
#* [[File:Icon settings.png|x25px]] – кнопка для перехода к [[Help:UI manual#Настройка сервера Svacer|настройке системы]]
#* [[File:Icon RuEng.png|x25px]] – переключатель языка пользовательского интерфейса
#* [[File:Icon question mark.png|x25px]] – кнопка для перехода на страницу документации к системе
#* [[File:Icon bell.png|25px]] – кнопка для перехода к [[Help:UI manual#Просмотр уведомлений|уведомлениям]]
#* [[File:Icon profile.png|x25px]] – кнопка меню пользователя, которое предоставляет следующие функции:
#** переход к [[Help:UI manual#Настройка профиля пользователя|настройке профиля пользователя]];
#** [[Help:UI manual#Выход из системы|выход из системы]];
#** [[Help:UI manual#Просмотр информации о программе|просмотр информации о программе]].
# Рабочая область – область экрана для просмотра информации и ввода, которая соответствует выбранному режиму работы или странице настроек.

:[[File:03 Основные элементы интерфейса – без VSCode.png|thumb|none|upright=3]]

== Базовые функции системы ==
=== Просмотр уведомлений ===
Чтобы посмотреть уведомления, нажмите кнопку [[File:Icon bell.png|25px]] в правом верхнем углу экрана.

В правой части экрана отобразится панель со списком уведомлений для авторизованного пользователя:
[[File:05 Уведомления.png|thumb|none|x300px|alt=NotificationList|Панель уведомлений]]

Нажмите кнопку [[File:Icon cross 01.png|15px]] для удаления уведомления.

Нажмите кнопку '''Очистить''' для удаления всех уведомлений.

=== Настройка профиля пользователя ===
Для перехода в профиль выберите пункт '''Профиль''' в меню пользователя в правом верхнем углу экрана:
[[File:06 Меню пользователя — без VSCode.png|thumb|none|250px|alt=UserMenu|Меню пользователя. Переход к настройке профиля]]

В правой части экрана отобразится панель '''Профиль''', которая состоит из трех разделов:
:1. '''Профиль пользователя''' – в этом разделе можно изменить атрибуты своего профиля (ФИО, контакты), кроме логина, а также [[Help:UI manual#Изменение пароля|поменять пароль]].
:[[File: 07 Профиль основные параметры.png|thumb|none|x400px|alt=ProfileSetting|Настройки профиля пользователя]]

:2. '''Общие настройки интерфейса''' – в этом разделе можно включить или выключить следующие функции:
:* сохранение примененной сортировки значений [[Help:UI manual#Таблица маркеров|в таблице маркеров]] при [[Help:UI manual#Выход из системы|выходе из системы]];
:* использование темной темы (темный фон, светлый текст) при просмотре файлов с исходным кодом;
:* переиспользование вкладки с исходным кодом [[Help:UI manual#Работа в режиме просмотра кода|в редакторе кода]].
:Эти настройки сохраняются для учетной записи пользователя и не сбрасываются при новой сессии.
:[[File:08 Профиль общие настройки интерфейса.png|thumb|none|x400px|alt=UserInterfaceSettings|Общие настройки интерфейса]]

:3. '''Настройки панели навигации''' – в этом разделе можно настроить отображение по умолчанию для детекторов и файлов [[Help:UI manual#Функции левой навигационной панели|на панели навигации]], а также для сортировки значений [[Help:UI manual#Вкладка «Файлы»|на вкладке '''Файлы''']].
:Эти настройки сохраняются для учетной записи пользователя и не сбрасываются при новой сессии.
:Временное отображение файлов [[Help:UI manual#Функции левой навигационной панели|на панели навигации]] и их сортировку можно настроить по нажатии иконки [[File:Icon wrench.png|x15px]] на панели навигации.
:[[File:09 Профиль глобальные настройки навигации.png|thumb|none|x400px|alt=LeftNavigationPanelSettings|Настройки панели навигации]]

=== Изменение пароля ===
Для изменения пароля:
:1. Выберите пункт '''Профиль''' в меню пользователя.
:2. В разделе '''Профиль пользователя''' нажмите на ссылку '''Изменить пароль''':
:[[File:10_Профиль_изменение пароля.png|thumb|none|450px|Переход к изменению пароля в профиле пользователя]]
:3. В открывшемся окне:
::а) Введите текущий пароль.
::б) Дважды введите новый пароль.
::в) Нажмите кнопку '''Изменить'''.
::[[File:11_Профиль_ввод нового пароля.png|thumb|none|350px|Окно изменения пароля]]

=== Просмотр информации о программе ===
Чтобы посмотреть информацию о программе, выберите пункт '''О программе''' в меню пользователя в правом верхнем углу экрана.
[[File:12_Меню пользователя_о программе — без VSCode.png|thumb|none|250px|Меню пользователя. Переход к просмотру информации о программе]]
Нажмите на ссылку в строке '''Документация''' для перехода на страницу документации к системе.

Для просмотра информации об изменениях нажмите кнопку '''Показать Журнал изменений'''.

[[File:13_О программме.png|thumb|none|600px|Информация о программе]]

== Выбор контекста (проекта, ветки и снимка) ==
Для работы [[Help:UI manual#Работа в режиме разметки|в режиме разметки]] или [[Help:UI manual#Работа в режиме просмотра кода|режиме просмотра кода]] требуется выбрать проект, ветку и снимок с результатами работы анализатора Svace, а в режиме формирования отчетов – проект и ветку. Это можно сделать в блоке, который расположен под [[Help:UI manual#Описание основных элементов пользовательского интерфейса|верхней панелью]].

[[File:14_Выбор проекта, верки, снимка.png|800px]]

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

== Работа в режиме разметки ==
Режим разметки предоставляет следующий набор элементов управления:
# Левая навигационная панель:
#* [[Help:UI manual#Вкладка «Детекторы»|вкладка '''Детекторы''']];
#* [[Help:UI manual#Вкладка «Файлы»|вкладка '''Файлы''']].
# Центральная панель:
#* [[Help:UI manual#Вкладка «Информация о снимке»|вкладка '''Информация о снимке''']];
#* одна или несколько [[Help:UI manual#Вкладка с исходным кодом|вкладок с исходным кодом''']] (отображаются после выбора файлов в таблице маркеров или левой панели);
#* [[Help:UI manual#Таблица маркеров|таблица маркеров]];
# [[Help:UI manual#Функции правой панели|Правая панель]].

[[File:96 Режим разметки. Набор элементов управления.png|800px|thumb|none|Режим разметки. Набор элементов управления]]

=== Функции левой навигационной панели ===
==== Вкладка «Детекторы» ====
На этой вкладке отображается список детекторов Svace, которые сработали в выбранном снимке.

Серьезность (критичность) детектора обозначена цветом:
* красный – наивысшая серьезность (CRITICAL);
* желтый – высокая серьезность (MAJOR);
* белый – обычная серьезность (NORMAL, MINOR, UNDEFINED).

На вкладке '''Детекторы''' пользователю доступны следующие функции:
:1. Отображение данных в виде списка – для этого нажмите кнопку [[File:icon_list.png|x25px]].
:2. Группировка детекторов по уровням серьезности (по умолчанию) – для этого нажмите кнопку [[File:icon_tree.png|x25px]].
<gallery mode="packed" heights="250px" style="float:left; clear:right; margin-right:1em; margin-left:1em">
16_Детекторы_список.png|Вкладка '''Детекторы''' с данными в виде списка
15_Детекторы_группировка.png|Вкладка '''Детекторы''' с группировкой детекторов по уровням серьезности
</gallery>
 
:3. Отображение списка маркеров в файлах, в которых сработал детектор – для этого нажмите кнопку [[File:icon_uncover.png|x15px]] в левой части его имени.
:[[File:checker_uncover.png|thumb|none|320px|Список маркеров, найденных детектором]]
:4. [[Help:UI manual#Блокировка разметки|Блокировка всех маркеров]], найденных детектором, для разметки другими пользователями – для этого нажмите кнопку [[File:icon_unlocked.png|x25px]] справа от названия детектора (отображается при наведении курсора).
:5. Применение фильтра по детектору [[Help:UI manual#Таблица маркеров|в таблице маркеров]] – для этого нажмите на имя детектора.
:6. Применение фильтра по серьезности [[Help:UI manual#Таблица маркеров|в таблице маркеров]] – для этого нажмите название группы серьезности.
:7. Отмена фильтрации – для этого нажмите кнопку [[File:icon_return.png|x25px]].
:8. Отображение [[Help:UI manual#Вкладка с исходным кодом|на вкладке исходного кода]] содержимого файла, места и содержания маркера, а также подробной информации о маркере [[Help:UI manual#Функции правой панели|на правой панели]] – для этого нажмите на маркер.
:9. Просмотр фрагмента кода в режиме предпросмотра – для этого нажмите кнопку [[File:Icon_goto.png|x25px]].

==== Вкладка «Файлы» ====
На этой вкладке отображается список файлов, в которых найдены маркеры.

[[File:17 Файлы.png|thumb|none|300px|Вкладка '''Файлы''']]

Для каждого файла отображаются:
* имя;
* количество найденных маркеров (предупреждений);
* количество размеченных маркеров;
* кнопки [[File:Icon plus.png|x25px]] и [[File:Icon minus.png|x25px]].

На вкладке '''Файлы''' пользователю доступны следующие функции:
:1. Применение фильтра по файлу [[Help:UI manual#Таблица маркеров|в таблице маркеров]] – для этого:
::а) Нажмите на имя файла. В этом случае содержимое файла отобразится [[Help:UI manual#Вкладка с исходным кодом|на вкладке с исходным кодом]] или
::б) Нажмите кнопку [[File:Icon plus.png|x25px]] в одной или нескольких строках. В этом случае содержимое файла (файлов) не отобразится.
:2. Исключение файла из фильтра по файлам [[Help:UI manual#Таблица маркеров|в таблице маркеров]] – для этого нажмите кнопку [[File:Icon minus.png|x25px]] в строке файла.
:3. Отмена фильтрации [[Help:UI manual#Таблица маркеров|в таблице маркеров]] для всех выбранных файлов – для этого нажмите кнопку [[File:Icon minus 2.png|x25px]] или кнопку [[File:icon_return.png|x25px]] [[Help:UI manual#Вкладка «Детекторы»|на вкладке '''Детекторы''']].
:4. [[Help:UI manual#Блокировка разметки|Блокировка всех маркеров]] в файле для разметки другими пользователями – для этого нажмите кнопку [[File:icon_unlocked.png|x25px]] справа от названия файла (отображается при наведении курсора).
:5. Отображение [[Help:UI manual#Вкладка с исходным кодом|на вкладке с исходным кодом]] содержимого файла, места и содержания маркера, а также подробной информации о маркере [[Help:UI manual#Функции правой панели|на правой панели]] – для этого нажмите на имя файла.
:6. Фильтрация по имени/пути файла в поле '''Отфильтровать файлы по полному пути'''. Поддерживается фильтрация с использованием [[Help:UI manual#Использование регулярных выражений|регулярных выражений]].
:7. Временная настройка отображения файлов и сортировки полей на вкладке '''Файлы''' – для этого нажмите кнопку [[File:icon_wrench.png|x25px]] и поменяйте настройки.
:Эти настройки будут действовать до конца сессии пользователя или до повторного изменения.

:[[File:18 Временная настройка панели навигации.png|thumb|none|800px|Временная настройка отображения файлов и сортировки полей]]

=== Функции центральной панели ===
==== Вкладка «Информация о снимке» ====
На этой вкладке отображается информация о выбранном снимке.

[[File:19 Информация о снимке.png|thumb|left|600px|Вкладка '''Информация о снимке''']]
 
На вкладке '''Информация о снимке''' пользователю доступны следующие функции:
# Просмотр подробной информации о снимке во всплывающем окне – для этого нажмите кнопку [[File:Icon info.png|x25px]].
# Переход к [[Help:UI manual#Экспорт кода с разметкой|экспорту кода с разметкой]] – для этого нажмите кнопку [[File:Icon book.png|x25px]].
# Экспорт снимка в формате .snap – для этого нажмите кнопку [[File:Icon export.png|x25px]].
# Просмотр параметров анализа во всплывающем окне – для этого нажмите кнопку [[File:Button Показать.png|x25px]] в строке '''Параметры анализа'''.
# Экспорт параметров анализа в формате .txt – для этого нажмите кнопку [[File:Button Скачать.png|x25px]] в строке '''Параметры анализа'''.
# [[Help:UI manual#Работа с таблицей статистики|Просмотр таблицы статистики]] – для этого нажмите кнопку [[File:Button Показать 2.png|x25px]] в строке '''Статистика'''. Информация в таблице сгруппирована по параметрам детекторов, найденным маркерам и статусу их разметки.
# Просмотр списка приложенных файлов для этого нажмите кнопку [[File:Button Показать.png|x25px]] в строке '''Приложенные файлы'''. Для скрытия списка нажмите кнопку [[File:Hide.png|x25px]].

==== Вкладка с исходным кодом ====
Вкладка открывается только после выбора файла [[Help:UI manual#Вкладка «Детекторы»|на вкладке '''Детекторы''']] или [[Help:UI manual#Вкладка «Файлы»|'''Файлы''']], а также [[Help:UI manual#Таблица маркеров|в таблице маркеров]]. Одновременно может быть открыто несколько вкладок с исходным кодом, если выключена [[Help:UI manual#Настройка профиля пользователя|настройка '''Переиспользование вкладки в редакторе кода''']].

В верхней части вкладки отображается полный путь к файлу.
[[File:20 Исходный код.png|thumb|none|600px|Пример двух открытых вкладок с исходным кодом]]

На вкладке с исходным кодом пользователю доступны следующие функции:
:1. Отображение кода на весь экран – для этого нажмите кнопку [[File:Icon expand.png|x25px]].
:2. Отображение всех маркеров – для этого нажмите кнопку [[File:Icon view marks.png|x25px]].
:3. Скрытие всех маркеров – для этого нажмите кнопку [[File:Icon hide marks.png|x25px]].
:4. Отображение списка маркеров в этом файле – для этого нажмите кнопку [[File:Icon list 2.png|x25px]].

:[[File:21 Исходный код Отображение списка маркеров.png|thumb|none|300px|right|Cписок маркеров в файле]]

:5. Выбор отображения информации о маркере и его разметки относительно строки кода, в которой он найден:
:* выше строки кода (по умолчанию) – нажмите кнопку [[File:Icon above.png|x25px]];
:* ниже строки кода – нажмите кнопку [[File:Icon below.png|x25px]].
<gallery mode="packed" heights="200px" style="float:left; clear:right; margin-right:1em; margin-left:2em">
File:above_marker_info.png|Пример отображения информации о маркере над строкой кода
File:below_marker_info.png|Пример отображения информации о маркере под строкой кода
</gallery>
 
:6. Возврат к исходному маркеру (например, если был выбран другой связанный маркер на вкладке '''Трасса''' [[Help:UI manual#Функции правой панели|правой панели]]) – для этого нажмите кнопку [[File:Icon target.png|x25px]] в верхней части блока с информацией о маркере.
:7. [[Help:UI manual#Разметка маркера|Разметка маркера]] – установите '''Статус''', '''Серьезность''' и '''Действия''' в верхней части блока с информацией о маркере.
:8. Отображение блока информации об элементе трассы для строки кода – нажмите кнопку '''К трассе'''.
::Для последовательного перехода к другим элементам трассы воспользуйтесь кнопками [[File:Button up.png|x25px]] и [[File:Button down.png|x25px]].
:[[File:97 Блок информации о элементе трассы.png|thumb|none|600px|Блок информации о элементе трассы]]
:9. Переход к строке, в которой объявлена/определена переменная – нажмите правую кнопку мыши на строке исходного кода и выберите пункт '''Перейти к объявлению / Перейти к определению'''.
:10. Просмотр ссылок на панели внизу экрана – нажмите правую кнопку мыши на строке исходного кода и выберите пункт '''Найти ссылки'''. На этой панели отображается иерархический список файлов с номерами строк, в которых найдены ссылки:
:[[File:Исходный_код_Референсы.png|thumb|none|600px|Cписок файлов с номерами строк, в которых найдены ссылки]]

:* Чтобы перейти к строке кода, на которую найдена ссылка, нажмите на ссылку с номером строки на панели [1].
:* Чтобы посмотреть фрагмента кода, на который найдена ссылка, в режиме предпросмотра, нажмите кнопку [[File:icon_preview_code.png|x25px]] [2].
:11. Переход к просмотру выбранного файла [[Help:UI manual#Работа в режиме просмотра кода|в режиме просмотра кода]] – нажмите правую кнопку мыши на строке исходного кода и выберите пункт '''Открыть в режиме код'''.
:12. Копирование строки кода – нажмите правую кнопку мыши на строке исходного кода и выберите пункт '''Copy'''.
:13. Вызов командной строки – нажмите правую кнопку мыши на строке исходного кода и выберите пункт '''Command Palette'''.
:[[File:25 Исходный код Вызов командной строки.png|thumb|none|600px|Командная строка]]

==== Таблица маркеров ====
Для раскрытия таблицы маркеров нажмите кнопку [[File:Button Показать таблицу.png|x25px]] в верхней части [[Help:UI manual#Функции центральной панели|центральной панели]], а для её скрытия – [[File:Button Скрыть таблицу.png|x25px]].
В верхней части таблицы находится панель, которая содержит:
* [[File:Field Детектор.png|x25px]] – поле с информацией [[Help:UI manual#Использование фильтров|о примененных фильтрах]]: как назначенных [[Help:UI manual#Функции левой навигационной панели|в навигационной панели]], так и с помощью [[Help:UI manual#Настройка и использование пользовательских фильтров|пользовательских фильтров]] и запросов
* поле запроса для фильтрации данных;
* кнопка [[File:Icon download.png|x25px]] – выгрузка отображаемых маркеров в формате .csv или .pdf;
* кнопка [[File:Icon edit.png|x25px]] – переход [[Help:UI manual#Групповая разметка маркеров|к групповой разметке]] выбранных маркеров (доступна, если выбраны маркеры в таблице).

:[[File:26 Таблица маркеров.png|thumb|none|600px|Таблица маркеров с примененными фильтрами]]

В таблице маркеров пользователю доступны следующие функции:
# Выбор маркеров для [[Help:UI manual#Групповая разметка маркеров|групповой разметки]] – для этого установите флажок в строке маркера.
# Просмотр подробной информации о маркере [[Help:UI manual#Функции правой панели|в правой панели]] и его места и содержания [[Help:UI manual#Вкладка с исходным кодом|на вкладке с исходным кодом]] – для этого дважды кликните на строку маркера или нажмите на имя файла в столбце '''Файл'''. Также для выбора можно использовать клавиши ↑ и ↓ – для перемещения по строкам, и Enter – для подтверждения выбора.
# Копирование детальной информации о маркере в буфер обмена – для этого нажмите правой кнопкой мыши на маркер и выберите пункт '''Копировать'''.
# Копирование ссылки на маркер в буфер обмена – для этого нажмите правой кнопкой мыши на маркер и выберите пункт '''Копировать ссылку на маркер'''.
# Переход к [[Help:UI manual#Сравнение маркеров|сравнению одного маркера с другим]] – для этого нажмите правой кнопкой мыши на маркер и выберите пункт '''Сравнить с ...'''

=== Функции правой панели ===
Эта панель предоставляет подробную информацию о маркере и его [[Help:UI manual#Разметка маркера|разметке]]:
* статус [[Help:UI manual#Блокировка разметки|блокировки разметки]];
* статус [[Help:UI manual#Разметка маркера|разметки, его серьезность и требуемое действие]];
* автор последней разметки и прочее;
[[File:27 Правая панель.png|thumb|none|upright=3|Правая панель]]

На правой панели пользователю доступны следующие функции:
:1. Копирование ссылки на маркер – для этого нажмите кнопку [[File:Icon copy link.png|x25px]].
:2. [[Help:UI manual#Блокировка разметки|Блокировка маркера]] для разметки другими пользователями – для этого нажмите кнопку [[File:icon_unlocked.png|x25px]] в верхней части правой панели.
:3. [[Help:UI manual#Разметка маркера|Разметка маркера]] – для этого установите '''Статус''', '''Серьезность''' и '''Действие''' в верхней части правой панели.
:4. Просмотр истории разметки со связанными комментариями – для этого нажмите кнопку [[File:Icon history.png|x25px]] в верхней части правой панели.
:[[File:28 История изменения маркера.png|thumb|none|upright=2.5|Пример истории изменения разметки маркера]]

:5. Отображение маркера [[Help:UI manual#Вкладка с исходным кодом|на вкладке с исходным кодом]] одним из двух способов:
::а) Нажмите кнопку с именем файла и номером строки в верхней части правой панели [1].
::б) Нажмите кнопку '''Найти в коде''' на вкладке '''Подробности''' [2]. Это позволяет всегда вернуться к нужной точке при навигации по коду.
:[[File:29 Отображение маркера в коде 1.png|thumb|none|upright=2|Правая панель. Способы перехода к маркеру на вкладке с исходным кодом]]
:6. Переход к блоку с информацией об элементе трассы – для этого нажмите на ссылку с именем файла и номером строки на вкладке '''Трасса''' [1].
:7. Отображение кода, который соответствует строке трассы, в отдельном окне в режиме предпросмотра – для этого на вкладке '''Трасса''' нажмите кнопку [[File:Icon preview code.png|x25px]] рядом с именем файла и номером строки [2].
:[[File:31 Предпросмотр кода.png|thumb|none|upright=2.5|Элементы управления для работы с элементом трассы]]
:8. Просмотр и добавление комментариев к маркеру на вкладке '''Комментарии'''. Комментарии для каждого маркера уникальны. Добавление одинаковых комментариев недоступно.
:9. Редактирование и удаление комментариев на вкладке '''Комментарии''' с помощью кнопок [[File:Icon edit2.png|x25px]] и [[File:Icon delete.png|x25px]].
:Если [[Help:UI manual#Работа с проектами|для проекта]] установлен флажок '''Обязательный комментарий при разметке''', то удаление связанного с разметкой комментария недоступно. Его можно только отредактировать.
:[[File:32 Комментарии.png|thumb|none|upright=2|Вкладка '''Комментарии''']]
:'''Примечание:''' ''Пользователь может отредактировать и удалить только свои комментарии. Пользователю с доступом '''Изменение любых комментариев''' доступно редактирование и удаление комментариев всех пользователей. Если такой пользователь внёс изменения, то изначальный автор теряет возможность изменять свой комментарий (если у него нет доступа '''Изменение любых комментариев'''), так как авторство передаётся пользователю, который последним внёс изменения. Для отредактированного комментария отображается слово '''изменено''', при наведении курсора на которое отображается сообщение с логином пользователя, изменившего комментарий, и датой редактирования.''

:10. Просмотр подробной информации на вкладке '''Подробности'''.
:[[File:33 Подробная информация о маркере.png|thumb|none|upright=2|Вкладка '''Подробности''']]
:11. Просмотр информации о детекторе, который обнаружил маркер, – для этого нажмите на его имя на вкладке '''Подробности'''.
:[[File:34 Информация о детекторе.png|thumb|none|upright=2.5|Пример информации о детекторе]]
:12. Просмотр истории обнаружения маркера в снимках – для этого нажмите кнопку [[File:Icon history.png|x25px]] слева от названия снимка на вкладке '''Подробности'''.
:[[File:35 История маркера.png|thumb|none|upright=2.5|Пример истории маркера]]
:13. Запуск хуков (скриптов) – для этого нажмите кнопку '''Запустить''' на вкладке '''Подробности''' и выберите хук, который требуется запустить.
 

=== Использование фильтров ===
==== Общая информация ====
Настройка и использование фильтров доступны [[Help:UI manual#Работа в режиме разметки|в режиме разметки]].

Существует пять видов фильтров:

# Фильтры [[Help:UI manual#Функции левой навигационной панели|левой навигационной панели]] [1]: детекторы, файлы или серьезность.
# Доступные для разметки – позволяют отобразить только маркеры, которые доступны пользователю для разметки, т. е. при использовании этого фильтра в списке не будут отображаться маркеры, заблокированные другими пользователями. Фильтр применяется по нажатии кнопки [[File:Icon view2.png|x25px]] [2] в правой части блока [[Help:UI manual#Выбор контекста (проекта, ветки и снимка)|выбора проекта, ветки и снимка]].
# Размеченный – позволяют отобразить только размеченные маркеры. Фильтр применяется по нажатии кнопки [[File:Icon view.png|x25px]] [3] в правой части блока [[Help:UI manual#Выбор контекста (проекта, ветки и снимка)|выбора проекта, ветки и снимка]].
# [[Help:UI manual#Настройка и использование пользовательских фильтров|Пользовательские фильтры]] – доступны по нажатии кнопки [[File:Button Фильтры.png|x25px]] [4] в правой части блока [[Help:UI manual#Выбор контекста (проекта, ветки и снимка)|выбора проекта, ветки и снимка]].
# Запрос – фильтр, указанный в поле в верхней части [[Help:UI manual#Таблица маркеров|таблицы маркеров]] [5].

:[[File:36 Фильтры.png|thumb|none|upright=3|Существующие фильтры]]

Посмотреть примененные фильтры (кроме '''Доступные для разметки''') и последовательность их применения можно в поле [[File:field Детектор.png|x25px]] в верхней части [[Help:UI manual#Таблица маркеров|таблицы маркеров]].

Все виды фильтров можно использовать одновременно, но при определенном порядке применения фильтры могут быть сброшены:
* запрос сбрасывается после применения любого другого фильтра;
* фильтры [[Help:UI manual#Функции левой навигационной панели|левой навигационной панели]] сбрасываются после применения [[Help:UI manual#Настройка и использование пользовательских фильтров|пользовательских фильтров]] и других фильтров [[Help:UI manual#Функции левой навигационной панели|на левой навигационной панели]];
* [[Help:UI manual#Настройка и использование пользовательских фильтров|пользовательские фильтры]] и фильтры [[Help:UI manual#Функции левой навигационной панели|левой навигационной панели]] не сбрасываются при применении фильтра '''Размеченный''';
* при переключении на другой [[Help:UI manual#Выбор контекста (проекта, ветки и снимка)|проект, ветку или снимок]] примененные фильтры '''Размеченный''' и [[Help:UI manual#Настройка и использование пользовательских фильтров|'''Пользовательский''']] не сбрасываются и применяются к выбранному снимку.

По нажатии кнопки [[File:Button Фильтры 2.png|x25px]] в правой части блока [[Help:UI manual#Выбор контекста (проекта, ветки и снимка)|выбора проекта, ветки и снимка]] можно отменить примененные фильтры: пользовательский или все.

==== Настройка и использование пользовательских фильтров ====
Настроить пользовательские фильтры можно [[Help:UI manual#Работа в режиме разметки|в режиме разметки]]. Для этого:
:1. Нажмите кнопку [[file:button Фильтры.png|x25px]] в правой части блока [[Help:UI manual#Выбор контекста (проекта, ветки и снимка)|выбора проекта, ветки и снимка]]. В правой части экрана отобразится панель пользовательских фильтров, которые разделены на три группы:
:* параметры детекторов;
:* параметры разметки маркеров;
:* файлы.
:2. На вкладке '''Пользовательский''':
::а) Настройте параметры фильтрации – выберите значения в списках полей или нажмите кнопки со значениями.
::б) Нажмите на кнопку [[File:Icon cancel.png|x15px]] справа от значения в списке, чтобы отменить его выбор.
::в) Если параметры нужно исключить из поиска, нажмите на кнопку [[File:Icon plus 2.png|x25px]]. Кнопка поменяется на [[File:Icon minus 3.png|x25px]].
::г) Если параметры нужно включить в поиск, нажмите на кнопку [[File:Icon minus 3.png|x25px]]. Кнопка поменяется на [[File:Icon plus 2.png|x25px]].
::д) Нажмите кнопку [[File:Button Очистить.png|x25px]], чтобы очистить все параметры фильтрации.
::е) Нажмите кнопку [[File:Button Сохранить как.png|x25px]], в открывшемся диалоге введите название и нажмите кнопку '''Сохранить'''.
::ж) Нажмите кнопку [[File:Button Применить.png|x25px]], чтобы применить фильтр. После применения кнопка фильтра станет зеленой, а ее название поменяется на название сохраненного фильтра.
::[[File:36 Пользовательские фильтры.png|thumb|none|upright=2|Пользовательские фильтры. Вкладка '''Пользовательский''']]
:3. На вкладке '''Сохраненные''':
::а) Для редактирования сохраненного фильтра нажмите кнопку [[File:Icon edit3.png|x25px]].
::б) Создайте дубликат фильтра – нажмите кнопку [[File:Icon duplicate.png|x25px]].
::в) Удалите фильтр – нажмите кнопку [[File:Icon delete 2.png|x25px]].
::г) Примените фильтр – нажмите на его название и нажмите кнопку [[File:Button Применить.png|x25px]].
::[[File:37 Фильтры сохраненные.png|thumb|none|upright=2|Пользовательские фильтры. Вкладка '''Сохраненные''']]
После применения:
* примененный фильтр будет отмечен [[File:Icon check.png|x25px]];
* кнопка фильтра станет зеленой, а ее название поменяется на название сохраненного фильтра.

=== Сравнение снимков и маркеров ===
Чтобы сравнить снимки и маркеры в них:
:1. [[Help:UI manual#Выбор контекста (проекта, ветки и снимка)|Выберите исходные проект, ветку и снимок]].
:2. [[Help:UI manual#Работа в режиме разметки|В режиме разметки]] нажмите кнопку [[File:Button Сравнить с.png|x25px]].
:3. В открывшемся окне выберите проект, ветку и снимок для сравнения; нажмите кнопку [[File:Button Применить.png|x25px]].
:[[File:38 Выбор снимка для сравнения.png|thumb|none|upright=1.5|Выбор проекта, ветки и снимка для сравнения]]
:Результат сравнения отобразится [[Help:UI manual#Функции левой навигационной панели|в левой навигационной панели]] и [[Help:UI manual#Функции центральной панели|центральной панели]], причем:
:* вкладка '''Информация о снимке''' поменяется на вкладку '''Информация о различиях''' с информацией о двух сравниваемых снимках;
:* применится первый режим сравнения, в котором найдены результаты.
:4. Выберите режим сравнения.
:[[File:39 Выбор режима сравнения.png|800px|thumb|none|Выбор режима сравнения]]
:[[Help:UI manual#Функции левой навигационной панели|В левой навигационной панели]] и [[Help:UI manual#Функции центральной панели|центральной панели]] отобразятся только результаты выбранного режима сравнения.
:В режимах '''Сопоставленные''' и '''Одинаковые''' [[Help:UI manual#Таблица маркеров|в таблице маркеров]] добавится столбец с номером версии: V1 – маркер в файле текущего снимка, V2 – маркер в файле целевого снимка.
'''''Примечание''': если при просмотре кода файла целевого снимка перейти к просмотру файла [[Help:UI manual#Работа в режиме просмотра кода|в режиме '''Код''']] (команда '''Открыть в режиме код'''), то режим сравнения закроется, отобразится контекст целевого снимка.''
<gallery mode="slideshow" style="float:left; clear:right; margin-right:1em; margin-left:2em" "="">
File:40 Пример сравнения новые.png|Пример результатов сравнения в режиме '''Новые'''
File:41 Пример сравнения Отсутствующие.png|Пример результатов сравнения в режиме '''Отсутствующие'''
File:42 Пример сравнения Сопоставленные.png|Пример результатов сравнения в режиме '''Сопоставленные'''
File:43 Пример сравнения Одинаковые.png|Пример результатов сравнения в режиме '''Одинаковые'''
</gallery>
 
:5. Посмотрите различия в параметрах анализа – нажмите кнопку '''Показать различия''' на вкладке '''Информация о различиях'''.
:[[File:44 Различия в результатах анализа.png|600px|thumb|none|Сравнение настроек анализа]]
:6. Посмотрите различия в статистике разметки – нажмите кнопку '''Различия разметок'''.
:[[File:45 Различия в статистике по детекторам.png|thumb|none|600px|Сравнение статистики разметок]]
:7. Нажмите кнопку [[File:Icon download CSV.png|x25px]] или [[File:Icon download PDF.png|x25px]], чтобы скачать статистику в формате CSV или PDF.
:8. Отмените сравнение – нажмите кнопку [[File:Icon cancel 2.png|x25px]] в блоке выбора проекта, ветки и снимка.
 

=== Сравнение маркеров ===
Чтобы сравнить два маркера:
:1. [[Help:UI manual#Работа в режиме разметки|В режиме разметки]] [[Help:UI manual#Выбор контекста (проекта, ветки и снимка)|выберите исходные проект, ветку и снимок]].
:2. Раскройте [[Help:UI manual#Таблица маркеров|таблицу маркеров]].
:3. Нажмите правой кнопкой мыши на строке маркера и выберите пункт '''Сравнить с ...''' Откроется окно выбора маркера для сравнения.
:[[File:46 Выбор маркера для сравнения.png|thumb|none|upright=2|Окно выбора маркера для сравнения]]
:4. Выберите проект, ветку и снимок. Отобразится список маркеров в выбранном снимке, где можно ввести запрос для поиска маркеров.
:[[File:47 Результат сравнения маркеров.png|thumb|none|upright=2|Выбор маркера для сравнения]]
:5. Дважды кликните на строке маркера, чтобы перейти в окно сравнения маркеров.
:[[File:48 Различия исходного кода.png|thumb|none|upright=3|Окно сравнения маркеров]]

=== Разметка маркера ===
Разметить маркер можно [[Help:UI manual#Работа в режиме разметки|в режиме разметки]] с помощью кнопок в верхней части [[Help:UI manual#Функции правой панели|правой панели]] или в виждете [[Help:UI manual#Вкладка с исходным кодом|на вкладке с исходным кодом]], а также по нажатии кнопки [[File:Icon edit.png|x25px]] в этих же частях интерфейса. Разметка маркера заключается в установке статуса, а также опционально серьезности (критичности) и требуемого действия. Установка серьезности и действия доступны только после установки статуса.
<gallery mode="packed" heights="180px" style="float:left; clear:right; margin-right:1em; margin-left:0">
49 Разметка Статус.png|Выбор Статуса разметки маркера
50 Разметка Серьезность.png|Выбор Серьезности разметки маркера
51 Разметка Действие.png|Выбор Действия разметки маркера
20_Исходный_код.png|Кнопки разметки в виджете маркера на вкладке с исходным кодом
</gallery>
 
Если [[Help:UI manual#Работа с проектами|для проекта]] установлен флаг '''Обязательный комментарий при разметке''', то при установке статуса, серьезности или действия откроется окно разметки, в котором обязательно нужно ввести комментарий.
[[File:99 Окно разметки.png|400px|thumb|none|Окно разметки. Поле '''Комментарий''' – обязательное]]
Результаты разметки со связанными комментариями отображаются [[Help:UI manual#Функции правой панели|в правой панели]] на вкладке '''Комментарии'''. При этом можно поменять текст комментария, но не результат разметки. Для её изменения нужно заново установить статус, серьёзность и действие.
[[File:100 Правая панель Комментарии с разметкой.png|300px|thumb|none|Правая панель. Комментарии, добавленные при разметке]]

=== Групповая разметка маркеров ===
Для групповой разметки:
:1. [[Help:UI manual#Работа в режиме разметки|В режиме разметки]] [[Help:UI manual#Выбор контекста (проекта, ветки и снимка)|выберите исходные проект, ветку и снимок]].
:2. Включите отображение [[Help:UI manual#Таблица маркеров|таблицы маркеров]].
:3. Выберите маркеры для разметки – установите флажки в строках таблицы.
:4. Нажмите кнопку [[File:icon edit.png|x25px]] (доступна, если выбраны маркеры в таблице).
:[[File:53 Выбор маркеров для группразметки.png|thumb|none|upright=2.5|Выбор маркеров для групповой разметки]]
:Отобразится окно для групповой разметки.
:[[File:54 Окно групповой разметки.png|thumb|none|upright=2.5|Окно групповой разметки]]
:5. Разметьте выбранные маркеры: выберите статус разметки, а затем (опционально) статус серьезности (критичности) и требуемое действие – нажмите кнопки со значениями.
:6. Добавьте общий комментарий для выбранных маркеров. 
:После того, как пользователь присвоил статусы и (или) написал комментарий, станет доступной кнопка '''Применить'''. 
:'''''Примечание''': ввод комментария обязателен, если [[Help:UI manual#Работа с проектами|для проекта]] установлен флаг '''Обязательный комментарий при разметке'''''.
:7. Если требуется отменить изменения, нажмите [[File:icon cross 01.png|x15px]] в правом верхнем углу окна или кнопку '''Отмена'''. Диалоговое окно закроется, изменения не будут применены, выделение с выбранных для разметки маркеров не снимается.
:9. Нажмите кнопку '''Применить''', чтобы запустить процесс разметки. 
Прогресс разметки отображается в соответствующем окне. Запущенный процесс можно полностью отменить нажатием кнопки '''Отмена'''. 
В результате применения разметки текст маркеров [[Help:UI manual#Таблица маркеров|в таблице маркеров]] окрасится в цвет, соответствующий выставленному статусу.

<gallery mode="packed" heights="120px" style="float:left; clear:right; margin-right:1em; margin-left:0">
56 Окно прогресса разметки.png|Окно прогресса разметки
57 Результат групповой разметки.png|Пример таблицы маркеров после применения групповой разметки
</gallery>
 

=== Блокировка разметки маркеров===
Пользователь может заблокировать другим пользователям возможность [[Help:UI manual#Разметка маркера|размечать маркер]] или [[Help:UI manual#Групповая разметка маркеров|группу маркеров]]. Это позволяет избежать коллизий при разметке маркеров несколькими пользователями.

Для блокировки разметки используйте кнопку [[File:icon unlocked.png|x25px]] в следующих частях пользовательского интерфейса:
:1. [[Help:UI manual#Вкладка «Детекторы»|На вкладке '''Детекторы''']]. В этом случае блокировка распространяется на все маркеры выбранного детектора в открытом проекте и ветке, для всех снимков ветки.
:2. [[Help:UI manual#Вкладка «Файлы»|На вкладке '''Файлы''']]. В этом случае блокировка распространяется на все маркеры в выбранном файле в открытом проекте и ветке, для всех снимков ветки.
:3. В верхней части [[Help:UI manual#Функции правой панели|правой панели]]. В этом случае блокировка распространяется на все эквивалентные маркеры в открытом проекте и ветке, для всех снимков ветки.

<gallery mode="packed" heights="250px" style="float:left; clear:right; margin-right:1em; margin-left:1em">
58 Блокировка на вкладке Детекторы.png|Блокировка маркера на вкладке '''Детекторы'''
File:59_Блокировка_на_вкладке_Файлы.png|Блокировка маркера на вкладке '''Файлы'''
60_Блокировка_на_правой_панели.png|Блокировка маркера на правой панели
</gallery>
 

Если один пользователь заблокировал маркер, то другой пользователь не сможет заблокировать детектор, которому принадлежит этот маркер, и файл, в котором этот маркер найден. 

Чтобы посмотреть все блокировки, перейдите в раздел [[Help:UI manual#Настройка сервера Svacer|'''Настройки''']] на [[Help:UI manual#Управление блокировками разметки|вкладку '''Блокировки''']]:

[[File:61 Просмотр всех блокировок.png|thumb|none|800px|Таблица блокировок]]

В этом разделе можно удалить только свои блокировки. Пользователь с доступом '''Удаление блокировок''' может удалить любые блокировки.

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

==== Способ 1 – в пользовательском интерфейсе сервера Svacer ====

Для этого:
:1. [[Help:UI manual#Работа в режиме разметки|В режиме разметки]] [[Help:UI manual#Выбор контекста (проекта, ветки и снимка)|выберите исходные проект, ветку и снимок]].
:2. На вкладке '''Информация о снимке''' в строке свойства '''ID''' нажмите кнопку [[File:Icon book.png|x25px]].
:[[File:62 Переход к экспорту кода с разметкой.png|600px|thumb|none|Переход к экспорту кода с разметкой]]
:3. В открывшемся окне выберите шаблон для экспорта в списке справа (по умолчанию '''Нет''', т. е. разметка экспортироваться не будет) и опционально заполните поля для удаления префиксов и исключения путей:
:[[File:63 Окно экспорта кода с разметкой.png|600px|thumb|none|Окно экспорта кода с разметкой]]

Пример удаления префиксов путей: <code>/.build/</code> – чтобы убрать папку '''.build''' при экспорте.

При экспорте можно исключить файлы, соответствующие [[Help:UI manual#Использование регулярных выражений|регулярным выражениям]] в поле '''Исключить пути'''. В итоге создастся архив со всеми исходниками и, если был выбран шаблон разметки, то в исходном коде будет вставлена актуальная разметка, соответствующая выбранному шаблону.

==== Способ 2 – через консольную команду svacer markup export ====

Синтаксис команды:
<pre>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>]</pre>
Где:
* <code>user</code>, <code>password</code> — имя пользователя и пароль учетной записи на сервере Svacer;
* <code>project</code> — проект на сервере Svacer, из которого будет экспортирован код;
* <code>branch</code> — ветка в проекте, выбранном выше (по умолчанию '''master'''), из которой будет экспортирован код;
* <code>snapshot</code> — снимок в выбранных проекте и ветке (по умолчанию последний загруженный), из которого будет экспортирован код;
* <code>stripPrefixes</code>, <code>excludePaths</code> — аналогичны полям '''Удалить префиксы''' и '''Исключить пути''' в форме экспорта разметки в пользовательском интерфейсе, описанной выше;
* <code>template</code> — определяет название шаблона для экспорта разметки. Если название не указано, разметка не экспортируется.

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

Наличие в файлах комментариев зависит от того, был ли выбран шаблон разметки.

=== Работа с таблицей статистики ===
Чтобы посмотреть краткую статистику о разметке маркеров:
:1. [[Help:UI manual#Выбор контекста (проекта, ветки и снимка)|Выберите исходные проект, ветку и снимок]].
:2. Перейдите [[Help:UI manual#Работа в режиме разметки|в режим разметки]].
:3. На вкладке '''Информация о снимке''' в строке свойства '''Статистика''' нажмите кнопку [[File:Button Показать 2.png|x25px]].

:[[File:64 Переход к просмотру статистики.png|600px|thumb|none|Переход к просмотру статистики]]

:Отобразится таблица статистики:
:[[File:65 Таблица статистики.png|600px|thumb|none|Таблица статистики]]
:4. Нажмите кнопку [[File:Icon download CSV.png|x20px]] или [[File:Icon download PDF.png|x20px]], чтобы выгрузить статистику в соответствующем формате.
:5. Нажмите кнопку [[File:Icon filter.png|x20px]] в строке статистики, чтобы применить [[Help:UI manual#Настройка и использование пользовательских фильтров|пользовательский фильтр]] с параметрами, которые соответствуют выбранному значению.

== Работа в режиме просмотра кода ==
Режим позволяет посмотреть снимки исходного кода, связанного с результатами анализатора Svace.

Для этого:
:1. Перейдите в режим просмотра кода с помощью переключателя [[File:Button Код.png|x25px]] в верхней части экрана.
:2. [[Help:UI manual#Выбор контекста (проекта, ветки и снимка)|Выберите исходные проект, ветку и снимок]]. 
:'''''Примечание''': по умолчанию выбран контекст (проект, ветка), заданный ранее в режиме [[Help:UI manual#Работа в режиме разметки|'''Разметка''']] или [[Help:UI manual#Режим формирования отчетов|'''Отчеты''']]. Если Пользователь перешел в раздел '''Кoд''' из режима сравнения снимков раздела [[Help:UI manual#Работа в режиме разметки|'''Разметка''']], то для изменения контекста требуется отменить режим сравнения.''
:В левой части экрана отобразится иерархический список файлов снимка, а в правой – поле для отображения исходного кода файла.
:[[File:67 Режим просмотра кода.png|600px|thumb|none|Режим просмотра кода]]
:3. В левой части экрана раскройте группу файлов и нажмите на имя файла.
:4. Также доступен поиск файлов, для этого кликните на поле поиска или нажмите комбинацию клавиш Ctrl+Shift+O, в открывшемся окне введите поисковый запрос и выберите файл.
:В правой части отобразится исходный код файла.
:[[File:68 Режим просмотра кода открыт один файл.png|600px|thumb|none|Пример одного открытого файла]]
:4. Если требуется, откройте другие файлы.
:Они отобразятся на отдельных вкладках, если выключена [[Help:UI manual#Настройка профиля пользователя|настройка '''Переиспользование вкладки в редакторе кода''']].
:[[File:69 Режим просмотра кода открыто три файла.png|600px|thumb|none|Пример трёх открытых файлов]]
:5. Вызовите функции, доступные по нажатию правой кнопки мыши на строке исходного кода
:* '''Перейти к объявлению''' – для перехода к строке, в которой объявлена переменная;
:* '''Перейти к определению''' – для перехода к строке, в которой определена переменная и функция;
:* '''Найти ссылки''' – для просмотра ссылок в панели с иерархическим списком файлов, именами файлов и номерами строк, в которых найдены ссылки;
::[[File:24 Исходный код Cписок файлов со ссылками.png|thumb|none|600px|Cписок файлов с номерами строк, в которых найдены ссылки]]
:* '''Copy''' – для копирования строки в буфер обмена;
:* '''Command Palette''' – для вызова командной строки.

==Управление проектами и группами проектов==
В разделе '''Проекты''' отображаются все проекты со всеми ветками и снимками.
Для удобства работы проекты могут быть [[Help:UI manual#Работа с группами проектов|сгруппированы]]. Проект может быть включен в несколько групп проектов.
[[File:101 Раздел Проекты.png|thumb|none|upright=3|Раздел '''Проекты''']]

===Работа с проектами===
Список проектов отображается в левой части экрана и организован в виде иерархии. При этом:
* для проектов, разметку маркеров которых нужно в обязательном порядке снабжать комментариями, отображается иконка [[File:Icon comment.png|x25px]];
* в нижней части списка отображается общее количество проектов и веток с учетом примененных фильтров, а также выбранных проектов и веток.
В списке доступны:
* поиск по имени проекта;
* фильтрация списка по группам проектов;
* сортировка по названию или дате создания (по умолчанию – по названию).
При работе с проектами пользователю доступны следующие функции:
:1. Загрузка актуальных данных с сервера – для этого нажмите кнопку [[File:Icon refresh.png|x25px]].
:2. Просмотр списка веток – для этого нажмите на название проекта.
:Ветки отобразятся в этом же списке проекта на втором уровне.
:3. Просмотр списка снимков – для этого нажмите на название ветки.
:Список снимков отобразится в виде таблицы в правой части экрана.
:4. [[Help:UI manual#Работа с группами проектов|Группировка проектов]].
:5. Создание проекта:
::а) Нажмите кнопку '''Создать проект'''.
::б) В открывшемся окне введите его название, выберите одну или несколько групп и установите флажок, если требуется при разметке маркеров обязательно добавлять комментарий.
::в) Нажмите кнопку '''Создать'''.
:При создании проекта автоматически создается ветка '''master'''.
:При импорте снимка в интерфейсе командной строки проект, при его отсутствии, добавляется автоматически.
:[[File:102 Создание проекта.png|thumb|none|upright=1.5|Окно создания проекта]]
:6. Добавление ветки:
::а) Нажмите кнопку [[File:Button menu.png|x25px]] в строке проекта.
::б) В меню выберите пункт '''Создать ветку'''.
::в) В открывшемся окне введите название.
:При импорте снимка в интерфейсе командной строки ветка, при ее отсутствии, добавляется автоматически.
:[[File:103 Создание ветки.png|thumb|none|upright=1.5|Окно добавления ветки в проект]]
:7. Редактирование параметров проекта:
::а) Нажмите кнопку [[File:Button menu.png|x25px]] в строке проекта.
::б) В меню выберите пункт '''Редактировать'''.
::в) В открывшемся окне измените название проекта, скорректируйте список групп, в которые включен проект, и установите или снимите флажок обязательности комментария при разметке.
:8. Удаление одного проекта:
::а) Нажмите кнопку [[File:Button menu.png|x25px]] в строке проекта.
::б) В меню выберите пункт '''Удалить'''.
::в) Подтвердите удаление.
:9. Удаление нескольких проектов с ветками:
::а) Выберите проекты для удаления – установите флажки в левой части названий проектов и веток или нажмите кнопку '''Выбрать всё'''.
::б) Нажмите кнопку '''Удалить''' в верхней части списка проектов и подтвердите удаление.
При удалении проекта удаляются все его ветки и снимки, разрывается связь проекта с группами.

===Работа с группами проектов===
Работа с группами проектов доступна на отдельной панели '''Группы проектов''', которая отрывается по нажатии кнопки [[File:Icon gear.png|x25px]] в списке проектов. При этом в нижней части списка отображается общее количество групп.

В списке групп доступны:
* поиск по названию группы;
* фильтрация списка по проектам.

[[File:104 Панель групп.png|thumb|none|upright=3|Панель '''Группы проектов''']]
При работе с группами проектов пользователю доступны следующие функции:
:1. Просмотр списка связанных с группой проектов – для этого нажмите на название группы.
:Проекты отобразятся в этом же списке групп на втором уровне.
:2. Добавление группы:
::а) Нажмите кнопку '''Создать группу'''.
::б) В открывшемся окне введите название группы и выберите проекты, которые в неё войдут, нажмите кнопку '''Создать'''.
:Созданная группа отобразится в списке на панели '''Группы проектов'''.
:[[File:105 Создание группы.png|thumb|none|upright=1.5|Окно '''Создать группу''']]
:3. Редактирование параметров группы:
::а) Нажмите кнопку [[File:Icon edit2.png|x25px]] в строке группы.
::б) В открывшемся окне измените название группы, скорректируйте состав включенных в группу проектов.
::в) Нажмите на кнопку [[File:Icon cancel.png|x25px]] справа от названия проекта в списке, чтобы исключить его из группы.
::г) Нажмите кнопку '''Сохранить'''.
:[[File:106 Редактирование группы.png|thumb|none|upright=1.5|Окно Редактировать группу]]
:4. Исключение одного проекта из группы – для этого нажмите кнопку [[File:Icon hide marks.png|x25px]] в правой части списка проектов группы.
:5. Удаление одной группы – для этого нажмите кнопку [[File:Icon delete.png|x25px]] в правой части списка групп и подтвердите удаление.
:6. Удаление нескольких групп:
::а) Выберите группы для удаления – установите флажки в левой части названий групп или нажмите кнопку '''Выбрать всё'''.
::б) Нажмите кнопку '''Удалить''' в верхней части списка групп проектов и подтвердите удаление.
:При удалении группы разрывается связь проекта с группой. Сами проекты не удаляются.

===Работа с ветками===
При работе с ветками проекта пользователю доступны следующие функции:
:1. Просмотр списка снимков – для этого нажмите на название ветки.
:Список снимков отобразится в виде таблицы в правой части экрана.

:2. Редактирование ветки:
::а) Нажмите кнопку [[File:Button menu.png|x25px]] в строке ветки.
::б) В меню выберите пункт '''Редактировать'''.
::в) В открывшемся окне измените название ветки.
:[[File:107 Редактирование ветки.png|thumb|none|upright=1.5|Окно редактирования ветки]]

:3. Клонирование ветки проекта:
::а) Нажмите кнопку [[File:Button menu.png|x25px]] в строке ветки.
::б) В меню выберите пункт '''Клонировать'''.
::в) В открывшемся окне введите название новой ветки и нажмите кнопку '''Клонировать'''.
:[[File:108 Клонирование ветки.png|thumb|none|upright=1.5|Окно клонирования ветки]]

:4. Удаление ветки:
::а) Нажмите кнопку [[File:Button menu.png|x25px]] в строке ветки.
::б) В меню выберите пункт '''Удалить'''.
::в) Подтвердите удаление.
:При удалении ветки удаляются все ее снимки.

:5. Копирование разметки в другой контейнер (проект и ветку):
::а) Нажмите кнопку [[File:Button menu.png|x25px]] в строке ветки и в меню выберите пункт '''Копировать разметку'''.
::б) В открывшемся окне выберите проект и ветку, в которые нужно скопировать разметку, а также действия, которые нужно выполнить при наличии разметки.
::в) Нажмите кнопку '''Копировать'''.
:[[File:109 Копирование разметки.png|thumb|none|upright=1.5|Окно копирования разметки в другой контейнер]]
Разметка в контейнере состоит из множества размеченных маркеров. В целевой ветке уже может находиться разметка. Все множество маркеров в исходной ветке можно разбить на два:
* «Уникальные» – маркеры, которые есть только в исходной ветке;
* «Общие» – маркеры, которые есть как в ветке-источнике, так и в ветке-приемнике.
При выполнении операции копирования разметка в уникальных маркерах всегда копируется в ветку-приемник. Для «Общих» маркеров возможны несколько вариантов продолжения копирования, но по умолчанию выбран пункт '''Не копировать''' – в этом случае разметка в «Общих» маркерах в ветке-приемнике не изменяется.

Если выбрано действие '''Перезаписать''', разметка на «Общих» маркерах в целевом контейнере будет заменена разметкой из ветки-источника.

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

'''Пример'''
:Есть несколько контейнеров:
:* A с разметкой {(M1, D1), (M2, D2), (M3, D3)}
:* B с разметкой {(M4, D4), (M2, D5), (M3, D6)},
::где M — это маркер, а D — разметка (включая метку времени).

:Операцию сравнения на разметке обозначим как >. Если метка времени в D1 больше, чем в D2, то D1 > D2.
:Пусть D2 > D5, а D3 < D6. Тогда операция копирования всегда скопирует разметку D1 (но не сам маркер), так как маркер M1 новый для контейнера B.

:Маркеры M2, M3 — общие для двух контейнеров, поэтому то, какая разметка будет в контейнере-приемнике, будет зависеть от выбранного варианта разрешения конфликта:
:* если выбран пункт '''Не копировать''', то в контейнере B на маркерах M2, M3 будет разметка D5, D6 соответственно;
:* если выбран пункт '''Перезаписать''', то на M2, M3 будет разметка D2, D3;
:* если выбран пункт '''Перезаписать только старую разметку''', то на M2, M3 разметка будет: D2, D6, так как D2 > D5 и D6 > D3.
:При выполнении копирования наличие маркера в ветке-приемнике не проверяется.
:При успешном копировании выводится всплывающее сообщение вида: ''Выполнено успешно. Всего: Х, Заменено:Y''
:Это сообщение означает, что всего было скопировано X инвариантов вместе с разметкой и среди скопированных инвариантов Y штук было скопировано с заменой.

===Работа со снимками===
Список снимков отображается в правой части экрана в виде таблицы после выбора ветки проекта. При этом в нижней части списка отображается общее количество снимков в выбранной ветке и количество выбранных снимков.
В списке доступны:
* поиск по названию снимка;
* сортировка по значениям столбцов (по умолчанию — по дате создания).
Для настройки снимков пользователю доступны следующие функции:
:1. Импорт снимка из файла:
::а) Нажмите кнопку '''Импорт''' в верхней части табличного списка снимков.
::б) В открывшемся окне выберите файл в формате .snap, введите название снимка (опционально) и нажмите кнопку '''Импортировать'''.
:'''''Примечание''': если название не введено, то при импорте будет то же название, которое было при экспорте результатов анализа из Svace.''
:[[File:110 Импорт снимка.png|thumb|none|upright=1.5|Окно импорта снимка]]
:2. Переход к разметке маркеров снимка:
::а) Нажмите кнопку [[File:Button menu.png|x25px]] в крайнем правом столбце строки снимка.
::б) В меню выберите пункт '''Разметить'''.
:3. Редактирование снимка:
::а) Нажмите кнопку [[File:Button menu.png|x25px]] в крайнем правом столбце строки снимка.
::б) В меню выберите пункт '''Редактировать'''.
::в) Поменяйте название.
:[[File:111 Редактирование снимка.png|thumb|none|upright=1.5|Окно редактирования снимка]]
:4. Экспорт снимка в файл формата .snap:
::а) Нажмите кнопку [[File:Button menu.png|x25px]] в крайнем правом столбце строки снимка.
::б) В меню выберите пункт '''Экспортировать'''.
:5. Просмотр информации о снимке в JSON-формате:
::а) Нажмите кнопку [[File:Button menu.png|x25px]] в строке снимка крайнем правом столбце.
::б) В меню выберите пункт '''Просмотреть JSON'''.
:[[File:112 Просмотр JSON снимка.png|thumb|none|upright=3|Окно просмотра информации о снимке в JSON-формате]]
:6. Удаление одного снимка:
::а) Нажмите кнопку [[File:Button menu.png|x25px]] в строке снимка крайнем правом столбце.
::б) В меню выберите пункт '''Удалить'''.
::в) Подтвердите удаление.
:7. Удаление нескольких снимков:
::а) Чтобы выбрать для удаления все снимки, установите флажок в заголовке табличного списка снимков.
::б) Чтобы выбрать несколько снимков, установите флажки в крайнем правом столбце табличного списка.
::в) Нажмите кнопку '''Удалить''' в верхней части табличного списка снимков и подтвердите удаление.

== Режим формирования отчетов ==
Режим позволяет сформировать отчеты на основе хранимой информации, посмотреть их в пользовательском интерфейсе и выгрузить в формате .json. Для этого:
:1. [[Help:UI manual#Выбор контекста (проекта, ветки и снимка)|Выберите исходные проект и ветку]].
:'''''Примечание''': по умолчанию выбран контекст (проект, ветка), заданный ранее в режиме [[Help:UI manual#Работа в режиме разметки|'''Разметка''']] или [[Help:UI manual#Режим формирования отчетов|'''Отчеты''']]. Если Пользователь перешел в раздел '''Отчеты''' из режима сравнения снимков раздела [[Help:UI manual#Работа в режиме разметки|'''Разметка''']], то для изменения контекста требуется отменить режим сравнения.''
:2. Перейдите в раздел '''Отчеты''' в верхней части экрана.
:Отобразится форма формирования отчетов:
:[[File:70 Форма формирования отчетов.png|thumb|none|upright=3|Форма формирования отчетов]]
:3. На панели слева выберите требуемый отчет: '''Общий отчет''' или '''Тренды'''.
:4. Выберите текущий и целевой снимки:
:[[File:71 Выбор снимков для формирования отчета.png|thumb|none|upright=3|Выбор снимков для формирования отчета]]
:5. Нажмите кнопку [[File:Button Play.png|x25px]] для запуска формирования отчета и его отображения в пользовательском интерфейсе.
:6. Нажмите кнопку [[File:Icon download.png|x25px]] для выгрузки отчета в формате .json.

<gallery mode="slideshow" style="float:left; clear:right; margin-right:1em; margin-left:2em" "="">
File:72 Пример общего отчета.png|Пример общего отчета. Часть 1
File:72.2 Пример общего отчета часть2.png|Пример общего отчета. Часть 2
File:72.3 Пример общего отчета часть3.png|Пример общего отчета. Часть 3
File:72.4 Пример общего отчета часть4.png|Пример общего отчета. Часть 4
File:72.5 Пример общего отчета часть5.png|Пример общего отчета. Часть 5
</gallery> 

:[[File:73 Пример отчета Тренды.png|600px|thumb|none|Пример отчета '''Тренды''']]

== Настройка сервера Svacer ==
Перейти в раздел '''Настройки''' можно по нажатии кнопки [[File:Icon settings.png|x25px]] в верхней правой части экрана.

В этом разделе пользователю, в зависимости от роли, доступны следующие функции:
* [[Help:UI manual#Управление пользователями, ролями и организациями|управление пользователями, ролями и организациями]];
* [[Help:UI manual#Настройка глобальных фильтров|настройка глобальных фильтров]];
* [[Help:UI manual#Управление блокировками разметки|управление блокировками]];
* [[Help:UI manual#Управление шаблонами разметки|управление шаблонами разметки]];
* [[Help:UI manual#Просмотр списка всех детекторов и его выгрузка в формате PDF|просмотр и выгрузка списка детекторов]];
* [[Help:UI manual#Просмотр информации о сервере|просмотр информации о сервере]];
* [[Help:UI manual#Управление клиентами OAuth|управление клиентами OAuth]].

=== Управление пользователями, ролями и организациями===
==== Управление пользователями ====
Реестром учетных записей пользователей можно управлять на вкладке '''Пользователи''' в разделе '''Управление пользователями''' страницы '''Настройки'''. 
Для [[Help:Advanced config and CLI features#Поддержка протокола LDAP для аутентификации пользователей|учетных записей с доступом по LDAP]] рядом с логином отображается индикатор [[File:Icon LDAP.png|x25px]], а для учетных записей с признаком '''Мастер разметки''' – индикатор [[File:Icon markup master.png|x25px]]. 
В разделе доступны:
* поиск по атрибутам учётной записи пользователя;
* фильтрация списка по типам учётных записей:
:* все;
:* системные;
:* LDAP;
:* заблокированные;
:* активные.
* сортировка по колонкам '''Логин''', '''ФИО''' и '''Дата создания''' (по умолчанию).
:[[File:74 Вкладка Пользователи на странице Настройки.png|thumb|none|upright=3|Вкладка '''Пользователи''' в разделе '''Управление пользователями''' страницы '''Настройки''']]
Для управления пользователями:
:1. Создайте учетную запись пользователя:
::а) Нажмите кнопку '''Создать'''.
::Откроется окно добавления учетной записи пользователя.
::[[File:76 Окно Добавить пользователя.png|thumb|none|upright=1.5|Окно '''Создать пользователя''']]
::б) Заполните поля:
::* Логин;
::* Пароль;
::* e-mail;
::* ФИО.
::в) Выберите [[Help:UI manual#Управление организациями|организации]], в которые должен входить пользователь, а также назначьте ему [[Help:UI manual#Управление ролями|роли]] – выберите значения в раскрывающихся списках полей '''Организации''' и '''Роли''' соответственно. Для отмены выбора нажмите на кнопку [[File:Icon cancel.png|x25px]] справа от значения.
::г) Включите опции '''Изменить пароль при первом входе в систему''' и '''Мастер разметки'''. 
::'''''Примечание''': Если для учётной записи активирована опция '''Мастер разметки''', есть разрешение на разметку и этот пользователь разметил маркер в каком-либо снимке, то изменить его разметку может только пользователь, в учётной записи которого также активирована опция '''Мастер разметки''' или которому предоставлен серверный доступ '''Изменение любой разметки'''.''
::д) Нажмите кнопку '''Создать'''.
: В таблице со списком пользователей добавится новая запись.

:2. Воспользуйтесь функциями в строке учетной записи в крайнем правом столбце – нажмите кнопку [[File:Button menu.png|x25px]] и выберите пункт:
:* '''Редактировать''' – для перехода к редактированию данных профиля;
:* '''Изменить пароль''' – для перехода к изменению пароля;
:* '''Сбросить настройки пользователя''' – для возврата пользовательских настроек к их значениям по умолчанию;
:* '''Заблокировать''' – для блокировки учетной записи. В этом случае для учетной записи пользователя блокируется доступ к системе, а в списке рядом с логином учетной записи отображается индикатор [[File:Icon_Archived.png|x25px]];
:* '''Разблокировать''' – для восстановления доступа пользователя к системе;
:* '''Удалить''' – для удаления учётной записи пользователя;
:* '''Показать доступы пользователя''' – для отображения списка объединенных доступов всех ролей, назначенных пользователю:
::[[File:113 Список доступов пользователя.png|thumb|none|upright=3|Список доступов пользователя]]
:'''''Примечание''': Функции блокировки и удаления недоступны для системных учетных записей. При изменении логина или списка доступов у авторизованного пользователя, он будет перенаправлен на страницу авторизации.''

:3. Воспользуйтесь функциями управления несколькими учётными записями одновременно:
::а) Чтобы выбрать несколько записей, установите флажки в первом столбце списка пользователей.
::б) Чтобы выбрать все отображаемые учётные записи, установите один флажок в заголовке столбцов в первом столбце списка.
::в) Нажмите кнопку '''Действия''' в верхней части списка пользователей и выберите пункт: '''Сбросить настройки пользователя''', '''Заблокировать''', '''Разблокировать''' или '''Удалить'''. В списке активны только действия, доступные всем выбранным учетным записям.
:4. Для [[Help:Advanced config and CLI features#Поддержка протокола LDAP для аутентификации пользователей|учетной записи с доступом по LDAP]] обновите данные – в окне редактирования данных профиля пользователя нажмите кнопку '''Загрузить из LDAP'''.
:Загрузятся параметры профиля пользователя и его контакты из профиля в службе каталогов, если они там указаны.
:[[File:78 Загрузка данных из LDAP.png|thumb|none|upright=1.5|Загрузка данных из LDAP]]

==== Управление ролями ====
Реестром ролей можно управлять на вкладке '''Роли''' в разделе '''Управление пользователями''' страницы '''Настройки'''.
:[[File:79 Переход к управлению ролями.png|thumb|none|upright=3|Вкладка '''Роли''' в разделе '''Управление пользователями''' страницы '''Настройки''']]
'''''Примечание''': роли [[Help:UI manual#Описание ролевой модели|admin, filter_master и importer]] являются встроенными с особым значением. Их нельзя удалить или изменить.'' 
Доступен поиск по названию роли и сортировка по колонкам '''Название''' (по умолчанию) и '''Пользователи'''. 
Для управления ролями доступны следующие функции:
:1. Создание новой роли:
::а) Нажмите кнопку '''Создать'''.
::[[File:81 Окно добавления роли.png|thumb|none|upright=3|Окно добавления роли]]
::б) Заполните поля появившейся формы:
:::*введите название роли;
:::*в блоке '''Серверные доступы''' выберите доступы – нажмите кнопку '''Выбрать всё''' или установите флажки для активации доступов.
:::При наведении курсора на иконку [[File:Icon question mark2.png|x25px]] отображается пояснение к доступу.
:::*в блоке '''Проектные доступы''' выберите тип доступа: группа проектов или определённый проект или его ветка;
:::*если выбран тип '''Группа проектов''', выберите название группы и установите флажки для активации доступов;
:::*если выбран тип '''Проект / Ветка''', выберите название проекта или ветки проекта, установите флажки для активации доступов.
:::Если выбрано значение '''Все''', то доступы будут предоставлены для всех проектов;
:::*для удаления строки с проектными доступами в блоке '''Проектные доступы''' нажмите кнопку [[File:Icon delete.png|x25px]] в крайнем правом столбце.
::в) Нажмите кнопку '''Создать'''.

:2. Просмотр доступов роли, нажмите на ссылку '''Показать доступы''' в столбце '''Доступы'''.
:[[File:114 Список доступов роли.png|thumb|none|upright=3|Список доступов роли]]

:3. Редактирование роли:
::а) Нажмите кнопку [[File:Button menu.png|x25px]] в строке роли в крайнем правом столбце.
::б) В меню выберите пункт '''Редактировать''' и внесите изменения.

:4. Создание копии роли:
::а) Нажмите кнопку [[File:Button menu.png|x25px]] в строке исходной роли в крайнем правом столбце.
::б) В меню выберите пункт '''Создать копию'''.
:В реестр ролей добавится новая запись с именем исходной роли и добавленным порядковым номером копии.

:5. Просмотр информации о роли в JSON-формате:
::а) Нажмите кнопку [[File:Button menu.png|x25px]] в строке исходной роли в крайнем правом столбце.
::б) В меню выберите пункт '''Просмотреть JSON'''.

:6. Удаление роли:
::а) Нажмите кнопку [[File:Button menu.png|x25px]] в строке исходной роли в крайнем правом столбце.
::б) В меню выберите пункт '''Удалить'''.
::в) Подтвердите удаление.

:7. Удаление несколько ролей одновременно:
::а) Для выбора нескольких записей установите флажки в первом столбце списка ролей.
::б) Чтобы выбрать все записи, установите один флажок в заголовке столбцов в первом столбце списка ролей.
::в) Нажмите кнопку '''Удалить''' и подтвердите удаление.

==== Управление организациями ====
Пользователи могут быть связаны с организациями. Один пользователь может принадлежать нескольким организациям. Организации носят информационный характер и не влияют на права пользователей в системе. 
Реестром организаций можно управлять на вкладке '''Организации''' в разделе '''Управление пользователями''' страницы '''Настройки'''.
[[File:92 Вкладка Организации на странице Настройки.png|thumb|none|upright=3|Вкладка '''Организации''' в разделе '''Управление пользователями''' страницы '''Настройки''']]
Доступен поиск по названию и сокращенному названию организации и сортировка по колонкам '''Название''' (по умолчанию), '''Сокращенное название''' и '''Пользователи'''.
Для управления организациями, доступны следующие функции:
:1. Создание организации:
::а) Нажмите кнопку '''Создать'''.
::б) Заполните поля появившейся формы.
::в) Нажмите кнопку '''Создать'''.
::[[File:93 Окно добавления организации в реестр.png|thumb|none|upright=1.5|Окно добавления организации в реестр]]

:2. Редактирование организации:
::а) Нажмите кнопку [[File:Icon edit2.png|x25px]] в крайнем правом столбце.
::б) В появившейся форме отредактируйте данные организации.
::в) Нажмите кнопку '''Сохранить'''.

:3. Удаление организации:
::а) Нажмите кнопку [[File:Icon delete.png|x25px]] в крайнем правом столбце.
::б) В появившемся диалоге подтвердите удаление, нажав на кнопку '''Удалить'''.

:4. Удаление несколько организаций одновременно:
::а) Для выбора нескольких записей установите флажки в первом столбце списка организаций.
::б) Чтобы выбрать все организации, установите один флажок в заголовке столбцов в первом столбце списка.
::в) Нажмите кнопку '''Удалить''' и подтвердите удаление.

=== Настройка глобальных фильтров ===
В разделе '''Глобальные фильтры''' страницы '''Настройки''' можно настроить глобальные фильтры, применительно [[Help:UI manual#Выбор контекста (проекта, ветки и снимка)|к выбранным проекту или ветке проекта]]: 
'''''Примечание''': по умолчанию выбран контекст (проект, ветка), заданный ранее в режиме '''Разметка''', '''Код''' или '''Отчеты'''.''
[[File:82 Вкладка Фильтры на странице Настройки.png|thumb|none|upright=3|Раздел '''Фильтры''' на странице '''Настройки''']]

В разделе доступен поиск по названию фильтра.

Для настройки фильтров:
:1. Выберите проект и ветку в верхней строке раздела. По умолчанию указаны проект и ветка, выбранные в разделе '''Разметка'''.
:2. Чтобы добавить фильтр, нажмите кнопку '''Создать'''.
:Отобразится новая строка:
:[[File:83 Новая строка с фильтром.png|thumb|none|upright=3|Новая строка с фильтром]]

:3. Чтобы изменить настройки фильтров:
::а) Введите или поменяйте название фильтра
::б) Включите или выключите фильтр – нажмите на значение в столбце '''Статус''', чтобы отобразилась иконка [[File:Icon check2.png|x25px]] (по умолчанию) или [[File:Icon cross 01.png|x25px]].
::в) Выберите область применения фильтра – нажмите на значение в столбце '''Область''' один или два раза, чтобы отобразилось значение '''ветка''' или '''проект'''.
::г) Введите [[Help:UI manual#Использование регулярных выражений|регулярное выражение]] или загрузите его из файла в столбцах '''Включить пути по шаблону''', '''Исключить пути по шаблону''' и '''Детекторы'''.
::д) Выберите уровни серьезности (критичности) и надежности:
::* [[File:Icon_critical_on.png|x30px]] – уровень выбран;
::* [[File:Icon_critical_off.png|x30px]] – уровень не выбран.
::Для изменения выбора нажмите на название уровня.
:4. Нажмите кнопку [[File:Icon delete.png|x25px]] в крайнем правом столбце, чтобы удалить один фильтр.
:5. Чтобы удалить несколько фильтров:
::а) Для выбора нескольких записей установите флажки в первом столбце списка фильтров.
::б) Чтобы выбрать все записи, установите один флажок в заголовке столбцов в первом столбце списка фильтров.
::в) Нажмите кнопку '''Удалить'''.
:6. Для сохранения и применения изменений нажмите кнопку '''Применить'''.
:'''''Примечание''': если не применить изменения, то при переходе в другой раздел системы отобразится сообщение о том, что изменения не применены:''
:[[File:115 Запрос на изменение глобальных фильтров.png|thumb|none|upright=1.5]]

=== Управление блокировками разметки ===
Чтобы посмотреть список всех [[Help:UI manual#Блокировка разметки|блокировок]], перейдите на вкладку '''Блокировки''' страницы '''Настройки''':
[[File:89 Вкладка Блокировки на странице Настройки.png|800px|thumb|none|Раздел '''Блокировки''' страницы '''Настройки''']]
'''''Примечание''': пользователю отображается список блокировок в контейнерах, к которым у него есть доступ. Удаление не своих блокировок доступно пользователям с соответствующим доступом.'' 
Доступен поиск по контейнерам, заблокированным сущностям и пользователям, сортировка по всем колонкам (по умолчанию – сортировка по дате).

Для удаления одной блокировки:
:1. Нажмите кнопку [[File:Icon delete.png|x25px]] в строке проекта в крайнем правом столбце.
:2. Подтвердите удаление.
Для удаления нескольких блокировок:
:1. Чтобы выбрать для удаления все блокировки, установите флажок в заголовке табличного списка.
:2. Чтобы выбрать несколько блокировок, установите флажки в крайнем правом столбце табличного списка.
:3. Нажмите кнопку '''Удалить''' в верхней части списка.

=== Управление шаблонами разметки ===
Управление шаблонами разметки доступно в разделе '''Шаблоны разметки''' страницы '''Настройки''':
[[File:84 Вкладка Шаблоны на странице Настройки.png|thumb|none|upright=3|Раздел '''Шаблоны разметки''' на странице '''Настройки''']]

Шаблоны разметки нужны для импорта/[[Help:UI manual#Экспорт кода с разметкой|экспорта разметки]]. С их помощью комментарии в исходном коде будут преобразовываться в разметку на сервере истории и обратно.

Шаблон с именем DEFAULT есть всегда, его нельзя отредактировать или удалить.

'''Примечание''': ''для корректного создания или изменения шаблонов разметки следует обратиться к разработчикам Svacer.''

Для управления шаблонами:
:1. Нажмите кнопку '''Создать'''.
:Откроется окно создания шаблона.
:[[File:Добавление шаблона разметки.png|thumb|none|upright=1.5|Окно создания шаблона разметки]]
:2. Введите название шаблона.
:3. Нажмите кнопку '''Создать'''.
:Шаблон появится в списке шаблонов для разметки в правой панели формы
:4. Отредактируйте поля шаблона разметки:
:[[File:85 Поля шаблона, доступные для редактирования.png|thumb|none|upright=2.5|Редактирование шаблона разметки]]
:5. Нажмите '''Сохранить'''.
:6. Чтобы клонировать существующий шаблон разметки, нажмите кнопку [[File:Icon_clone.png|x20px]] в правой части строки шаблона в списке.
:7. Для удаления одного шаблона:
::а) Нажмите кнопку [[File:Icon delete.png|x25px]] в правой части строки шаблона в списке.
::б) Подтвердите удаление.
:8. Для удаления нескольких шаблонов:
::а) Выберите шаблоны для удаления – установите флажки в левой части названий шаблонов или нажмите кнопку '''Выбрать всё'''.
::б) Нажмите кнопку '''Удалить''' в верхней части списка шаблонов и подтвердите удаление.

=== Просмотр списка всех детекторов и его выгрузка в формате PDF ===
Чтобы посмотреть список всех детекторов, перейдите в раздел '''Детекторы''' страницы '''Настройки''':
[[File:88 Вкладка Детекторы на странице Настройки.png|thumb|none|upright=3|Раздел '''Детекторы''' страницы '''Настройки''']]

Нажмите кнопку [[File:Icon question mark.png|x25px]] в строке детектора, чтобы посмотреть подробную информацию:
[[File:34 Информация о детекторе.png|thumb|none|upright=2.5|Окно с информацией о детекторе]]

Нажмите кнопку '''Экспорт в PDF''', чтобы выгрузить список детекторов в формате .pdf.

=== Управление клиентами OAuth ===
Svacer поддерживает авторизацию по протоколу OAuth. Для авторизации используются запросы <code>GET /api/oauth/authorize</code> и <code>POST /api/oauth/token</code> в соответствии со стандартом.

Управление клиентами доступно в разделе '''Клиенты OAuth''' на странице '''Настройки''':
[[File:91 Вкладка Клиенты OAuth на странице Настройки.png|thumb|none|upright=3|Раздел '''Клиенты OAuth''' на странице '''Настройки''']]
Доступен поиск по имени и домену клиента OAuth, сортировка по колонкам '''Название''' (по умолчанию) и '''Домен'''.

Для управления клиентами OAuth:
:1. Создайте клиента OAuth:
::а) Нажмите кнопку '''Создать'''.
::б) В окне '''Создание клиента OAuth''' введите название и домен.
::в) Нажмите кнопку '''Создать'''.
::[[File:116 Создание клиента OAuth.png|thumb|none|upright=1.5|Окно '''Создание клиента OAuth''']]
::Отобразится окно с секретом клиента. 
::'''''Внимание'''! Секрет отображается только один раз – при создании клиента.''
::[[File:117 Пример секрета клиента OAuth.png|thumb|none|upright=1.5]]
::г) Нажмите кнопку '''Скопировать в буфер обмена''' и сохраните секрет в надежном месте.
:2. Чтобы скопировать ID клиента OAuth, нажмите кнопку [[File:Icon clone.png|x25px]].
:3. Для перехода к изменению имени и домена клиента OAuth нажмите кнопку [[File:Icon edit2.png|x25px]] в крайнем правом столбце.
:4. Для удаления одного клиента OAuth:
::а) Нажмите кнопку [[File:Icon delete.png|x25px]] в крайнем правом столбце.
::б) Подтвердите удаление.
:5. Для удаления нескольких клиентов OAuth:
::а) Чтобы выбрать для удаления все клиенты, установите флажок в заголовке табличного списка.
::б) Чтобы выбрать несколько клиентов, установите флажки в крайнем правом столбце табличного списка.
::в) Нажмите кнопку '''Удалить''' в верхней части табличного списка клиентов и подтвердите удаление.

=== Просмотр информации о сервере ===
В разделе '''Информация о сервере''' на странице '''Настройки''' отображаются:
* параметры, с которыми запущен сервер;
* логи сервера;
* журнал базы данных.

[[File:90 Вкладка Информация о сервере на странице Настройки.png|thumb|none|upright=3|Раздел '''Информация о сервере''' на странице '''Настройки''']]

Доступны функции:
* копирование записей в системном логе и журнале;
* выгрузка системного лога и журнала в файлы в формате .log

== Выход из системы ==
Для выхода из системы выберите пункт '''Выйти''' в меню пользователя в правом верхнем углу экрана.
[[File:95 Выход из системы —без VSCode.png|thumb|none|upright=1.5|Выход из системы]]

== Использование регулярных выражений ==
Регулярные выражения можно использовать для поиска и фильтрации данных [[Help:UI manual#Функции левой навигационной панели|в левой навигационной панели]] [[Help:UI manual#Вкладка «Файлы»|на вкладке '''Файлы''']] и в окне настройки [[Help:UI manual#Настройка и использование пользовательских фильтров|пользовательских фильтров]] в блоке '''Файлы'''.

Особенности реализации:
:1. Поиск происходит только по регулярному выражению. Если требуется найти специальный символ в качестве обычного символа, его нужно экранировать (например, точку: <code>\.</code>)
:2. При поиске находятся вхождения подстроки в полном пути к файлу (аналогично grep). Если требуется найти по полной строке, используйте символы начала и конца строки: <code>^</code> и <code>$</code>
:3. Поиск не зависит от регистра символов (case insensitive)
:В окне настройки [[Help:UI manual#Настройка и использование пользовательских фильтров|пользовательских фильтров]] в блоке '''Файлы''' можно применить фильтр как для отображения только маркеров из файлов, которые подходят под паттерн, так и для скрытия таких маркеров. Для переключения между этими режимами используйте кнопки [[File:Icon plus 2.png|x20px]] и [[File:Icon minus 3.png|x20px]], которые расположены рядом с полем ввода.

Примеры регулярных выражений:
:1. Поиск файлов с текстом <code>sha</code> или <code>md5</code> в любом месте пути или имени файла:
:<pre>sha|md5</pre>
:2. Отображение только маркеров из файлов с расширением .c:
:<pre>.*\.c$</pre>
:3. Скрытие маркеров из файлов, имя которых начинается с символа <code>q</code> и которые имеют расширения .с или .сс:
::а) Используйте выражение <code>/q[^/]*\.c$|/q[^/]*\.cc$</code>
::б) Нажмите кнопку [[File:Icon plus 2.png|x20px]] рядом с полем ввода, чтобы она поменялась на [[File:Icon minus 3.png|x20px]]
:4. Отображение только маркеров из файлов, которые имеют текст <code>string</code> в конце имени файла и с расширением из одного символа:
:<pre>/.*string\..$</pre>
:5. Скрытие маркеров из файлов в директориях <code>asn1</code> и <code>pem</code>:
::а) Используйте выражение <code>/asn1/|/pem/</code>
::б) Нажмите кнопку [[File:Icon plus 2.png|x20px]] рядом с полем ввода, чтобы она поменялась на [[File:Icon minus 3.png|x20px]]
:6. Отображение только маркеров из файлов, которые имеют в имени три цифры подряд:
:<pre>.*/.*[0-9]{3}[^/]*$</pre>
:где <code>[^/]*$</code> означает, что после трех цифр и до конца строки может встречаться любой символ, кроме <code>/</code>. Это позволяет исключить директории, имеющие три цифры в названии.

== Описание ролевой модели ==
=== Серверные доступы ===
{| class="wikitable"
! Полномочие (доступ) !! Описание !! Влияние на графический интерфейс !! admin !! filter_master !! importer
|-
| Создание проектов
|| Создание проектов. Пользователь, создавший проект, имеет полный доступ к управлению этим проектом
|| Наличие полномочия делает доступным:
* раздел [[Help:UI manual#Управление проектами и группами проектов|'''Проекты''']];
* кнопку '''Создать проект''';
* форму создания и редактирования проекта.

Наличие доступа предоставляет автору проекта полные права на управление своими проектами, включая разметку (даже при отсутствии у него соответствующего проектного доступа), а также позволяет удалять приложения к снимкам в созданных проектах
|| + || – || –

|-
| Настройка групп проектов
|| Создание, редактирование и удаление групп проектов
|| Наличие полномочия делает доступным:
* раздел [[Help:UI manual#Управление проектами и группами проектов|'''Проекты''']] с кнопкой для перехода к настройке групп;
* панель [[Help:UI manual#Работа с группами проектов|'''Группы проектов''']] с полным списком проектов в группах.
Наличие доступа предоставляет права на просмотр маркеров во всех проектах
|| + || – || –

|-
| Управление пользователями
|| Создание, редактирование и удаление пользователей
|| Наличие полномочия делает доступной вкладку [[Help:UI manual#Управление пользователями|'''Пользователи''']] в разделе [[Help:UI manual#Управление пользователями, ролями и организациями|'''Настройки – Управление пользователями''']] со всеми функциями управления учетными записями пользователей
|| + || – || –

|-
| Управление ролями
|| Создание, редактирование и удаление ролей
|| Наличие полномочия делает доступной вкладку [[Help:UI manual#Управление ролями|'''Роли''']] в разделе [[Help:UI manual#Управление пользователями, ролями и организациями|'''Настройки – Управление пользователями''']] со всеми функциями управления ролями
|| + || – || –

|-
| Управление организациями
|| Создание, редактирование и удаление организаций
|| Наличие полномочия делает доступной вкладку [[Help:UI manual#Управление организациями|'''Организации''']] в разделе [[Help:UI manual#Управление пользователями, ролями и организациями|'''Настройки – Управление пользователями''']] со всеми функциями управления организациями
|| + || – || –

|-
| Управление шаблонами разметки
|| Создание, редактирование и удаление шаблонов разметки
|| Наличие полномочия делает доступным раздел [[Help:UI manual#Управление шаблонами разметки|'''Настройки – Шаблоны разметки''']] со всеми функциями управления учетными записями шаблонами
|| + || – || –

|-
| Удаление блокировок
|| Просмотр и удаление блокировок всех пользователей
|| Наличие полномочия позволяет просматривать и удалять блокировки всех пользователей в разделе [[Help:UI manual#Управление блокировками разметки|'''Настройки – Блокировки''']]
|| + || – || –

|-
| Управление клиентами OAuth
|| Создание, редактирование и удаление клиентов OAuth
|| Наличие полномочия делает доступным раздел [[Help:UI manual#Управление клиентами OAuth|'''Настройки – Клиенты OAuth''']] со всеми функциями управления клиентами OAuth
|| + || + || +

|-
| Администрирование сервера
|| Просмотр настроек сервера, системных лог-файлов и выполнение операций по администрированию сервера Svacer
|| Наличие полномочия делает доступным раздел [[Help:UI manual#Просмотр информации о сервере|'''Настройки – Информация о сервере''']]
|| + || – || –

|-
| Создание резервных копий
|| Создание, просмотр и восстановление резервных копий в интерфейсе командной строки
|| –
|| + || – || –

|-
| Запуск скриптов
|| Запуск скриптов (hooks) по кнопке, расположенной на вкладке '''Подробности''' в правой панели, содержащей информацию о маркере
|| Наличие полномочия добавляет строку '''Хуки''' на вкладке '''Подробности''' правой панели с возможностью запуска скриптов
|| + || – || –

|-
| Использование Public API
|| Использование REST API для интеграции с внешними системами
|| –
|| + || – || –

|-
| Изменение любой разметки
|| Изменение любой разметки маркеров, включая выполненную пользователями с признаком [[Help:UI manual#Управление пользователями, ролями и организациями|'''Мастер разметки''']]
|| Доступ позволяет переразмечать маркеры (добавлять новую разметку), которые разметили любые пользователи, в том числе те, для которых активирована опция [[Help:UI manual#Управление пользователями, ролями и организациями|'''Мастер разметки''']].
При этом:
# Полномочие не предоставляет доступ ко всем проектам. Т. е. пользователь с таким полномочием может изменять разметку только в проектах, к которым у него имеется доступ.
# Для переразметки маркеров пользователю должен быть предоставлен проектный доступ '''Разметка маркеров'''.
# Чтобы переразметить заблокированный маркер, сначала нужно [[Help:UI manual#Блокировка разметки маркеров|снять его блокировку]]
|| + || – || –

|-
| Изменение любых комментариев
|| Редактирование и удаление любых пользовательских комментариев к маркерам
|| Доступ позволяет изменять/удалять комментарии, которые создали любые пользователи, в том числе те, для которых активирована опция [[Help:UI manual#Управление пользователями, ролями и организациями|'''Мастер разметки''']].
При этом:
# Полномочие не предоставляет доступ ко всем проектам. Т. е. пользователь с таким полномочием может изменять разметку только в проектах, к которым у него имеется доступ.
# Для добавления комментариев пользователю должно быть предоставлено проектное полномочие '''Разметка маркеров'''.
# Чтобы поменять комментарий к заблокированному маркеру, сначала нужно [[Help:UI manual#Блокировка разметки маркеров|снять его блокировку]]
|| + || – || –
|}
=== Проектные доступы===
{| class="wikitable"
! Полномочие (доступ) !! Описание !! Влияние на графический интерфейс !! admin !! filter_master !! importer
|-
| Управление проектом и его ветками
|| Редактирование и удаление проекта, включая операции по управлению ветками и снимками проекта, настройке глобальных фильтров, импорту/экспорту разметки и просмотру маркеров
|| Наличие полномочия делает доступным:
* раздел [[Help:UI manual#Управление проектами и группами проектов|'''Проекты''']];
* все функции управления проектом (проектами в группе) и его содержимым (за исключением разметки маркеров) – т. е. все операции с проектом, ветками и снимками.
Наличие полномочия позволяет удалять приложения к снимкам и экспортировать разметку с исходным кодом
|| + || – || –

|-
| Управление ветками и снимками
|| Редактирование и удаление ветки проекта, включая операции по управлению снимками, настройке глобальных фильтров, импорту/экспорту разметки и просмотру маркеров
|| Наличие полномочия делает доступным:
* раздел [[Help:UI manual#Управление проектами и группами проектов|'''Проекты''']];
* все функции управления веткой и снимками проекта (за исключением разметки маркеров) – т. е. доступны все операции с веткой и снимками, но не операции управления проектом.
Наличие полномочия позволяет удалять приложения к снимкам и экспортировать разметку с исходным кодом.
Запрещено клонировать ветку при наличии доступа только к этой ветке
|| + || – || –

|-
| Настройка глобальных фильтров
|| Создание, редактирование и удаление глобальных фильтров
|| Наличие полномочия делает доступным раздел [[Help:UI manual#Настройка глобальных фильтров|'''Настройки – Глобальные фильтры''']].
Список проектов и веток в разделе определяется полномочиями к этим проектам и веткам
|| + || + || –

|-
| Импорт снимков
|| Загрузка, редактирование названия и удаление снимков
|| Наличие полномочия делает доступным:
* раздел [[Help:UI manual#Управление проектами и группами проектов|'''Проекты''']];
* функции просмотра проекта и ветки, управления снимками в указанной ветке, просмотра маркеров в снимке
|| + || – || +

|-
| Импорт разметки
|| Импорт разметки из исходного кода и управление подавлением маркеров в интерфейсе командной строки
|| Наличие полномочия делает доступным просмотр маркеров в указанном контейнере
|| + || – || +

|-
| Экспорт разметки
|| Экспорт разметки с исходным кодом
|| Наличие полномочия позволяет выполнить экспорт разметки с исходными кодами и просматривать маркеры в указанном контейнере
|| + || – || +

|-
| Просмотр маркеров
|| Просмотр маркеров и кода снимков, экспорт снимков, просмотр блокировок маркеров
|| Наличие полномочия предоставляет доступ к следующим функциям [[Help:UI manual#Работа в режиме разметки|в режиме разметки]]:
* просмотр и выбор снимков в указанной ветке;
* просмотр содержимого снимков и маркеров (без возможности разметки);
* экспорт снимков и пр.
Также наличие полномочия предоставляет доступ к разделу [[Help:UI manual#Управление блокировками разметки|'''Настройки – Блокировки''']], но только в части просмотра блокировок в доступных контейнерах, без возможности их удаления
|| + || + || +

|-
| Разметка маркеров
|| Просмотр и разметка маркеров в снимках, включая добавление комментариев, управление списком блокировок
|| Наличие полномочия позволяет пользователю размечать маркеры в указанном снимке, добавлять комментарии, управлять своими блокировками, т. е. для собственных блокировок доступны кнопки удаления, а блокировки других пользователей доступны только для просмотра.
При отсутствии полномочия в таблице маркеров недоступны поля для установки флажков, а кнопка групповой разметки – неактивна
|| + || – || –

|-
| Использование Report API
|| Использование Report API для получения статистических показателей
|| –
|| + || – || –
|}

=== Известные ограничения ===

* Управление ''своими'' проектами без дополнительных прав может не работать для проектов, созданных до Release 7-0-0.

Help:Vscode

2023-11-21T09:46:46Z

Writer:

[[Category:Help]]

<big>В версии 8.0.0 интеграция с VS Code не поддерживается: было много изменений, и мы пока не обновили расширение VSCode для работы с ними, но обновим и выпустим немного позже.</big>


== Инструкция по работе с расширением Svacer для Visual Studio Code ==
=== Установка ===
==== Установка из официального магазина VSCode ====
Чтобы установить расширение Svacer для Visual Studio Code:
*перейдите по ссылке [https://marketplace.visualstudio.com/items?itemName=ISP-RAS.svacer Visual Studio Marketplace] и нажмите кнопку '''Install'''
*или на странице расширений VSCode найдите '''Svacer''' и нажмите кнопку '''Установить''':
[[File:Установка из магазина приложений.png|thumb|none|800px|Установка расширения из магазина приложений]]
Приложение считается успешно установленным, если появилось соответствующее сообщение и на панели слева отобразилась вкладка расширения [[File:Иконка_расширения.png|x25px]]

==== Установка из файла ====
Получить установочный файл можно:
*на странице официального магазина приложений VSCode по ссылке: [https://marketplace.visualstudio.com/items?itemName=ISP-RAS.svacer&ssr=false#version-history Visual Studio Marketplace]
*в пользовательском интерфейсе сервера Svacer. Для этого выберите пункт '''Скачать расширение для VSCode''' в меню пользователя: 
[[File:Установка из файла 1.png|800px]] 
Имя установочного файла имеет вид ''<code>svacer-<version>.vsix</code>''.

Для установки:
:1. На странице расширений VSCode нажмите кнопку [[File:Иконка 3 точки.png|x25px]] и выберите пункт '''Установка из VSIX''':
:[[File:Установка из файла 2.png|800px]]

:2. В открывшемся окне проводника выберите скачанный установочный файл ''<code>svacer-<version>.vsix</code>''
Также расширение '''Svacer''' можно установить с помощью параметра командной строки
'''<code>--install-extension</code>''', указав путь к файлу: 
'''<code>--install-extension <path-to-file>/svacer-<version>.vsix</code>''' 
Приложение считается успешно установленным, если появилось соответствующее сообщение и на панели слева отобразилась вкладка расширения [[File:Иконка_расширения.png|x25px]]

=== Настройка подключения к серверу Svacer ===
Для работы расширения требуется настроить подключение к серверу Svacer:
:1. Перейдите на вкладку расширения [[File:Иконка расширения.png|x25px]]
:2. На панели '''ИНСТРУМЕНТЫ SVACER: Информация Svacer''' нажмите кнопку [[File:Иконка Шестеренка.png|25px]] и выберите пункт '''Параметры расширения''' 
:[[File:Настройка подключения 1.png|800px]] 

:В правой части окна VSCode откроется вкладка '''Параметры'''. 

:[[File:Настройка подключения 2.png|800px]] 

:3. Укажите адрес и порт сервера Svacer
:4. Настройте остальные параметры (опционально)
:{| class="wikitable" style="text-align: left"
|-
! Название !! Описание !! По умолчанию
|-
! scope="row" colspan="3"| Настройки сервера
|-
| Hostname || Имя или IP-адрес Svacer || localhost
|-
| Port || Порт Svacer || 8080
Если значение оставить пустым, то будет использован порт по умолчанию для выбранного протокола
|-
| Use Https || Использовать протокол https || false
|-
! scope="row" colspan="3"| Настройки рабочей области
|-
| Include Traces || Отображать трассу для маркеров || true
|-
| Include Comments || Отображать комментарии пользователей || true
|}

===Авторизация ===
Для доступа к серверу Svacer требуется авторизоваться:
:1. Нажмите кнопку [[File:Иконка аккаунт.png|x25px]] и выберите пункт '''Войдите с помощью SvacerAuth, чтобы использовать Svacer''', либо на вкладке расширения в разделе '''ИНФОРМАЦИЯ SVACER''' нажмите кнопку '''Авторизоваться'''
:[[File:Авторизация 1.png|none|400px]]

:[[File:Авторизация 2.png|none|600px]]

:2. Нажмите кнопку '''Разрешить''' в появившемся окне:
:[[File:Авторизация 3.png|400px]]

:3. Подтвердите открытие в браузере внешнего веб-сайта для авторизации
:В браузере по умолчанию откроется страница ввода учётных данных:
<gallery mode=packed heights="350px" style="float:left; clear:right; margin-right:1em; margin-left:1em">
Авторизация 4.png
Авторизация 5.png
</gallery>
 
:4. Введите логин и пароль
:Отобразится страница с запросом разрешения:
:[[File:Авторизация 6.png|400px]]
:5. Нажмите кнопку '''Разрешить'''
:6. Подтвердите открытие расширения Svacer в VSCode
:Откроется окно VSCode с открытой вкладкой расширения, на которой отображается список проектов Svacer: 
:[[File:Авторизация 7.png|800px|none]]

=== Алгоритм работы ===
Каждый раз для разметки маркеров того или иного снимка проекта требуется выполнять следующие действия:
# [[#Открытие папки исходного кода|Открыть папку для хранения исходного кода]]
# [[#Выбор проекта, ветки и снимка|Выбрать проект, ветку и снимок]]
# [[#Загрузка исходного кода|Загрузить исходный код]]
# [[#Загрузка маркеров|Загрузить маркеры]]
# [[#Выбор маркера|Выбрать маркер]]
# [[#Просмотр исходного кода|Посмотреть исходный код файла]]
# [[#Разметка маркера|Разметить маркеры]]
# [[#Управление комментариями|Добавить, изменить или удалить комментарии]] (опционально)
# [[#Блокировка и разблокировка маркеров|Заблокировать или разблокировать маркеры]] (опционально)
# [[#Выбор другого снимка проекта|Выбрать другие снимки проекта]] (опционально)

==== Открытие папки исходного файла ====
Чтобы открыть папку для хранения исходного кода:
:1. Перейдите в окно проводника операционной системы одним из трех способов:
:* способ 1 – в меню '''Файл''' выберите пункт '''Открыть папку'''
:* способ 2 – на вкладке '''Проводник''' нажмите кнопку '''Открыть папку'''
:* способ 3 – нажмите клавиши CTRL+K и следом CTRL+O
:2. Выберите папку, в которой будет храниться исходный код снимка проекта
<gallery mode=packed heights="400px" style="float:left; clear:right; margin-right:1em; margin-left:1em">
Открытие папки 1.png|Открытие папки. Способ 1
Открытие папки 2.png|Открытие папки. Способ 2
</gallery>
 
Открытая папка и её содержимое будет отображается на вкладке '''Проводник'''.

==== Выбор проекта, ветки и снимка ====
Для этого перейдите в раздел '''ПРОЕКТЫ''' и с помощью кнопки [[File:Иконка стрелочка.png|x20px]] раскройте проект и ветку, нажмите на снимок. 
Для перехода в раздел '''ПРОЕКТЫ''' можно использовать [[#Поддерживаемые команды|команду]] '''Инструменты Svacer: Перевести фокус на представление Проекты Svacer'''. 
Выбранные проект, ветка и снимок отмечены точкой справа, а информация о них отображается в разделе '''ИНФОРМАЦИЯ SVACER'''. 
Для последнего загруженного снимка отображается надпись '''latest'''. 
[[File:Выбор снимка.png|300px]]

==== Загрузка исходного кода ====
Для этого запустите на выполнение команду '''Svacer: Загрузить исходный код.''' 
[[File:Загрузка исходного кода 1.png|600px]] 

В процессе загрузки будет отображаться строка прогресса. Например: 
[[File:Загрузка исходного кода 2.png|400px]] 

После завершения загрузки отобразится сообщение об успехе и количестве загруженных файлов. Например: 
[[File:Загрузка исходного кода 3.png|400px]]

==== Загрузка маркеров ====
Для этого в разделе '''ИНФОРМАЦИЯ SVACER''' нажмите кнопку '''Загрузить маркеры''' или запустите на выполнение [[#Поддерживаемые команды|команду]] '''Svacer: Загрузить данные с сервера'''.
[[File:Загрузка маркера 1.png|thumb|none|300px|Загрузка маркеров. Вариант 1]]
[[File:Загрузка маркера 2.png|thumb|none|600px|Загрузка маркеров. Вариант 2]]
После завершения загрузки:
:1. Отобразится сообщение об успехе и количестве загруженных маркеров. Например:
:[[File:Загрузка маркера 3.png|400px]]
:2. Раздел '''ПРОЕКТЫ SVACER''' закроется
:3. Отобразятся разделы '''ФАЙЛЫ SVACER''' и '''ДЕТЕКТОРЫ SVACER'''
[[File:Загрузка маркера 4.png|800px]]

==== Выбор маркера ====
Для этого:
:1. Выберите маркер в одном из двух разделов:
::а) '''ФАЙЛЫ SVACER''' – в этом разделе отображаются все файлы [[#Выбор проекта, ветки и снимка|выбранного снимка проекта]], в которых найдены маркеры
::: Если навести курсор на строку с файлом, отобразится сообщение, которое содержит полный путь к файлу и количество маркеров в нем, а также появится кнопка [[File:Icon block.png|x20px]] или [[File:Icon unblock.png|x20px]] для блокировки или разблокировки маркеров для разметки другими пользователями – по имени файла.
::: Чтобы раскрыть список маркеров в файле, нажмите кнопку [[File:Иконка стрелочка.png|x20px]] или на имя файла.
::б) '''ДЕТЕКТОРЫ SVACER''' – в этом разделе отображаются все детекторы, которые сработали в выбранном снимке проекта
::: Серьезность (критичность) детектора обозначена цветом:
:::* красный – наивысшая серьезность (CRITICAL)
:::* желтый – высокая серьезность (MAJOR)
:::* белый – обычная серьезность (NORMAL, MINOR, UNDEFINED)
::: Если навести курсор на строку с детектором, отобразится сообщение с его серьёзностью и количеством маркеров, а также появится кнопка [[File:Icon block.png|x20px]] или [[File:Icon unblock.png|x20px]] для блокировки или разблокировки маркеров для разметки другими пользователями – по детектору.
::: Чтобы раскрыть список маркеров, найденных этим детектором, нажмите кнопку [[File:Иконка стрелочка.png|x20px]] или на имя детектора.
<gallery mode=packed heights="250px" style="float:left; clear:right; margin-right:1em; margin-left:4em">
Выбор маркера 1.png|Выбор маркера в списке файлов
Выбор маркера 2.png|Выбор маркера в списке детекторов
</gallery>
 
:: Слева отобразится раздел '''МАРКЕРЫ SVACER''' со списком маркеров, найденных в файле, а справа отобразится редактор исходного кода с фокусом на выбранном маркере.
:: В первой строке раздела '''МАРКЕРЫ SVACER''' указано имя файла, в котором обнаружен маркер. Список маркеров файла сгруппирован по названию детектора.
::[[File:Выбор маркера 3.png|800px]]
:2. Нажмите кнопку [[File:Иконка стрелочка.png|x20px]] или на название маркера в разделе '''МАРКЕРЫ SVACER''', чтобы раскрыть следующую информацию о нем:
:: а) Трасса, построенная при анализе кода
::: Для каждого элемента (записи) трассы отображается имя файла, номер строки и описание
::: Если нажать на элемент трассы, в редакторе откроется исходный код файла с фокусом на строку, указанную в трассе
:: б) Данные [[#Разметка маркера|разметки]]
:: в) [[#Управление комментариями|Комментарии пользователей]]
::[[File:Выбор маркера 4.png|400px]]

==== Просмотр исходного кода ====
Открыть файл с исходным кодом можно открыть двумя способами:
:1. Нажмите на маркер в одном из разделов: '''ФАЙЛЫ SVACER, ДЕТЕКТОРЫ'''
:2. Нажмите кнопку [[File:Иконка цель.png|x20px]] справа от маркера в разделе '''МАРКЕРЫ SVACER'''
Наведите курсор на маркер в коде, чтобы посмотреть детальную информацию:
[[File:Просмотр кода 1.png|none|800px]]
Чтобы посмотреть и проанализировать трассу, нажмите на элемент (запись) трассы в подразделе '''Трасса маркера''' раздела '''МАРКЕРЫ SVACER'''.

В редакторе кода откроется исходный код файла с фокусом на строку выбранного элемента трассы.

Также просмотреть исходный код файла можно на вкладке '''Проводник'''. Для этого нажмите на имя файла в иерархическом списке файлов проекта.
[[File:Просмотр кода 2.png|none|800px]]

==== Разметка маркера ====
Для этого в подразделе '''Разметка маркера''' раздела '''МАРКЕРЫ SVACER''' выберите '''Статус''', '''Серьёзность''' и '''Действие'''.

Установка серьёзности и действия доступны только после установки статуса.
[[File:Разметка маркера.png|none|400px]]

==== Управление комментариями ====
Добавлять, изменять и удалять комментарии можно в подразделе '''Комментарии маркера''' раздела '''МАРКЕРЫ SVACER''' с помощью кнопок [[File:Иконка плюс.png|x20px]], [[File:Иконка редактирования.png|x20px]] и [[File:Иконка корзина.png|x20px]] соответственно.
Кнопка [[File:Иконка плюс.png|x20px]] отображается при наведении курсора на шапку подраздела, а кнопки [[File:Иконка редактирования.png|x20px]] и [[File:Иконка корзина.png|x20px]] – на сам комментарий.
[[File:Управление комментариями.png|none|300px]]

==== Блокировка и разблокировка маркеров ====
Для блокировки разметки используйте кнопку [[File:Icon block.png|x20px]] в следующих частях интерфейса:
:1. В разделе '''ДЕТЕКТОРЫ SVACER'''
: В этом случае блокировка распространяется на все маркеры выбранного детектора в открытом проекте и ветке, для всех снимков ветки.
:2. В разделе '''ФАЙЛЫ SVACER'''
: В этом случае блокировка распространяется на все маркеры в выбранном файле в открытом проекте и ветке, для всех снимков ветки.
:3. В разделе '''МАРКЕРЫ SVACER'''
: В этом случае блокировка распространяется на все эквивалентные маркеры в открытом проекте и ветке, для всех снимков ветки.
Если один пользователь заблокировал маркер, то в строке маркера отображается [[File:Icon other block.png|x20px]]. В этом случае другой пользователь не сможет заблокировать и разблокировать детектор, которому принадлежит этот маркер, и файл, в котором этот маркер найден.

Чтобы разблокировать маркер нажмите кнопку [[File:Icon unblock.png|x20px]]

==== Выбор другого снимка проекта ====
Чтобы перейти к другому снимку этого или другого проекта:
:1. Нажмите кнопку [[File:Иконка очистки предупреждений.png|x20px]] в шапке раздела '''ИНФОРМАЦИЯ SVACER''' (отображается при наведении курсора) или запустите на выполнение [[#Поддерживаемые команды|команду]] '''Svacer: Очистить предупреждения'''
:[[File:Выбор другого снимка 1.png|none|400px]]

:2. Закройте папку с исходными кодами – в меню '''Файл''' выберите пункт '''Закрыть папку''' или воспользуйтесь горячими клавишами CTRL+K и F
:[[File:Выбор другого снимка 2.png|none|400px]]

:3. Повторите действия [[#Алгоритм работы|алгоритма работы]]

=== Поддерживаемые команды ===
Чтобы открыть список доступных команд, нажмите клавиши CTRL+SHIFT+P или введите '''<code>></code>''' в строке поиска.
{| class="wikitable" style="text-align: left"
|-
! Команда !! Аналог команды !! Описание
|-
| Svacer: Информация о проекте || svacer.info || Отобразить сообщение с информацией о выбранных проекте, ветке и снимке
|-
| Svacer: Загрузить исходный код|| svacer.loadSources || Загрузка исходного кода выбранного снимка проекта
|-
| Svacer: Загрузить данные с сервера || svacer.load || Загрузка результатов анализа (маркеров) выбранного снимка проекта
|-
| Svacer: Очистить предупреждения || svacer.clear || Очистить результаты анализа (маркеры) выбранного снимка проекта. После очистки маркеров становится доступен раздел со списком проектов
|-
| Svacer: Сбросить выбранный проект || – || Сброс выбранного проекта в разделах '''ИНФОРМАЦИЯ SVACER''' и '''ПРОЕКТЫ SVACER'''
|-
| Представление: Показать Инструменты Svacer || – || Перейти к панели '''ИНСТРУМЕНТЫ SVACER'''
|-
| Инструменты Svacer: Перевести фокус на представление Информация Svacer || – || Перейти в раздел '''ИНФОРМАЦИЯ SVACER'''
|-
| Инструменты Svacer: Перевести фокус на представление Файлы Svacer || – || Перейти в раздел '''ФАЙЛЫ SVACER'''
|-
| Инструменты Svacer: Перевести фокус на представление Проекты Svacer || – || Перейти в раздел '''ПРОЕКТЫ SVACER'''
|}

Help:CLI

2023-11-14T09:30:22Z

Writer:

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

svacer <command name> --help

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

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

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

=== Создание PDF отчета для проекта ===
Для создания PDF отчета по проекту из интерфейса командной строки используется команда '''pdfgen'''. Назначение команды состоит в том, чтобы добиться из консоли результатов (создание PDF файла отчета), аналогичным следующим действиям пользователя в GUI:
# Выгрузка таблицы маркеров в формате PDF ([[#pic1|Рис. 1]])
# Предварительное формирование содержимого таблицы маркеров
#* По режимам сравнения (new, missing, same, matched) с указанием цели и источника сравнения, ([[#pic2|Рис. 2]])
#* По используемым фильтрам Custom (ограниченный набор из 4 параметров) ([[#pic3|Рис. 3]])

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


[[File:SimpleReport.png|none|left|alt=SimpleReport window]]
'''Рис. 1 — Отчет без сравнения'''


[[File:CompareReport.png|none|left|alt=CompareReport window]]
'''Рис. 2 — Отчет со сравнением'''


[[File:CompareFiltersReport.png|none|left|alt=CompareFiltersReport window]]
'''Рис. 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 часа).

=== Импорт разметки из исходного кода на сервер истории ===
Импорт разметки из исходного кода на сервер истории возможен с помощью команды '''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>'''. В таком случае разметка будет импортирована из объекта сборки сразу после загрузки его на сервер.

==== Описание шаблона разметки DEFAULT ====
Сервер позволяет добавить собственные шаблоны разметки, для удобства добавлен не удаляемый шаблон DEFAULT. Список шаблонов можно увидеть в '''Settings > Markup templates''' (при наличии у пользователя доступа).

Шаблон можно использовать как для импорта, так и для экспорта разметки, поэтому можно проверить ожидаемый формат [[Help:UI_manual#Экспорт_кода_с_разметкой|через выгрузку кода с указанием шаблона]].

В шаблоне DEFAULT каждая разметка описывается на отдельной строчке перед маркером, при необходимости можно использовать несколько строчек. Импорт разметки со статусом Undecided (или не правильным) не производится (включая комментарий).

Пример:

//svacer_review: FORMAT_STRING.PARAM_EXCESS r:Confirmed|s:Minor|a:Undecided|c:
//svacer_review: UNINIT.LOCAL_VAR r:Confirmed|s:Unspecified|a:Fix required|c:will be fixed
printf("v = %d", fl3(), i);

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

=== Изменение инвариантов для распространения разметки между снимками с несовпадающими путями ===
Если на сервер был загружен снимок, в котором расположение некоторых (или всех) файлов поменялось, а при импорте не был указан флаг '''--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.
На текущий момент информация о подавленных предупреждения недоступна в веб-интерфейсе.

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

=== Поддержка протокола LDAP для аутентификации пользователей ===
==== Общий принцип аутентификации ====
Схема аутентификации с помощью протокола LDAP следующая:

# Сервер запускается с указанием конфигурационного файла с настройками для LDAP аутентификации
# В форме аутентификации пользователь выбирает нужный тип аутентификации (svacer или LDAP)
# При выборе аутентификации LDAP, после заполнения необходимых параметров, запрос на аутентификацию отправляется на сервер svacer
# Сервер Svacer, используя настройки из конфигурационного файла, обращается к внешнему LDAP серверу и проводит проверку пользователя
# В случае успешной аутентификации, в БД сервера Svacer создается запись (если ее еще нет) для пользователя, чтобы можно было управлять ролями данного пользователя
# Сервер возвращает токен безопасности для дальнейшей работы, аналогичный токену, возвращаемому при аутентификации локальных пользователей

Для каждого пользователя, успешно прошедшего проверку на LDAP сервере, создается локальная запись в БД Svacer. Управлять таким пользователем можно как и обычным пользователем, за исключением:
* Пользователю нельзя сменить пароль
* Пользователь не может сменить пароль самостоятельно
* В случае отсутствия связи между сервером Svacer и сервером LDAP, данный пользователь не сможет зайти в систему

==== Запуск сервера с поддержкой LDAP ====
Сервер может быть запущен как в с поддержкой аутентификации через LDAP, так и без. Для того, чтобы включить аутентификацию через LDAP необходимо указать конфигурационный файл. Типовой пример конфигурационного файла для подключения к контроллеру домена MS ActiveDirectory или серверу openLDAP можно получить с помощью команды:

svacer ldap print

Запуск сервера с поддержкой LDAP осуществляется командой:

svacer server --ldap ldap.json

При запуске сервер svacer формирует список доступных для LDAP аутентификации серверов и выводит соответствующее сообщение. Ниже приведен лог сервера, запущенного с поддержкой протокола LDAP.
[[File:LdapServerAdded.png|none|left|1000px|alt=LdapServerAdded]]

После запуска сервера svacer с поддержкой LDAP в GUI становится активна вкладка LDAP.

Для аутентификации с помощью LDAP необходимо выбрать сервер из выпадающего списка.

[[File:LdapServerChoose.png|none|left|alt=LdapServerChoose]]

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

Для отключения возможности аутентификации встроенными средствами сервера Svacer нужно использовать опцию '''disable-svacer-auth'''.

Пример:
svacer server --ldap ldap.json --disable-svacer-auth

==== Конфигурационный файл сервера для поддержки LDAP ====
Типовой пример конфигурации представлен ниже.

{
"servers": [
{
"name": "active_directory",
"basedn": "dc=domain,dc=home,dc=org",
"useGroup": true,
"hideURL": true,
"checkAlivePeriod": 60,
"connection": {
"url": "ldaps://192.168.11.71:636",
"mirrors":["ldaps://192.168.11.72:636","ldaps://192.168.11.73:636"]
"connectAs": "cn=ldap_service,cn=users,dc=domain,dc=home,dc=org",
"password": "12345678",
"ignoreCertCheck": false,
"caCertFiles":["/etc/ssl/certs/a*","/etc/ssl/certs/my_certs/*"]
},
"group": {
"basedn": "cn=users",
"filter": "(&(objectCategory=Group)(cn=dep_devops))",
"userMember": "member",
"display":"cn",
"svacerRole":"cn"
},
"user": {
"basedn": "cn=users",
"filter": "(&(objectCategory=Person)(sAMAccountName=*))",
"login": "sAMAccountName",
"group": "dn",
"info": {
"display": "cn",
"email": "email",
"firstName": "givenName",
"lastName": "sn"
}
},
"enabled": true
},
{
"name": "open_ldap",
"basedn": "dc=example,dc=com",
"useGroup": true,
"connection": {
"url": "ldap://127.0.0.1:389",
"connectAs": "cn=admin,dc=example,dc=com",
"password": "12345678"
},
"group": {
"basedn": "ou=groups",
"filter": "(&(objectClass=groupOfNames)(cn=svacer))",
"userMember": "member",
"display":"cn"
},
"user": {
"basedn": "ou=users",
"filter": "(&(objectClass=PosixAccount))",
"login": "uid",
"group": "dn",
"info": {
"display": "dn",
"email": "mail",
"firstName": "givenName",
"lastName": "sn"
}
},
"enabled": true
}
]
}

В конфигурации можно указать несколько серверов. Все сервера в совокупности рассматриваются как единый источник проверки пользователей. То есть если на двух серверах будут два пользователя с одинаковым логином, они будут считаться идентичными. Ниже приводится описание параметров конфигурации.
* name — произвольное имя (уникальное для каждого сервера)
* basedn — DN относительно которого будут проводится все операции в LDAP каталоге
* useGroup — проверять ли принадлежность пользователя к группе
* hideURL — не передавать сетевой адрес LDAP сервера. Конечные пользователи будут видеть в выпадающем списке только имя сервера, указанное в поле name. В поле URL будет пустая строка.
* checkAlivePeriod — Промежуток времени в секундах, который должен проходить между периодическими проверками доступности сервера LDAP. Если параметр равен 0 или не указан, такая проверка не проводится.
* connection — подсекция, описывающая параметры соединения с сервером
:* url — адрес сервера, формата: ldap[s]://domain:port В случае использования TLS для подключения к LDAP серверу, необходимо указать правильный порт (по умолчанию 636).
:* mirrors — список хостов, которые будут использованы в случае недоступности основного хоста, указанного в поле URL. Формат указания хостов тот же, что и в поле URL. Префикс ldap[s] должен быть одинаковым для всех хостов и совпадать с префиксом в поле URL.
:* connectAs — имя пользователя в формате DN, из под которого будут производится операции в LDAP каталоге
:* password — пароль пользователя
:* ignoreCheck — не проверять сертификат в случае ldaps:// соединения. Полезно при самоподписанных сертификатах. Если флаг установлен в значение false, необходимо установить значение поля caCertFiles.
:* CaCertFiles — массив значений, описывающих какие файлы корневых сертификатов добавлять в конфигурацию Svacer. Формат файлов сертификатов — PEM
* group — подсекция, описывает параметры проверки принадлежности пользователя к группе
:* basedn — RDN, добавляемая к общей DN. Относительно этого DN производится поиск группы
:* filter — фильтр, используемый при поиске группы. Необходимо, если надо указать несколько групп
:* userMember — атрибут в группе, содержащий пользователей, принадлежащих группе
:* display — атрибут, содержащий имя группы для отображения
:* svacerRole — атрибут, из которого будет извлечено имя роли, созданной в Svacer, и автоматически сопоставляемой с пользователем.
* user — подсекция, описывает параметры получения информации о пользователе
:* basedn — RDN, добавляемая к общей DN. Относительно этого DN производится поиск группы
:* filter — фильтр, используемый при поиске пользователей.
:* login — атрибут, в котором находится login пользователя.
:* group — атрибут в пользователе, на который ссылается атрибут group.userMember (обычно это «dn» пользователя)
:* info — подсекция описывающая в каких атрибутах находится информация о пользователе
::* display — атрибут, содержащий полное имя пользователя для отображения (ФИО)
::* email — атрибут с почтовым адресом
::* firstName — атрибут с именем
::* lastName — атрибут с фамилией
* enabled — использовать или нет данный сервер

[[LDAP_configuration|Примеры конфигурации взаимодействия с LDAP сервером]]

Рассмотрим пример обработки запроса на вход в систему LDAP пользователя, указавшего значение ivanov_ii в поле логина и выбравшего конфигурацию active_directory из примера выше
:# Svacer создает служебное подключение к хосту 192.168.11.71 со следующими параметрами
:#* используется TLS соединение (ldaps префикс)
:#* порт 636
:#* проверяется сертификат LDAP сервера (ignoreCertCheck = false); для проверки используются сертификаты CA (из папки /etc/ssl/certs — все сертификаты, начинающиеся с буквы a; из папки /etc/ssl/certs/my_certs/ — все сертификаты)
:#* логин для подключения к LDAP серверу: "cn=ldap_service,cn=users,dc=domain,dc=home,dc=org" (connectAs); пароль: 12345678 (password)
:# Если подключение к хосту невозможно (хост недоступен), то пробуются хосты 192.168.11.72,192.168.11.73 с параметрами, аналогичными параметрам пункта 1
:# Если подключение невозможно, процесс входа завершается с ошибкой
:# Производится поиск пользователя в LDAP каталоге со следующими параметрами:
:#* строка запроса: (&(sAMAccountName=ivanov_ii)((&(objectCategory=Person)(sAMAccountName=*)))), sAMAccountName — взят из поля user.login конфиг файла; ivanov_ii — введено пользователем; (&(objectCategory=Person)(sAMAccountName=*)) — взято из поля user.filter конфиг файла
:#*начальный узел, с которого будет произведен поиск: cn=users, dc=domain,dc=home,dc=org
:#*поиск производится по всему поддереву
:# Если пользователей не найдено или найдено больше 1 пользователя, процесс входа завершается с ошибкой
:# Флаг useGroup = true, поэтому производится дополнительная проверка группы пользователя
:#* выполняется поиск групп в каталоге LDAP со следующими параметрами:
:#**строка запроса: (&(objectCategory=Group)(cn=dep_devops)) — взято из поля group.filter
:#**начальный узел: cn=users, dc=domain,dc=home,dc=org, где cn=users — взято из поля group.basedn; значение dc=domain,dc=home,dc=org — взято из поля basedn конфиг файла
:#**поиск производится по всему поддереву
:#**определяется список пользователей группы (каждому пользователю соответствует значение атрибута с именем member (взято из поля group.userMember конфиг файла))
:#* Если ни одной группы не найдено, то процесс входа завершается с ошибкой
:#*Определяются группы, в которые входит пользователь. Для этого для каждой группы, найденной в пункте выше, просматривается список пользователей и ищется значение cn=ivanov_ii,cn=users,dc=domain,dc=home,dc=org (в поле user.group конфиг файла указано значение dn, что означает, что необходимо использовать DN пользователя для данной процедуры). Если атрибут найден, считается что пользователь принадлежит группе.
:#* Если пользователь не принадлежит ни к одной группе, процесс входа завершается с ошибкой
:# Производится попытка подключения к хосту LDAP с параметрами, аналогичными параметрам из пункта 1, за исключением логина (cn=ivanov_ii,cn=users,dc=domain,dc=home,dc=org) и пароля пользователя (введен в поле пароль формы входа)
:# Если подключение не удалось создать, то процесс входа завершается с ошибкой
:# Процесс аутентификации пользователя произведен успешно
:# Производится создание локального пользователя svacer с именем ivanov_ii, если его еще нет
:# Так как useGroup = true и указан атрибут svacerRole с непустым значением, то производится привязка ролей Savcer пользователя на основе его участия в группах LDAP (смотри соответствующий пункт)

==== Привязка группы LDAP к роли Svacer ====
Возможно автоматическое назначение пользователям LDAP ролей Svacer. Для использования данной функции необходимо выполнить следующие предварительные действия:
:* Администратор LDAP сервера создает в каталоге LDAP нужные группы (например cn=users,ou=svacer,dc=example,dc=com и cn=admins, ou=svacer,dc=example,dc=com), которые будут привязаны к ролям Svacer.
:* Администратор LDAP сервера помещает пользователей LDAP в соответствующие LDAP группы (cn=users,ou=svacer,dc=example,dc=com или cn=admins, ou=svacer,dc=example,dc=com)
:* Администратор Svacer создает роли в Svacer, имеющие в точности такое же название, как значение атрибута, указанного в поле svacerRole конфигурационного файла. В пример можно использовать аттрибут cn и в этом случае необходимо создать роли users и admins
:* Администратор Svacer добавляет в конфигурационный файл в поле svacerRole имя атрибута, по которому будет производится привязка. Для примера выше — строчку svacerRole="cn"
После выполнения данных действий, во время входа пользователя в систему пользователю будут добавлены роли по следующему алгоритму:
:* Производится поиск групп, к которым принадлежит пользователь. Поиск производится по параметрам, указанным в секции group конфигурационного файла. Для примера, пользователь может состоять в следующих группах: (cn=users,ou=svacer,dc=example,dc=com), (cn=dep_dev,dc=example,dc=com)
:* Для каждой найденной группы, выбирается значение атрибута, указанного в поле svacerRole. В примере — имя атрибута cn. Получаются два имени: users, dep_dev
:* Производится поиск ролей Svacer с именем users и dep_dev. Если такие роли найдены, то пользователю они будут добавлены. Так как в примере роль dep_dev не создана, то будет добавлена только роль users.

Удаление ролей автоматически не производится. Вместо этого предлагается ручного режим синхронизации ролей пользователя. Для синхронизации ролей с текущими группами, в которых состоит пользователь, используется команда cli

svacer ldap sync_roles --login [user_login] --server [server_name] --apply

Данная команда проверит наличие пользователя user_login в соответствующей роли группе LDAP и если его в группе не будет, уберет роль у пользователя. Также команда добавит недостающие роли, на основе механизма, описанного выше (при входе пользователя). Флаг apply позволяет "оценить" получаемые изменения прежде чем они будут применены. По умолчанию флаг apply = false.

==== Использование CLI сервера Svacer с поддержкой LDAP ====
Для выполнения некоторых действий в cli с помощью команды svacer требуется аутентификация пользователя. Для аутентификации с помощью ldap сервера необходимо указать в команде кроме имени пользователя и пароля имя сервера с помощью флага ldap_server (имя сервера регистр-зависимо). Например:

./svacer quickdiff --user loginok --password loginok --ldap_server openLDAP2 --project zstd --branch zstd_14 --snapshot_v1 v1.4.1 --snapshot_v2 zstd_140

Если флаг ldap_server не указан, аутентификация производится механизмами сервера svacer, как и в предыдущих версиях. Параметр ldap_server можно опустить, указав сервер в переменной окружения SVACER_LDAP_SERVER. Например:

SVACER_LDAP_SERVER=“openLDAP2“ ./svacer quickdiff --user loginok --password loginok --project zstd --branch zstd_14 --snapshot_v1 v1.4.1 --snapshot_v2 zstd_140

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

./svacer ldap servers --host 127.0.0.1 --port 8080

Вывод содержит два столбца (имя и URL сервера). В качестве значения для параметра ldap_server необходимо использовать содержимое первого столбца.

==== Обновление данных LDAP пользователей ====
Для каждого LDAP пользователя создается соответствующая ему запись в БД Svacer, в которую включается ФИО из LDAP и адрес его электронной почты. Через какое-то время данные пользователей могут меняться, в этом случае возможно обновить данные LDAP пользователей, хранящиеся в Svacer, синхронизировав их с данными LDAP сервера.
Для обновления данных одного пользователя можно воспользоваться окном редактирования пользователя, в котором можно нажать кнопку '''Load from LDAP'''. В соответствующие окна будут добавлены данные, загруженные из LDAP сервера.

[[File:ChangeUserProfile.png|none|left|alt=ChangeUserProfile]]

Также данные пользователей можно обновить с помощью интерфейса командной строки. Для этого можно использовать подкоманду '''updateUsers''' команды '''ldap'''. Общий синтаксис команды выглядит следующим образом:

./svacer ldap updateUsers --onlyEmpty

Флаг '''onlyEmpty''' позволяет обновлять только пустые поля ФИО и eMail. Заполненные поля не будут изменены. Команда обновит данные всех пользователей, записи о которых имеются в базе Svacer.

=== Поддержка сквозной аутентификации ===
Svacer поддерживает сквозную аутентификацию через reverse proxy. Для этого используется опция proxy-mode. При включении этой опции есть возможность проходить аутентификацию (используя HTTP Basic Authentication) на reverse proxy сервере и использовать эти данные для аутентификации на сервере Svacer.

При включенном proxy-mode используется header с прокси '''Authorization Basic ...''', откуда Svacer берет имя пользователя и пароль, проверяет и аутентифицирует пользователя, если аккаунт с таким логином и паролем существует в БД пользователей Svacer.

Пример запуска сервера с поддержкой сквозной аутентификации:

./svacer server --proxy-mode

=== Хуки ===
Для получения данных хуков при запуске сервера нужно указать опцию '''--hooks <path to JSON file>'''. Эта опция задаёт файл, содержащий информацию о расширении сервера посредством хуков, которые пользователь может вызывать из web-интерфейса.
Каждый хук соответствует некоторому процессу или скрипту, который сервер запускает в ответ на вызов соответствующей команды из web-интерфейса.
Формат файла Hooks следующий:
{
"hooks": [
{
"id": "<id>",
"label": "<label >",
"target": "<target>",
"input": ["<param1>", "<param2>",…],
"cmd": "<path to executable>",
"args": ["<arg1>", “<arg2>”, …]
},
...
]
}

'''Параметры хуков '''
{| class="wikitable"
! style="width:100px;" | Параметр || Описание
|-
| ''id''
| Идентификатор хука. Должен быть уникальным в файле
|-
| ''label''
| Имя команды, которую пользователь видит в web-интерфейсе
|-
| ''target''
| Место в UI, в которое будет добавлена команда. 
Сейчас поддерживается только одно значение — default. Оно соответствует вкладке Details на правой панели пользовательского интерфейса
|-
| ''input''
| Параметры, которые можно передать в запускаемый процесс, исходя из контекста вызова команды в web-интерфейсе. 
Поддерживаемые значения:
* markerID — UUID идентификатор маркера;
* branchID — UUID идентификатор ветки;
* snapshotID — UUID идентификатор снимка;
* projectID — UUID идентификатор проекта;
* url — URL маркера в web-интерфейсе, на котором была вызвана команда;
* marker — будет заменен на полное имя временного файла, содержащего сериализованное в JSON представление маркера, который включает в себя его трассу и информацию о разметке
|-
| ''cmd''
| Полный путь к процессу, который будет запущен. Не должен включать аргументы запуска
|-
| ''args''
| Аргументы, передаваемые в запускаемый процесс. Полный список аргументов запускаемого процесса состоит из списка <args> и списка значений, соответствующих полю <input>
|}

Одним из типичных сценариев использования хуков является создание кейсов для выбранного предупреждения в системах отслеживания ошибок, таких как Jira и Gitlab. Примеры скриптов для этого можно найти на странице [[Примеры использования хуков]].

=== Автомиграция разметки ===

На svacer возможно настроить автомиграцию разметки с ветки на ветку (необходимо разрешение на администрирование сервера у пользователя).

svacer server automigrate [command] [flags]

Существующие command:

* add - добавляет автомиграцию в соответствии с паттерном;

* delete - удаляет автомиграцию;

* show_config - показывает все заданные миграции (Config Table), их id, время создания и пользователя, которые её создал;

* show_automigrate - показывает таблицу всех существующих проектов и веток с которых и на какие происходят автоматические миграции (Automigrate Table);

* log - выводит список всех совершенных миграций (Done Automigrate Table).

Флаг '''pattern''' (применяется для command <add|delete|show_config|log>):

* Для add: Паттерн автомиграции формате: srcProject{Id|Name}/srcBranch{Id|Name}=>receiveProject{Id|Name|RegEx}/receiveBranch{Id|Name|RegEx}. RegEx - в формате SIMILAR TO RegEx для PostgreSQL
(https://www.postgresql.org/docs/current/functions-matching.html пункт 9.7.2).

* Для delete: Паттерн автомиграции в формате: srcProject{Id|Name}/srcBranch{Id|Name}=>receiveProject{Id|Name|RegEx}/receiveBranch{Id|Name|RegEx}. Паттерн должен быть точно таким же, каким он записан в Config Table.

* Для show_config: Паттерн автомиграции. Поиск будет происходить в следующем виде: ILIKE "'%"+pattern+"%'".

* Для log: Флаг в формате srcProjectId/srcBranchId=>receiveProjectId/receiveBranchId или srcProjectName/srcBranchName=>receiveProjectName/receiveBranchName для вывода автомиграций с данным паттерном.

Флаг '''id''' (применяется для command <delete|show_automigrate> в формате uuid):

* Для delete: id для удаления автомиграции (из Config Table)

* Для show_automigrate: id ветки/проекта или конфигурации для нахождения его в таблице автомиграций (Automigrate Table) и вывода автомиграций,где присутствует данный id.

Флаг '''format''' (применяется для command <show_config|show_automigrate|log>)

* Для show_config: Формат вывода таблицы. Возможные значения: table - вывод в виде таблицы, json - вывод в виде json, no-id - вывод без config id. Значения можно перечислить через запятую: json,no-id. По умолчанию table.

* Для show_automigrate|log: Формат вывода таблицы. Возможные значения: table - вывод в виде таблицы, json - вывод в виде json. По умолчанию table.

Также возможно использовать POST запрос по адресу /api/automigrate. В теле передается json, с полями action(not null), pattern, id. Выполняется по тому же принципу, что и CLI.

Принцип работы сервиса:

* При запуске сервера запускается сервис automigrate.

* При занесении новой миграции, находит все миграции, подходящие под паттерн, и копирует разметку на них.

* При удалении миграции, удаляет её из таблицы Config и удаляет из таблицы автомиграций.

* Не может копировать разметку с нескольких веток на одну (будет выдавать ошибку).

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

* Единственный случай, когда не даёт выполнить действие - это upload результатов svace через CLI (либо import с флагом --upload). Тогда выдает ошибку миграции и отменяет upload (может произойти, когда имя данной ветки (в качестве to_branch) подходит под несколько паттернов).

Help:CLI

2023-10-25T05:10:43Z

Writer: Разъяснение про импорт разметки с нечитаемым названием

Help:CLI

2023-09-13T12:53:57Z

Writer: Описание шаблона разметки DEFAULT

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

svacer <command name> --help

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

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

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

=== Создание PDF отчета для проекта ===
Для создания PDF отчета по проекту из интерфейса командной строки используется команда '''pdfgen'''. Назначение команды состоит в том, чтобы добиться из консоли результатов (создание PDF файла отчета), аналогичным следующим действиям пользователя в GUI:
# Выгрузка таблицы маркеров в формате PDF ([[#pic1|Рис. 1]])
# Предварительное формирование содержимого таблицы маркеров
#* По режимам сравнения (new, missing, same, matched) с указанием цели и источника сравнения, ([[#pic2|Рис. 2]])
#* По используемым фильтрам Custom (ограниченный набор из 4 параметров) ([[#pic3|Рис. 3]])

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


[[File:SimpleReport.png|none|left|alt=SimpleReport window]]
'''Рис. 1 — Отчет без сравнения'''


[[File:CompareReport.png|none|left|alt=CompareReport window]]
'''Рис. 2 — Отчет со сравнением'''


[[File:CompareFiltersReport.png|none|left|alt=CompareFiltersReport window]]
'''Рис. 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 часа).

=== Импорт разметки из исходного кода на сервер истории ===
Импорт разметки из исходного кода на сервер истории возможен с помощью команды '''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>'''. В таком случае разметка будет импортирована из объекта сборки сразу после загрузки его на сервер.

==== Описание шаблона разметки DEFAULT ====
Сервер позволяет добавить собственные шаблоны разметки, для удобства добавлен не удаляемый шаблон DEFAULT. Список шаблонов можно увидеть в '''Settings > Server information''' (при наличии у пользователя доступа).

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

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

Пример:

//svacer_review: FORMAT_STRING.PARAM_EXCESS r:Confirmed|s:Minor|a:Undecided|c:
//svacer_review: UNINIT.LOCAL_VAR r:Confirmed|s:Unspecified|a:Fix required|c:will be fixed
printf("v = %d", fl3(), i);

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

=== Изменение инвариантов для распространения разметки между снимками с несовпадающими путями ===
Если на сервер был загружен снимок, в котором расположение некоторых (или всех) файлов поменялось, а при импорте не был указан флаг '''--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.
На текущий момент информация о подавленных предупреждения недоступна в веб-интерфейсе.

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

=== Поддержка протокола LDAP для аутентификации пользователей ===
==== Общий принцип аутентификации ====
Схема аутентификации с помощью протокола LDAP следующая:

# Сервер запускается с указанием конфигурационного файла с настройками для LDAP аутентификации
# В форме аутентификации пользователь выбирает нужный тип аутентификации (svacer или LDAP)
# При выборе аутентификации LDAP, после заполнения необходимых параметров, запрос на аутентификацию отправляется на сервер svacer
# Сервер Svacer, используя настройки из конфигурационного файла, обращается к внешнему LDAP серверу и проводит проверку пользователя
# В случае успешной аутентификации, в БД сервера Svacer создается запись (если ее еще нет) для пользователя, чтобы можно было управлять ролями данного пользователя
# Сервер возвращает токен безопасности для дальнейшей работы, аналогичный токену, возвращаемому при аутентификации локальных пользователей

Для каждого пользователя, успешно прошедшего проверку на LDAP сервере, создается локальная запись в БД Svacer. Управлять таким пользователем можно как и обычным пользователем, за исключением:
* Пользователю нельзя сменить пароль
* Пользователь не может сменить пароль самостоятельно
* В случае отсутствия связи между сервером Svacer и сервером LDAP, данный пользователь не сможет зайти в систему

==== Запуск сервера с поддержкой LDAP ====
Сервер может быть запущен как в с поддержкой аутентификации через LDAP, так и без. Для того, чтобы включить аутентификацию через LDAP необходимо указать конфигурационный файл. Типовой пример конфигурационного файла для подключения к контроллеру домена MS ActiveDirectory или серверу openLDAP можно получить с помощью команды:

svacer ldap print

Запуск сервера с поддержкой LDAP осуществляется командой:

svacer server --ldap ldap.json

При запуске сервер svacer формирует список доступных для LDAP аутентификации серверов и выводит соответствующее сообщение. Ниже приведен лог сервера, запущенного с поддержкой протокола LDAP.
[[File:LdapServerAdded.png|none|left|1000px|alt=LdapServerAdded]]

После запуска сервера svacer с поддержкой LDAP в GUI становится активна вкладка LDAP.

Для аутентификации с помощью LDAP необходимо выбрать сервер из выпадающего списка.

[[File:LdapServerChoose.png|none|left|alt=LdapServerChoose]]

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

Для отключения возможности аутентификации встроенными средствами сервера Svacer нужно использовать опцию '''disable-svacer-auth'''.

Пример:
svacer server --ldap ldap.json --disable-svacer-auth

==== Конфигурационный файл сервера для поддержки LDAP ====
Типовой пример конфигурации представлен ниже.

{
"servers": [
{
"name": "active_directory",
"basedn": "dc=domain,dc=home,dc=org",
"useGroup": true,
"hideURL": true,
"checkAlivePeriod": 60,
"connection": {
"url": "ldaps://192.168.11.71:636",
"mirrors":["ldaps://192.168.11.72:636","ldaps://192.168.11.73:636"]
"connectAs": "cn=ldap_service,cn=users,dc=domain,dc=home,dc=org",
"password": "12345678",
"ignoreCertCheck": false,
"caCertFiles":["/etc/ssl/certs/a*","/etc/ssl/certs/my_certs/*"]
},
"group": {
"basedn": "cn=users",
"filter": "(&(objectCategory=Group)(cn=dep_devops))",
"userMember": "member",
"display":"cn",
"svacerRole":"cn"
},
"user": {
"basedn": "cn=users",
"filter": "(&(objectCategory=Person)(sAMAccountName=*))",
"login": "sAMAccountName",
"group": "dn",
"info": {
"display": "cn",
"email": "email",
"firstName": "givenName",
"lastName": "sn"
}
},
"enabled": true
},
{
"name": "open_ldap",
"basedn": "dc=example,dc=com",
"useGroup": true,
"connection": {
"url": "ldap://127.0.0.1:389",
"connectAs": "cn=admin,dc=example,dc=com",
"password": "12345678"
},
"group": {
"basedn": "ou=groups",
"filter": "(&(objectClass=groupOfNames)(cn=svacer))",
"userMember": "member",
"display":"cn"
},
"user": {
"basedn": "ou=users",
"filter": "(&(objectClass=PosixAccount))",
"login": "uid",
"group": "dn",
"info": {
"display": "dn",
"email": "mail",
"firstName": "givenName",
"lastName": "sn"
}
},
"enabled": true
}
]
}

В конфигурации можно указать несколько серверов. Все сервера в совокупности рассматриваются как единый источник проверки пользователей. То есть если на двух серверах будут два пользователя с одинаковым логином, они будут считаться идентичными. Ниже приводится описание параметров конфигурации.
* name — произвольное имя (уникальное для каждого сервера)
* basedn — DN относительно которого будут проводится все операции в LDAP каталоге
* useGroup — проверять ли принадлежность пользователя к группе
* hideURL — не передавать сетевой адрес LDAP сервера. Конечные пользователи будут видеть в выпадающем списке только имя сервера, указанное в поле name. В поле URL будет пустая строка.
* checkAlivePeriod — Промежуток времени в секундах, который должен проходить между периодическими проверками доступности сервера LDAP. Если параметр равен 0 или не указан, такая проверка не проводится.
* connection — подсекция, описывающая параметры соединения с сервером
:* url — адрес сервера, формата: ldap[s]://domain:port В случае использования TLS для подключения к LDAP серверу, необходимо указать правильный порт (по умолчанию 636).
:* mirrors — список хостов, которые будут использованы в случае недоступности основного хоста, указанного в поле URL. Формат указания хостов тот же, что и в поле URL. Префикс ldap[s] должен быть одинаковым для всех хостов и совпадать с префиксом в поле URL.
:* connectAs — имя пользователя в формате DN, из под которого будут производится операции в LDAP каталоге
:* password — пароль пользователя
:* ignoreCheck — не проверять сертификат в случае ldaps:// соединения. Полезно при самоподписанных сертификатах. Если флаг установлен в значение false, необходимо установить значение поля caCertFiles.
:* CaCertFiles — массив значений, описывающих какие файлы корневых сертификатов добавлять в конфигурацию Svacer. Формат файлов сертификатов — PEM
* group — подсекция, описывает параметры проверки принадлежности пользователя к группе
:* basedn — RDN, добавляемая к общей DN. Относительно этого DN производится поиск группы
:* filter — фильтр, используемый при поиске группы. Необходимо, если надо указать несколько групп
:* userMember — атрибут в группе, содержащий пользователей, принадлежащих группе
:* display — атрибут, содержащий имя группы для отображения
:* svacerRole — атрибут, из которого будет извлечено имя роли, созданной в Svacer, и автоматически сопоставляемой с пользователем.
* user — подсекция, описывает параметры получения информации о пользователе
:* basedn — RDN, добавляемая к общей DN. Относительно этого DN производится поиск группы
:* filter — фильтр, используемый при поиске пользователей.
:* login — атрибут, в котором находится login пользователя.
:* group — атрибут в пользователе, на который ссылается атрибут group.userMember (обычно это «dn» пользователя)
:* info — подсекция описывающая в каких атрибутах находится информация о пользователе
::* display — атрибут, содержащий полное имя пользователя для отображения (ФИО)
::* email — атрибут с почтовым адресом
::* firstName — атрибут с именем
::* lastName — атрибут с фамилией
* enabled — использовать или нет данный сервер

[[LDAP_configuration|Примеры конфигурации взаимодействия с LDAP сервером]]

Рассмотрим пример обработки запроса на вход в систему LDAP пользователя, указавшего значение ivanov_ii в поле логина и выбравшего конфигурацию active_directory из примера выше
:# Svacer создает служебное подключение к хосту 192.168.11.71 со следующими параметрами
:#* используется TLS соединение (ldaps префикс)
:#* порт 636
:#* проверяется сертификат LDAP сервера (ignoreCertCheck = false); для проверки используются сертификаты CA (из папки /etc/ssl/certs — все сертификаты, начинающиеся с буквы a; из папки /etc/ssl/certs/my_certs/ — все сертификаты)
:#* логин для подключения к LDAP серверу: "cn=ldap_service,cn=users,dc=domain,dc=home,dc=org" (connectAs); пароль: 12345678 (password)
:# Если подключение к хосту невозможно (хост недоступен), то пробуются хосты 192.168.11.72,192.168.11.73 с параметрами, аналогичными параметрам пункта 1
:# Если подключение невозможно, процесс входа завершается с ошибкой
:# Производится поиск пользователя в LDAP каталоге со следующими параметрами:
:#* строка запроса: (&(sAMAccountName=ivanov_ii)((&(objectCategory=Person)(sAMAccountName=*)))), sAMAccountName — взят из поля user.login конфиг файла; ivanov_ii — введено пользователем; (&(objectCategory=Person)(sAMAccountName=*)) — взято из поля user.filter конфиг файла
:#*начальный узел, с которого будет произведен поиск: cn=users, dc=domain,dc=home,dc=org
:#*поиск производится по всему поддереву
:# Если пользователей не найдено или найдено больше 1 пользователя, процесс входа завершается с ошибкой
:# Флаг useGroup = true, поэтому производится дополнительная проверка группы пользователя
:#* выполняется поиск групп в каталоге LDAP со следующими параметрами:
:#**строка запроса: (&(objectCategory=Group)(cn=dep_devops)) — взято из поля group.filter
:#**начальный узел: cn=users, dc=domain,dc=home,dc=org, где cn=users — взято из поля group.basedn; значение dc=domain,dc=home,dc=org — взято из поля basedn конфиг файла
:#**поиск производится по всему поддереву
:#**определяется список пользователей группы (каждому пользователю соответствует значение атрибута с именем member (взято из поля group.userMember конфиг файла))
:#* Если ни одной группы не найдено, то процесс входа завершается с ошибкой
:#*Определяются группы, в которые входит пользователь. Для этого для каждой группы, найденной в пункте выше, просматривается список пользователей и ищется значение cn=ivanov_ii,cn=users,dc=domain,dc=home,dc=org (в поле user.group конфиг файла указано значение dn, что означает, что необходимо использовать DN пользователя для данной процедуры). Если атрибут найден, считается что пользователь принадлежит группе.
:#* Если пользователь не принадлежит ни к одной группе, процесс входа завершается с ошибкой
:# Производится попытка подключения к хосту LDAP с параметрами, аналогичными параметрам из пункта 1, за исключением логина (cn=ivanov_ii,cn=users,dc=domain,dc=home,dc=org) и пароля пользователя (введен в поле пароль формы входа)
:# Если подключение не удалось создать, то процесс входа завершается с ошибкой
:# Процесс аутентификации пользователя произведен успешно
:# Производится создание локального пользователя svacer с именем ivanov_ii, если его еще нет
:# Так как useGroup = true и указан атрибут svacerRole с непустым значением, то производится привязка ролей Savcer пользователя на основе его участия в группах LDAP (смотри соответствующий пункт)

==== Привязка группы LDAP к роли Svacer ====
Возможно автоматическое назначение пользователям LDAP ролей Svacer. Для использования данной функции необходимо выполнить следующие предварительные действия:
:* Администратор LDAP сервера создает в каталоге LDAP нужные группы (например cn=users,ou=svacer,dc=example,dc=com и cn=admins, ou=svacer,dc=example,dc=com), которые будут привязаны к ролям Svacer.
:* Администратор LDAP сервера помещает пользователей LDAP в соответствующие LDAP группы (cn=users,ou=svacer,dc=example,dc=com или cn=admins, ou=svacer,dc=example,dc=com)
:* Администратор Svacer создает роли в Svacer, имеющие в точности такое же название, как значение атрибута, указанного в поле svacerRole конфигурационного файла. В пример можно использовать аттрибут cn и в этом случае необходимо создать роли users и admins
:* Администратор Svacer добавляет в конфигурационный файл в поле svacerRole имя атрибута, по которому будет производится привязка. Для примера выше — строчку svacerRole="cn"
После выполнения данных действий, во время входа пользователя в систему пользователю будут добавлены роли по следующему алгоритму:
:* Производится поиск групп, к которым принадлежит пользователь. Поиск производится по параметрам, указанным в секции group конфигурационного файла. Для примера, пользователь может состоять в следующих группах: (cn=users,ou=svacer,dc=example,dc=com), (cn=dep_dev,dc=example,dc=com)
:* Для каждой найденной группы, выбирается значение атрибута, указанного в поле svacerRole. В примере — имя атрибута cn. Получаются два имени: users, dep_dev
:* Производится поиск ролей Svacer с именем users и dep_dev. Если такие роли найдены, то пользователю они будут добавлены. Так как в примере роль dep_dev не создана, то будет добавлена только роль users.

Удаление ролей автоматически не производится. Вместо этого предлагается ручного режим синхронизации ролей пользователя. Для синхронизации ролей с текущими группами, в которых состоит пользователь, используется команда cli

svacer ldap sync_roles --login [user_login] --server [server_name] --apply

Данная команда проверит наличие пользователя user_login в соответствующей роли группе LDAP и если его в группе не будет, уберет роль у пользователя. Также команда добавит недостающие роли, на основе механизма, описанного выше (при входе пользователя). Флаг apply позволяет "оценить" получаемые изменения прежде чем они будут применены. По умолчанию флаг apply = false.

==== Использование CLI сервера Svacer с поддержкой LDAP ====
Для выполнения некоторых действий в cli с помощью команды svacer требуется аутентификация пользователя. Для аутентификации с помощью ldap сервера необходимо указать в команде кроме имени пользователя и пароля имя сервера с помощью флага ldap_server (имя сервера регистр-зависимо). Например:

./svacer quickdiff --user loginok --password loginok --ldap_server openLDAP2 --project zstd --branch zstd_14 --snapshot_v1 v1.4.1 --snapshot_v2 zstd_140

Если флаг ldap_server не указан, аутентификация производится механизмами сервера svacer, как и в предыдущих версиях. Параметр ldap_server можно опустить, указав сервер в переменной окружения SVACER_LDAP_SERVER. Например:

SVACER_LDAP_SERVER=“openLDAP2“ ./svacer quickdiff --user loginok --password loginok --project zstd --branch zstd_14 --snapshot_v1 v1.4.1 --snapshot_v2 zstd_140

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

./svacer ldap servers --host 127.0.0.1 --port 8080

Вывод содержит два столбца (имя и URL сервера). В качестве значения для параметра ldap_server необходимо использовать содержимое первого столбца.

==== Обновление данных LDAP пользователей ====
Для каждого LDAP пользователя создается соответствующая ему запись в БД Svacer, в которую включается ФИО из LDAP и адрес его электронной почты. Через какое-то время данные пользователей могут меняться, в этом случае возможно обновить данные LDAP пользователей, хранящиеся в Svacer, синхронизировав их с данными LDAP сервера.
Для обновления данных одного пользователя можно воспользоваться окном редактирования пользователя, в котором можно нажать кнопку '''Load from LDAP'''. В соответствующие окна будут добавлены данные, загруженные из LDAP сервера.

[[File:ChangeUserProfile.png|none|left|alt=ChangeUserProfile]]

Также данные пользователей можно обновить с помощью интерфейса командной строки. Для этого можно использовать подкоманду '''updateUsers''' команды '''ldap'''. Общий синтаксис команды выглядит следующим образом:

./svacer ldap updateUsers --onlyEmpty

Флаг '''onlyEmpty''' позволяет обновлять только пустые поля ФИО и eMail. Заполненные поля не будут изменены. Команда обновит данные всех пользователей, записи о которых имеются в базе Svacer.

=== Поддержка сквозной аутентификации ===
Svacer поддерживает сквозную аутентификацию через reverse proxy. Для этого используется опция proxy-mode. При включении этой опции есть возможность проходить аутентификацию (используя HTTP Basic Authentication) на reverse proxy сервере и использовать эти данные для аутентификации на сервере Svacer.

При включенном proxy-mode используется header с прокси '''Authorization Basic ...''', откуда Svacer берет имя пользователя и пароль, проверяет и аутентифицирует пользователя, если аккаунт с таким логином и паролем существует в БД пользователей Svacer.

Пример запуска сервера с поддержкой сквозной аутентификации:

./svacer server --proxy-mode

=== Хуки ===
Для получения данных хуков при запуске сервера нужно указать опцию '''--hooks <path to JSON file>'''. Эта опция задаёт файл, содержащий информацию о расширении сервера посредством хуков, которые пользователь может вызывать из web-интерфейса.
Каждый хук соответствует некоторому процессу или скрипту, который сервер запускает в ответ на вызов соответствующей команды из web-интерфейса.
Формат файла Hooks следующий:
{
"hooks": [
{
"id": "<id>",
"label": "<label >",
"target": "<target>",
"input": ["<param1>", "<param2>",…],
"cmd": "<path to executable>",
"args": ["<arg1>", “<arg2>”, …]
},
...
]
}

'''Параметры хуков '''
{| class="wikitable"
! style="width:100px;" | Параметр || Описание
|-
| ''id''
| Идентификатор хука. Должен быть уникальным в файле
|-
| ''label''
| Имя команды, которую пользователь видит в web-интерфейсе
|-
| ''target''
| Место в UI, в которое будет добавлена команда. 
Сейчас поддерживается только одно значение — default. Оно соответствует вкладке Details на правой панели пользовательского интерфейса
|-
| ''input''
| Параметры, которые можно передать в запускаемый процесс, исходя из контекста вызова команды в web-интерфейсе. 
Поддерживаемые значения:
* markerID — UUID идентификатор маркера;
* branchID — UUID идентификатор ветки;
* snapshotID — UUID идентификатор снимка;
* projectID — UUID идентификатор проекта;
* url — URL маркера в web-интерфейсе, на котором была вызвана команда;
* marker — будет заменен на полное имя временного файла, содержащего сериализованное в JSON представление маркера, который включает в себя его трассу и информацию о разметке
|-
| ''cmd''
| Полный путь к процессу, который будет запущен. Не должен включать аргументы запуска
|-
| ''args''
| Аргументы, передаваемые в запускаемый процесс. Полный список аргументов запускаемого процесса состоит из списка <args> и списка значений, соответствующих полю <input>
|}

Одним из типичных сценариев использования хуков является создание кейсов для выбранного предупреждения в системах отслеживания ошибок, таких как Jira и Gitlab. Примеры скриптов для этого можно найти на странице [[Примеры использования хуков]].

Help:Introduction

2023-05-03T06:23:40Z

Writer:

[[Category:Help]]
== Введение ==
Сервер историй '''Svacer''' ('''''Svace Server''''') предназначен для хранения и обработки результатов работы статического анализатора Svace. Он разработан с целью заменить старый сервер историй, встроенный в анализатор Svace. Допускается одновременное использование старого и нового серверов.

Svacer состоит из единственного исполняемого файла, который можно запустить как в [[Help:Installation|режиме сервера]] для хранения и обработки результатов анализа (при этом требуется PostgreSQL с созданной для Svacer БД), так и использовать как клиент для взаимодействия с этим сервером (в этом случае никаких зависимостей не требуется). Будучи запущенным в качестве сервера, Svacer предоставляет [[Help:ServerClient#Вход_в_сервер|web-UI]] и [[Help:ServerClient#Публичные_REST_запросы|REST API]] для взаимодействия. При использовании Svacer как клиента доступны команды для [[Help:ServerClient#Процесс_импорта|импорта]] предупреждений, [[Help:ServerClient#Загрузка_данных_на_сервер|загрузки]] их на сервер и другие возможности взаимодействия с сервером.

=== Термины ===

{| class="wikitable"
|-
| ''Project''
| Проект, подлежащий анализу. По умолчанию именем проекта считается имя директории, в которой был запущен ''svace build'' и ''svace analyze''.
На сервере проект содержит в себе несколько '''branch''' с результатами работы анализатора
|-
| ''Branch (ветка)''
| Ветка в проекте с результатами работы анализатора. По умолчанию проект имеет одну ветку — master
|-
| ''Snapshot (снимок)''
| Результат работы ''svace analyze'', импортированный в промежуточное хранилище или на сервер. Содержит:
* имя проекта;
* имя ветки;
* результаты анализа (предупреждения);
* исходники, которые были включены в build, на котором производился анализ;
* вспомогательная информация для навигации по исходникам;
* дополнительные данные;
Допускается импортирование снимков без исходного кода и дополнительной информации
|-
| ''Marker (маркер, предупреждение)''
| Предупреждение от Svace с информацией о позиции в исходном файле
|-
| ''Svacer''
| Svace History Server, а также исполняемый файл, содержащий код сервера
|-
| ''Разметка''
| Проставление статуса маркера с опциональным добавлением комментария
|}

=== Состав дистрибутива ===

{| class="wikitable"
|-
| '''bin/svacer bin/svacer.exe'''
| Бинарный файл сервера и утилита для импортирования результатов. Режим работы зависит от аргументов
|-
| '''support/svace-migration/svace-migration.jar'''
| Утилита подготовки данных для импорта из старого сервера историй.
Требует JDK для запуска. Может использоваться JDK из состава дистрибутива Svace
|-
| '''extra/docker-compose*.yml''' || Docker-compose файлы для запуска БД PostgreSQL и Svacer в docker-контейнерах
|-
| '''integrations/vscode''' || Расширение для Visual Studio Code и документация на него
|}

=== Зависимости ===

{| class="wikitable"
|-
| PostgreSQL версии 10 и выше. Требуется только при запуске Svacer в роли сервера
| Параметры подключения определяются аргументом при запуске сервера или переменной окружения SVACER_PG_URL. По умолчанию, используется следующий connect URL:
'''postgres://svace:svace@0.0.0.0:5432/svace''' 
Можно использовать PostgreSQL в docker-контейнере. 
'''Настоятельно рекомендуем''' использовать выделенный сервер для хранения БД, особенно в production
|-
| libc.so libpthread.so libdl.so linux-vdso.so
| Серверная часть написана на Go с CGO_ENABLED=1 ввиду необходимости читать sqlite-файлы из результатов работы анализатора Svace
|-
| Выделенная директория для хранения object storage
| Сервер использует встроенную key-value database для хранения информации об исходном коде: контент-файлов и вспомогательной информации для навигации
|-
| Svace
| Для импорта данных на сервер историй требуется наличие Svace на хосте, откуда происходит импорт. Svace используется для получения информации из .svace-dir
|}

=== Используемые порты ===

Приведены значения по умолчанию. Все значения могут быть переопределены.
{| class="wikitable"
|-
| 3002
| Используется для предоставления gRPC API.
gRPC API является внутренним и предназначен для загрузки данных на сервер
|-
| 8080
| Используется для предоставления REST API и web-сервера для предоставления web-UI
|}

=== Системные требования ===
{| class="wikitable"
|-
| CPU
| x86-64. Для обработки больших проектов рекомендуется не менее 8 ядер
|-
| RAM
| От 4 Гб. Для обработки больших проектов рекомендуется не менее 16 Гб
|-
| HDD
| От 1 Гб до нескольких Тб при хранении множества снимков больших проектов
|-
| OS
|
* Ubuntu 18 и выше
* Debian 10 и выше
* RHEL/CentOS 7 и 8
* Astra Linux Special Edition 1.7, базовый уровень защищенности
* Microsoft Windows 10 (build 19043.2130, build 19044.2130)
|}