8.1.9. Configuration related APIs

All APIs below require authentication. You must send your apikey in header parameter.

apikey:<your_unique_apikey>

Processing history clean up

(cleanup records older than)

PUT /admin/config/scanhistory

Properties

Property

Value

DESCRIPTION

Setting processing history cleanup time. The cleanup range is defined in hours .

URL

http://<server>:<port>/admin/config/scanhistory

REQUIRED RIGHTS

retention: [read, write]

HTTP METHOD

PUT

CONTENT TYPE

json

BODY

{"cleanuprange":24}

Response

Result code

Value

Description

200

{"cleanuprange":24}

Request processed successfully.

403

{"err":"Access denied"}

The apikey is missing or invalid.

405

{"err":"Access denied"}

The user has no rights for this operation.

500

{"err":"Error while modifying configuration"}

Internal server error.

Quarantine clean up

(cleanup records older than)

PUT /admin/config/quarantine

Properties

Property

Value

DESCRIPTION

Setting quarantine cleanup time. The cleanup range is defined in hours .

URL

http://<server>:<port>/admin/config/quarantine

REQUIRED RIGHTS

retention: [read, write]

HTTP METHOD

PUT

CONTENT TYPE

json

BODY

{"cleanuprange":24}

Response

Result code

Value

Description

200

{"cleanuprange":24}

Request processed successfully.

403

{"err":"Access denied"}

The apikey is missing or invalid.

405

{"err":"Access denied"}

The user has no rights for this operation.

500

{"err":"Error while modifying configuration"}

Internal server error.

Audit records (update history) clean up

(cleanup record older than)

PUT /admin/config/auditlog

Properties

Property

Value

DESCRIPTION

Setting audit records (update history) cleanup time. The cleanup range is defined in hours .

URL

http://<server>:<port>/admin/config/auditlog

REQUIRED RIGHTS

retention: [read, write]

HTTP METHOD

PUT

CONTENT TYPE

json

BODY

{"cleanuprange":24}

Response

Result code

Value

Description

200

{"cleanuprange":24}

Request processed successfully.

403

{"err":"Access denied"}

The apikey is missing or invalid.

405

{"err":"Access denied"}

The user has no rights for this operation.

500

{"err":"Error while modifying configuration"}

Internal server error.

Sanitized file clean up

(cleanup records older than)

PUT /admin/config/sanitize

Properties

Property

Value

DESCRIPTION

Setting sanitized files cleanup time. The cleanup range is defined in minutes .

URL

http://<server>:<port>/admin/config/sanitize

REQUIRED RIGHTS

retention: [read, write]

HTTP METHOD

PUT

CONTENT TYPE

json

BODY

{"maxage":360}

Response

Result code

Value

Description

200

{"maxage":360}

Request processed successfully.

403

{"err":"Access denied"}

The apikey is missing or invalid.

405

{"err":"Access denied"}

The user has no rights for this operation.

500

{"err":"Error while modifying configuration"}

Internal server error.

Update settings

(reference: Update settings)

PUT /admin/config/update

Properties

Property

Value

DESCRIPTION

Setting processing history cleanup time. The cleanup range is defined in hours .

URL

http://<server>:<port>/admin/config/update

REQUIRED RIGHTS

update: [read, write]

HTTP METHOD

PUT

CONTENT TYPE

json

BODY

{
"autoupdateperiod": 240,
"deleteafterimport": true,
"disabledupdate": [
{
"days": "5-7",
"from": 480,
"to": 960
},
{
"days": "1-2",
"from": 480,
"to": 960
}
],
"pickupfolder": "/tmp/core-data/update_autoadd",
"source": "internet"
}

Response

Result code

Value

Description

200

{
"autoupdateperiod": 240,
"deleteafterimport": true,
"disabledupdate": [
{
"days": "5-7",
"from": 480,
"to": 960
},
{
"days": "1-2",
"from": 480,
"to": 960
}
],
"pickupfolder": "/tmp/core-data/update_autoadd",
"source": "internet"
}

Request processed successfully.

403

{"err":"Access denied"}

The apikey is missing or invalid.

405

{"err":"Access denied"}

The user has no rights for this operation.

500

{"err":"Error while modifying configuration"}

Internal server error.

Upon successful modification, in the response you must see the same JSON structure you have just set.

Explanation

There are three update methodology.

The actual method depends on the source setting:

"source": "internet"
 
OR
 
"source": "folder"
 
OR
 
"source": "manual"

