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:

  1. Obtain an authorization token

  2. Back up and restore the Manager

  3. Set up the Manager

  4. Connect appliances to the Manager

  5. 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:

  1. Create a backup file

  2. Find out the backup status

  3. Download backup file

  4. 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:

  1. Set up authentication:

    1. (Get authorization token - already covered in the previous section)

    2. Change admin password

  2. Configure network settings:

    1. Upload SSL certificate

    2. Configure the application URL

    3. List the allowed hosts

    4. Set network time sync

  3. Configure user authentication

    1. Federated login

    2. SSH access

  4. Configure Spectra Intelligence

  5. Update the Manager

  6. License the Manager

  7. Set up logging and alerting

    1. SNMP

    2. SMTP

    3. System alerting

    4. Central logging

  8. 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:
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:

  1. Add appliances to the Manager

  2. Authorize appliances

  3. Update appliances

  4. Upload SSL certificate to appliances

  5. 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:

  1. GET /api/v1/appliances/ and read the timestamp.

  2. Change configuration and apply it.

  3. GET /api/v1/appliances/ and observe the changed timestamp.

  4. 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.