v. 7.

TSOC API Developer's Guide

TrapX® Security, January 2022

trapx.com
 Contents

Contents
Preface ......................................................................................... 3
Introducing the TSOC API .......................................................... 4
API Overview ............................................................................... 5
API Call and Response Structures ......................................................................5
Handling Asynchronous Calls .............................................................................5

Using the API: High-Level Tasks................................................ 9

Working with Security Events ..............................................................................9
Excepting (Whitelisting) Events .........................................................................11
Working with DeceptionGrid Appliances ..........................................................12
Working with Network Interfaces for Traps ......................................................14
Working with Emulation Traps ...........................................................................16
Customizing Emulation Types ...........................................................................17
Working with Deception Tokens ........................................................................18
Working with Full OS Linux................................................................................18

API Call Reference .................................................................... 20

appliance/ Calls ...................................................................................................20
asset/ Calls ..........................................................................................................26
async/ Calls .........................................................................................................30
events/ Calls ........................................................................................................34
exception/ Calls...................................................................................................40
fosl/ Calls .............................................................................................................44
general/ Calls ......................................................................................................46
interface/ Calls ....................................................................................................49
mwtrap/ Calls ......................................................................................................54
system/ Calls .......................................................................................................65
versions/ Calls.....................................................................................................66
spindata/ Calls.....................................................................................................68
tokens/ Calls........................................................................................................71

DeceptionGrid TSOC API Developer's Guide, © TrapX 2

 Preface

Preface
This Developer's Guide is about developing client scripts directly using TrapX DeceptionGrid
TSOC's REST API.
As alternatives to directly using the API, TrapX provides various CLI and SDK options that are
recommended in most cases. See the separate DeceptionGrid CLI / SDK Developer's Guide.
For general background information on DeceptionGrid's architecture and functionality, see
the DeceptionGrid Administration Guide and the DeceptionGrid Security Deployment Guide.

DeceptionGrid TSOC API Developer's Guide, © TrapX 3

 Introducing the TSOC API

Introducing the TSOC API

TSOC's REST API enables developing client scripts for integrating DeceptionGrid with
organizational orchestration and security analysis systems.
The TrapX Security Operations Console (TSOC) is DeceptionGrid's central management
component. It manages DeceptionGrid Appliances, which host emulation traps on their
network interfaces; and it also manages Full OS Traps. The API enables programmatically
performing many of TSOC's functions, as a scalable, automatable alternative to using TSOC's
web interface. In general, the current version of the API enables the following types of
integration:

• Provisioning orchestration: Manage DeceptionGrid Appliances, and configure

Appliances' interfaces and traps.
• Security Analysis: Retrieve recorded security event details and associated files, for
use in organizational security analysis systems.

DeceptionGrid TSOC API Developer's Guide, © TrapX 4

 API Overview

API Overview
The following topics describe the general basic workings of the TSOC REST API.

In This Section
API Call and Response Structures.......................................................5
Handling Asynchronous Calls .............................................................5

API Call and Response Structures

TSOC accepts REST API calls at the same address and port as for its web interface (UI). To this
address, append
/api/v<version>/<resource>
where <version> is the API version, and <resource> defines the call. For example:
https://192.168.10.10:8443/api/v1.5/mwtrap/create
Generally, the <resource> part of call URLs designates the kind of task being requested;
individual objects are designated in request payloads.
All tasks are performed with HTTP POST calls, even when the task is information retrieval.
The API accepts only HTTP POST calls.
Request payloads and responses are all in JSON format.
Every API call must include, in its payload, TSOC's API key (see the DeceptionGrid
Administration Guide), in an api_key field. For example:
$ curl -k -s -S \
> https://192.168.10.10:8443/api/v1.5/mwtrap/create \
> -d '{"api_key":"1234567890", \
...
> }'
All responses include standard HTTP status codes, including error codes. In addition, some
responses may include api_status (boolean, indicating task success) and/or
api_message fields. Client scripts should check all of these. These response elements are
not listed in per-call documentation topics (see API Call Reference on page 20).
All calls and responses are secured by HTTPS. TSOC does not accept unsecured HTTP calls.

Handling Asynchronous Calls

Most calls are blocking, meaning that the response will be sent only after the requested task
has been performed. However, some calls, marked in the reference (see API Call Reference
on page 20) as such, are asynchronous, meaning an initial response is sent immediately. A
subsequent call can query for the task's status.

DeceptionGrid TSOC API Developer's Guide, © TrapX 5

 API Overview

To enable continuity between calls related to a task, the response to the initial call includes a
request_id, to be specified in status queries. All subsequent responses to status queries
also include the request_id.
To query for status, call async/status (see async/status on page 32) and in the payload specify
the request_id . Alternatively, to cancel the task, call async/cancel (see async/cancel on
page 31) and in the payload specify the request_id .
All responses to initial asynchronous calls, to status queries, and to task cancellation specify
the task's status, with one of the following values:

• started
• in progress
• failed
• succeeded
• cancelled
The response also includes a detailed log .
The following are examples of an initial asynchronous call, subsequent status query, and
finally cancellation.

Initial asynchronous call

$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/appliance/initialize \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Grumpy", \
> "email":"ciso@corporate.net", \
> "timezone":"America/New_York"}}'

Response
<<HTTP status code: 202 Accepted>>
{
"request_id" : "ffEb4726-e751-3260-20ad-0372961f36a4",
"status" : "started",
"log" : [
{
"timestamp" : "2018-01-16T12:54:17.21Z",
"level" : "INFO",
"message" : "initializing appliance Dwarves:Grumpy"
}
]
DeceptionGrid TSOC API Developer's Guide, © TrapX 6
 API Overview

Status query
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/async/status \
> -d '{"api_key":"…", \
> "request_id":"ffEb4726-e751-3260-20ad-0372961f36a4"}'

Response
<<HTTP status code: 200 OK>>
{
"request_id" : "ffEb4726-e751-3260-20ad-0372961f36a4",
"status" : "in progress",
"log" : [
{
"timestamp" : "2018-01-16T12:54:17.21Z",
"level" : "INFO",
"message" : "initializing appliance Dwarves:Grumpy"
},
{
"timestamp" : "2018-01-16T12:54:18.13Z",
"level" : "INFO",
"message" : "created databases for appliance Dwarves:Grumpy"
},
{
"timestamp" : "2018-01-16T12:54:18.16Z",
"level" : "INFO",
"message" : "sent DB credentials to appliance Dwarves:Grumpy"
}
]
}

Task cancellation
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/async/cancel \
> -d '{"api_key":"…", \

DeceptionGrid TSOC API Developer's Guide, © TrapX 7

 API Overview

> "request_id":"ffEb4726-e751-3260-20ad-0372961f36a4"}'

Response
<<HTTP status code: 200 OK>>
{
"request_id" : "ffEb4726-e751-3260-20ad-0372961f36a4",
"status" : "cancelled",
"log" : [
{
"timestamp" : "2018-01-16T12:54:17.21Z",
"level" : "INFO",
"message" : "initializing appliance Dwarves:Grumpy"
},
{
"timestamp" : "2018-01-16T12:54:18.13Z",
"level" : "INFO",
"message" : "created databases for appliance Dwarves:Grumpy"
},
{
"timestamp" : "2018-01-16T12:54:18.16Z",
"level" : "INFO",
"message" : "sent DB credentials to Dwarves:Grumpy"
},
{
"timestamp" : "2018-01-16T12:54:18.53Z",
"level" : "INFO",
"message" :
"request cancelled, aborting initialization of Dwarves:Grumpy"
}
]
}

DeceptionGrid TSOC API Developer's Guide, © TrapX 8

 Using the API: High-Level Tasks

Using the API: High-Level Tasks

The following topics provide high-level workflows for working with the TSOC API.

In This Section
Working with Security Events ............................................................9
Excepting (Whitelisting) Events ........................................................11
Working with DeceptionGrid Appliances .........................................12
Working with Network Interfaces for Traps ....................................14
Working with Emulation Traps .........................................................16
Customizing Emulation Types ..........................................................17
Working with Deception Tokens ......................................................18
Working with Full OS Linux...............................................................18

Working with Security Events

For integration with organizational security analysis systems, you can retrieve recorded
security events and their associated files. You can also delete events from TSOC.
For working with event retrieval, follow this high-level workflow:

1. Search: Using events/search (see events/search on page 36), request events that
match a specified event filter (a set of specified event criteria), in a specified
format (JSON or STIX2 ).
The response includes the number of matching events, those events' details, and a
search_id for subsequent reference.
If there are more than the maximum per-page number of events (by default: 100;
customizable in the TSOC Administration menu - see the DeceptionGrid
Administration Guide), they are divided among 'pages' of up to that number of
events. In this case, the response specifies the number of such pages. The response
also includes the first page's events.

DeceptionGrid TSOC API Developer's Guide, © TrapX 9

 Using the API: High-Level Tasks

Provided events include all event details, and indicate whether or not the event has
associated files; but do not include those files themselves. The existence of
associated packet capture (PCAP) files (or not) is indicated by boolean
x_trapx_com_pcap ; of associated binary files - by boolean
x_trapx_com_binary .
2. Show: If the initial search response indicated pagination, use events/show (see
events/show on page 39) with the search_id to request the events of a specified
page.
The response includes the number of provided events, and those events' details.
3. Download: If an event's details indicated that it has associated PCAP and/or binary
files, use events/download (see events/download on page 36) to request the files of
a specified file type (pcap or binary ), of a specified event (by its identifier as
received in event x_trapx_com_eventid ).
The response includes a binary blob base64 representation of the requested file. In
the case of binary, the file is a ZIP archive containing all associated binaries
(archived even if only a single file), encrypted with password: MALICIOUS.
4. Cancel: When the paginated search results are no longer needed, use events/cancel
(see events/cancel on page 34) with the search_id to release cached results,
freeing TSOC resources.
If not canceled, the results will be retained until an hour after the initial search.

