Version: 1.4.2

API TRON.ASOC: Руководство по автоматизации

В разделе приведено описание ключевых API-запросов для настройки системы TRON.ASOC и примеры использования. Полная спецификация запросов доступна в Swagger UI по ссылке – https://{your-domain}/api/v1/swagger/index.html.

Базовая информация по каждому из запросов

Базовый URL: {your-domain}/api/v1.

Общие заголовки (Headers):

Content-Type: application/json
Authorization: Bearer {your_token}

Общие HTTP-коды ответов:

200 OK – Успешный запрос
400 Bad request – Некорректные параметры запроса
401 Unauthorized – Отсутствует или недействителен токен аутентификации
403 Forbidden – Недостаточно прав для выполнения операции
500 Internal Server Error – Внутренняя ошибка сервера

Типовой процесс настройки

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

api/v1/auth/login - вход в систему с использованием Логина/Пароля
api/v1/token – создание токена
api/v1/role – создание роли
api/v1/user – создание пользователя
api/v1/source – добавление источника сканирования
api/v1/sources-type/1/test – проверка подключения источника
api/v1/tool – добавление инструмента
api/v1/project – создание проекта
api/v1/layer – создание слоя
api/v1/quality-gate – создание контроля качества
api/v1/security-rule – добавление правила безопасности
api/v1/check – добавление проверки безопасности к слою
api/v1/check/{{SecurityCheckId}}/run – запуск сканирования
api/v1/check/{{SecurityCheckId}}/stop - остановка сканирования
api/v1/issues?filter – получение списка выявленных проблем
api/v1/report – создание отчета
api/v1/report/summary/download? – выгрузка отчета

Детализация запросов

info

Во всех примерах ниже:

{your-domain} необходимо заменить на используемый домен (например, my.asoc.tronasoc.ru).
{{accessToken}} необходимо заменить на действительный JWT-токен (полученный через /auth/login или созданный через /token).

Авторизация

Запрос: POST {{baseUrl}}/api/v1/auth/login

Назначение: Получение JWT-токена для последующих запросов (время жизни по умолчанию - 9 часов).

Тело запроса (Body):

username - имя пользователя
password - пароль

Пример запроса:

curl --location 'https://{your-domain}/api/v1/auth/login' \
--header 'Content-Type: application/json' \
--data '{
    "username": "username111",
    "password": "123456778"
}'

Создание токена

Запрос: POST {{baseUrl}}/api/v1/token

Назначение: Создание долгосрочного API-токена для интеграций

В запросе необходимо задать следующее:

expires_at – дату истечения токена
name – имя токена

Пример запроса:

curl --location 'https://{your-domain}/api/v1/token' \
--header 'Content-Type: application/json' \
--data '{
    "expires_at": "2028-12-31T23:59:34.911353Z",
    "name": "DK Api Token"
}'

Создание роли

Запрос: POST {{baseUrl}}/api/v1/role

Назначение: Создание новой роли для пользователей

В запросе указать следующие переменные:

role_code – код роли
role_name – название роли
roles – перечень настроек роли

Пример запроса:

curl --location 'https://{your-domain}/api/v1/role' \
--header 'Content-Type: application/json' \
--data '{
    "role_code": "dev",
    "role_name": "qa-s",
    "roles":{"settings.authentication":["r","w","x","d"],
             "administration.roles":["r","w","x","d"],
             "administration.users":["r","w","x","d"]
            }
}'

Создание пользователя

Запрос: POST {{baseUrl}}/api/v1/user

Назначение: Создание нового пользователя в системе

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

username – имя пользователя
password – пароль пользователя
password_confirmation – подтверждение пароля пользователя
display_name – отображаемое имя
email – адрес электронной почты
need_password_change – требуется ли обновление пароля при входе
active_directory – является ли пользователем AD (Подробнее см. Аутентификация LDAP)
roles – набор ролей

Пример запроса

curl --location 'https://{your-domain}/api/v1/user' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "User1",
    "password": "******",
    "password_confirmation": "******",
    "display_name": "User1",
    "email": "Username1@user.com",
    "need_password_change": false,
    "active_directory": false,
    "roles": ["isoff"]
}'

Добавление источника сканирования

Запрос: POST {{baseUrl}}/api/v1/source

Назначение: Добавление источника сканирования (например, Git-репозитория)

Запрос на добавление источника сканирования включает следующие переменные:

