Version: 1.4.2

TRON.ASOC API: Automation guide

This section describes the key API requests for configuring TRON.ASOC and provides usage examples. You can find the full request specification 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 with 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 scanning 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 a 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/summary/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 token 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

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 their password when they sign 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 scanning source

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

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

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

name - Scanning source name
description - Scanning source description
source_type_id - Scanning source type ID
settings - Additional settings:
url - Source URL
branch_name - Source branch name
auth_method - Authentication method for the source
login - Authentication Username 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 a 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 settings:

url - Source URL
branch_name - Source branch name
auth_method - Authentication method for the source
login - Authentication Username 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 the PT AI tool, specify the following variables in the request:

scan_result_lang—Scan results language
url—Tool URL
auth_method—Authentication method
api_token—Token for connecting to the tool, 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 block 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 block 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 block 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 block of the request:

layer_id - Pipeline ID
quality_gate_id - Quality gate ID
action - Action for linking the quality gate to the layer

Request example:

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

Create a security rule

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

To create a security rule, specify the following variables in the data block 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 all
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 pipeline, specify the following variables in the data block of the request:

layer_id - Layer ID
project_code - Project code
security_tool_id - Security tool ID
tool_auth - Security tool authentication parameters
scan_result_lang - Scan result language
url - Security tool URL
auth_method - Authentication method
scan_source_id - Scanning source ID
source_auth - Scanning source authentication parameters
url - Scanning source URL
auth_method - Authentication method
branch_name - Repository branch name (scanning source)
run_scan_task - Scan start parameters
type - Scan start type

Request example (PT AI and 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

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 an 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 scan

Request example:

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

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. 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 name 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 block of the request:

name - Report name
type - Report type
filter - Required filters from the available filters:
period - Selected time period
project_code - Project name 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/summary/download?

Purpose: Download a report in the specified format

To download a report, send a request with the following parameters:

format - Report format (pdf, csv, json)
filter[project_code] - Project name code
filter[created_at_start] - Report period start date
filter[created_at_end] - Report period end date

Request example:

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

Basic information for each request​

Typical configuration process​

Request details​

Authentication​

Create a token​

Create a role​

Create a user​

Add a scanning source​

Test a 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 scanning source

Test a 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