Skip to main content
Version: Spectra Detect 5.2.1

Management API

tip

This is a companion guide for the Manager's API endpoints. For a full reference, including the OpenAPI specification, see the Manager API reference (available in the help menu on the Manager appliance).

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
  6. Configure connectors
tip

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

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

Find out the backup status​

GET /api/v1/backup/

Returns the current backup status and availability.

Response:

{
  "status": "error",
  "message": "idle", // when the message is 'idle', the backup is ready
  "backup_filename": "example"
}

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/

Path parameters:

  • id – user ID

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 body:

{
  "username": "string",
  "email": "user@example.com",
  "first_name": "string",
  "last_name": "string",
  "password": "string"
}

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.

Path 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 body:

{
  "base_url": "string", 
  "allowed_hosts": "string", // allowlisted IP addresses or URLs, separated by a newline (`\n`) character
  "certificate_path": "string",
  "certificate_key_path": "string",
  "reset_ssl": true
}

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 body:

{
  "enable": true,
  "servers": "string" // must be separated by a newline (`\n`) character
}

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/system/config/sshd/

New in version 3.4.

Sends the SSH configuration to the appliance.

Request body:

{
  "banner_content": "string",
  "macs": "string",
  "ciphers": "string",
  "kexalgorithms": "string",
  "authorized_keys_file": "string",
  "client_alive_interval": "string",
  "client_alive_count_max": "string",
  "permit_root_login": "yes"
}

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.

Example request body:

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

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:

{
  "filename": "string",
  "sha1": "string",
  "version": "string", // version introduced by the update
  "requires": "string", // required version to use this update file
  "time": "2019-08-24T14:15:22Z" // build time
}

Then update the Manager to the latest available version:

POST /api/v1/update/latest/

Starts Manager upgrade.

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 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/v1/license/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.

Example 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:

  • file – license file

Example request:

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

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 body:

{
  "enable": true,
  "community": "string",
  "trap_sink_enable": true, // enable sending traps
  "trap_community": "string", // community string for traps
  "trap_sink": "string", // trap receiver address
// 👇 The Manager sends a trap when this value is exceeded 
// (percentage of used CPU threads over 1, 5 and 15 minutes)
  "trap_avg_load_threshold_1min": 1, 
  "trap_avg_load_threshold_5min": 1, 
  "trap_avg_load_threshold_15min": 1,
  "trap_memory_threshold": 1, // percentage of used memory
  "trap_disk_threshold": 1 // percentage of used disk
}
POST /api/v1/config/smtp/

New in version 3.4.

Sends SMTP configuration to the Manager.

Request body:

{
  "host": "string", // SMTP relay server
  "port": 65535,
  "user": "",
  "password": "",
  "password_set": false,
  "use_tls": false,
  "default_from_email": "user@example.com"
}
POST /api/v1/config/systemalerting/

New in version 3.4.

Sends configuration for syslog usage to the Manager.

Request body:

{
  "syslog_enable": true,
  "syslog_host": "string",
  "syslog_port": 65535,
  "syslog_transport_protocol": "TCP",
  "syslog_enable_audit_logs": true
}
POST /api/v1/config/central_logging/

New in version 3.4.

Configures central logging on the Manager.

Request body:

{
  "central_logging__enable": true,
  "central_logging__retention_period": 1, // in days
  "central_file_storage__enable": true,
  "central_file_storage__ttl": 1, // how long to keep files on the Manager (in hours)
  "central_file_storage__file_size_limit": 1, // in MiB
  "central_storage_general__min_free_space": 10, // in GiB
}

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 body:

{
  "yararulesets_enable": true
}

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 body:

{
  "local_ip": "192.168.0.1", // IP address of the primary Manager
  "remote_ip": "192.168.0.1", // 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": "192.168.0.1", // shared IP address to access the Manager when in redundant mode
  "failover_timeout": 3 // seconds between the unavailability of the primary and activation of the redundant Manager
}

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.

Request body:

{
  "values": {
    "local_ip": "string", // primary Manager IP address
    "remote_ip": "string", // secondary Manager IP address
    "remote_url": "string", // secondary Manager URL
    "user": "string", // admin
    "pwd": "string" // admin password
  }
}

Finally, verify that redundancy works:

POST /api/v1/cluster/verify/

Performs checks between appliances.

Request body:

{
  "remote_ip": "192.168.0.1", // IP address of the secondary Manager
  "section": "ssh" // aspect of redundancy to check (can be `ssh` or `versions`)
}

Response:

{
  "return_code": 0, // HTTP response status code
  "message": "string", // request-related message
  "messages": [
    "string" // messages related to redundancy
  ],
  "reduser_ssh_connect": true, // is SSH connectivity established?
  "postgres_ssh_connect": true, // is the redundant database accessible?
  "rld_ssh_tunnel_connect": true, // can an SSH tunnel be established?
  "version_local": 0, // version of the primary Manager
  "version_remote": 0 // 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 body:

{
  "name": "string",
  "type": "a1000", // possible values: a1000, tiscale-worker, tiscale-hub
  "url": "http://example.com",
  "snmp_community": "string",
  "haproxy_password": "string" // load balancer password (Hub)
}

The appliance type accepts legacy names for the products:

  • a1000 is Spectra Analyze
  • tiscale-worker is Spectra Detect Worker
  • tiscale-hub is Spectra Detect Hub

The response object format is the same as the request object.

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.

Path parameters:

  • id – ID of the appliance

Spectra Analyze​

PUT /api/v1/appliances/{id}/authorization/

New in version 4.1.

Path parameters:

  • id – ID of the appliance

Request body:

{
  "token": "string"
}

Update appliances​

Get the list of available upgrades:

GET /api/v1/package-management/

Returns the list of available update binaries for connected appliances.

Response body:

{
  "bins": [
    {
      "type": "string",
      "version": "string"
    }
  ],
  "used_space": 0, // how much space is used up on the appliance
  "allowed_space": 0, // how much space is left on the appliance
  "is_ticloud_data_available": true // is Spectra Intelligence data on upgrade binaries available
}

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.

Path parameters:

  • appliance_type – what type of appliance?
    • a1000 stands for Spectra Analyze
    • c1000 stands for Spectra Detect Manager
    • tiscale-hub stands for Spectra Detect Hub
    • tiscale-worker stands for Spectra Detect Worker
  • version – version of the appliance

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 body:

{
  "appliance_name": "string"
}

You can check the upgrade status at any point:

POST /api/upgrade/status/

Request body:

{
  "appliance_name": "string"
}

Response:

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

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.

Path parameters:

  • id – ID of the appliance

Form parameters:

  • file – certificate file

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.

In the response, the structure of the fields in the results array is as follows:

{
  "id": 0,
  "appliance_name": "string",
  "type": "a1000",
  "release": "string",
  "cluster": "string", // "standalone" if not in a group
  "state": "string", // whether primary or secondary
  "appliance_hostname": "string"
}

...and licensing status:

GET /api/v1/appliances/licensing/

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

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:

{
  "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

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 body:

{
  "name": "string"
}

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.

PATCH /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.

Path parameters:

  • name – name of the configuration group

Request body:

{
  "content": { 
    "snmp__enable": true,
    "snmp__community": "^$",
    "snmp__trap_sink_enable": true,
    "snmp__trap_community": "^$"
    // ...

Check that the configuration is correct:

GET /api/v1/config-group/retrieve/{name}/

Returns the configuration for the group.

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

Path parameters:

  • name – name of the configuration group

Request body:

{
  "applyconfiguration": [
    "string" // 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.

{
  "id": 0,
  "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  "ip": "string",
  "status": "string",
  "authorized": true,
  "online": true,
  "latency": 0.1,
  "maintenance": true,
  "last_seen_online": "2019-08-24T14:15:22Z",
  "system_data": {},
  "haproxy_password": "string",
  "created": "2019-08-24T14:15:22Z",
  "updated": "2019-08-24T14:15:22Z",
  "group_name": "string",
  "redundancy_status": "string",
  "configured_redundancy_status": "string",
  "redundant_with": "string",
  "connected_workers": [],
  "application_url": "string",
  "available_update_version": "string",
  "has_update_log_endpoint": true,
  "last_applied_config_timestamp": "2019-08-24T14:15:22Z",
  "configuration_status": "changes_awaiting_apply", // check this field
  "configuration_status_details": {}
}

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

The possible values are:

  • changes_awaiting_apply
  • pending
  • error
  • done
  • mismatch
  • unsupported
  • no_configuration_group

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 – response page (if the contents are too large for a single response)
  • page_size – number of results to return per page

If necessary, remove a group:

DELETE /api/v1/config-group/delete/{name}/

Removes a group.

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

Request body:

{
  "name": "string", // name of the Hub group
  "primary_router_id": "string", // ID for the primary Hub (arbitrary string)
  "primary_host": "string", // name, not URL
  "fallback_router_id": "string", // also arbitrary string
  "fallback_host": "string", // name, not URL
  "vrrp_enabled": false, // enable/disable sharing a virtual IP address
  "virtual_router_id": 1, // ID of the virtual Hub
  "auth_pass": "string", // VRRP authentication password
  "different_networks": true, // whether the Hubs are inside different networks
  "virtual_ipaddress": "string", // virtual Hub IP address
  "api_worker_token": "string", // file analysis token
  "srv_available_worker_token": "string", // service availability check token
  "srv_worker_token": "string", // operational stats token
}

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}/.

Path parameters:

  • name – name of the configuration group

Request body:

{
  "appliances": [
    "string" // list of appliances in the group
  ],
  "content": {} 
}

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

Path parameters:

  • appliance_id – ID of the appliance

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

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.

Configure connectors​

Enable connector​

To enable a connector for a specific appliance, use the following endpoint. This action is supported only for appliances of type "Hub".

POST /api/v1/appliances/{id}/connectors/{connector_name}/

Path parameters:

  • id: The appliance ID, which must be a string of digits (e.g., 123).
  • connector_name: The name of the connector to enable. Must be one of the following:
    • abusebox
    • azure-data-lake
    • fileshare
    • graph-api
    • s3
    • share-file
    • smtp

Get connector configuration​

To retrieve the configuration for a specific connector of an appliance, use the following endpoint. This action is supported only for appliances of type "Hub".

GET /api/v1/appliances/{id}/connectors/{connector_name}/v1/config/

Path parameters:

  • id: The appliance ID, which must be a string of digits (e.g., 123).
  • connector_name: The name of the connector whose configuration should be returned. Must be one of the following:
    • abusebox
    • azure-data-lake
    • fileshare
    • graph-api
    • s3
    • share-file
    • smtp

For a complete list of available configuration options, response fields, and examples for each connector service, refer to the API Reference Guide on the Manager.

Configure connector​

To configure a specific connector for an appliance, use the following endpoint. This action is supported only for appliances of type "Hub".

POST /api/v1/appliances/{id}/connectors/{connector_name}/v1/config/

Path parameters:

  • id: The appliance ID, which must be a string of digits (e.g., 123).
  • connector_name: The name of the connector that should be configured. Must be one of the following:

    • abusebox

    • azure-data-lake

    • fileshare

    • graph-api

    • s3

    • share-file

    • smtp

Request body​

For a complete list of available configuration options, response fields, and examples for each connector service, refer to the API Reference Guide on the Manager.