name - имя источника сканирования
description - описание источника сканирования
source_type_id - ID типа источника сканирования
settings - дополнительные настройки:
url - url источника
branch_name - название ветки источника
auth_method - метод аутентификации в источнике
login - логин аутентификации в источнике
password - пароль аутентификации в источнике

Пример запроса:

curl --location 'https://{your-domain}/api/v1/source' \ 
--header 'Content-Type: application/json' \ 
--header 'Authorization: Bearer {{accessToken}}' \ 
--data-raw '{ 
	"name": "CLICustomSource_20241006T103832251Z_3", 
	"description": "CLICustomSource_20241006T103832251Z_3", 
	"source_type_id": 1, 
	"settings": { 
		"url": "https://ximilab.gitlab.yandexcloud.net/ximidev/tron-asoc/core", 
		"branch_name": "develop", 
		"auth_method": "Login/Password", 
		"login": "***", 
		"password": "***" 
	}
 }'

Проверка подключения (Test connection) источника

Запрос: POST {{baseUrl}}/api/v1/sources-type/1/test

Также предусмотрена возможность отдельной проверки подключения к источнику CI/CD с указанием следующих переменных в настройках settings:

url - url источника
branch_name - название ветки источника
auth_method - метод аутентификации в источнике
login - логин аутентификации в источнике
password - пароль аутентификации в источнике

Пример запроса:

curl --location 'https://{your-domain}/api/v1/sources-type/1/test' \ 
--header 'Content-Type: application/json' \ 
--header 'Authorization: Bearer {{accessToken}}' \ 
--data-raw '{ 
	"settings": { 
		"url": "https://ximilab.gitlab.yandexcloud.net/ximidev/tron-asoc/core", 
		"branch_name": "develop", 
		"auth_method": "Login/Password", 
		"login": "***", 
		"password": "***" 
}
 }'

Добавление инструмента

Запрос: POST {{baseUrl}}/api/v1/tool

Назначение: Добавление инструмента безопасности

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

Для инструмента PT AI необходимы следующие переменные в запросе:

scan_result_lang – язык результатов сканирования
url – url инструмента
auth_method – метод аутентификации
api_token – токен подключения к инструменту (кроме CLI-инструментов и Manual)

Пример запроса (PT AI):

curl --location 'https://{your-domain}/api/v1/tool' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{accessToken}}' \
--data '{
    "description": "{{createSecurityToolDescription}}",
    "type_id": 1,
    "settings": {
        "scan_result_lang": "EN",
        "url": "{{PTAIUrl}}",
        "auth_method": "Api Token",
        "api_token": "{{PTAIApiToken}}"
    }
}'

Создание Проекта

Запрос: POST {{baseUrl}}/api/v1/project

Назначение: Создание нового проекта

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

code - код проекта
name - название проекта
description - описание проекта
tags – набор тегов проекта

Пример запроса:

curl --location 'https://{your-domain}/api/v1/project' \ 
--header 'Content-Type: application/json' \ 
--header 'Authorization: Bearer {{accessToken}}' \ 
--data '{
	"code": "ASOC967492", 
	"name": "ASOC967492", 
	"description": "Project ASOC967492" 
 	"tags": ["tgasoc"]
}'

Пример запроса для создания проекта с кастомными полями:

curl --location 'https://{your-domain}/api/v1/project' \
--header 'Content-Type: application/json' \
--data '{
    "code": "ASOC50733846",
    "name": "ASOC50733846",
    "description": "Test project ASOC50733846",
    "tags": ["QA:test"],
    "field_values": [
        {"field_id": 421, "value": "QA"},
        {"field_id": 422, "value": "2025-06-24T00:00:00Z"},
        {"field_id": 423, "value": "72e9730b-4cbb-49a7-82ac-fa1f5cad7ab4"},
        {"field_id": 424, "value": "https://ximilab.gitlab.yandexcloud.net/ximidev/tron-asoc/front"},
        {"field_id": 425, "value": "5145fdca-072c-4672-a956-220f60192203"}
       
    ]
}'

Создание слоя

Запрос: POST {{baseUrl}}/api/v1/layer

Назначение: Создание слоя в проекте

В запросе необходимо указать следующие параметры:

name - название
description - описание
project_code – код проекта
layer_type_id – тип слоя
is_template – признак создания слоя из шаблона

Пример запроса:

curl --location 'https://{your-domain}/api/v1/layer' \
--header 'Content-Type: application/json' \
--data '{
    "name": "",
    "description": "",
    "project_code": "ASOC50733846",
    "layer_type_id": 1,
    "is_template": false
}'

Создание Контроля качества

Запрос: POST {{baseUrl}}/api/v1/quality-gate

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

name - название контроля качества

Пример запроса:

curl --location 'https://{your-domain}/api/v1/quality-gate' \ 
--header 'Content-Type: application/json' \ 
--header 'Authorization: Bearer {{accessToken}}' \ 
--data '{ 
	"name": "QG40701017" 
}'

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

quality_gate_id - ID контроля качества
condition_type - тип условия
condition_value - значение условия
operator - значение оператора условия
value - значение по умолчанию

Пример запроса:

curl --location 'https://{your-domain}/api/v1/condition' \ 
--header 'Content-Type: application/json' \ 
--header 'Authorization: Bearer {{accessToken}}' \ 
--data '{ 
	"quality_gate_id": "6f50b8e7-e238-4640-28a7b87e4924", 
	"condition_type": "severity", 
	"condition_value": "4", 
	"operator": "not_greater_than", 
	"value": "0" 
}'

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

layer_id - ID пайплайна
quality_gate_id - ID контроля качества
action - действие по привязке контроля качества к слою

Пример запроса:

curl --location 'https://{your-domain}/api/v1/quality-gate/link-pipe' \ 
--header 'Content-Type: application/json' \ 
--header 'Authorization: Bearer {{accessToken}}' \ 
--data '{ 
	"layer_id": "b37012de-80ae-4e10-9178-eee6b609ddb0", 
	"quality_gate_id": "6f50b8e7-e238-4640-28a7b87e4924", 
	"action": "lock" 
}'

Создание Правила безопасности

Запрос: POST {{baseUrl}}/api/v1/security-rule

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

name - название правила безопасности
rule_params - параметры правила:
instrument_type - тип инструмента
tool_type_name - название инструмента
category - категория инструмента
cve - название CVE
cwe - название CWE
active_for_all - область действия правила (для всех или нет)
suppressing_status - статус исключения проблемы безопасности
expiry_status - статус по истечении срока действия правила

Пример запроса:

curl --location 'https://{your-domain}/api/v1/security-rule' \ 
--header 'Content-Type: application/json' \ 
--header 'Authorization: Bearer {{accessToken}}' \ 
--data '{ 
	"name": "SR58594878", 
	"rule_params": { 
		"instrument_type": "Container Security", 
		"tool_type_name": "Kaspersky Container Security", 
		"category": "Container os dependency vulnerability", 
		"cve": "CVE-2023-52426", 
		"cwe": "CWE-776", 
		"active_for_all": false 
	}, 
	"suppressing_status": 6, 
	"expiry_status": 3 
}'

Добавление Проверки безопасности

Запрос: POST {{baseUrl}}/api/v1/check

Назначение: Создание проверки безопасности – связывает инструмент, источник и слой в проекте

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

layer_id - ID слоя
project_code - код проекта
security_tool_id - ID инструмента безопасности
tool_auth - параметры аутентификации инструмента безопасности
scan_result_lang - язык результата сканирования
url - url инструмента безопасности
auth_method - метод аутентификации
scan_source_id - ID источника сканирования
source_auth - параметры аутентификации источника сканирования
url - url источника сканирования
auth_method - метод аутентификации
branch_name - название ветки репозитория (источника сканирования)
run_scan_task - параметры запуска сканирования
type - тип запуска сканирования

Пример запроса (PT AI и Gitlab):

curl --location 'https://{your-domain}/api/v1/check' \ 
--header 'Content-Type: application/json' \ 
--header 'Authorization: Bearer {{accessToken}}' \ 
--data '{ 
	"pipeline_id": "34e19795-517a-4c7a-bdaf83b74d51", 
	"project_code": "ASOC967492", 
	"security_tool_id": "e6d95be5-5939-4f41-7b31a5e0719d", 
	"tool_auth": { 
		"scan_result_lang": "EN", 
		"url": "***", 
		"auth_method": "Api Token", 
		"api_token": "***" 
	}, 
	"scan_source_id": "0952f5d8-55af-4229--ffc179b7da20", 
	"source_auth": { 
		"url": "https://github.com/http-party/http-server", 
		"auth_method": "Anonymous", 
		"branch_name": "master" 
	}, 
	"run_scan_task": { 
		"type": "manual"
	 } 
}'

