Spectra Detect Manager API Guide

This is a companion guide to the full API reference that can be found in the Help menu on the Manager appliance.

Important

For setups using a self-signed certificate, add -k or --insecure before the appliance URL in the curl examples.

Here are the steps covered in this guide:

Obtain an authorization token
Back up and restore the Manager
Set up the Manager
Connect appliances to the Manager
Configure appliances

Obtain an authorization token

To use the Manager API, you first need an authorization token that needs to be included in all API calls. You can obtain this token using the authentication API or the web interface.

The authorization token is a string of alphanumeric characters, between 30 and 60 characters in length. The authorization token should be provided in the HTTP Authorization header. The value of this field must be in this format:

Token exampletoken

where exampletoken should be replaced with the user’s own authorization token string.

Call the authentication API with your username and password using the multipart/form-data content type.

POST /api/v1/auth/token/

Form Parameters:

username – Your username.
password – Your password.

Example request:

curl -X POST 'https://c1000.example.com/api/v1/auth/token/' --form "username=user123" --form "password=pass123"

Example response:

{
  "token": "<token>"
}

This token has to be included in all further requests to the API in the Authorization header. For example:

curl -H "Authorization: Token <token>" https://c1000.example.com/api/configuration/appliances

Back up and restore the Manager

New in version 3.4.

In certain cases, you may want to perform a complete backup of the Manager before performing any other actions. Backup files contain central configuration settings, user accounts on the Manager instance, a database of connected appliances and all of their configuration files, appliance groups, and synchronized YARA rules.

Uploading the backup archive to a clean machine restores the data stored in the Manager database, but configuration settings first need to be applied to configuration groups to take effect.

The steps are:

Create a backup file
Find out the backup status
Download backup file
Upload and restore the Manager from backup

Create a backup file

POST /api/v1/backup/create/

Creates a backup file that can be downloaded with the GET /api/v1/backup/download/ endpoint.

Response JSON Object:

message (string) – status message

Find out the backup status

GET /api/v1/backup/

Returns the current backup status and availability.

Response JSON Object:

status (string) – backup creation status; the backup is ready when the value is idle
message (string) – status message
backup_filename (string) – name of the backup file

Download backup file

GET /api/v1/backup/download/: Downloads the backup file.

Upload and restore the Manager from backup

POST /api/v1/backup/restore-upload/

Uploads the backup file to the Manager.

Form Parameters:

file – the backup file

Set up the Manager

New in version 3.4.

Perform the following actions to set up the Manager. This guide is a reference for an enterprise-ready deployment of Spectra Detect, with redundancy and password rotation requirements, for example. Skip the steps that are not relevant to your desired setup. If you have additional requirements that are not covered by this guide, you can always find the complete API reference on the Manager itself (Help menu).

The steps for an initial setup are:

Set up authentication:
1. (Get authorization token - already covered in the previous section)
2. Change admin password
Configure network settings:
1. Upload SSL certificate
2. Configure the application URL
3. List the allowed hosts
4. Set network time sync
Configure user authentication
1. Federated login
2. SSH access
Configure Spectra Intelligence
Update the Manager
License the Manager
Set up logging and alerting
1. SNMP
2. SMTP
3. System alerting
4. Central logging
Enable synchronization and redundancy

Change admin password

First, you need to get the ID of the admin user. It’s almost certainly 1, but you can get all users and their IDs by calling this endpoint:

GET /api/v1/authentication/users/

Returns all users on the appliance.

Example response:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "username": "admin",
      "email": "hello@example.com",
      "first_name": "",
      "last_name": "",
      "directory_name": "",
      "directory_type": 0,
      "last_login": "2024-02-07T12:10:04.744401Z",
      "date_joined": "2024-01-03T03:01:30.166022Z",
      "is_superuser": true,
      "is_active": true
    }
  ]
}

Then change the administrator password:

PUT /api/v1/authentication/users/(id)/password/

Parameters:

id – user ID

Request JSON Object:

passsword – your new password

Example request body:

{
  "password": "Correct Horse Battery Staple"
}

Add or remove users

To create a new user, use this endpoint:

POST /api/v1/authentication/users/add/

Creates a new user.

Request JSON Object:

username (string) – the new user’s username
email (string) – user’s email
first_name (string) – first name
last_name (string) – last name
password (string) – user’s password