To delete security events from TSOC, use events/delete (see events/delete on page 34).
The following is an example of an initial search for events, subsequent retrieval of following
event pages, and finally release of cached results.
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/events/search \
> -d '{"api_key":"…","filter":{…}}'
<<HTTP status code: 200 OK>>
{
"search_id" : "...",
"number_of_events" : 945,
"page_size" : 100,
"number_of_pages" : 10,
"page" : 1,
"events" : [ {...}, ..., {...} ]
}
$ for i in $(seq 2 10); do \
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/events/show \
DeceptionGrid TSOC API Developer's Guide, © TrapX 10
 Using the API: High-Level Tasks

> -d '{"api_key":"…","search_id":"…","page":'$i'}'; \
> done
<<HTTP status code: 200 OK>>
{
"search_id" : "...",
"number_of_events" : 12345,
"page_size" : 100,
"number_of_pages" : 124,
"page" : 2,
"events" : [ {...}, ..., {...} ]
}
...
<<HTTP status code: 200 OK>>
{
"search_id" : "...",
"number_of_events" : 12345,
"page_size" : 100,
"number_of_pages" : 124,
"page" : 10,
"events" : [ {...}, ..., {...} ]
}
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/events/cancel \
> -d '{"api_key":"…","search_id":"…"}'
<<HTTP status code: 200 OK>>
{ "api_status": true }

Excepting (Whitelisting) Events

You can manage event exceptions.
Exception configuration objects include different fields depending on whether the trap type
is Emulation, NIS, or Full OS. You can request templates (see exception/templates on page 42)
of these objects, populate their fields and then submit them to define an actual exception (see
exception/create on page 40).
You can request a list (see exception/list on page 41) of an Appliance's configured exceptions.
The returned exceptions have an non-displayed Filter ID field, which is used in

DeceptionGrid TSOC API Developer's Guide, © TrapX 11

 Using the API: High-Level Tasks

subsequent actions to change the exception (see exception/replace on page 43) or to remove
it (see exception/remove on page 42).

Working with DeceptionGrid Appliances

You can manage DeceptionGrid Appliance initialization to TSOC, and can obtain Appliance
information to use for managing networking (see Working with Network Interfaces for Traps
on page 14).
In API calls, a DeceptionGrid Appliance is defined by the combination of its group ID (gid) and
its own unique ID (uid). These were defined during Appliance post-installation setup, and
appear in TSOC's web interface. For example,
"gid":"Wilds","uid":"WildTest220", defines this Appliance:

For some purposes, Full OS traps are treated like Appliances. For Full OS traps, the trap name
is used for both gid and uid .
You can perform the following tasks with Appliances:

• List existing Appliances and Full OS traps and their details, using appliance/list (see
appliance/list on page 22) . Optionally, filter by initialization state (pending /
initializing / established ), or specify one or more already-known
Appliances to discover their details.
Provided details include gid, uid, department, architecture (for
example: FullOS Windows x64), software version, whether it is
connected, and initialization state.
• Obtain the software version and architecture of one or more specified Appliances,
using appliance/version (see appliance/version on page 24) .
• Initialize: Use appliance/initialize (see appliance/initialize on page 20) (asynchronous)
to initialize a newly-installed and set up Appliance or Full OS trap to TSOC, including
configuring similar settings as when initializing from the TSOC web interface.
• Remove an Appliance or Full OS trap from TSOC, using appliance/remove (see
appliance/remove on page 25) .
The following is an example of listing all Appliances, initializing a pending Appliance, and
subsequently checking on the initialization status:
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/appliance/list \
> -d '{"api_key":"…","state":"all"}'
<<HTTP status code: 200 OK>>

DeceptionGrid TSOC API Developer's Guide, © TrapX 12

 Using the API: High-Level Tasks

[
{
"gid":"Dwarves","uid":"Happy",
"state":"established","connected":true,
"arch":"x86_64","version":"6.2.73",
"department":"Sales"
},
{
"gid":"Dwarves","uid":"Grumpy",
"state":"pending","connected":true,
"arch":"FullOS Windows x64","version":"1.2.89"
},
]
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/appliance/initialize \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Grumpy", \
> "email":"ciso@corporate.net", \
> "timezone":"America/New_York"}}'
<<HTTP status code: 202 Accepted>>
{
"request_id" : "ffEb4726-e751-3260-20ad-0372961f36a4",
"status" : "started",
"log" : [
{
"timestamp" : "2018-01-16T12:54:17.21Z",
"level" : "INFO",
"message" : "initializing appliance Dwarves:Grumpy"
}
]
}
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/async/status \
> -d '{"api_key":"…", \

DeceptionGrid TSOC API Developer's Guide, © TrapX 13

 Using the API: High-Level Tasks

> "request_id":"ffEb4726-e751-3260-20ad-0372961f36a4"}'
<<HTTP status code: 200 OK>>
{
"request_id" : "ffEb4726-e751-3260-20ad-0372961f36a4",
"status" : "in progress",
"log" : [
{
"timestamp" : "2018-01-16T12:54:17.21Z",
"level" : "INFO",
"message" : "initializing appliance Dwarves:Grumpy"
},
{
"timestamp" : "2018-01-16T12:54:18.13Z",
"level" : "INFO",
"message" : "created databases for appliance Dwarves:Grumpy"
},
{
"timestamp" : "2018-01-16T12:54:18.16Z",
"level" : "INFO",
"message" : "sent DB credentials to appliance Dwarves:Grumpy"
}
]
}

Working with Network Interfaces for Traps

You can manage the various types of network interfaces on DeceptionGrid Appliances (see
Working with DeceptionGrid Appliances on page 12).
Interfaces are defined per-Appliance by interface name . These names conform to the
following syntax, by interface type:

• Physical interface: The interface's name. For example:

eth2
• Subinterface (of a parent single-network static interface, usually only eth0):
<parent>:<ID>
For example:
eth0:3
When creating the subinterface, <ID> is any new ID number.
DeceptionGrid TSOC API Developer's Guide, © TrapX 14
 Using the API: High-Level Tasks

• VLAN (child interface of trunk-connected interface such as eth2):

vlan<VLAN-ID>
where <VLAN-ID> is the actual network VLAN's ID number. For example:
vlan13
• VLAN Alias (child interface of VLAN interface):
vlan<VLAN-ID>:<alias-ID>
where <VLAN-ID> is the parent's VLAN ID.
For example:
vlan13:52
When creating the VLAN Alias, <alias-ID> is any new ID number.

Interface properties include, as relevant, its type, parent, name as above, MAC address
(read-only), IP configuration (static/DHCP, address, netmask and gateway), and segment.
You can perform the following tasks with interfaces:

• Create a new virtual interface using interface/create (see interface/create on page

51) , including setting its configurable properties.
• Reconfigure an existing interface's changeable properties using interface/configure
(see interface/configure on page 49) .
• List existing interfaces and their properties, by specified Appliance, optionally for just
one or more of its specified interfaces, using interface/list (see interface/list on page
52) .
• Remove an interface, using interface/remove (see interface/remove on page 53) .
• Retrieve interface names by their trap names, using mwtrap/interface (see
mwtrap/interface on page 61) .
The following is an example of creating a series of VLAN interfaces:
$ for i in $(seq 91 99); do \
> curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/interface/create \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dopey"}, \
> "interface":{"name":"vlan'$i'", \
> "type":"vlan", \
> "parent":"eth2", \
> "configuration":"dhcp"}}'; \
> done
<<HTTP status code: 200 OK>>
{

DeceptionGrid TSOC API Developer's Guide, © TrapX 15

 Using the API: High-Level Tasks

"appliance":{"gid":"Dwarves","uid":"Dopey"},"api_status":true,
"interface":{"name":"vlan91","type":"vlan","parent":"eth2",
"mac_addr":"00:0c:29:13:80:91","configuration":"dhcp",
"address":"192.168.91.38","netmask":"255.255.255.0",
"gateway":"192.168.91.1"}
}
...
<<HTTP status code: 200 OK>>
{
"appliance":{"gid":"Dwarves","uid":"Dopey"},"api_status":true,
"interface":{"name":"vlan99","type":"vlan","parent":"eth2",
"mac_addr":"00:0c:29:13:80:99","configuration":"dhcp",
"address":"192.168.99.38","netmask":"255.255.255.0",
"gateway":"192.168.99.1"}
}

Working with Emulation Traps

You can manage emulation traps on configured interfaces (see Working with Network
Interfaces for Traps on page 14).
An interface can have a single emulation trap. The trap is defined primarily by the
interface name; for convenience and some management purposes, a trap also has a trap
name, which is stored and displayed by TSOC but not saved or recognized by Appliances. So,
trap creation, configuration, and removal use the interface name (not the trap name).
Trap details are defined in a configuration JSON object. This object includes the
interface name (which defines the trap) and emulation details such as emulation type
(operating_system_type ; for example, Windows_Server or VoIP Device), emulated
OS version, and emulated services and their configurations. This configuration object does not
include trap name and does not include spin data.
In general, creating a trap requires two main steps (1-2); you can do the second step in any
one of three ways (a-c):

DeceptionGrid TSOC API Developer's Guide, © TrapX 16

 Using the API: High-Level Tasks

1. Using mwtrap/create (see mwtrap/create on page 59) , enable a trap on a specified

interface and set the trap name (allocates a named TSOC database).
2. Configure the trap by providing a configuration object, in one of the ways described
below.
The fields and valid values of trap configuration objects vary according to emulation
type and possibly Appliance software version, and it is not recommended to try to
create them from scratch. Instead, do either of the following:
• (a) Using mwtrap/clone (see mwtrap/clone on page 59) , copy full configuration
(configuration object + spin data) between specified interfaces.
• Modify the values of an existing configuration object; then, using
mwtrap/configure (see mwtrap/configure on page 55) , apply the configuration
object to the trap.
You can obtain a configuration object for modification in either of the following
ways:
• (b) Using mwtrap/current (see mwtrap/current on page 60) , retrieve the
configuration of an existing configured trap.
• (c) TSOC can provide configuration templates for all supported (preconfigured
or custom) emulation types. Using mwtrap/supported (see
mwtrap/supported on page 63) , you can retrieve a list of emulation types
supported for a specified Appliance; using mwtrap/templates (see
mwtrap/templates on page 64) , you can retrieve a specified Appliance's
configuration templates, optionally for specified emulation types.
Configuration templates include default values, and some _options fields
that describe valid customization options, for informational purposes.
Configuration field values that are files (ZIP archives of custom web pages; SSL
certificate and key) must be base64 encoded.