When choosing the Internet method means the product will do automatic update downloading from the internet.

To set the frequency of these updates choose the corresponding value presented on the autoupdateperiod key's value.

"autoupdateperiod": 240

The value is representing minutes (how often the product will check for updates on the internet)

You can set when NOT to distribute update packages to scan nodes:

"disabledupdate": [
{
"days": "1",
"from": 480,
"to": 960
},
{
"days": "5-7",
"from": 480,
"to": 960
}
]

This is a JSON array, in which you can define the time period when you do not want to distribute update packages to scan nodes.

The JSON below mean that from Friday to Sunday (week starts on Monday (1), ends on Sunday (7)) from 8:00 to 16:00 you do not want to distribute packages.

From and to is the distance in minutes from 0:00 (8:00 → 480 minutes, 16:00 → 960 minutes)

{
"days": "5-7",
"from": 480,
"to": 960
},

When selecting folder as an update source, then the most important settings are:

"deleteafterimport": true
 
AND
 
"pickupfolder": "/tmp/core-data/update_autoadd"

deleteafterimport means if you want to clean the pickup folder after the updates have been applied,

pickupfolder sets the folder where the core will look for update files.

Default settings

{
"autoupdateperiod": 240,
"deleteafterimport": true,
"disabledupdate": [],
"pickupfolder": "/tmp/core-data/update_autoadd",
"source": "internet"
}

Roles

(Create new role)

POST /admin/role

Properties

Property

Value

DESCRIPTION

Add a new user role to the system.

URL

http://<server>:<port>/admin/role

REQUIRED RIGHTS

users: [read, write]

HTTP METHOD

POST

CONTENT TYPE

json

BODY

{
"name": "new_role",
"display_name": "New Role",
"rights": {
"agents":[
"read",
"write"
],
"cert":[
"read",
"write"
],
"configlog":[
"read",
"write"
],
"engines":[
"read",
"write"
],
"external":[
"read",
"write"
],
"license":[
"read",
"write"
],
"quarantine":[
"read",
"write"
],
"retention":[
"read",
"write"
],
"rule":[
"read",
"write"
],
"scan":[
"read",
"write"
],
"scanlog":[
"read",
"write"
],
"skip":[
"read",
"write"
],
"update":[
"read",
"write"
],
"updatelog":[
"read",
"write"
],
"users":[
"read",
"write"
],
"workflow":[
"read",
"write"
],
"zone":[
"read",
"write"
]
}
}

Response

Result code

Value

Description

200

{
"display_name": "New Role",
"editable": true,
"id": 6,
"name": "new_role",
"rights": {
"agents": [
"read",
"write"
],
"cert": [
"read",
"write"
],
"configlog": [
"read",
"write"
],
"engines": [
"read",
"write"
],
...
},
"user_count": 0
}

Request processed successfully.

400

 

Failed to apply changes.

403

{"err":"Access denied"}

The apikey is missing or invalid.

405

{"err":"Access denied"}

The user has no rights for this operation.

500

{"err":"Error while modifying configuration"}

Internal server error.

Users

( Create new users )

POST /admin/user

Properties

Property

Value

DESCRIPTION

Add a new user to the system.

URL

http://<server>:<port>/admin/user

REQUIRED RIGHTS

users: [read, write]

HTTP METHOD

POST

CONTENT TYPE

json

BODY