Response example:

{
  "id": 0,
  "username": "string",
  "email": "user@example.com",
  "first_name": "string",
  "last_name": "string",
  "directory_name": "string",
  "directory_type": 0,
  "last_login": "2019-08-24T14:15:22Z",
  "date_joined": "2019-08-24T14:15:22Z",
  "is_superuser": true,
  "is_active": true
}

To remove a user, use this:

DELETE /api/v1/authentication/users/(id)/delete/

Deletes a user.

Parameters:

id – user’s ID

Example adding and deleting a user:

curl --url https://{server}/api/v1/authentication/users/add/
     --header 'Authorization: Token <token>'
     --json '{"username":"hello","email":"example@example.com","password":"example"}'

curl --url https://{server}/api/v1/authentication/users/3/delete
     --header 'Authorization: Token <token>'
     --request DELETE

Configure network settings

The Manager can operate without a valid SSL certificate, but to maximize security in communication between users and the appliance, you may want to first upload a valid SSL certificate to the Manager.

To upload the certificate to the Manager, use the File Upload endpoint. In case multiple chunks are needed to upload the file, refer to the API Reference Guide on the Manager.

POST /api/v1/system/upload/

Uploads a file to the Manager.

Form Parameters:

file – the certificate file
flowIdentifier – UUID4 hex code ID of the file
flowFilename – name of the file
flowTotalSize – size of the SSL certificate file
flowCurrentChunkSize – size of the current “chunk” of the upload
flowChunkNumber – number of the current “chunk” of the upload

The certificate file itself should be in the .pem format and should contain just the public certificate of the server (Manager). It should be accompanied with a corresponding private key (.key), which must be uploaded separately.

The flowIdentifier value is the identifier of the file. It must be a 32 characters long hexadecimal value and it should be a universally unique identifier (UUID). Once the certificate is uploaded to the appliance, it will be named according to the flowFilename and flowIdentifier fields as follows:

flowIdentifier + .flowFilename

So if the flowFilename is valid_cert.pem, the resulting upload file name will be:

ce2e9dc9-9cf4-4b64-ab09-b67ff58370f7.valid_cert.pem

Certificate files are small enough that they can be uploaded in a single chunk, so set flowCurrentChunkSize to be equal to the flowTotalSize, and set the flowChunkNumber to 1.

Repeat the process to upload the certificate key.

Curl code sample

# Add --insecure before the URL if you are using a self-signed SSL certificate
curl -X POST https://{server}/api/v1/system/upload/
     -H "Authorization: Token <token>"
     -F "flowChunkNumber=1"
     -F "flowCurrentChunkSize=892"
     -F "flowFilename=valid_cert.pem"
     -F "flowIdentifier=ce2e9dc99cf44b64ab09b67ff58370f7"
     -F "flowTotalSize=892"
     -F "file=@ssl_cert.pem"

While the SSL certificate upload is optional, you must set up the base URL and allowed hosts. This request also allows completing your SSL setup.

POST /api/v1/config/network/

Request JSON Object:

base_url (string) – Manager URL
allowed_hosts (string) – allowlisted IP addresses or URLs, separated by a newline (\n) character
certificate_path (string) – path to the uploaded certificate file
certificate_key_path (string) – path to the uploaded certificate key
reset_ssl (boolean) – restart SSL configuration

Example request body:

{
  "base_url": "c1000.example.com",
  "allowed_hosts": "worker1.example.com\nworker2.example.com",
  "certificate_path": "/my/default/path",
  "certificate_key_path": "/my/default/path",
  "reset_ssl": true
}

In addition, enable network time synchronization:

POST /api/v1/config/ntp/

Request JSON Object:

enable (boolean) – enable/disable NTP
servers (string) – list of NTP servers, separated by a newline (\n) character

Example request body:

{
  "enable": true
}

Configure user authentication

After configuring the minimum necessary settings for proper networking of the Manager, continue with provisioning user access. In enterprise deployments, a federated (single sign-on) login is often used. This guide references only some of the available fields - for a complete overview, check the API reference on the Manager itself.

POST /api/v1/config/directory/: New in version 3.4.

Sends LDAP/OIDC configuration to the Manager.

After sending the configuration with POST /api/v1/config/directory/, you can verify that the configuration is updated using GET /api/v1/config/directory/.

Enable SSH root login