To be able to subsequently upload spin data for a relevant service of an emulation trap, use
spindata/enable (see spindata/enable on page 69) to allow FTP access; spindata/disable (see
spindata/disable on page 68) to block FTP access; and spindata/status (see spindata/status on
page 70) to check current FTP status.
For informational and management purposes related to trap names, the following calls are
available:

• To list an Appliance's configured traps by trap names, use mwtrap/list (see

mwtrap/list on page 62)
• To find the interfaces on which are configured traps specified by their trap names,
use mwtrap/interface (see mwtrap/interface on page 61)
• To find trap names by specified interfaces, use mwtrap/trap (see mwtrap/trap on
page 65)
To remove a trap from an interface, use mwtrap/remove (see mwtrap/remove on page 62).

DeceptionGrid TSOC API Developer's Guide, © TrapX 17

 Using the API: High-Level Tasks

Customizing Emulation Types

You can customize emulation types, creating new emulation types as appropriate for your
organizational environment.
After you customize an emulation type, the customized emulation type becomes available at
trap creation from TSOC or from client scripts (see Working with Emulation Traps on page 16).
Using the TSOC API, you can base custom types on the existing types provided by TrapX, as
below. As an alternative, the TrapX SDK includes a tool for basing custom types on existing
organizational endpoints.
You can define custom emulation types with configuration templates that are similar to
regular trap configuration objects (see Working with Emulation Traps on page 16), with the
following differences:

• Templates for customization include a base_operating_system_type field,

which is set to an emulation type that defines basic emulation behavior, some of
which can be customized.
• Templates for customization include a customizable OS fingerprint field.
To obtain templates for customization, use mwtrap/custom_templates (see
mwtrap/custom_templates on page 58). Each provided template is for a different
base_operating_system_type, and all are initially have their
operating_system_type set to CUSTOM TYPE . Then, customize as follows:

• (Mandatory) change the operating_system_type to a descriptive name.

• Set the OS fingerprint to a relevant fingerprint label as defined in the Nmap database
(nmap-os-db).
• Set defaults and available options for OS version, hostname, domain, and enabled
services.
Note: In the current release, service default parameters configured here are not
available when creating traps from the TSOC web interface.

Make the customized emulation type available for trap creation by using
mwtrap/custom_create (see mwtrap/custom_create on page 56). To subsequently remove it,
use mwtrap/custom_delete (see mwtrap/custom_delete on page 57).

Working with Deception Tokens

You can manage Deception Token assignment to campaigns.
Tokens are identified by token ID number. You can retrieve traps' token details (see tokens/list
on page 74): per-trap token types and ID numbers. Specific token configuration is not
included.
Campaigns are identified by campaign name. You can retrieve existing campaigns (see
tokens/campaigns on page 72), including their existing assigned tokens.
To manage token assignment to campaigns, for any existing campaign you can add tokens (see
tokens/assign on page 71) or remove tokens (see tokens/delete on page 73).
DeceptionGrid TSOC API Developer's Guide, © TrapX 18
 Using the API: High-Level Tasks

Working with Full OS Linux

You can manage an Appliance's full OS Linux for high-interaction SSH.
You can enable the full OS Linux (with specified gateway) (see fosl/enable on page 45); you
can disable it (see fosl/disable on page 45), or query whether it is currently enabled (see
fosl/status on page 46).
You can revert it to its original state (see fosl/revert on page 46). You can manage its
credentials list by retrieving the current list (see fosl/current on page 44) or setting the list
(see fosl/configure on page 44).

DeceptionGrid TSOC API Developer's Guide, © TrapX 19

 API Call Reference

API Call Reference

The following API calls are available.

In This Section
appliance/ Calls ................................................................................20
asset/ Calls ........................................................................................26
async/ Calls .......................................................................................30
events/ Calls .....................................................................................34
exception/ Calls ................................................................................40
fosl/ Calls ..........................................................................................44
general/ Calls ....................................................................................46
interface/ Calls .................................................................................49
mwtrap/ Calls ...................................................................................54
system/ Calls.....................................................................................65
versions/ Calls...................................................................................66
spindata/ Calls ..................................................................................68
tokens/ Calls .....................................................................................71

appliance/ Calls
The following appliance/ API calls are available.

In This Section
appliance/initialize ...........................................................................20
appliance/list ....................................................................................22
appliance/version .............................................................................24
appliance/remove ............................................................................25

appliance/initialize

Description

Initialize a newly-installed and set up Appliance or Full OS trap to TSOC, including configuring
similar settings as when initializing from the TSOC web interface.

Note: Asynchronous (see Handling Asynchronous Calls on page 5)

Payload elements
api_key
appliance : JSON object including:

DeceptionGrid TSOC API Developer's Guide, © TrapX 20

 API Call Reference

• gid , uid : Appliance identifier (see Working with DeceptionGrid Appliances on page
12)
• department: The company or department (see general/departments on page 47)
to which to assign the Appliance
• email
• timezone (optional): The relevant time zone key name (see
general/supported_timezones on page 48). Default is UTC
• segment (optional)
• description (optional)
• VM infrastructure (for full OS trap): The trap's virtual infrastructure (see
general/vm_infrastructure on page 48)
• VM name (for full OS trap): The trap's name as defined at installation

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
Standard asynchronous task response elements (see Handling Asynchronous Calls on page 5)

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/appliance/initialize \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Grumpy", \
> "email":"ciso@corporate.net", \
> "timezone":"America/New_York"}}'
<<HTTP status code: 202 Accepted>>
{
"request_id" : "ffEb4726-e751-3260-20ad-0372961f36a4",
"status" : "started",
"log" : [
{
"timestamp" : "2018-01-16T12:54:17.21Z",
"level" : "INFO",
"message" : "initializing appliance Dwarves:Grumpy"
}
]
}

DeceptionGrid TSOC API Developer's Guide, © TrapX 21

 API Call Reference

$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/async/status \
> -d '{"api_key":"…", \
> "request_id":"ffEb4726-e751-3260-20ad-0372961f36a4"}'
<<HTTP status code: 200 OK>>
{
"request_id" : "ffEb4726-e751-3260-20ad-0372961f36a4",
"status" : "in progress",
"log" : [
{
"timestamp" : "2018-01-16T12:54:17.21Z",
"level" : "INFO",
"message" : "initializing appliance Dwarves:Grumpy"
},
{
"timestamp" : "2018-01-16T12:54:18.13Z",
"level" : "INFO",
"message" : "created databases for appliance Dwarves:Grumpy"
},
{
"timestamp" : "2018-01-16T12:54:18.16Z",
"level" : "INFO",
"message" : "sent DB credentials to appliance Dwarves:Grumpy"
}
]
}

appliance/list

Description

Request list and details of existing Appliances and Full OS traps (see Working with
DeceptionGrid Appliances on page 12).

Payload elements
api_key
One (not both) of:

DeceptionGrid TSOC API Developer's Guide, © TrapX 22

 API Call Reference

• state (default): Filter by state, one of:

• all (default)
• pending
• initializing
• established
• appliance : One or more (in array) Appliance JSON objects, each of which includes
the Appliance's gid and uid

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
List of Appliances, each including:
gid
uid
arch : The Appliance's architecture (for example: FullOS Windows x64)
version
department
connected (boolean): Whether the Appliance is online
state: One of:

• pending
• initializing
• established

Examples
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/appliance/list \
> -d '{"api_key":"…","state":"all"}'
<<HTTP status code: 200 OK>>
[
{
"gid":"Dwarves","uid":"Happy",
"state":"established","connected":true,
"arch":"x86_64","version":"6.2.73",
"department":"Sales"
},
{

DeceptionGrid TSOC API Developer's Guide, © TrapX 23

 API Call Reference

"gid":"Dwarves","uid":"Grumpy",
"state":"pending","connected":true,
"arch":"FullOS Windows x64","version":"1.2.89"
},
]

$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.0/appliance/list \
> -d '{"api_key":"…", \
> "appliance":[{"gid":"Dwarves","uid":"Grumpy"}, \
> {"gid":"Dwarves","uid":"Frumpy"}]}'
<<HTTP status code: 200 OK>>
[
{
"gid":"Dwarves","uid":"Grumpy",
"state":"pending","connected":true,
"arch":"FullOS Windows x64","version":"1.2.89"
},
{
"gid":"Dwarves","uid":"Frumpy",
"state":null,"connected":null,
"arch":null,"version":null
}
]

appliance/version

Description

Request the software architecture and version of one or more specified Appliances and Full
OS traps (see Working with DeceptionGrid Appliances on page 12).

Payload elements
api_key
appliance : One or more (in array) Appliance JSON objects, each of which includes the
Appliance's gid and uid

DeceptionGrid TSOC API Developer's Guide, © TrapX 24

 API Call Reference

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
List of Appliances, each including:
gid
uid
arch : The Appliance's architecture (for example: FullOS Windows x64)
version

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.0/appliance/version \
> -d '{"api_key":"…", \
> "appliance":[{"gid":"Dwarves","uid":"Happy"}, \
> {"gid":"Dwarves","uid":"Sneezy"}]}'
<<HTTP status code: 200 OK>>
[
{
"gid":"Dwarves","uid":"Happy",
"arch":"x86_64","version":"6.2.73"
},
{
"gid":"Dwarves","uid":"Sneezy",
"arch":"x86_64","version":"6.2.89"
}
]

appliance/remove

Description

Remove the Appliance from TSOC.

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid

DeceptionGrid TSOC API Developer's Guide, © TrapX 25

 API Call Reference

Response elements

Only standard response elements (see API Call and Response Structures on page 5)

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/appliance/remove \
> -d '{"api_key":"…",{"gid":"Dwarves","uid":"Dopey"}}'
<<HTTP status code: 200 OK>>
{ "gid":"Dwarves","uid":"Dopey","api_status":true }

asset/ Calls
The following asset/ API calls are available.

In This Section
asset/discovery .................................................................................26
asset/inventory ................................................................................27
asset/retrieve ...................................................................................29

asset/discovery

Description

