Help:Import from Svace

TL;DR

 svacer import --svace <path-to-svace>
 svacer upload

Эти две команды импортируют результаты анализа из .svace-dir в текущей директории и загрузят их на сервер Svacer по адресу localhost:8080.

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

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

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

Можно импортировать результаты и из других статических анализаторов, поддерживающих формат SARIF.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Если ветка с таким именем или id не будет найдена, то при загрузке данных (svacer upload ..., либо svacer import --upload ...) загрузка произойдет, но без склонированной разметки.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   svacer upload ... --quick-stats --out-format text ...

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

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

   svacer upload ... --quick-stats --out-format json ...

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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