{
"api_key": "b8a4b52f19de88e365aa4f7e403fa91b352f",
"directory_id": 1,
"display_name": "asdasd",
"email": "asd@asd",
"name": "asdasd",
"password": "asd",
"roles": [
"1",
"2",
...
],
"ui_settings": {
"refresh_rate": "{\"value\":30}",
"time_period": "{\"value\":24,\"unitInHour\":1}",
...
}


Response

Result code

Value

Description

200

{
"api_key": "0df0d168c333e43b2d67c620a8da48ce904c",
"directory_id": 1,
"display_name": "asdasdsd",
"email": "asd@asd",
"id": 2,
"name": "asdasd",
"rights": {
"agents": [
"read",
"write"
],
"cert": [
"read",
"write"
],
"configlog": [
"read",
"write"
],
"engines": [
"read",
"write"
],
...
},
"roles": [
"1",
"2"
],
"ui_settings": {
"refresh_rate": "{\"value\":30}",
"time_period": "{\"value\":24,\"unitInHour\":1}"
}
}

Request processed successfully.

400

 

Failed to apply changes.

403

{"err":"Access denied"}

The apikey is missing or invalid.

405

{"err":"Access denied"}

The user has no rights for this operation.

500

{"err":"Error while modifying configuration"}

Internal server error.

Import

(Import configuration from file)

POST /admin/import

Properties

Property

Value

DESCRIPTION

Import configuration from file.

URL

http://<server>:<port>/admin/import

REQUIRED RIGHTS

Administrators right

HTTP METHOD

POST

CONTENT TYPE

json

BODY

Already exported config json.

{
"config": {
"policy.rule.rule": {
"items": [
{
"active": true,
"allow_cert": false,
"allow_cert.cert": "None",
...
}

Response

Result code

Value

Description

200

{"result":"Successfully imported"}

Request processed successfully.

304

{ }

The configuration has not changed.

400

{"err":"Unable to parse JSON body"}

The format of the configuration file is invalid.

400

{"err":"Unable to import new configuration"}

Internal server error.

403

{"err":"Access denied"}

The apikey is missing, or the user has no rights for this operation.

500

{"err":"Unable to save new configuration"}

Internal server error.

Update

(Trigger update mechanism manually)

POST /admin/update

Properties

Property

Value

DESCRIPTION

Trigger the update mechanism manually to fetch and deploy packages.

URL

http://<server>:<port>/admin/update

REQUIRED RIGHTS

engines: [read, write]

HTTP METHOD

POST

Response

Result code

Value

Description

200

{"result":"Update triggered successfully."}

Request processed successfully.

403

{"err":"Access denied"}

The apikey is missing or invalid.

405

{"err":"Access denied"}

The user has no rights for this operation.

500

{"err":"Error triggering update"}

Internal server error.

Change password

(Modify user password)

POST /user/changepassword

Properties

Property

Value

DESCRIPTION

Modify the password set for the user identified by apikey.

URL

http://<server>:<port>/user/changepassword

REQUIRED RIGHTS


HTTP METHOD

POST

CONTENT TYPE

json

BODY

{
"old_password": "oldpassword",
"new_password": "newpassword"
}

Response

Result code

Value

Description

200

{"result":"Successful"}

Request processed successfully.

400

{"err":"Access denied"}

The apikey is missing or invalid.

405

{"err":"Access denied"}

The user has no rights for this operation.

500

{"err":"Password modification failed"}

Internal server error.

Nodes

(Get node list and statuses)

GET /stat/nodes

Properties

Property

Value

DESCRIPTION

Get the list of connected nodes and status of all of them.

URL

http://<server>:<port>/stat/nodes

REQUIRED RIGHTS

agents: [read]

HTTP METHOD

GET

Response

Result code

Value

Description

200

{
"external_nodes_allowed":false,
"max_node_count":1,
"statuses": [
{
"address":"",
"cpu_cores":8,
"engines":[
{
"active":true,
"db_ver":"5.1.0-304",
"def_time":"1970-01-01T00:00:00.000Z",
"eng_name":"Archive engine",
"eng_ver":"5.1.0-304",
"engine_type":"archive",
"id":"7z_4_linux"
},
{
"active":true,
"db_ver":"25050",
"def_time":"2018-10-19T07:01:16.000Z",
"eng_name":"ClamAV",
"eng_ver":"0.100.2-104",
"engine_type":"av",
"id":"clamav_1_linux"
}
],
"free_disk_space":173993443328,
"id":":69",
"issues":[
{
"description":"1 engines are not deployed to this node",
"severity":"warning"
}
],
"load":14,
"os":"Linux Mint 18.3 Sylvia",
"scan_queue":0,
"total_mem":40100,
"version":"4.13.1"
}
]
}

Request processed successfully.

403

{"err":"Access denied"}

The apikey is missing or invalid.

405

{"err":"Access denied"}

The user has no rights for this operation.

Engines

(Get the list of engines)

GET /stat/engines

Properties

Property

Value

DESCRIPTION

Get the list of engines and status of all of them.

URL

http://<server>:<port>/stat/engines

REQUIRED RIGHTS

Need "full details" visibility for at least one of the workflow rules. When the visibility is set for "Everybody", then the apikey is not required.

HTTP METHOD

GET

Response

Result code

Value

Description

200

[
{
"abandoned": false,
"active": true,
"def_time": "",
"download_progress": 100,
"download_time": "2018-12-03T12:41:43.841Z",
"eng_id": "7z_4_linux",
"eng_name": "Archive engine",
"eng_type": "Bundled engine",
"eng_ver": "5.1.0-304",
"engine_type": "archive",
"state": "production",
"type": "engine"
},
{
"abandoned": false,
"active": true,
"def_time": "2018-10-19T07:01:16.000Z",
"download_progress": 100,
"download_time": "2018-12-03T12:41:43.901Z",
"eng_id": "clamav_1_linux",
"eng_name": "ClamAV",
"eng_type": "Bundled engine",
"eng_ver": "0.100.2-104",
"engine_type": "av",
"state": "production",
"type": "engine"
},
{
"abandoned": false,
"active": false,
"def_time": "",
"download_progress": 100,
"download_time": "2018-12-03T12:41:43.961Z",
"eng_id": "clamav_1_windows",
"eng_name": "ClamAV",
"eng_type": "Bundled engine",
"eng_ver": "0.99.2-24",
"engine_type": "av",
"state": "downloaded",
"type": "engine"
},
{
"abandoned": false,
"active": true,
"def_time": "",
"download_progress": 100,
"download_time": "2018-12-03T12:41:43.991Z",
"eng_id": "ds_3_wine",
"eng_name": "Data sanitization",
"eng_type": "Bundled engine",
"eng_ver": "5.2.8-778-338",
"engine_type": "ds",
"state": "production",
"type": "engine"
},
{
"abandoned": false,
"active": true,
"def_time": "2016-06-13T00:00:00.000Z",
"download_progress": 100,
"download_time": "2018-12-03T12:41:43.820Z",
"eng_id": "filetype_1_linux",
"eng_name": "FileType",
"eng_type": "Bundled engine",
"eng_ver": "5.30.07192015-259",
"engine_type": "filetype",
"state": "production",
"type": "engine"
},
...
]

Request processed successfully.

403

{"err":"Access denied"}

The apikey is missing or invalid.

405

{"err":"Access denied"}

The user has no rights for this operation.

500

{"err": "Error querying engine list"}

Internal server error.

Pin engine to prevent auto-updates

(Pin engines to prevent applying automatic updates on them. Manual updates still can be applied.)

POST /admin/engine/{engineId}/pin

Properties

Property

Value

DESCRIPTION

Set engine to be pinned.

URL

http://<server>:<port>/admin/engine/{engineId}/pin

REQUIRED RIGHTS

engines : [read, write]

HTTP METHOD

POST

Header Parameters

Header

Description

Allowed Values

Required

apikey

Authentication

<your_unique_apikey>

YES

type

Pin engine or database to prevent applying automatic updates on it.

(If the type is not defined both engine and database will be pinned.)

engine / database

NO

Response

Result code

Value

Description

200

{"result":"Engine is pinned"}
{"result":"Database is pinned"}
{"result":"Both engine and database are pinned"}

Request processed successfully.

400

{"err":"The type header value has to be 'engine' or 'database'"}

Bad request.

403

{"err":"Access denied"}

The apikey is missing or invalid.

405

{"err":"Access denied"}

The user has no rights for this operation.

500

{"err":"Can't pin the engine"}
{"err":"Can't pin the database"}
{"err":"Error has occurred. Engine is pinned/unpinned, Database is pinned/unpinned"}

Internal server error.

Unpin engine to apply auto-updates

(Unpin engines so automatic updates will be applied on them.)

PUT /admin/engine/{engineId}/unpin

Properties

Property

Value

DESCRIPTION

Set engine to be unpinned.

URL

http://<server>:<port>/admin/engine/{engineId}/unpin

REQUIRED RIGHTS

engines : [read, write]

HTTP METHOD

POST

Header Parameters

Header

Description

Allowed Values

Required

apikey

Authentication

<your_unique_apikey>

YES

type

Unpin engine or database to applying automatic updates on it.

(If it is not defined both engine and database will be unpinned.)

engine / database

NO

Response

Result code

Value

Description

200

{"result":"Engine is unpinned"}
{"result":"Database is unpinned"}

Request processed successfully.

400

{"err":"The type header value has to be 'engine' or 'database'"}

Bad request.

403

{"err":"Access denied"}

The apikey is missing or invalid.

405

{"err":"Access denied"}

The user has no rights for this operation.

500

{"err":"Can't unpin the engine"}
{"err":"Can't unpin the engine"}
{"err":"Error has occurred. Engine is pinned/unpinned, Database is pinned/unpinned"}

Internal server error.

Enable engines

(Enable to use engine on the nodes)

POST /admin/engine/{engineId}/enable

Properties

Property

Value

DESCRIPTION

Enable to use the selected engine on the nodes.

URL

http://<server>:<port>/admin/engine/{engineId}/enable

REQUIRED RIGHTS

engines : [read, write]

HTTP METHOD

POST

Response

Result code

Value

Description

200

{"result":"Engine is enabled"}

Request processed successfully.

403

{"err":"Access denied"}

The apikey is missing or invalid.

405

{"err":"Access denied"}

The user has no rights for this operation.

500

{"err": "Can't enable the engine"}

Internal server error.

Disable engines

(Disable to use engine on nodes)

POST /admin/engine/{engineId}/disable

Properties

Property

Value

DESCRIPTION

Disable to use the selected engines on the nodes.

URL

http://<server>:<port>/admin/engine/{engineId}/disable

REQUIRED RIGHTS

engines: [read, write]

HTTP METHOD

POST

Response

Result code

Value

Description

200

{"result":"Engine is disabled"}

Request processed successfully.

403

{"err":"Access denied"}

The apikey is missing or invalid.

405

{"err":"Access denied"}

The user has no rights for this operation.

500

{"err": "Can't disable the engine"}

Internal server error.

Session settings

(Configure settings for session generated upon a successful login)

PUT /admin/config/session

Properties

Property

Value

DESCRIPTION

Configure settings for session generated upon a successful login

See more at 8.1.1.1. Login / Create a Session

URL

http://<server>:<port>/admin/config/session

REQUIRED RIGHTS

Administrators right

HTTP METHOD

PUT

CONTENT TYPE

json

BODY

{
"absoluteSessionTimeout": 0,
"allowCrossIpSessions": true,
"allowDuplicateSession": true,
"sessionTimeout": 300000
}

Response

Result code

Value

Description

200

{
"absoluteSessionTimeout": 0,
"allowCrossIpSessions": true,
"allowDuplicateSession": true,
"sessionTimeout": 300000
}

Request processed successfully.

403

{"err":"Access denied"}

The apikey is missing or invalid.

405

{"err":"Access denied"}

The user has no rights for this operation.

500

{"err":"Error while modifying configuration"}

Internal server error.

Webhook configurations - Retrieval

(Retrieve webhook supported settings)

GET /admin/config/webhook

Properties

Property

Value

DESCRIPTION

Getting settings supported for webhook mode

URL

http://<server>:<port>/admin/config/webhook

REQUIRED RIGHTS

Administrators right

HTTP METHOD

GET

Response

Result code

Value

Description

200

{
"maxretrytime": 3,
"delayduration": 1000,
"deplayprogression": 1000
}

Request processed successfully.

+ maxretrytime: number of allowed retries sending callback to client when failed

+ delayduration and delayprogression: in milliseconds.

For example: maxretrytime= 3

Sending callback failed for some reasons

  • 1st retry triggered after delayduration (ms)

  • 2nd retry triggered after delayduration+ delayprogression (ms)

  • 3rd retry triggered after delayduration+ 2*delayprogression (ms)

403

{"err":"Access denied"}

The apikey is missing or invalid.

405

{"err":"Access denied"}

The user has no rights for this operation.

500

{"err":"Internal server error"}

Internal server error.

Webhook configurations - Modification

(Retrieve webhook supported settings)

PUT /admin/config/webhook

Properties

Property

Value

DESCRIPTION

Modifying settings supported for webhook mode

URL

http://<server>:<port>/admin/config/webhook

REQUIRED RIGHTS

Administrators right

HTTP METHOD

PUT

CONTENT TYPE

json

BODY

{
"maxretrytime": <number>,
"delayduration": <number>,
"deplayprogression": <number>
}

+ maxretrytime: number of allowed retries sending callback to client when failed

+ delayduration and delayprogression: in milliseconds.

For example: maxretrytime= 3

Sending callback failed for some reasons

  • 1st retry triggered after delayduration (ms)

  • 2nd retry triggered after delayduration+ delayprogression (ms)

  • 3rd retry triggered after delayduration+ 2*delayprogression (ms)

Response

Result code

Value

Description

200

{
"maxretrytime": <number>,
"delayduration": <number>,
"deplayprogression": <number>
}

Request processed successfully.

403

{"err":"Access denied"}

The apikey is missing or invalid.

405

{"err":"Access denied"}

The user has no rights for this operation.

500

{"err":"Internal server error"}

Internal server error.