Configure a specified Appliance's Asset Discovery settings, and/or check current settings.
For the call payload, all Asset Discovery settings are optional; only provided ones are changed.
To check current settings, provide only the appliance .

Note: Currently, setting Asset Discovery scheduling is possible only in the TSOC UI.

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid
enabled (boolean; optional): Whether Asset Discovery is enabled for the Appliance
scope (optional): One of:

• all
• Array of interface name s

Response

In addition to standard response elements (see API Call and Response Structures on page 5):
Current (updated) Asset Discovery settings

DeceptionGrid TSOC API Developer's Guide, © TrapX 26

 API Call Reference

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/asset/discovery \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Sneezy"}, \
> "scope":["vlan31","vlan32","vlan33","vlan34","vlan35"]}'
<<HTTP status code: 200 OK>>
{
"enabled": true,
"scope": ["vlan31","vlan32","vlan33","vlan34","vlan35"],
}

asset/inventory

Description

Provide an external inventory of endpoints, according to which trap emulation profiles can be
automatically set.
You can provide one of the following:

• A connection to the organizational Active Directory, from which TSOC will retrieve
endpoint information.
• A CSV list of endpoints. Each row represents an endpoint, and must include exactly
four fields:
• IP address: Enables TSOC to establish the endpoint's relevance to a given trap
• Hostname: Required only if IP address is not provided, in which case TSOC will
attempt to resolve the IP by Hostname
• Empty field (reserved for future development)
• OS
For example:
192.168.11.12,fubar,,Microsoft Windows Server 2012
192.168.12.13,snafu,,Linux 3.12 - 4.4
192.168.13.14,xyzzy,,Cisco Catalyst WS-C5000 switch
,johndoe-laptop,,Microsoft Windows 7

The inventory is global, for all Appliances.

Note: Only a single inventory is maintained; providing an inventory completely overwrites

any existing inventory.

DeceptionGrid TSOC API Developer's Guide, © TrapX 27

 API Call Reference

Payload elements
api_key
source : One of:

• AD
• upload
If source is AD :

• server : Active Directory IP address or resolvable hostname

• At least one of:
• port : If omitted, will use 389 if protocol is LDAP, or 636 if protocol is
LDAPS
• protocol : If omitted, will use LDAP if port is 389, or LDAPS if port is 636
• username and password : Credentials with read permissions for the Active
Directory
• schema : The Active Directory schema
If source is upload :

• inventory : CSV-formatted string, probably the contents of a provided file (see

Example below)

Response

Only standard response elements (see API Call and Response Structures on page 5)

Example (AD)
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/asset/inventory \
> -d '{"api_key":"…", \
> "source":"AD","server":"192.168.11.12","port":389 \
> "username":"readadmin", \
> "password":"ba1b2c544665b377b7f77d5e8295850c", \
> "schema":"…"}'
<<HTTP status code: 200 OK>>
{ "api_status": true }

Example (CSV upload)

$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/asset/inventory \
> -d '{"api_key":"…", \

DeceptionGrid TSOC API Developer's Guide, © TrapX 28

 API Call Reference

> "source":"upload", \
> "inventory":"'$(cat inventory.csv)'"}'
<<HTTP status code: 200 OK>>
{ "api_status": true }

asset/retrieve

Description

Retrieve Asset Discovery results, for the specified interface of a specified Appliance.

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid
interface : Name of interface whose Asset Discovery results to retrieve

Response

In addition to standard response elements (see API Call and Response Structures on page 5):
appliance : As in request
interface : As in request
trap : Name of interface's emulation trap
enabled (boolean): Whether Asset Discovery is currently enabled for this interface. If true:

• last_scan : Timestamp of last discovery (if never run yet - null, and following
elements not provided)
• results : List of JSON dictionaries for found assets, each including (similar to CSV
download from TSOC Asset Discovery):
• address : Asset's IP address
• hostname : Corresponding hostname, if resolved
• category
• fingerprint : OS fingerprint as defined in the Nmap database
• confidence : Confidence in fingerprint detection, in percent

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/asset/retrieve \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Sneezy"}, \

DeceptionGrid TSOC API Developer's Guide, © TrapX 29

 API Call Reference

