Version: 1.5.1

TRON.ASOC API: Automation guide

This section describes the key API requests for configuring TRON.ASOC and provides usage examples. The complete request specification is available in Swagger UI at https://{your-domain}/api/v1/swagger/index.html.

Basic information for each request

Base URL: {your-domain}/api/v1.

Common headers:

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

Common HTTP response codes:

200 OK—Successful request
400 Bad request—Invalid request parameters
401 Unauthorized—The authentication token is missing or invalid
403 Forbidden—You don't have sufficient permissions to perform the operation
500 Internal Server Error—Internal server error

Typical configuration process

For initial configuration using basic operations, use the following list of requests:

api/v1/auth/login - Sign in using a Username and Password
api/v1/token—Create a token
api/v1/role—Create a role
api/v1/user—Create a user
api/v1/source—Add a scan source
api/v1/sources-type/1/test—Test the source connection
api/v1/tool—Add a tool
api/v1/project—Create a project
api/v1/layer—Create a layer
api/v1/quality-gate—Create a quality gate
api/v1/security-rule—Add a security rule
api/v1/check—Add a security check to the layer
api/v1/check/{{SecurityCheckId}}/run—Start a scan
api/v1/check/{{SecurityCheckId}}/stop - Stop a scan
api/v1/issues?filter—Get a list of detected issues
api/v1/report—Create a report
api/v1/report/{id}/download—Download a report

Request details

info

In all the examples below:

{your-domain} must be replaced with the domain you're using, for example, my.asoc.tronasoc.ru.
{{accessToken}} must be replaced with a valid JWT token obtained through /auth/login or created through /token.

Authentication

Request: POST {{baseUrl}}/api/v1/auth/login

Purpose: Get a JWT token for subsequent requests. The default lifetime is 9 hours.

Request body:

username - Username
password - Password

Request example:

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

Create a token

Request: POST {{baseUrl}}/api/v1/token

Purpose: Create a long-term API token for integrations

Specify the following in the request:

expires_at—Token expiration date
name—Token name

Request example:

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"
}'

Create a role

Request: POST {{baseUrl}}/api/v1/role

Purpose: Create a new role for users

Specify the following variables in the request:

role_code—Role code
role_name—Role name
roles—Role settings
description—Role description (optional)
domain_group—List of LDAP groups assigned to the role (optional)
system_scopes—List of system scopes for the role (optional)

Request example:

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"]
            }
}'

Create a user

Request: POST {{baseUrl}}/api/v1/user

Purpose: Create a new user in the system

Specify the following variables in the request

username—Username
password—User password
password_confirmation—User password confirmation
display_name—Display name
email—Email address
need_password_change—Whether the user must change the password when signing in
active_directory—Whether the user is an AD user (see LDAP authentication for more information)
roles—Set of roles

Request example

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"]
}'

Add a scan source

Request: POST {{baseUrl}}/api/v1/source

Purpose: Add a scan source, for example, a Git repository

The request to add a scan source includes the following variables:

name - Scan source name
description - Scan source description
source_type_id - Scan source type ID
settings - Additional settings:
url - Source URL
branch_name - Source branch name
auth_method - Authentication method for the source
login - Authentication login for the source
password - Authentication password for the source

Request example:

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 the source connection

Request: POST {{baseUrl}}/api/v1/sources-type/1/test

You can also test the CI/CD source connection separately by specifying the following variables in the settings configuration:

url - Source URL
branch_name - Source branch name
auth_method - Authentication method for the source
login - Authentication login for the source
password - Authentication password for the source

Request example:

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": "***" 
}
 }'

Add a tool

Request: POST {{baseUrl}}/api/v1/tool

Purpose: Add a security tool

To add a tool, specify the variables required by the tool. The variables vary depending on the selected tool.

For PT AI, specify the following variables in the request:

scan_result_lang—Scan result language
url—Tool URL
auth_method—Authentication method
api_token—Tool connection token, except for CLI tools and Manual

Request example (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}}"
    }
}'

Create a project

Request: POST {{baseUrl}}/api/v1/project

Purpose: Create a new project

To create a project, specify the following variables in the data section of the request:

code - Project code
name - Project name
description - Project description
tags—Project tags

Request example:

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"]
}'

Request example for creating a project with custom fields:

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"}
       
    ]
}'

Create a layer

Request: POST {{baseUrl}}/api/v1/layer

Purpose: Create a layer in a project

Specify the following parameters in the request:

name - Name
description - Description
project_code—Project code
layer_type_id—Layer type
is_template—Whether to create the layer from a template

Request example:

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
}'

Create a quality gate

Request: POST {{baseUrl}}/api/v1/quality-gate

To create a quality gate, specify the following variables in the data section of the request:

name - Quality gate name

Request example:

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