Warning

Dangerous! Some services like password rotation solutions require root SSH access to the devices they are managing. This opens up the attack surface considerably.

POST /api/v1/config/ssh/

New in version 3.4.

Sends the SSH configuration to the appliance.

Request JSON Object:

permit_root_login (boolean) – Enable/disable SSH root login.
sshd_control (boolean) – Enable/disable the appliance’s control over the sshd service.

Configure Spectra Intelligence

Next, configure the connection between Spectra Intelligence and the Manager. This is a prerequisite for licensing the Manager using Spectra Intelligence. In addition, connecting it to Spectra Intelligence allows it to download upgrade binaries.

POST /api/v1/config/ticloud/

New in version 3.4.

Sends the configuration for Spectra Intelligence to the Manager.

Request JSON Object:

enable (boolean) – enable/disable Spectra Intelligence
url (string) – URL of Spectra Intelligence (default: https://appliance-api.reversinglabs.com)
user (string) – Spectra Intelligence username
token (string) – Spectra Intelligence password
timeout (integer) – how long before any request times out (seconds)
proxy_enabled (boolean) – enable/disable proxy to Spectra Intelligence
proxy_host (string) – URL of the proxy
proxy_port (integer) – proxy port
proxy_user (string) – username for the proxy
proxy_password (string) – password for the proxy

Example request body:

{
  "enable": true,
  "url": "https://appliance-api.reversinglabs.com",
  "user": "u/myusername",
  "token": "exampleABC123",
  "timeout": 10
}

To verify the changes, send a GET request to the same endpoint (GET /api/v1/config/ticloud/).

Update the Manager

New in version 3.4.

Get the list of available upgrades:

GET /api/v1/update-system/available-update/

Gets available upgrades.

Response JSON Object:

filename (string) – name of the update file
sha1 (string) – SHA1 hash of the update file
version (string) – version introduced by the update file
requires (string) – required version to use this update file
time (string) – build time of the update file

Example response:

{
  "filename": "string",
  "sha1": "string",
  "version": "string",
  "requires": "string",
  "time": "2019-08-24T14:15:22Z"
}

Then update the Manager to the latest available version:

POST /api/v1/update/latest/

Starts Manager upgrade.

Status Codes:

200 OK – no response body
400 Bad Request – response body contains the following fields:

Response JSON Object:

code (integer) – error code
message (string) – error message
detail (object) – additional details

Example requests:

curl -X GET https://{server}/api/v1/update-system/available-update/
     -H 'Authorization: Token <token>'

curl -X POST https://{server}/api/v1/update/latest/
     -H 'Authorization: Token <token>'

License the Manager

The Manager can be licensed in two ways, either by configuring Spectra Intelligence or by uploading a license file.

Using Spectra Intelligence

New in version 4.0.

To configure Spectra Intelligence on the Manager, use the following endpoint.

POST /api/v1/license/configure/cloud/

Performs a licensing request using Spectra Intelligence.

Request JSON Object:

enable (boolean) – enable/disable Spectra Intelligence
url (string) – URL of Spectra Intelligence (default: https://appliance-api.reversinglabs.com)
user (string) – Spectra Intelligence username
token (string) – Spectra Intelligence password
timeout (integer) – how long before any request times out (seconds)
proxy_enabled (boolean) – enable/disable proxy to Spectra Intelligence
proxy_host (string) – URL of the proxy
proxy_port (integer) – proxy port
proxy_user (string) – username for the proxy
proxy_password (string) – password for the proxy

Example POST body

{
  "url": "https://appliance-api.reversinglabs.com",
  "user": "string",
  "token": "string",
  "timeout": 1,
  "proxy_enabled": true,
  "proxy_host": "string",
  "proxy_port": 0,
  "proxy_user": "string",
  "proxy_password": "string"
}

Example curl request

curl -X POST 'https://c1000.example.com/api/license/v1/configure/cloud' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token exampletoken' \
--data '{
"url": "https://appliance-api.reversinglabs.com",
"user": "string",
"token": "string",
"timeout": 1,
"proxy_enabled": true,
"proxy_host": "string",
"proxy_port": 0,
"proxy_user": "string",
"proxy_password": "string"
}'

Conversely, perform a GET /api/v1/license/configure/cloud/ to retrieve the configuration.

Using a license file

New in version 3.4.

The alternative to Spectra Intelligence is manually uploading a license file. To do so, first create a unique machine ID:

POST /api/v1/license/machine-id/generate/

Generate a machine ID.

Response JSON Object:

machineId (string) – unique ID of the machine

Example curl request.

curl -X POST https://c1000.example.com/api/v1/license/machine-id/generate/ -H 'Authorization: Token exampletoken'

When the Manager responds with the machine ID, email it to ReversingLabs support. We will respond with a license file that can then be uploaded to the Upload License File endpoint:

PUT /api/v1/license/upload/

Uploads a license file.

Form Parameters:

license – license file

Example curl request.

curl -X PUT https://example.c1000.com/api/license/v1/upload -H 'Authorization: Token exampletoken' -F 'file=@example_license_file'

Response JSON Object:

message (string) – message returned (differs depending on the response code)

Set up logging and alerting

This chapter covers methods to monitor performance of the Manager itself. All the endpoints listed below also accept the GET method, which returns the current configuration.

POST /api/v1/config/snmp/

New in version 3.4.

Send SNMP configuration to the Manager. The Manager uses SNMP v2c.

Request JSON Object:

enable (boolean) – enable/disable SNMP monitoring
community (string) – community string to use
trap_sink_enable (boolean) – enable/disable sending traps
trap_community (string) – community string for traps
trap_sink (string) – address of the trap receiver
trap_avg_load_threshold_1min (integer) – Manager sends a trap when this value is exceeded (percentage of used CPU threads over 1 minute)
trap_avg_load_threshold_5min (integer) – Manager sends a trap when this value is exceeded (percentage of used CPU threads over 5 minutes)
trap_avg_load_threshold_15min (integer) – Manager sends a trap when this value is exceeded (percentage of used CPU threads over 15 minutes)
trap_memory_threshold (integer) – Manager sends a trap when this value is exceeded (percentage of used memory)
trap_disk_threshold (integer) – Manager sends a trap when this value is exceeded (percentage of used disk)

Response JSON Object:

message (string) – response message
detail (object) – details (if any)
code (integer) – HTTP response code

POST /api/v1/config/smtp/

New in version 3.4.

Sends SMTP configuration to the Manager.

Request JSON Object:

host (string) – hostname of the SMTP relay server
port (integer) – port where the relay server is listening for SMTP traffic
user (string) – SMTP username
password (string) – SMTP password
password_set (boolean) – use/don’t use password for authentication to the SMTP server
use_tls (boolean) – use/don’t use TLS encryption
default_from_email (string) – default email address displayed in the “from” field

Response JSON Object:

message (string) – response message
detail (object) – details (if any)
code (integer) – HTTP response code

POST /api/v1/config/systemalerting/

New in version 3.4.

Sends configuration for syslog usage to the Manager.

Request JSON Object:

syslog_enable (boolean) – enable/disable syslog
syslog_host (string) – hostname of the syslog server
syslog_port (integer) – receiving port of the syslog server
syslog_transport_protocol (string) – protocol to use (TCP/UDP)
syslog_enable_audit_logs (boolean) – include audit logs in syslog

Response JSON Object:

message (string) – response message
detail (object) – details (if any)
code (integer) – HTTP response code

POST /api/v1/config/central_logging/

New in version 3.4.

Configures central logging on the Manager.

Request JSON Object:

central_logging__enable (boolean) – enable/disable central logging
central_logging__retention_period (string) – how long to keep collected logs
central_file_storage__enable (boolean) – enable/disable storing samples on the Manager
central_file_storage__ttl (integer) – time (hours) after which stored samples are removed
central_file_storage__file_size_limit (integer) – maximum file size to store
central_storage_general__min_free_space (integer) – minimum free space left on the disk after which new file uploads are rejected

Response JSON Object:

message (string) – response message
detail (object) – details (if any)
code (integer) – HTTP response code

Enable synchronization and redundancy

One last step before completing the setup of the Manager is to enable the synchronization of YARA rulesets, as well as setting up a redundant Manager that takes over in case of a failure of the primary.

YARA sync

POST /api/v1/config/sync/

New in version 3.4.

Enables or disables the synchronization of YARA rulesets across connected appliances.

Request JSON Object:

yararulesets_enable (boolean) – enable/disable sync

Response JSON Object:

message (string) – response message
detail (object) – details (if any)
code (integer) – HTTP response code

Set up a redundant cluster

New in version 4.0.

Note

The prerequisite for this is to have another Manager already operational and accessible on the network.

The first step is to create a cluster and set up the basic configuration:

POST /api/v1/cluster/create/

Creates a Manager cluster.

Request JSON Object:

local_ip (string) – IP address of the primary Manager
remote_ip (string) – IP address of the secondary Manager
vpn_network (string) – virtual private network range in CIDR notation; subnet mask can only be /29 or lower
virtual_ip (string) – shared IP address to access the Manager when in redundant mode
failover_timeout (integer) – time (seconds) between the unavailability of the primary and activation of the redundant Manager

Response JSON Object:

return_code – HTTP response status code
message – response message

After this, you must perform a mutual authentication between the two appliances:

POST /api/v1/cluster/exchange_keys/

Performs an authentication step with the secondary Manager. The endpoint expects a JSON body that contains a values field. This field is an object that contains the fields described below:

Request JSON Object:

local_ip (string) – IP address of the primary Manager
remote_ip (string) – IP address of the secondary Manager
remote_url (string) – URL of the secondary Manager
user (string) – username (admin)
pwd (string) – admin password

Finally, verify that redundancy works:

POST /api/v1/cluster/verify/

Performs checks between appliances.

Request JSON Object:

remote_ip (string) – IP address of the secondary Manager
section (string) – aspect of redundancy to check (can be ssh or versions)

Response JSON Object:

return_code (integer) – HTTP response status code
message (string) – request-related message
messages (array) – messages related to redundancy
reduser_ssh_connect (boolean) – is SSH connectivity established?
postgres_ssh_connect (boolean) – is the redundant database accessible?
rld_ssh_tunnel_connect (boolean) – can an SSH tunnel be established?
version_local (integer) – version of the primary Manager
version_remote (integer) – version of the secondary Manager

Connect appliances to the Manager

This section covers the following actions:

Add appliances to the Manager
Authorize appliances
Update appliances
Upload SSL certificate to appliances
Check connected appliances

Add appliances to the Manager

New in version 3.4.

Note

Appliances first must be up and running.

To configure appliances with the Manager, start with adding them:

POST /api/v1/appliances/create/

Adds an appliance to the Manager.

Request JSON Object:

name (string) – name of the appliance
type (string) – appliance type (a1000, tiscale-worker, tiscale-hub)
url (string) – URL of the appliance
snmp_community (string) – SNMP community string
haproxy_password (string) – load balancer password

Response JSON Object:

name (string) – name of the appliance
type (string) – appliance type (a1000, tiscale-worker, tiscale-hub)
url (string) – URL of the appliance
id (string) – appliance ID
snmp_community (string) – SNMP community string
haproxy_password (string) – load balancer password

Authorize appliances

After being added to the Manager, appliances must be authorized. The authorization process is different, depending on the appliance. The API endpoint is the same, but two different methods must be used: GET for Hubs and Workers, and PUT for Spectra Analyze.

Tip

Use GET /api/v1/configuration/appliances/ to get the IDs of all connected appliances.

Hub, Worker

GET /api/v1/appliances/(id)/authorization/

New in version 3.4.

Parameters:

id – ID of the appliance

Spectra Analyze

PUT /api/v1/appliances/(id)/authorization/

New in version 4.1.

Parameters:

id – ID of the appliance

Request JSON Object:

token (string) – authentication token

Update appliances

Get the list of available upgrades:

GET /api/v1/package-management/

Returns the list of available update binaries for connected appliances.

Response JSON Object:

bins (array) – list of binaries, with type and version info
used_space (string) – how much space is used on the appliance
allowed_space (string) – how much space is left on the appliance
is_ticloud_data_available (boolean) – is Spectra Intelligence data on upgrade binaries available

Example response:

{
    "bins": [
        {
        "type": "string",
        "version": "string"
        }
    ],
    "used_space": 0,
    "allowed_space": 0,
    "is_ticloud_data_available": true
}

After retrieving the list of available updates, use the appliance type and version from the bins object to download one of the available updates:

POST /api/v1/package-management/(appliance_type)/(version)

Downloads an update package from the Spectra Intelligence cloud.

Parameters:

appliance_type – what type of appliance (a1000, c1000, tiscale-hub, tiscale-worker)
version – version of the appliance

Response JSON Object:

id (integer) – appliance ID
status (string) – download status

{
  "id": 0,
  "status": "string"
}

Once the update downloads, the following request will upgrade a single appliance (upgrading multiple appliances at the same time isn’t supported). To upgrade an appliance, find its name using GET /api/v1/configuration/appliances/ and include it in the request body (see example below).

POST /api/upgrade/start/

Starts appliance upgrade.

Request JSON Object:

appliance_name (string) – appliance name

You can check the upgrade status at any point:

POST /api/upgrade/status/

Returns status 200 OK, and the body displays the current status, which can be:

idle: there is no update happening
pending: an update is planned
downloading: an update is currently being downloaded to the appliance
installing: an update is installing
error: there was an error installing an update

The body will also contain the entire upgrade log, if available. If not, it will contain the message “Update log not available.”

Request JSON Object:

appliance_name (string) – appliance name

Response JSON Object:

update_status (string) – update status
update_log (string) – update log

Example response:

{
  "update_status": "idle",
  "update_log": "<entire update log>"
}

Here’s a list of curl commands corresponding to the steps above:

curl -X GET https://{server}/api/v1/package-management/
     -H 'Authorization: Token <token>'

curl -X POST "https://{server}/api/v1/package-management/tiscale-worker/3.4.0/"
     -H "Content-Type: application/json"
     -H 'Authorization: Token <token>'
     -d '{}'

curl -X POST https://{server}/api/upgrade/start/
     -H 'Authorization: Token <token>'
     -d '{"appliance_name":"<appliance_name>"}'

curl -X POST https://{server}/api/upgrade/status/
     -H 'Authorization: Token <token>'
     -d '{"appliance_name":"<appliance_name>"}'

Upload SSL certificate to appliances

Note

Hub and Worker only. Uploading SSL certificates to Spectra Analyze through the Manager is not possible.

POST /api/v1/appliances/upload-certificate/(id)/

New in version 4.0.

Uploads an SSL certificate to an appliance.

Parameters:

id – ID of the appliance

Form Parameters:

file – certificate file

Response JSON Object:

message (string) – response message

Check connected appliances

After adding appliances, verify their connectivity:

GET /api/v1/configuration/appliances/

This endpoint returns a list of appliances connected to the Manager.

The structure of the fields in the results array is as follows:

Response JSON Object:

id (string) – appliance ID
appliance_name (string) – appliance name
type (string) – appliance type
release (string) – appliance version
cluster (string) – group name (standalone if not in a group)
state (string) – whether it’s primary or secondary (if in redundant mode)

… and licensing status:

GET /api/v1/appliances/licensing/

Returns the licensing status of all appliances connected to the Manager.

Response JSON Object:

uuid (string) – UUID of the appliance
name (string) – appliance name
ip (string) – appliance IP address
hostname (string) – appliance hostname
product (string) – type of appliance
status (string) – licensing status

Example response:

{
  "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  "name": "string",
  "ip": "192.168.0.1",
  "hostname": "example.com",
  "product": "a1000",
  "status": "VALID"
}

Configure appliances

This section describes how to centrally configure and manage connected appliances.

Licensing connected appliances

There are two ways to license connected appliances: using Spectra Intelligence and using license files.

Using Spectra Intelligence

To license connected appliances using the Spectra Intelligence cloud, configure it for that appliance, either through a group (Standard configuration groups, Hub groups) or individually (Individual configuration: Spectra Analyze).

The relevant portion required in the body of the request is:

{
  "content":
    {
      "cloud__enabled": true,
      "cloud__url": "data.reversinglabs.com",
      "cloud__user": "example_username",
      "cloud__token": "example_password",
      "cloud__token_set": true
    }
}

Using license files

To license connected appliances using license files, they all need to have a machine ID. Machine IDs can be generated for appliances without one, or generated for all appliances at once. If regenerating machine IDs for all appliances, those that already have a license will have to be licensed again.

GET /api/v1/license/

Generates a machine ID only for those appliances that don’t have it.

The response contains individual objects (each of which represents an appliance) with the following fields:

Response JSON Object:

status (string) – appliance status
product (string) – type of appliance
machineId (string) – machine ID
version (integer) – appliance version
serialNumber (string) – serial number of the appliance
licenseType (string) – type of license
company (string) – user’s company
expiryDate (string) – when the license expires
creationDate (string) – when the license was created

Example response:

{
    "status": "VALID",
    "product": "TISCALE_WORKER",
    "machineId": "string",
    "version": 0,
    "serialNumber": "148d7a56-176d-413b-9eb5-c62f6f5bb67a",
    "licenseType": "WILDCARD",
    "company": "string",
    "expiryDate": "2019-08-24",
    "creationDate": "2019-08-24"
}

If, for some reason, all machine IDs have to be generated, use GET api/v1/appliances/licensing/machine-id/.

Send one or more machine IDs to ReversingLabs support and, once we respond with license files, upload them to the Manager using the PUT /api/v1/appliances/licensing/ endpoint. The Manager will automatically match the license to the appropriate appliance.

PUT /api/v1/appliances/licensing/

Uploads a license file for one of the connected appliances.

Form Parameters:

file – license file to be uploaded

Response JSON Object:

message (string) – success/failure message
name (string) – appliance name
success (boolean) – success/failure

Standard configuration groups

New in version 3.4.

This section describes actions related to creating and managing configuration groups for Spectra Detect Workers.

Start with creating a configuration group:

POST /api/v1/config-group/create/

Creates a Worker configuration group.

Request JSON Object:

name (string) – name of the configuration group

Then, add the appliances and specify their configuration. Both PUT and PATCH methods are supported.

Note

In this guide, we display only some of the possible configuration options as there are almost 400 configurable fields. See the full API reference on the Manager for all options.

PUT /api/v1/config-group/content/(name)/

Saves configuration (but doesn’t apply it). The body must be a JSON object with two top-level fields: appliances and content.

Parameters:

name (string) – name of the configuration group

Request JSON Object:

appliances (array) – array of appliance names
content (object) – object containing configuration values

Here are some of the configurable fields in the content object:

Request JSON Object:

systemalerting__syslog_enable (boolean) – enable/disable forwarding system logs for the group
s3_integration_secret_access_key (string) – secret access key for an output S3 bucket
splunk__host (string) – URL of the connected Splunk instance

Check that the configuration is correct:

GET /api/v1/config-group/retrieve/(name)/

Returns the configuration for the group.

Parameters:

name – name of the configuration group

Apply the configuration:

PUT /api/v1/config-group/update/(name)/

Applies the configuration set in the previous step.

Parameters:

name (string) – name of the configuration group

Request JSON Object:

applyconfiguration (array) – list of appliances in the group

To verify that the configuration is applied, call the following endpoint:

GET /api/v1/appliances/

Get a list of appliances with their configuration details. The response contains an array called results, with objects inside. Each object corresponds to one connected appliance.

Response JSON Object:

results (array) – array with different appliances

In individual objects, the relevant fields are the name of your configuration group and the last_applied_config_timestamp field.

Response JSON Object:

group_name (string) – group name
last_applied_config_timestamp (string) – last time a configuration has been applied to this appliance

If you have applied the configuration to all the appliances in a configuration group, then find an object that contains the group_name corresponding to your configuration group, and inspect its last_applied_config_timestamp.

Important

This timestamp is updated twice, and the configuration is really applied (i.e. present on individual appliances) only after the second timestamp update. This usually takes around a minute. Therefore, one possible workflow would be:

GET /api/v1/appliances/ and read the timestamp.
Change configuration and apply it.
GET /api/v1/appliances/ and observe the changed timestamp.
Query the same endpoint (in a minute or so) and observe the second change.

If you have several groups with different configurations, use this query to list them:

GET /api/v1/config-group/list/

Lists configuration groups.

Query Parameters:

page (integer) – response page (if the contents are too large for a single response)
page_size (integer) – number of results to return per page

If necessary, remove a group:

DELETE /api/v1/config-group/delete/(name)/

Removes a group.

Parameters:

name – name of the group to remove

Here’s a list of curl commands corresponding to the steps above:

# Add --insecure before the URL if you are using a self-signed SSL certificate

curl -X POST https://{server}/api/v1/config-group/create/
     -H 'Authorization: Token <token>'
     -H 'Content-Type: application/json'
     -d '{"name":"TestGroup1"}'

curl -X PATCH https://{server}/api/v1/config-group/save/TestGroup1/
     -H 'Authorization: Token <token>'
     -H 'Content-Type: application/json'
     -d '{"appliances":["Test"]}'

curl -X PATCH https://{server}/api/v1/config-group/save/TestGroup1/
     -H 'Authorization: Token <token>'
     -H 'Content-Type: application/json'
     -d '{"content":
           {
             "cloud__enabled":true,
             "cloud__url":"https://appliance-api.reversinglabs.com",
             "cloud__user":"Test",
             "cloud__token":"Test",
             "cloud__timeout":60,
             "cloud__proxy_enabled":false,
             "cloud__proxy_host":"",
             "cloud__proxy_port":null,
             "cloud__proxy_user":"",
             "cloud__proxy_password":"",
             "cloud__max_fetch_file_size":500
           }
         }'

curl -X PATCH https://{server}/api/v1/config-group/update/TestGroup1/
     -H 'Authorization: Token <token>'
     -H 'Content-Type: application/json'
     -d '{"applyconfiguration":["Test"]}'

Hub groups

New in version 3.4.

A special case of configuration groups is using Hub groups. These are just like regular configuration groups, but you can also create and manage Hubs, including all the functionalities that they offer. The prerequisite for the following actions is adding at least one Hub using POST /api/v1/appliances/create/ (you can’t have a Hub group without a Hub).

The first step is to create a Hub group and add all Hub-only configuration options. These settings cannot be changed in a later request and must be set when creating the Hub group.

POST /api/v1/tiscale-hub-group/create/

Creates a Hub group.

Required fields:

Request JSON Object:

name (string) – name of the Hub group
primary_router_id (string) – ID for the primary Hub (arbitrary string)
primary_host (string) – name (not URL) of the primary Hub
primary_priority (integer) – priority order (primary Hub must be higher than secondary)

Optional fields (required if using more than one Hub):

Request JSON Object:

fallback_router_id (string) – ID of the redundant Hub
fallback_host (string) – name (not URL) of the redundant Hub
fallback_priority (integer) – priority order (redundant Hub must be lower than primary)
vrrp_enabled (boolean) – enable/disable sharing a virtual IP address
virtual_router_id (integer) – ID of the virtual Hub
auth_pass (string) – VRRP authentication password
different_networks (boolean) – whether the Hubs are inside different networks
virtual_ipaddress (string) – virtual Hub IP address
api_worker_token (string) – token for file analysis requests to Workers
srv_available_worker_token (string) – token for checking Worker availability
srv_worker_token (string) – token for checking Workers’ operational stats

After creating a Hub group, the next step is to save and apply its configuration. The steps are the same as for regular configuration groups, and the only difference is the endpoint. Hub-only parameters (i.e. those relating exclusively to Hub groups, and not regular configuration groups) must be set upon Hub group creation.

PUT /api/v1/tiscale-hub-group/save/(name)/: Save Hub group configuration. The parameters are the same as in PUT /api/v1/config-group/content/(name)/.

PATCH /api/v1/tiscale-hub-group/update/(name)/

Applies the configuration set in the previous step (equivalent to PUT /api/v1/config-group/update/(name)/.

Parameters:

name (string) – name of the configuration group

Request JSON Object:

applyconfiguration (array) – list of appliances in the group

The rest of the configuration steps (verifying, checking the timestamp etc.) are described in the chapter on Standard configuration groups.

Individual configuration: Spectra Analyze

New in version 5.0.

It is also possible to configure only individual Spectra Analyze appliances (instead of through groups).

PUT /api/v1/appliances/content/(appliance_id)/save/

Saves the entire configuration (but doesn’t yet apply it).

Parameters:

appliance_id (string) – ID of the appliance

There are many configurable fields that you can send (the full list is in the reference on the Manager). Some examples:

Request JSON Object:

systemalerting__syslog_enable (boolean) – enable/disable sending alerts to syslog
backup__purge_schedule (string) – how often to purge the appliance
tcbase__allowed_hosts (string) – what are the allowed hosts that Spectra Analyze will respond to

While the request above uses PUT, it is also possible to use PATCH. All the parameters are the same, and the only difference is that PATCH allows partial saving (and PUT always replaces the entire configuration).

After saving the configuration, you once again must apply it:

POST /api/v1/appliances/content/(appliance_id)/apply/: Applies the uploaded configuration to Spectra Analyze.