> "interface":"vlan99"}'
<<HTTP status code: 200 OK>>
{
"appliance": {"gid":"Dwarves","uid":"Sneezy}
"interface": "vlan99",
"enabled": true,
"trap": "Production3",
"last_scan": "2018-11-04T21:03:54.13-05:00",
"results": [
{
"address": "172.16.99.10",
"category": "Cisco Device",
"fingerprint": "Cisco Catalyst 2960 or 3600 switch (IOS 12.3)"
},
...
{
"address": "172.16.99.34",
"category": "ESXi",
"fingerprint": "VMware ESXi 6.0.0",
"confidence": 96.6
},
...
{
"address": "172.16.99.137",
"category": "Windows Station",
"fingerprint": "Microsoft Windows 7",
"confidence": 82.7
}
]
}

async/ Calls
The following async/ API calls are available.

DeceptionGrid TSOC API Developer's Guide, © TrapX 30

 API Call Reference

In This Section
async/cancel .....................................................................................31
async/status......................................................................................32

async/cancel

Description

Cancel a previously-called asynchronous task, by the task's request-id .

Part of workflow for handling asychronous calls (see Handling Asynchronous Calls on page 5).

Payload elements
api_key
request_id

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
request_id
status : One of

• started
• in progress
• failed
• succeeded
• cancelled
log

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/async/cancel \
> -d '{"api_key":"…", \
> "request_id":"ffEb4726-e751-3260-20ad-0372961f36a4"}'
<<HTTP status code: 200 OK>>
{
"request_id" : "ffEb4726-e751-3260-20ad-0372961f36a4",
"status" : "cancelled",
"log" : [
{
"timestamp" : "2018-01-16T12:54:17.21Z",

DeceptionGrid TSOC API Developer's Guide, © TrapX 31

 API Call Reference

"level" : "INFO",
"message" : "initializing appliance Dwarves:Grumpy"
},
{
"timestamp" : "2018-01-16T12:54:18.13Z",
"level" : "INFO",
"message" : "created databases for appliance Dwarves:Grumpy"
},
{
"timestamp" : "2018-01-16T12:54:18.16Z",
"level" : "INFO",
"message" : "sent DB credentials to Dwarves:Grumpy"
},
{
"timestamp" : "2018-01-16T12:54:18.53Z",
"level" : "INFO",
"message" :
"request cancelled, aborting initialization of Dwarves:Grumpy"
}
]
}

async/status

Description

Query for the status of a previously-called asynchronous task, by the task's request-id .
Part of workflow for handling asychronous calls (see Handling Asynchronous Calls on page 5).

Payload elements
api_key
request_id

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
request_id
status : One of

DeceptionGrid TSOC API Developer's Guide, © TrapX 32

 API Call Reference

• started
• in progress
• failed
• succeeded
• cancelled
log

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/async/status \
> -d '{"api_key":"…", \
> "request_id":"ffEb4726-e751-3260-20ad-0372961f36a4"}'
<<HTTP status code: 200 OK>>
{
"request_id" : "ffEb4726-e751-3260-20ad-0372961f36a4",
"status" : "in progress",
"log" : [
{
"timestamp" : "2018-01-16T12:54:17.21Z",
"level" : "INFO",
"message" : "initializing appliance Dwarves:Grumpy"
},
{
"timestamp" : "2018-01-16T12:54:18.13Z",
"level" : "INFO",
"message" : "created databases for appliance Dwarves:Grumpy"
},
{
"timestamp" : "2018-01-16T12:54:18.16Z",
"level" : "INFO",
"message" : "sent DB credentials to appliance Dwarves:Grumpy"
}
]
}

DeceptionGrid TSOC API Developer's Guide, © TrapX 33

 API Call Reference

events/ Calls
The following events/ API calls are available.

In This Section
events/cancel ...................................................................................34
events/delete ...................................................................................34
events/download .............................................................................36
events/search ...................................................................................36
events/show .....................................................................................39

events/cancel

Description

Release cached security events, subsequent to initial search (see events/search on page 36)
that produced paginated results, to free TSOC resources.
Part of workflow for retrieving events (see Working with Security Events on page 9).

Payload elements
api_key
search_id: As received from initial search (see events/search on page 36)

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
search_id

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/events/cancel \
> -d '{"api_key":"…","search_id":"…"}'
<<HTTP status code: 200 OK>>
{ "api_status": true }

events/delete

Description

Delete from TSOC all security events matching a previous search (see events/search on page
36).
Part of workflow for working with events (see Working with Security Events on page 9).

DeceptionGrid TSOC API Developer's Guide, © TrapX 34

 API Call Reference

Payload elements
api_key
search_id: As received from initial search (see events/search on page 36)

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
search_id

Example

Example of full deletion cycle:

$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/events/search \
> -d '{"api_key":"…","filter":{…}}'
<<HTTP status code: 200 OK>>
{
"search_id" : "...",
"number_of_events" : 12345,
"page_size" : 100,
"number_of_pages" : 124,
"page" : 1,
"events" : [ {...}, ..., {...} ]
}
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/events/delete \
> -d '{"api_key":"…","search_id":{…}}'
<<HTTP status code: 200 OK>>
{
"search_id" : "...",
"api_status" : true,
"api_message" : "12345 events will be deleted"
}

DeceptionGrid TSOC API Developer's Guide, © TrapX 35

 API Call Reference

events/download

Description

Request files of specified type (PCAP / binary) associated with specified event, subsequent to
initial search (see events/search below) or page retrieval (see events/show on page 39) whose
response provided that event and indicated the existence of such associated files.
Part of workflow for retrieving events (see Working with Security Events on page 9).

Payload elements
api_key
event: As received in the event's x_trapx_com_eventid
file: Type to retrieve -pcap or binary

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
Binary blob base64 representation of the requested file. In the case of binary, the file is a
ZIP archive containing all associated binaries (archived even if only a single file), encrypted
with password: MALICIOUS.

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/events/download \
> -d '{"api_key":"…", \
> "event":"MWT000000001234","file":"binary"}'
<<HTTP status code: 200 OK>>
<binary contents>

events/search

Description

Initially request security events.

Part of workflow for retrieving events (see Working with Security Events on page 9).

Payload elements
api_key
format (optional): The requested format of events. One of:

• JSON (default)
• STIX2

DeceptionGrid TSOC API Developer's Guide, © TrapX 36

 API Call Reference

filter : May include any of the following fields; only trap_type is mandatory. All must
be matched (AND). Fields are the same as in TSOC Event Analyzer, except where specified
otherwise. Fields marked for traps only are relevant to both Full OS and Emulation traps.

• trap_type : Mandatory. One of

• Full OS
• Emulation
• NIS
• event_id , event_first , event_last : Specific event or range of events, by
ID.
• event_type : One or more (in array) of
• connection
• reconnaissance
• interaction
• infection
• attacker_hostname (traps only)
• attacker_address (traps only)
• trap_name: One or more (in array)
• protocol
• port
• start_time , end_time : Date & time range of events' starting time, in RFC3339
format
• NAC_state: One or more (in array) of
• diverted
• restored
• notified
• appliance_uid: One or more (in array)
• department / company: One or more (in array)
• malware_name (traps only)
• malware_md5 (traps only)
• malware_severity (traps only): One or more (in array) of
• low
• medium
• high
• source_country, destination_country (NIS only): One or more (in array)
• payload (NIS only): Events with payload (boolean)

DeceptionGrid TSOC API Developer's Guide, © TrapX 37

 API Call Reference

• attack_type (NIS only): One or more (in array) of

• Trojans & BotCC
• TOR
• Intelligence

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
search_id: Identifier, for subsequent reference
number_of_events: Total number of matching events
If the number of matching events exceeds the maximum per-page number of events (by
default: 100; customizable in the TSOC Administration menu - see the DeceptionGrid
Administration Guide):

• page_size: The maximum number of events per page

• number_of_pages
• page: 1
events: Array of provided events. Each event includes, in addition to actual event details:

• x_trapx_com_eventid: The event ID

• x_trapx_com_pcap: Whether or not the event has one or more associated
PCAP files (boolean)
• x_trapx_com_binary: Whether or not the event has one or more associated
binary files (boolean)

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/events/search \
> -d '{"api_key":"…","filter":{…}}'
<<HTTP status code: 200 OK>>
{
"search_id" : "...",
"number_of_events" : 945,
"page_size" : 100,
"number_of_pages" : 10,
"page" : 1,
"events" : [ {...}, ..., {...} ]
}

DeceptionGrid TSOC API Developer's Guide, © TrapX 38

 API Call Reference

events/show

Description

Request security events by page, subsequent to initial search (see events/search on page 36)
that produced paginated results.
Part of workflow for retrieving events (see Working with Security Events on page 9).

Payload elements
api_key
search_id: As received from initial search (see events/search on page 36)
page: The page number of events to return
format (optional): The requested format of events. One of:

• JSON (default)
• STIX2

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
number_of_events: Total number of matching events
page_size: The maximum number of events per page
number_of_pages
page: The current page number as requested
search_id
events: Array of provided events, as in response to initial search (see events/search on page
36) .

Example

Retrieving event pages 2-10

$ for i in $(seq 2 10); do \
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/events/show \
> -d '{"api_key":"…","search_id":"…","page":'$i'}'; \
> done
<<HTTP status code: 200 OK>>
{
"search_id" : "...",
"number_of_events" : 12345,

DeceptionGrid TSOC API Developer's Guide, © TrapX 39

 API Call Reference

"page_size" : 100,
"number_of_pages" : 124,
"page" : 2,
"events" : [ {...}, ..., {...} ]
}
...
<<HTTP status code: 200 OK>>
{
"search_id" : "...",
"number_of_events" : 12345,
"page_size" : 100,
"number_of_pages" : 124,
"page" : 10,
"events" : [ {...}, ..., {...} ]
}

exception/ Calls
The following exception/ API calls are available.

In This Section
exception/create ..............................................................................40
exception/list ....................................................................................41
exception/templates ........................................................................42
exception/remove ............................................................................42
exception/replace ............................................................................43

exception/create

Description

Define one or more event Exceptions for a specified Appliance, by submitting one or more
Exception configuration objects.
Part of the workflow for Excepting events (see Excepting (Whitelisting) Events on page 11).

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid

DeceptionGrid TSOC API Developer's Guide, © TrapX 40

 API Call Reference

exception : Array of one or more Exception configuration objects, with fields as in

Exception templates (see exception/templates on page 42).

Response elements

Only standard response elements (see API Call and Response Structures on page 5)

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/exception/create \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dopey"}, \
> "exception":[{…},…,{…}]}'
<<HTTP status code: 200 OK>>
{ "api_status": true }

exception/list

Description

Retrieve a list of a specified Appliance's configured Exceptions, optionally for specified trap
types. The returned exceptions have an non-displayed Filter ID field, which is used in
subsequent actions to change the exception (see exception/replace on page 43) or to remove
it (see exception/remove on page 42).
Part of the workflow for Excepting events (see Excepting (Whitelisting) Events on page 11).

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid
Trap Type (optional): One or more (in array) of (as relevant for Appliance): Emulation
Trap , NIS Windows FullOS Trap. Default is all relevant types

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
exceptions : Array of configured Exceptions, including Filter ID field.

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/exception/list \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dopey"}}'
DeceptionGrid TSOC API Developer's Guide, © TrapX 41
 API Call Reference

<<HTTP status code: 200 OK>>

{ "exceptions": [ {...}, {...}, ..., {...} ] }

exception/templates

Description

Retrieve a specified Appliance's Exception configuration object templates, optionally for

specified trap types.
Part of the workflow for Excepting events (see Excepting (Whitelisting) Events on page 11).

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid
Trap Type (optional): One or more (in array) of (as relevant for Appliance): Emulation
Trap , NIS Windows FullOS Trap. Default is all relevant types

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
templates : Array of Exception configuration object templates.

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/exception/templates \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dopey"}, \
> "Trap Type":"Emulation Trap"}'
<<HTTP status code: 200 OK>>
{ "templates": [ {...}, {...}, ..., {...} ] }

exception/remove

Description

Delete one or more event Exceptions from a specified Appliance.

Part of the workflow for Excepting events (see Excepting (Whitelisting) Events on page 11).

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid
DeceptionGrid TSOC API Developer's Guide, © TrapX 42
 API Call Reference

exception : Array of one or more Filter ID s as obtained from listed Exceptions (see
exception/list on page 41).

Response elements

Only standard response elements (see API Call and Response Structures on page 5)

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/exception/remove \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dopey"}, \
> "exception":[111,112,113]}'
<<HTTP status code: 200 OK>>
{ "api_status": true }
or
{ "api_status": false, "api_message": "unknown exception 113
ignored" }

exception/replace

Description

Change the configuration of one or more event Exceptions on a specified Appliance, by

submitting one or more Exception configuration objects. Each submitted configuration object
must include the Filter ID of the Exception to be replaced.
Part of the workflow for Excepting events (see Excepting (Whitelisting) Events on page 11).

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid
exception : Array of one or more Exception configuration objects, including Filter ID
as obtained from listed Exceptions (see exception/list on page 41).

Response elements

Only standard response elements (see API Call and Response Structures on page 5)

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/exception/replace \
> -d '{"api_key":"…", \
DeceptionGrid TSOC API Developer's Guide, © TrapX 43
 API Call Reference

> "appliance":{"gid":"Dwarves","uid":"Dopey"}, \
> "exception":[{…},…,{…}]}'
<<HTTP status code: 200 OK>>
{ "api_status": true}

fosl/ Calls
The following fosl/ API calls are available.

In This Section
fosl/configure ...................................................................................44
fosl/current.......................................................................................44
fosl/disable .......................................................................................45
fosl/enable........................................................................................45
fosl/revert .........................................................................................46
fosl/status .........................................................................................46

fosl/configure
Set credential list of Appliance-hosted full OS Linux for high-interaction SSH.
Part of theworkflow for working with full OS Linux (see Working with Full OS Linux on page
18).

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid
credentials : JSON collection of new full set of credential pairs (replacing all current
pairs), each as "username":"password".

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
credentials : Resulting JSON collection of current credential pairs, each as
"username":"password"

fosl/current
Retrieve current credential list of Appliance-hosted full OS Linux for high-interaction SSH.
Part of theworkflow for working with full OS Linux (see Working with Full OS Linux on page
18).

DeceptionGrid TSOC API Developer's Guide, © TrapX 44

 API Call Reference

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
credentials : JSON collection of current credential pairs, each as "username":"password"

fosl/disable
Disable Appliance-hosted full OS Linux for high-interaction SSH.
Part of theworkflow for working with full OS Linux (see Working with Full OS Linux on page
18).

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
status : Resulting status enable / disable

fosl/enable

Description

Enable Appliance-hosted full OS Linux for high-interaction SSH, with specified gateway.

Note: If the full OS Linux is already enabled, this command will have no effect (gateway
won't change).

Part of the workflow for working with full OS Linux (see Working with Full OS Linux on page
18).

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid
gateway_interface (optional): Allow the full OS's outbound network access through
specified interface, real or virtual, by name as when working with interfaces (see Working with
Network Interfaces for Traps on page 14). Omit or empty for None (no access).

DeceptionGrid TSOC API Developer's Guide, © TrapX 45

 API Call Reference

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
status : Resulting status enable / disable
gateway_interface : Resulting setting for outbound network access

fosl/revert
Revert Appliance-hosted full OS Linux for high-interaction SSH to its original state, to remove
all changes made by attackers.
Part of theworkflow for working with full OS Linux (see Working with Full OS Linux on page
18).

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
Current status: enable / disable

fosl/status
Retrieve status of Appliance-hosted full OS Linux for high-interaction SSH.

Note: Retrieved status does not include current Gateway.

Part of theworkflow for working with full OS Linux (see Working with Full OS Linux on page
18).

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
status : Current status enable / disable
gateway_interface (if status = enable ): Current setting for outbound network
access

general/ Calls
The following general/ API calls are available.
DeceptionGrid TSOC API Developer's Guide, © TrapX 46
 API Call Reference

In This Section
general/audit ....................................................................................47
general/departments .......................................................................47
general/supported_timezones.........................................................48
general/vm_infrastructure ...............................................................48

general/audit

Description

Request TSOC audit logs.

Payload elements
api_key

Response

In addition to standard response elements (see API Call and Response Structures on page 5):
Binary blob base64 representation of a ZIP archive containing the log files (archived even if
only a single file).

general/departments

Description

Request list of configured companies (in an MSSP deployment) or departments.

Payload elements
api_key

Response

In addition to standard response elements (see API Call and Response Structures on page 5):
JSON array of company / department strings

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/general/departments \
> -d '{"api_key":"…"}'
<<HTTP status code: 200 OK>>
[ "Production", "Sales", "Marketing", "Development",
"Administration" ]

DeceptionGrid TSOC API Developer's Guide, © TrapX 47

 API Call Reference

general/supported_timezones

Description

Request list of recognized time zones

Payload elements
api_key

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
All recognized time zones. Element keys are strings such as "UTC" or "Asia/Jerusalem", and
values are strings with the RFC3339 format.

Example

The following is a partial example of the response:

{
"UTC" : "2018-01-07T10:58:51.56Z",
"America/New_York" : "2018-01-07T05:58:51.56-05:00",
"America/Los_Angeles" : "2018-01-07T02:58:51.56-08.00",
"America/Santiago" : "2018-01-07T07:58:51.56-03:00",
"Asia/Calcutta" : "2018-01-07T16:26:51.56+05:30",
"Asia/Jerusalem" : "2018-01-07T12:58:51.56+02:00",
"Asia/Kathmandu" : "2018-01-07T16:43:51.56+05:45",
"Australia/Melbourne" : "2018-01-07T21:58:51.56+11:00",
"Australia/Darwin" : "2018-01-07T20:28:51.56+09:30"
}

general/vm_infrastructure

Description

Request list of configured VM infrastructure names, for use with Full OS traps.

Note: Currently, DeceptionGrid supports only a single VM infrastructure.

Payload elements
api_key

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
JSON array of VM infrastructure strings

DeceptionGrid TSOC API Developer's Guide, © TrapX 48

 API Call Reference

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/ecosystem/vm_infrastructure\
> -d '{"api_key":"…"}'
<<HTTP status code: 200 OK>>
[ "vmware" ]

interface/ Calls
The following interface/ API calls are available.

In This Section
interface/configure ..........................................................................49
interface/create................................................................................51
interface/list .....................................................................................52
interface/remove .............................................................................53

interface/configure

Description

Reconfigure an existing virtual interface's properties (see Working with Network Interfaces
for Traps on page 14).
An interface's type and parent cannot be changed.

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid
interface : JSON object including the new interface's properties:

• name : Name of interface to be reconfigured

• configuration : dhcp (valid only for VLAN interface) or static
• If the configuration is static : address , netmask , and gateway to
be assigned
• segment : Name of the organizational network area, enabling Attack Visualization
by network segments

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
All fields from request payload; In the response, interface also includes

DeceptionGrid TSOC API Developer's Guide, © TrapX 49

 API Call Reference

• type
• parent
• The assigned address , netmask , and gateway , regardless of
configuration
• mac_addr : The interface's MAC address

Example
$ for i in $(seq 91 99); do \
> curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/interface/configure \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dopey"}, \
> "interface":{"name":"vlan'$i'", \
> "configuration":"static" \
> "address":"192.168.'$i'.123", \
> "netmask":"255.255.255.0", \
> "gateway":"192.168.'$i'.254"}}'; \
> done
<<HTTP status code: 200 OK>>
{
"appliance":{"gid":"Dwarves","uid":"Dopey"},"api_status":true,
"interface":{"name":"vlan91","type":"vlan","parent":"eth2",
"mac_addr":"00:0c:29:13:80:91","configuration":"static",
"address":"192.168.91.123","netmask":"255.255.255.0",
"gateway":"192.168.91.1"}
}
...
<<HTTP status code: 200 OK>>
{
"appliance":{"gid":"Dwarves","uid":"Dopey"},"api_status":true,
"interface":{"name":"vlan99","type":"vlan","parent":"eth2",
"mac_addr":"00:0c:29:13:80:99","configuration":"static",
"address":"192.168.99.123","netmask":"255.255.255.0",
"gateway":"192.168.99.1"}
}

DeceptionGrid TSOC API Developer's Guide, © TrapX 50

 API Call Reference

interface/create

Description

Create a new virtual interface and set its configurable properties (see Working with Network
Interfaces for Traps on page 14).

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid
interface : JSON object including the new interface's properties:

• type : One of:

• phys
• subinterface
• vlan
• alias
• name : Name for new interface, according to interface naming syntax (see Working
with Network Interfaces for Traps on page 14)
• parent (only for subinterface and alias):
• When creating a subinterface or VLAN interface: The physical interface, by its
name , on which to create it
• When creating a VLAN Alias interface: The VLAN interface, by its name , on which
to create it
• configuration : dhcp (valid only for VLAN interface) or static
• If the configuration is static : address , netmask , and gateway to
be assigned
• segment : Name of the organizational network area, enabling Attack Visualization
by network segments

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
All fields from request payload; In the response, interface also includes

• The assigned address , netmask , and gateway , regardless of

configuration
• mac_addr : The new interface's MAC address

Example
$ curl -k -s -S \

DeceptionGrid TSOC API Developer's Guide, © TrapX 51

 API Call Reference

> https://<TSOC_IP>:8443/api/v1.5/interface/create \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dopey"}, \
> "interface":{"name":"vlan89","type":"vlan", \
> "parent":"eth2","configuration":"dhcp"}}'
<<HTTP status code: 200 OK>>
{
"appliance":{"gid":"Dwarves","uid":"Dopey"},"api_status":true,
"interface":{"name":"vlan89","type":"vlan","parent":"eth2",
"mac_addr":"00:0c:29:13:80:04","configuration":"dhcp",
"address":"192.168.89.67","netmask":"255.255.255.0",
"gateway":"192.168.89.1"}
}

