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": 240The 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": trueAND"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. |