To add conditions to a quality gate, specify the following variables in the data section of the request:

quality_gate_id - Quality gate ID
condition_type - Condition type
condition_value - Condition value
operator - Condition operator value
value - Default value

Request example:

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" 
}'

To add a quality gate to a layer, specify the following variables in the data section of the request:

layer_id - Layer ID
quality_gates - Array of quality gates to assign. Each element contains:
quality_gate_id - Quality gate ID
action - Action for assigning the quality gate to the layer

Request example:

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

Create a security rule

Request: POST {{baseUrl}}/api/v1/security-rule

To create a security rule, specify the following variables in the data section of the request:

name - Security rule name
rule_params - Rule parameters:
instrument_type - Tool type
tool_type_name - Tool name
category - Tool category
cve - CVE name
cwe - CWE name
active_for_all - Rule scope, whether it applies to everyone
suppressing_status - Security issue suppression status
expiry_status - Status after the rule expires

Request example:

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 
}'

Add a security check

Request: POST {{baseUrl}}/api/v1/check

Purpose: Create a security check that links a tool, source, and layer in a project

To add a security check to a layer, specify the following variables in the data section of the request:

layer_id - Layer ID
security_tool_id - Security tool ID
tool_settings - Security tool settings:
scan_result_lang - Scan result language
url - Security tool URL
auth_method - Authentication method
api_token - Tool connection token
scan_source_id - Scan source ID
source_auth - Scan source authentication parameters:
url - Scan source URL
auth_method - Authentication method
branch_name - Repository branch name (scan source)
run_scan_task - Scan launch parameters:
type - Scan launch type
branches—List of source branches to scan (optional)
check_group_id—Security check group ID (optional)

Request example (PT AI and GitLab):

curl --location 'https://{your-domain}/api/v1/check' \ 
--header 'Content-Type: application/json' \ 
--header 'Authorization: Bearer {{accessToken}}' \ 
--data '{ 
	"layer_id": "34e19795-517a-4c7a-bdaf83b74d51", 
	"security_tool_id": "e6d95be5-5939-4f41-7b31a5e0719d", 
	"tool_settings": { 
		"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

Note: We recommend saving the id of the created check (SecurityCheckId) from the response so you can start it later. See below.

Start a scan

Request: POST {{baseUrl}}/api/v1/check/{{SecurityCheckId}}/run or POST {{baseUrl}}/api/v1/layer/{{LayerId}}/run

Purpose: Manually start a specific security check or the entire layer

To start a scan, specify SecurityCheckId, the security check ID, or LayerId, the layer ID, in the request.

Request examples:

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'

Stop a scan

Request: POST {{baseUrl}}/api/v1/check/{{SecurityCheckId}}/stop

Purpose: Manually stop a specific security check

Request example:

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

Get a list of detected issues

Request: GET {{baseUrl}}/api/v1/issues?filter

Purpose: Get a filtered list of detected vulnerabilities

To get scan results, specify filters for the results. Add a filter to the api/v1/issues?filter request in the following format: [tool]=PT%20Application%20Inspector&page=1&limit=10&filter[project_code]=ASOC96749244, where tool is the tool name, page is the page, limit is the record limit (50 by default), and filter[project_code] is the project code.

Request example:

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}}'

Create a report

Request: POST {{baseUrl}}/api/v1/report

Purpose: Create a report asynchronously

To create a report, specify the following variables in the data section of the request:

name - Report name
type - Report type
filter - Required filters from the available options:
period - Selected time period
project_code - Project code

Request example:

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" ] 
	} 
}'

Download a report

Request: GET {{baseUrl}}/api/v1/report/{id}/download

Purpose: Download a previously created report in the specified format.

To download a report, first create it through POST /report and save the id from the response. Then send a request with the following parameters:

id (path) - Report ID returned when the report was created
format (query) - Report format (html, csv, json, pdf)

Request example:

curl --location 'https://{your-domain}/api/v1/report/3f1c8a7e-2c11-4b9d-9c8a-7d2e0c1b4a55/download?format=csv' \ 
--header 'Authorization: Bearer {{accessToken}}'

Basic information for each request​

Typical configuration process​

Request details​

Authentication​

Create a token​

Create a role​

Create a user​

Add a scan source​

Test the source connection​

Add a tool​

Create a project​

Create a layer​

Create a quality gate​

Create a security rule​

Add a security check​

Start a scan​

Stop a scan​

Get a list of detected issues​

Create a report​

Download a report​

Basic information for each request

Typical configuration process

Request details

Authentication

Create a token

Create a role

Create a user

Add a scan source

Test the source connection

Add a tool

Create a project

Create a layer

Create a quality gate

Create a security rule

Add a security check

Start a scan

Stop a scan

Get a list of detected issues

Create a report

Download a report