interface/list

Description

Request a list of a specified Appliance's interfaces, with their properties (see Working with
Network Interfaces for Traps on page 14).

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid
interface (optional): One or more (in array) interface name s. Default is all interfaces

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
All fields from request payload; In the response, interface includes one or more (in array)
interface objects that include:

• name
• type
• parent
• mac_addr : The interface's MAC address
• configuration : dhcp (valid only for VLAN interface) or static
• address
• netmask

DeceptionGrid TSOC API Developer's Guide, © TrapX 52

 API Call Reference

• gateway
• segment : Name of the organizational network area, enabling Attack Visualization
by network segments

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/interface/list \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dopey"}, \
> "interface":["vlan91","vlan92","vlan93", \
> "vlan94","vlan95","vlan96", \
> "vlan97","vlan98","vlan199"]}'
<<HTTP status code: 200 OK>>
{
"appliance":{"gid":"Dwarves","uid":"Dopey"},
"interface":[
{"name":"vlan91","type":"vlan","parent":"eth2",
"mac_addr":"00:0c:29:13:80:91","configuration":"dhcp",
"address":"192.168.91.38","netmask":"255.255.255.0",
"gateway":"192.168.91.1"},
...
{"name":"vlan99","type":"vlan","parent":"eth2",
"mac_addr":"00:0c:29:13:80:98","configuration":"dhcp",
"address":"192.168.98.38","netmask":"255.255.255.0",
"gateway":"192.168.98.1"}
]

interface/remove

Description

Delete a single specified interface (see Working with Network Interfaces for Traps on page 14)
from an Appliance.

Note: A VLAN interface that has child VLAN Alias interfaces cannot be removed.

Payload elements
api_key

DeceptionGrid TSOC API Developer's Guide, © TrapX 53

 API Call Reference

appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid
interface : A single interface name

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
All fields from request payload

Example
$ for i in $(seq 91 99); do \
> curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/interface/remove \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dopey"}, \
> "interface":"vlan'$i'"}'; \
> done
<<HTTP status code: 200 OK>>
{
"appliance":{"gid":"Dwarves","uid":"Dopey"},
"interface":"vlan91","api_status":true
}
...
<<HTTP status code: 200 OK>>
{
"appliance":{"gid":"Dwarves","uid":"Dopey"},
"interface":"vlan99","api_status":true
}

mwtrap/ Calls
The following mwtrap/ API calls are available.

DeceptionGrid TSOC API Developer's Guide, © TrapX 54

 API Call Reference

In This Section
mwtrap/configure ............................................................................55
mwtrap/custom_create ...................................................................56
mwtrap/custom_delete ...................................................................57
mwtrap/custom_templates .............................................................58
mwtrap/clone ...................................................................................59
mwtrap/create .................................................................................59
mwtrap/current................................................................................60
mwtrap/interface .............................................................................61
mwtrap/list .......................................................................................62
mwtrap/remove ...............................................................................62
mwtrap/supported ...........................................................................63
mwtrap/templates ...........................................................................64
mwtrap/trap .....................................................................................65

mwtrap/configure

Description

Apply one or more configuration objects to respective traps, as specified by interface name in
the configuration object(s).
Part of the workflow for working with emulation traps (see Working with Emulation Traps on
page 16).

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid
configuration : One or more (in array) configuration objects, each of which is a modified
existing trap configuration (see mwtrap/current on page 60) or modified trap template (see
mwtrap/templates on page 64) and includes the interface name to which to apply the trap
configuration.
Configuration field values that are files (ZIP archives of custom web pages; SSL certificate and
key) must be base64 encoded.

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
configuration : One or more (in array) configuration objects representing resulting
configuration(s)

DeceptionGrid TSOC API Developer's Guide, © TrapX 55

 API Call Reference

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/mwtrap/configure \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dopey"}, \
> "configuration":[{"interface":"vlan98",…}, \
> {"interface":"vlan99",…}]}'
<<HTTP status code: 200 OK>>
{
"configuration": [
{"interface":"vlan98",...},
{"interface":"vlan99",...}
]
}

mwtrap/custom_create

Description

Make one or more provided customized emulation types available for trap creation.
Part of the workflow for customizing emulation types (see Customizing Emulation Types on
page 17) .

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid
template : One or more (in array) customized emulation templates to be made available
for trap creation

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
template : One or more (in array) resulting new available emulation types

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/mwtrap/custom_create \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dopey"}, \
DeceptionGrid TSOC API Developer's Guide, © TrapX 56
 API Call Reference

> "template":[ \
> {"operating_system_type":"HP
Printer","base_operating_system_type":"Lexmark Printer",…}, \
> {"operating_system_type":"Mellanox
Switch","base_operating_system_type":"Cisco Switch",…} \
> ]}'
<<HTTP status code: 200 OK>>
{
"template": [
{"operating_system_type":"HP
Printer","base_operating_system_type":"Lexmark printer",...},
{"operating_system_type":"Mellanox
Switch","base_operating_system_type":"Cisco Switch",...}
]
}

mwtrap/custom_delete

Description

Remove one or more customized emulation types (see Customizing Emulation Types on page
17).

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid
template : One or more (in array) type names of customized emulation types to be
removed

Response elements

Only standard response elements (see API Call and Response Structures on page 5)

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/mwtrap/custom_delete \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dopey"}, \
> "template":"HP Printer"}'
<<HTTP status code: 200 OK>>

DeceptionGrid TSOC API Developer's Guide, © TrapX 57

 API Call Reference

{
"api_status": true,
"api_message": "Trap type 'HP Printer' deleted from
Dwarves:Dopey"
}

mwtrap/custom_templates

Description

Retrieve templates for customization, as supported for the specified appliance, optionally for
specified base emulation types.
Part of the workflow for customizing emulation types (see Customizing Emulation Types on
page 17) .

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid
base_operating_system_type : One or more (in array) emulation types on whom
retrieved customizable templates will be based

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
templates : One or more (in array) customizable templates

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/mwtrap/custom_templates \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dopey"}, \
> "base_operating_system_type":["Windows Server","Linux
Server"]}'
<<HTTP status code: 200 OK>>
{
"templates": [
{"operating_system_type":"Custom
Trap","base_operating_system_type":"Windows Server",...},
{"operating_system_type":"Custom
Trap","base_operating_system_type":"Linux Server",...}

DeceptionGrid TSOC API Developer's Guide, © TrapX 58

 API Call Reference

]
}

mwtrap/clone

Description

Copy full configuration (including spin data) between specified interfaces.

Part of the workflow for working with emulation traps (see Working with Emulation Traps on
page 16).

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid
src : Interface name from which to copy configuration
dst : Interface name to which to copy configuration

Response elements

Only standard response elements (see API Call and Response Structures on page 5)

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/mwtrap/clone \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dopey"}, \
> "src":"vlan98","dst":"vlan99"}'
<<HTTP status code: 200 OK>>
{ "api_status": true }

mwtrap/create

Description

Enable a trap on a specified interface (allocates a TSOC database) and set the trap name.
Part of the workflow for working with emulation traps (see Working with Emulation Traps on
page 16).

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid
DeceptionGrid TSOC API Developer's Guide, © TrapX 59
 API Call Reference

interface : The interface name (see Working with Network Interfaces for Traps on page
14) on which to enable a trap
trap : A new name for the trap being created

Response elements

Only standard response elements (see API Call and Response Structures on page 5)

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/mwtrap/create \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dopey"}, \
> "interface":"vlan91","trap":"classified91"}'
<<HTTP status code: 200 OK>>
{
"api_status": true,
"api_message": "Trap classified91 successfully created on
Dwarves:Dopey"
}

mwtrap/current

Description

Retrieve the configuration of an existing configured trap.

Part of the workflow for working with emulation traps (see Working with Emulation Traps on
page 16).

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid
interface (optional): One or more (in array) interface names, whose trap configuration(s)
to retrieve. Default is all interfaces

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
configuration : One or more (in array) trap configuration objects

DeceptionGrid TSOC API Developer's Guide, © TrapX 60

 API Call Reference

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/mwtrap/current \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dopey"}, \
> "interface":["vlan98","vlan99"]}'
<<HTTP status code: 200 OK>>
{
"configuration": [
{"interface":"vlan98",...},
{"interface":"vlan99",...}
]
}

mwtrap/interface

Description

Retrieve the interface names on which are configured traps specified by their trap names.
Part of the workflow for working with emulation traps (see Working with Emulation Traps on
page 16).

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid
trap: One or more (in array) trap names, whose parent interface name(s) to retrieve.

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
interface : One or more (in array) interface names, in the same order as the payload trap
names. If only some traps are found, the others' corresponding interfaces are returned as
null .

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/mwtrap/interface \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dopey"}, \
DeceptionGrid TSOC API Developer's Guide, © TrapX 61
 API Call Reference

> "trap":["classified19","classified92","classified93"]}'
<<HTTP status code: 200 OK>>
{ "interface": [ null, "vlan92", "vlan93" ] }

mwtrap/list

Description

List a specified Appliance's configured traps by trap names.

Part of the workflow for working with emulation traps (see Working with Emulation Traps on
page 16).

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
traps : Array of trap names.

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/mwtrap/list \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dopey"}}'
<<HTTP status code: 200 OK>>
{ "traps": [ "classified_MT", "classified91", ... ,
"classified99" ] }

mwtrap/remove

Description

Remove a trap from a specified interface.

Part of the workflow for working with emulation traps (see Working with Emulation Traps on
page 16).

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid

DeceptionGrid TSOC API Developer's Guide, © TrapX 62

 API Call Reference

One of:

• interface : The interface name (see Working with Network Interfaces for Traps on
page 14) from which to remove the trap
• trap : The name of the trap to remove

Response elements

Only standard response elements (see API Call and Response Structures on page 5)

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/mwtrap/remove \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dopey"}, \
> "trap":"classified91"}'
Response:
<<HTTP status code: 200 OK>>
{
"api_status": true,
"api_message": "Trap classified91 successfully removed from
Dwarves:Dopey"
}

mwtrap/supported

Description

Retrieve a list of emulation types (for example, Windows_Server or VoIP Device) supported
for a specified Appliance.
Part of the workflow for working with emulation traps (see Working with Emulation Traps on
page 16).

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
traps : Array of emulation types.

DeceptionGrid TSOC API Developer's Guide, © TrapX 63

 API Call Reference

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/mwtrap/supported \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dopey"}}'
<<HTTP status code: 200 OK>>
{ "traps": [ "Windows Server", "Linux Server", ... , "VoIP
Device" ] }

mwtrap/templates

Description

Retrieve a specified Appliance's configuration templates, optionally for specified emulation

types.
Part of the workflow for working with emulation traps (see Working with Emulation Traps on
page 16).

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid
operating_system_type (optional): One or more (in array) emulation type(s) whose
configuration templates to retrieve. Default is all emulation types supported for the Appliance

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
templates : Array of configuration object templates.

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/mwtrap/templates \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dopey"}, \
> "operating_system_type":["Windows Server","Linux Server"]}'
<<HTTP status code: 200 OK>>
{
"templates": [
{"operating_system_type":"Windows Server",...},

DeceptionGrid TSOC API Developer's Guide, © TrapX 64

 API Call Reference

{"operating_system_type":"Linux Server",...}
]
}

mwtrap/trap

Description

Retrieve trap names for specified interfaces.

Part of the workflow for working with emulation traps (see Working with Emulation Traps on
page 16).

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid
interface : One or more (in array) interface names (see Working with Network Interfaces
for Traps on page 14) whose trap names to retrieve

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
trap : One or more (in array) trap names, in the same order as the payload interface names.
If only some traps are found, the others' are returned as null .

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/mwtrap/trap \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dopey"}, \
> "interface":["vlan19","vlan92","vlan93"]}'
<<HTTP status code: 200 OK>>
{ "trap": [ null, "classified92", "classified93" ] }

system/ Calls
The following system/ API calls are available.

DeceptionGrid TSOC API Developer's Guide, © TrapX 65

 API Call Reference

In This Section
system/tsoc_shutdown ....................................................................65

system/tsoc_shutdown
Perform administrative, graceful shutdown of TSOC, such as for periodic backup or other
administrative purposes.

Payload elements
api_key
None

Response elements

Only standard response elements (see API Call and Response Structures on page 5)None

versions/ Calls
The following versions/ API calls are available.

In This Section
versions/supported_versions ...........................................................66
versions/tsoc_version ......................................................................68

versions/supported_versions

Description

For API and/or SDK, retrieve API/SDK versions supported by the TSOC; or, for specified
API/SDK version, retrieve compatibility information.
If only API or SDK version is specified - returns TSOC compatibility information for that version.
If both API and SDK versions are specified - returns compatibility information for the
combination.

Payload elements
api_key
api (optional): API version number for which to return compatibility information. If omitted
or null - return API version range supported by the TSOC
sdk (optional): SDK version number for which to return compatibility information. If omitted
or null - return SDK version range supported by the TSOC

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
api , sdk : Supported version, or range of versions: min and max , if relevant
compatible (boolean, if relevant)

DeceptionGrid TSOC API Developer's Guide, © TrapX 66

 API Call Reference

Examples

Find out what versions of the API and the SDK the TSOC supports:
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/versions/supported_versions
\
> -d '{"api_key":"…"}'
<<HTTP status code: 200 OK>>
{
"api": {"min":"1.0", "max":"1.7"},
"sdk": {"min":"1.0", "max":"1.5"},
"compatible": true
}
Find out what TSOC-supported versions of the API and the SDK are compatible with
API version 1.7:
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/versions/supported_versions
\
> -d '{"api_key":"…","api":"1.7"}'
<<HTTP status code: 200 OK>>
{
"api": "1.7",
"sdk": {"min":"1.4", "max":"1.5"},
"compatible": true
}
Find out what TSOC-supported versions of the API and the SDK are compatible with SDK
version 1.5:
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/versions/supported_versions
\
> -d '{"api_key":"…","sdk":"1.5"}'
<<HTTP status code: 200 OK>>
{
"api": {"min":"1.6", "max":"1.7"},
"sdk": "1.5",
"compatible": true

DeceptionGrid TSOC API Developer's Guide, © TrapX 67

 API Call Reference

}
Find out if SDK version 1.3 is compatible with API version 1.7:
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/versions/supported_versions
\
> -d '{"api_key":"…","api":"1.7","sdk":"1.3"}'
<<HTTP status code: 200 OK>>
{
"api": null,
"sdk": null,
"compatible": false,
"message": "Use SDK 1.4-1.5 with API 1.7, or API 1.0-1.5 with
SDK 1.3"
}

versions/tsoc_version

Description

Retrieve TSOC's version.

Payload elements
api_key

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
TSOC version (string)

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/versions/tsoc_version \
> -d '{"api_key":"…"}'
"6.2 GA.11"

spindata/ Calls
The following spindata/ API calls are available.

DeceptionGrid TSOC API Developer's Guide, © TrapX 68

 API Call Reference

In This Section
spindata/disable ...............................................................................68
spindata/enable ...............................................................................69
spindata/status.................................................................................70

spindata/disable

Description

Disable previously enabled (see spindata/enable on page 69) FTP access to an interface for a
specified emulated service.
Part of the workflow for working with emulation traps (see Working with Emulation Traps on
page 16).

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid
interface : The interface name to which to disable FTP access, for the following service
service : The emulated service for which to disable FTP access

Response elements

Only standard response elements (see API Call and Response Structures on page 5)

Example
> https://<TSOC_IP>:8443/api/v1.5/spindata/disable \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dopey"}, \
> "interface":"vlan98","service":"SMB"}'
<<HTTP status code: 200 OK>>
{ "api_status": true }

spindata/enable

Description

Allow FTP access to an interface to enable uploading spin data to a specified service of the
interface's trap.
Part of the workflow for working with emulation traps (see Working with Emulation Traps on
page 16).

DeceptionGrid TSOC API Developer's Guide, © TrapX 69

 API Call Reference

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid
interface : The interface name to which to allow FTP access, for the following service
service : The emulated service which will serve the uploaded spin data
client_addr : The IP address from which an FTP client will be allowed to access the
interface

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
url : The credentials and target address to use for FTP access
space : Includes:

• total : Total disk space allocated for the service's spin data
• used : The amount of allocated disk space already used for spin data

Example
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/spindata/enable \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dopey"}, \
>
"interface":"vlan98","service":"SMB","client_addr":"172.16.1.4
4"}'
<<HTTP status code: 200 OK>>
{
"url": "ftp://baaibys:Yjaxc@172.16.1.52:9445",
"space": { "total": 4500, "used": 0.132 }
}

spindata/status

Description

Check current FTP status for a specified service of an interface's trap.

Part of the workflow for working with emulation traps (see Working with Emulation Traps on
page 16).

DeceptionGrid TSOC API Developer's Guide, © TrapX 70

 API Call Reference

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid
interface : The interface name for which to check FTP status, for the following service
service : The emulated service for which to check FTP status

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
interface : The interface name
running (boolean): Whether FTP access is currently enabled
If running = true :

• url : The target address and port to use for FTP access
• service : The service for which FTP access is running
• client_addr : The FTP client address which is currently allowed to access FTP

Example
> https://<TSOC_IP>:8443/api/v1.5/spindata/status \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dopey"}, \
> "interface":"vlan98","service":"SMB"}'
<<HTTP status code: 200 OK>>
{
"interface": "vlan98"
"running": true,
"service": "SMB",
"url": "ftp://172.16.1.52:9445",
"client_addr": 172.16.1.44
}

tokens/ Calls
The following tokens/ API calls are available.

DeceptionGrid TSOC API Developer's Guide, © TrapX 71

 API Call Reference

In This Section
tokens/assign....................................................................................71
tokens/campaigns ............................................................................72
tokens/delete ...................................................................................73
tokens/list .........................................................................................74

tokens/assign

Description

Assign tokens to specified campaigns. Specified tokens are added to already-assigned tokens.
Part of the workflow for managing deception tokens (see Working with Deception Tokens on
page 18).

Payload elements
api_key
JSON key-value pairs where each key is a campaign name, and its value is token ID numbers
to be added to the campaign.

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
JSON object where each key is a campaign name, and its value is an array of all of the
campaign's assigned token ID numbers, including the newly-added ones.

Examples
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/tokens/assign \
> -d '{"api_key":"…", \
> "Servers":[25,27],"Workstations":[24,28]}'
<<HTTP status code: 200 OK>>
{
"Servers": [ 12, 17, 23, 25, 27 ],
"Workstations": [ 19, 24, 26, 28, 31, 33 ]
}

tokens/campaigns

Description

Retrieve a specified department's or company's existing campaigns; or, a specified Appliance's

tokens by campaigns. Retrieved campaigns list their existing assigned tokens by ID numbers.

DeceptionGrid TSOC API Developer's Guide, © TrapX 72

 API Call Reference

Part of the workflow for managing deception tokens (see Working with Deception Tokens on
page 18).

Payload elements
api_key
One of:

• department : Name of department or company whose campaigns to retrieve

• appliance : JSON object identifying the Appliance (see Working with
DeceptionGrid Appliances on page 12), including the Appliance's gid and uid,
whose tokens' campaigns to retrieve

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
JSON object where each key is a campaign name, and its value is an array of the campaign's
currently assigned token ID numbers.

Examples
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/tokens/campaigns \
> -d '{"api_key":"…", \
> "department":"Zurich Office"}'
<<HTTP status code: 200 OK>>
{
"Servers": [ 12, 17, 23 ],
"Workstations": [ 19, 26, 31, 33 ],
"Linux": [ 17, 31, 38, 42 ]
}
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/tokens/campaigns \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dopey"}}'
<<HTTP status code: 200 OK>>
{
"Servers": [ 12, 23 ],
"Workstations": [ 19, 26, 33 ],
"Linux": [ 38, 42 ]
}
DeceptionGrid TSOC API Developer's Guide, © TrapX 73
 API Call Reference

tokens/delete

Description

Remove tokens from specified campaigns.

Part of the workflow for managing deception tokens (see Working with Deception Tokens on
page 18).

Payload elements
api_key
JSON key-value pairs where each key is a campaign name, and its value is token ID numbers
to be removed from the campaign.

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
JSON object where each key is a campaign name, and its value is an array of all of the
campaign's assigned token ID numbers, reflecting the results of the requested removal.

Examples
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/tokens/delete \
> -d '{"api_key":"…", \
> "Servers":[17,27],"Workstations":[33]}'
<<HTTP status code: 200 OK>>
{
"Servers": [ 12, 23, 25 ],
"Workstations": [ 19, 24, 26, 28, 31 ]
}

tokens/list

Description

Retrieve traps' token details: per-trap token types and ID numbers. Specific token
configuration is not included.
Part of the workflow for managing deception tokens (see Working with Deception Tokens on
page 18).

Payload elements
api_key
appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 12), including the Appliance's gid and uid
DeceptionGrid TSOC API Developer's Guide, © TrapX 74
 API Call Reference

One of:

• interface : One or more (in array) interface names (see Working with Network
Interfaces for Traps on page 14), whose traps' token details to retrieve. Tokens will be
listed by interface name.
• trap : One or more (in array) trap names, whose token details to retrieve. Tokens
will be listed by trap name.

Response elements

In addition to standard response elements (see API Call and Response Structures on page 5):
tokens : List of token objects, each including:

• Either interface name or trap name, depending on payload

• id number of the token
• label : Token type

Examples
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/tokens/list \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dumpy"}, \
> "interface":["vlan91","vlan92","vlan93"]}'
<<HTTP status code: 200 OK>>
{
"tokens": [
{ "id": 127, "label": "SMB share", "interface": "vlan91" },
...,
{ "id": 495, "label": "ODBC connection", "interface": "vlan93"
}
]
}
$ curl -k -s -S \
> https://<TSOC_IP>:8443/api/v1.5/tokens/list \
> -d '{"api_key":"…", \
> "appliance":{"gid":"Dwarves","uid":"Dumpy"}, \
> "trap":["classified91","classified92","classified93"]}'
<<HTTP status code: 200 OK>>
{

DeceptionGrid TSOC API Developer's Guide, © TrapX 75

 API Call Reference

"tokens": [
{ "id": 127, "label": "SMB share", "trap": "classified91" },
...,
{ "id": 495, "label": "ODBC connection", "trap":
"classified93" }
]
}

DeceptionGrid TSOC API Developer's Guide, © TrapX 76

Support
Support for TrapX products is provided by TrapX or by an authorized TrapX Service Partner.
More information and technical support for TrapX products are available at:

• support.trapx.com/portal
• support@trapx.com
• Americas: 1-855-249-4453
EMEA & Asia Pacific: +44-208-819-9849

Documentation Feedback
TrapX Security continually strives to produce high quality documentation. If you have any
comments, please contact Documentation@trapx.com.

About TrapX Security®

TrapX Security is the pioneer and global leader in cyber deception technology, with flagship
solution DeceptionGrid effectively detecting, deceiving, and defeating advanced cyber attacks
and human attackers in real-time. DeceptionGrid provides automated, highly accurate insight
into malicious activity unseen by other types of cyber defenses. Deploying DeceptionGrid
sustains a proactive security posture, fundamentally halting the progression of an attack.
DeceptionGrid changes cyber-attack economics by shifting the cost to the attacker.
The TrapX Security customer base includes worldwide Forbes Global 2000 commercial and
government customers in key industries including defense, healthcare, finance, energy, and
consumer products. Learn more at www.trapx.com .

Disclaimer
Product specifications are subject to change without notice. This document is believed to be
accurate and reliable at the time of printing. However, due to ongoing product improvements
and revisions, TrapX cannot guarantee accuracy of printed material after the Date Published
nor can it accept responsibility for errors or omissions. Before consulting this document, check
the corresponding Release Notes regarding feature preconditions and/or specific support in
this release. In cases where there are discrepancies between this document and the Release
Notes, the information in the Release Notes supersedes that in this document. Updates to this
document and other documents as well as software files can be obtained by TrapX customers.

Trademarks and Copyright

© Copyright 2022 TrapX Security Ltd. All rights reserved. This document is subject to change
without notice. TrapX, TrapX Security, DeceptionGrid and CryptoTrap are trademarks or
registered trademarks of TrapX Security in the United States and other countries. Other
trademarks used in this document are the property of their respective owners.
Updated 25/1/22

DeceptionGrid TSOC API Developer's Guide, © TrapX 77