info

Примечание: В ответе этого запроса рекомендуется сохранить id созданной проверки (SecurityCheckId) для её последующего запуска (см. ниже).

Запуск сканирования

Запрос: POST {{baseUrl}}/api/v1/check/{{SecurityCheckId}}/run или POST {{baseUrl}}/api/v1/layer/{{LayerId}}/run

Назначение: Ручной запуск конкретной проверки безопасности или всего слоя

Для запуска сканирования необходимо указать в запросе SecurityCheckId - ID проверки безопасности или LayerId - ID слоя

Примеры запроса:

curl --location 'https://{your-domain}/api/v1/check/08bcc80e-a3fc-4ec3-91b4-dc34754d48e1/run' \ 
--header 'Authorization: Bearer {{accessToken}}'

curl --location 'https://{your-domain}/api/v1/layer/{{LayerId}}/run'

Остановка сканирования

Запрос: POST {{baseUrl}}/api/v1/check/{{SecurityCheckId}}/stop

Назначение: Ручная остановка сканирования конкретной проверки безопасности

Пример запроса:

curl --location --request POST 'https://{your-domain}/api/v1/check//stop'

Получение списка найденных проблем

Запрос: GET {{baseUrl}}/api/v1/issues?filter

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

Для получения результатов сканирования необходимо указать фильтры для получения результатов. Для этого добавляется фильтр в запрос api/v1/issues?filter в следующем формате: [tool]=PT%20Application%20Inspector&page=1&limit=10&filter[project_code]=ASOC96749244, где tool - название инструмента, page - страница, limit - ограничение по количеству записей (по умолчанию 50), filter[project_code] - код проекта

Пример запроса:

curl --location 'https://{your-domain}/api/v1/issues?filter[tool]=PT%20Application%20Inspector&page=1&limit=10&filter[project_code]=ASOC96749244' \ 
--header 'Authorization: Bearer {{accessToken}}'

Создание отчета

Запрос: POST {{baseUrl}}/api/v1/report

Назначение: Асинхронное создание отчета

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

name - название отчета
type - тип отчета
filter - требуемые фильтры из доступных:
period - выбранный период времени
project_code - код проекта

Пример запроса:

curl --location 'https://{your-domain}/api/v1/report' \ 
--header 'Content-Type: application/json' \ 
--header 'Authorization: Bearer {{accessToken}}' \ 
--data '{ 
	"name": "", 
	"type": "summary", 
	"filter": { 
		"period": "all", 
		"project_code": [ "ASOC96749244" ] 
	} 
}'

Выгрузка отчета

Запрос: GET {{baseUrl}}/api/v1/report/summary/download?

Назначение: Выгрузка отчета в указанном формате

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

format - формат отчета (pdf, csv, json)
filter[project_code] - код проекта
filter[created_at_start] - дата начала периода отчета
filter[created_at_end] - дата конца периода отчета

Пример запроса:

curl --location 'https://{your-domain}/api/v1/report/summary/download?format=csv&filter[project_code]=ISSUETESTING20241106T071418970Z%2CASOC52372013&filter[created_at_start]=2000-01-01&filter[created_at_end]=2025-01-20' \ 
--header 'Authorization: Bearer {{accessToken}}'

Базовая информация по каждому из запросов​

Типовой процесс настройки​

Детализация запросов​

Авторизация​

Создание токена​

Создание роли​

Создание пользователя​

Добавление источника сканирования​

Проверка подключения (Test connection) источника​

Добавление инструмента​

Создание Проекта​

Создание слоя​

Создание Контроля качества​

Создание Правила безопасности​

Добавление Проверки безопасности​

Запуск сканирования​

Остановка сканирования​

Получение списка найденных проблем​

Создание отчета​

Выгрузка отчета​

Базовая информация по каждому из запросов

Типовой процесс настройки

Детализация запросов

Авторизация

Создание токена

Создание роли

Создание пользователя

Добавление источника сканирования

Проверка подключения (Test connection) источника

Добавление инструмента

Создание Проекта

Создание слоя

Создание Контроля качества

Создание Правила безопасности

Добавление Проверки безопасности

Запуск сканирования

Остановка сканирования

Получение списка найденных проблем

Создание отчета

Выгрузка отчета