v. 7.

CLI / SDK Developer's Guide

TrapX® Security, January 2022

trapx.com
 Contents

Contents
Preface ......................................................................................... 3
CLI / SDK Overview ..................................................................... 4
TSOC Interactive CLI................................................................... 5
TSOC Shell Commands .............................................................. 7
TSOC Python SDK....................................................................... 9
Installing the SDK .................................................................................................9
Configuring the SDK .............................................................................................9
Working with the SDK.........................................................................................10
SDK Management Commands ...........................................................................11

Using CLI / Shell / SDK Commands ......................................... 16

CLI / Shell / SDK High-Level Tasks ....................................................................16
CLI / Shell / SDK Command Reference ..............................................................25
Handling Asynchronous Commands ................................................................57

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 2

 Preface

Preface
This Developer's Guide is about using line commands and developing client scripts using
various TrapX DeceptionGrid CLI / SDK options.
For general background information on DeceptionGrid's architecture and functionality, see
the DeceptionGrid Administration Guide and the DeceptionGrid Security Deployment Guide.

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 3

 CLI / SDK Overview

CLI / SDK Overview

The following pages describe using line commands and developing client scripts to TrapX
DeceptionGrid TSOC, for a wide range of purposes, including:

• Deployment and provisioning: Manage DeceptionGrid Appliances and configure

Appliances' interfaces and traps.
• Security analysis: Retrieve recorded security event details and associated files, such
as for use in organizational security analysis systems.
You can access and use commands in any of the following ways (in order of recommendation
and relevance for most cases):

• Interactive CLI (see TSOC Interactive CLI on page 5): On any Windows or Linux
computer that can access TSOC, enter an environment that prompts and presents
menus for selecting available actions.
• Shell commands (see TSOC Shell Commands on page 7): On any Windows or Linux
computer that can access TSOC, execute full command syntax, or implement
commands in scripts such as to schedule tasks.
• Python SDK (see TSOC Python SDK on page 9): For advanced programmatic solutions,
implement SDK commands in a Python environment.
• REST API: In other programmatic environments, directly implement REST API calls.
Described in the separate TSOC API Developer's Guide.

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 4

 TSOC Interactive CLI

TSOC Interactive CLI

Interactive CLI is one of the ways for using TSOC commands: On any Windows or Linux
computer that can access TSOC, enter an environment that prompts and presents menus for
selecting available actions.
For Windows, TSOC CLI is provided as a single, ZIPped executable: tcli.exe . To install, simply
extract it to a convenient working directory.
Linux setup
For Linux, to access the interactive CLI you'll need to first install the TSOC SDK.
Requirements: One of

• Python 2.7 and above

• Python 3.x
To install or upgrade the TSOC SDK, place the provided .whl file on a client computer meeting
the above requirements, and from the file's location run:
pip install trapxsdk-<version>-py2.py3-none-any.whl
where <version> is as in the actual file name. The SDK and all required dependencies are
installed.

Note: The installation process includes downloading some dependencies, which requires
a connection to the internet.

To remove the SDK, run:

pip uninstall trapxsdk
Interactive CLI commands require two configuration files, both of which can be created from
inside the interactive CLI. The required configuration files are:

• TSOC connection configuration file: Specifies connection details to TSOC. Needs to be

created and configured once, and then usually doesn't need to be changed.
• Command configuration file: Specifies input (payload, parameters) for
CLI commands. Even commands that don't use any input require the existence of the
configuration file. You'll usually need to reconfigure this file before running each
command.
To enter the interactive CLI:

• On Windows: From the CLI's working directory, run:

tcli cli
• On Linux: From the SDK's working directory, run:
python -m trapxsdk cli

Upon entering the CLI, if the config.json TSOC connection configuration file doesn't yet exist
in the CLI working directory, you'll be prompted to create it, after which you can edit it
(outside the CLI) and confirm it.

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 5

 TSOC Interactive CLI

The file's contents are a single JSON object with the following keys (in any order):

• tsoc (required): The TSOC address

• api_key (required): TSOC's API key (see the DeceptionGrid Administration Guide)
• api_version : Currently v1.5
• check_certificate (boolean; default is false): Validate TSOC's certificate (if the
certificate has been organizationally signed).
• logfile : Path to file in which to store logs.
• silent (boolean): false = detailed outputs in stdout
• api_exceptions (boolean): false = receive tuple with status instead of detailed
exceptions
• privilege_api_key: Required only for high-privileged actions. Obtain from the
TSOC administration menu.
Upon confirming the TSOC connection configuration file, you'll be presented with a list of
available commands. Select the number of the command you want to use.
You'll be prompted to (re)create, specify, and/or confirm the command configuration file; edit
it (outside the CLI) according to command input requirements (see Using CLI / Shell / SDK
Commands on page 16), and confirm to run the command.

Note: Commands that do not use any input still require the existence of the command
configuration file. In that case it will contain only an empty JSON object: {} .

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 6

 TSOC Shell Commands

TSOC Shell Commands

Shell commands are one of the ways for using TSOC commands: On any Windows or Linux
computer that can access TSOC, execute full command syntax, or implement commands in
scripts such as to schedule tasks.
For Windows, enable TSOC shell commands with the provided single, ZIPped
executable: tcli.exe . To install, simply extract it to a convenient working directory.
Linux setup
For Linux, to enable TSOC shell commands you'll need to first install the TSOC SDK.
Requirements: One of

• Python 2.7 and above

• Python 3.x
To install or upgrade the TSOC SDK, place the provided .whl file on a client computer meeting
the above requirements, and from the file's location run:
pip install trapxsdk-<version>-py2.py3-none-any.whl
where <version> is as in the actual file name. The SDK and all required dependencies are
installed.

Note: The installation process includes downloading some dependencies, which requires
a connection to the internet.

To remove the SDK, run:

pip uninstall trapxsdk
Shell commands require two configuration files, specified in each command:

• TSOC connection configuration file: Specifies connection details to TSOC. Needs to be

created and configured once, and then usually doesn't need to be changed.
• Command configuration file: Specifies input (payload, parameters) for
CLI commands. You'll usually need to reconfigure this file before running each
command. Even commands that don't use any input require the existence of the
configuration file; in those cases the file will contain only an empty JSON object: {} .
To create templates for both types of files, it is recommended to use the interactive CLI (see
TSOC Interactive CLI on page 5).
The TSOC connection configuration file's contents are a single JSON object with the following
keys (in any order):

• tsoc (required): The TSOC address

• api_key (required): TSOC's API key (see the DeceptionGrid Administration Guide)
• api_version : Currently v1.5

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 7

 TSOC Shell Commands

• check_certificate (boolean; default is false): Validate TSOC's certificate (if the

certificate has been organizationally signed).
• logfile : Path to file in which to store logs.
• silent (boolean): false = detailed outputs in stdout
• api_exceptions (boolean): false = receive tuple with status instead of detailed
exceptions
• privilege_api_key: Required only for high-privileged actions. Obtain from the
TSOC administration menu.
Syntax for shell commands is (from the working directory):

• On Windows:
tcli --config_path <connection_config_file> --
config_cmd_path <command_config_file> <command>
• On Linux:
python -m trapxsdk --config_path <connection_config_file> --
config_cmd_path <command_config_file> <command>

Where:
<connection_config_file> is the path to and name of the TSOC connection
configuration file, relative to current location
<command_config_file> is the path to and name of the command configuration file,
relative to current location
<command> is the command to be submitted to TSOC, as in the command reference (see
Using CLI / Shell / SDK Commands on page 16).
For example (on Windows, with both configuration files as created from interactive CLI):
tcli --config_path config.json --config_cmd_path
config_cmd.json create_mwtrap

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 8

 TSOC Python SDK

TSOC Python SDK

The Python SDK is one of the ways for using TSOC commands: For advanced programmatic
solutions, implement SDK commands in a Python environment.

In This Section
Installing the SDK ................................................................................9
Configuring the SDK............................................................................9
Working with the SDK ......................................................................10
SDK Management Commands..........................................................11

Installing the SDK

The TSOC SDK is supported on Windows, MAC OS, and Linux.
Requirements: One of

• Python 2.7 and above

• Python 3.x
To install or upgrade the TSOC SDK, place the provided .whl file on a client computer meeting
the above requirements, and from the file's location run:
pip install trapxsdk-<version>-py2.py3-none-any.whl
where <version> is as in the actual file name. The SDK and all required dependencies are
installed.

Note: The installation process includes downloading some dependencies, which requires
a connection to the internet.

To remove the SDK, run:

pip uninstall trapxsdk

Configuring the SDK

Several parameters affect how the SDK in general works. You can preset their values in a
configuration file, or set values during SDK sessions.
Configuration parameters are:

• tsoc (required): The TSOC address

• api_key (required): TSOC's API key (see the DeceptionGrid Administration Guide)
• api_version : Currently v1.5
• check_certificate (boolean; default is false): Validate TSOC's certificate (if the
certificate has been organizationally signed).
• logfile : Path to file in which to store logs.
• silent (boolean): false = detailed outputs in stdout

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 9

 TSOC Python SDK

• api_exceptions (boolean): false = receive tuple with status instead of detailed

exceptions
• privilege_api_key: Required only for high-privileged actions. Obtain from the
TSOC administration menu.
You can set configuration in the following ways:

• Configuration file: In a configuration file, the parameters should be included in a

single JSON object. For example:
{
"tsoc":"127.0.0.1",
"api_key":"",
"api_version":"v1.0",
"logfile":"",
"silent":True,
"api_exceptions":False
}
You can then specify the configuration file to the SDK in the following ways:
• At SDK top-level class instantiation (see Working with the SDK below)
• During an SDK session, by using the manager.load_config_file command (see
manager.load_config_file on page 14)
• Set values during SDK session: Use manager.update_config (see
manager.update_config on page 15) to directly set one or more configuration values.
Some values can also be directly set at SDK top-level class instantiation (see Working
with the SDK below).
To read the current configuration, use manager.get_config (see manager.get_config on page
13) .

Working with the SDK

In This Section
Starting the SDK................................................................................10
SDK Commands ................................................................................11

Starting the SDK

To load the SDK, in python run:
import trapxsdk
Instantiate the trapxsdk.API class. For example:
api = trapxsdk.API()
You can include the following optional parameters:

• config_file_path : Configuration file (see Configuring the SDK on page 9) path.

• silent (boolean): false = Detailed outputs in stdout. Overrides configuration file
setting, for current session

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 10

 TSOC Python SDK

• api_exceptions (boolean): false = Receive tuple with status instead of detailed

exceptions. Overrides configuration file setting, for current session
• create_default_log (boolean): true = If the configuration file doesn't specify
a log file path, create one anyway in the default location

SDK Commands
SDK commands are methods of the above object, and support python dir and help .
Command top-level payload elements can be passed as arguments, or the payload can be a
JSON object containing those elements. For example, both of the following are equivalent:
api.download_files(event="MWT000000001234", file="binary")
api.download_files({"event":"MWT000000001234","file":"binary"}
)
To list the commands that work via TSOC, use manager.show_supported_commands (see
manager.show_supported_commands on page 14). For example:
api.manager.show_supported_commands()
For each of those commands, you can obtain a command payload template with default
placeholder input values, in one of these ways:

• Use manager.get_command_input_template (see

manager.get_command_input_template on page 13). For example:
api.manager.get_command_input_template(api.show_events,
without_appliance=True)
• To the command, apply .get_template . For example:
api.show_events.get_template(without_appliance=True)

Many commands relate to a specific DeceptionGrid appliance, and so their input includes an
Appliance identifer. You can globally set the current appliance to work with, and then omit
the identifier in subsequent commands, by using manager.set_appliance (see
manager.set_appliance on page 14). To find the currently set appliance, use
manager.get_appliance (see manager.get_appliance on page 12).
Available commands include SDK management commands (see SDK Management Commands
below), and commands to TSOC (see Using CLI / Shell / SDK Commands on page 16).
Sample scripts are available in the DeceptionNet Marketplace.

SDK Management Commands

The following manager. commands relate to how the SDK works, and do not interact with
TSOC.

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 11

 TSOC Python SDK

In This Section
manager.delete_config ....................................................................12
manager.delete_logfile ....................................................................12
manager.get_appliance ....................................................................12
manager.get_command_input_template ........................................13
manager.get_config .........................................................................13
manager.get_config_file_path .........................................................14
manager.load_config_file.................................................................14
manager.set_appliance ....................................................................14
manager.show_supported_commands ...........................................14
manager.update_config ...................................................................15

manager.delete_config

Description

Resets configuration parameters (see Configuring the SDK on page 9). After running this
command, no commands can be run on TSOC until its address and API key are set.

Payload elements

None

Response

The updated empty configuration

manager.delete_logfile

Description

Deletes current log file with all its contents.

Payload elements

None

Response

True (or error)

manager.get_appliance

Description

Retrieve the currently set appliance (see manager.set_appliance on page 14).

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 12

 TSOC Python SDK

Payload elements

None

Response
gid
uid

manager.get_command_input_template

Description

Obtain a template for an SDK command. As an alternative, to the command apply

.get_template .

Payload elements

command :The command for which to retrieve a template

with_description (optional, boolean)
without_appliance (optional, boolean): Omit appliance from template - to work with a
set appliance (see manager.set_appliance on page 14)

Response

Modifyable template for command payload JSON.

Examples

The following are equivalent:

api.manager.get_command_input_template(api.configure_mwtrap,
with_description=True)
api.configure_mwtrap.get_template(without_appliance=True)

manager.get_config

Description

Read the current configuration (see Configuring the SDK on page 9).

Payload elements

None

Response

The current configuration

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 13

 TSOC Python SDK

manager.get_config_file_path

Description

Retrieve the location of the current configuration file (see Configuring the SDK on page 9).

Payload elements

None

Response

The location of the current configuration file

manager.load_config_file

Description

Specify a configuration file (see Configuring the SDK on page 9) to work with.

Payload elements

config_file_path : Location of configuration file to begin working with

show_api_key (optional, boolean): Include API key in command response

Response

The updated configuration

manager.set_appliance

Description

Set the current appliance (see Working with DeceptionGrid Appliances on page 17) for
subsequent commands (in subsequent commands omit Appliance identifer).

Payload elements

One (not both) of:

• appliance : JSON object including Appliance gid and uid .

• gid and uid

Response
gid
uid

manager.show_supported_commands

Description

List the commands that work via TSOC.

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 14

 TSOC Python SDK

Payload elements

None

Response

List of the available SDK commands that use the TSOC REST API

manager.update_config

Description

Directly set one or more configuration values (see Configuring the SDK on page 9).

Payload elements

show_api_key (optional, boolean): Include API key in command response

Configuration values (see Configuring the SDK on page 9)

Response

Updated configuration

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 15

 Using CLI / Shell / SDK Commands

Using CLI / Shell / SDK Commands

The following pages provide information on using CLI / Shell / SDK commands to perform
various TSOC operations. The pages include high-level explanations of TSOC tasks (see CLI /
Shell / SDK High-Level Tasks below), and a detailed command reference (see CLI / Shell / SDK
Command Reference on page 25).

In This Section
CLI / Shell / SDK High-Level Tasks .....................................................16
CLI / Shell / SDK Command Reference .............................................25
Handling Asynchronous Commands ................................................57

CLI / Shell / SDK High-Level Tasks

In This Section
Working with Security Events ..........................................................16
Excepting (Whitelisting) Events ........................................................16
Working with DeceptionGrid Appliances .........................................17
Working with Network Interfaces for Traps ....................................18
Working with Emulation Traps .........................................................19
Customizing Emulation Types ..........................................................20
Mass Deploying Traps ......................................................................24
Working with Deception Tokens ......................................................25
Working with Full OS Linux...............................................................25

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.
To retrieve recorded events that match a specified event filter, use download_events (see
download_events on page 27) .
To delete security events from TSOC, use delete_events (see delete_events on page 27).

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 30)
of these objects, populate their fields and then submit them to define an actual exception (see
create_exception on page 29).

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 16

 Using CLI / Shell / SDK Commands

You can request a list (see list_exceptions on page 30) of an Appliance's configured exceptions.
The returned exceptions have an non-displayed Filter ID field, which is used in
subsequent actions to change the exception (see replace_exception on page 31) or to remove
it (see remove_exception on page 30).

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 18).
In SDK commands, 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 list_appliances (see
list_appliances on page 33). 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 31).
• Initialize: Use initialize_appliance (see initialize_appliance on page 32)
(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 remove_appliance (see
remove_appliance on page 33).
Many commands relate to a specific DeceptionGrid appliance, and so their input includes an
Appliance identifer. You can globally set the current appliance to work with, and then omit
the identifier in subsequent commands, by using manager.set_appliance (see
manager.set_appliance on page 14). To find the currently set appliance, use
manager.get_appliance (see manager.get_appliance on page 12).
DeceptionGrid CLI / SDK Developer's Guide, © TrapX 17
 Using CLI / Shell / SDK Commands

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 17).
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.
• 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 create_interface (see create_interface on page

35) , including setting its configurable properties.
• Reconfigure an existing interface's changeable properties using configure_interface
(see configure_interface on page 34) .
• List existing interfaces and their properties, by specified Appliance, optionally for just
one or more of its specified interfaces, using list_interface (see list_interfaces on page
35) .
• Remove an interface, using remove_interface (see remove_interface on page 37) .
• Retrieve interface names by their trap names, using mwtrap2interface (see
mwtrap2interface on page 44) .

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 18

 Using CLI / Shell / SDK Commands

Working with Emulation Traps

You can manage emulation traps on configured interfaces (see Working with Network
Interfaces for Traps on page 18).
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):

1. Using create_mwtrap (see create_mwtrap on page 42) , 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 clone_mwtrap (see clone_mwtrap on page 41) , copy full configuration
(configuration object + spin data) between specified interfaces.
• Modify the values of an existing configuration object; then, using
configure_mwtrap (see configure_mwtrap on page 41) , apply the configuration
object to the trap.
You can obtain a configuration object for modification in either of the following
ways:
• (b) Using current_mwtrap (see current_mwtrap on page 42) , retrieve the
configuration of an existing configured trap.
• (c) TSOC can provide configuration templates for all supported (preconfigured
or custom) emulation types. Using supported_mwtrap (see
supported_mwtrap on page 47) , you can retrieve a list of emulation types

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 19

 Using CLI / Shell / SDK Commands

supported for a specified Appliance; using mwtrap_templates (see

mwtrap_templates on page 45) , 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.
The following web service emulation fields' values can be replaced with paths to
local files for upload: web_pages (path to ZIPped pages),
ssl_cert_custom , ssl_key_custom (paths to certificate and key files,
non-ZIP).

To be able to subsequently upload spin data for a relevant service of an emulation trap, use
spindata_enable (see spindata_enable on page 46) to allow FTP access; spindata_disable (see
spindata_disable on page 46) to block FTP access; and spindata_status (see spindata_status
on page 47) 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 list_mwtraps (see

list_mwtraps on page 44)
• To find the interfaces on which are configured traps specified by their trap names,
use mwtrap2interface (see mwtrap2interface on page 44)
• To find trap names by specified interfaces, use interface2mwtrap (see
interface2mwtrap on page 44)
To remove a trap from an interface, use remove_mwtrap (see remove_mwtrap on page 45).

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 19).
You can customize emulation types in either of two ways, as in the following sections:

• Start from templates that match the configurations of the existing emulation types
provided by TrapX, and customize details
• Bring Your Own Trap (BYOT): Copy configurations from existing organizational
endpoints, optionally customizing details

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 20

 Using CLI / Shell / SDK Commands

In This Section
Bring Your Own Trap (BYOT) ............................................................20
Customizing Emulation Types from Provided Base Types ...............23
Bring Your Own Trap (BYOT)

You can define custom emulation types (see Customizing Emulation Types above) based on
your own existing organizational endpoints' configurations.
Overview

You can scan a specified endpoint in your network and create a custom trap template
matching the scanned endpoint's OS fingerprint and relevant supported services. You can
automatically (upon scan) make the custom type available in TSOC for trap creation, or you
can customize defaults and available options and then independently make the emulation
type available (see create_custom_trap_type on page 42).
Scanning returns a customizable configuration object that is similar to a regular trap
configuration object, with an additional field for OS fingerprint. You can specify to additionally
save the results to a local file; you can specify to automatically make the custom type available
in TSOC for trap creation, with no further customization.
Requirements

On the same computer from which you're scanning, you'll need to have the following installed:

• Nmap
• For the scanner to also copy web content from the scanned endpoint's web service:
Wget (included in most Linux distributions)
How to Scan

CLI
You can scan from the Interactive CLI (see TSOC Interactive CLI on page 5) by selecting Build
Your Own Trap.
Shell
Scanning by shell command (see TSOC Shell Commands on page 7) uses <command> byot ,
and specifies a command configuration file differently than other commands. The
TSOC connection configuration file is specified and configured as with other commands (see
TSOC Shell Commands on page 7).
Specify the command configuration file with --config_byot_path . You can create a file
template with the interactive CLI (see TSOC Interactive CLI on page 5) (or, run command
get_byot_config_template ).
For example:
tcli --config_path config.json byot --config_byot_path
config_byot.json
Command configuration items are:
DeceptionGrid CLI / SDK Developer's Guide, © TrapX 21
 Using CLI / Shell / SDK Commands

• gid, uid (required even if apply=false ): Appliance identifier (see Working with
DeceptionGrid Appliances on page 17)
• target and custom_type (required): Respectively, IP address of endpoint to be
scanned, and a descriptive name for the custom emulation type. This name will
populate the custom type's operating_system_type field, and will appear in
TSOC.
• nmap_path : Nmap executable
• apply (boolean, optional; default is False): Whether to automatically make the
custom type available in TSOC for trap creation, with no further customization
• output_file (boolean, optional; default is False): Whether to also save results to
a local file (when scanning multiple endpoints - saves to an independent file per
scanned endpoint)
• wget_path (optional, to copy web content from the scanned endpoint's web
service): usually something like
• Linux: /usr/bin/wget
• Windows: C:\Users\Administrator\Downloads\wget.exe
• debug_fast (boolean, optional; default is False): For support/PoC scenarios, can
scan fewer ports. In production should be: False
SDK
The scanning tool is part of the TrapX SDK (see TSOC Python SDK on page 9), enabling scanning
from inside a python interpreter. However, unlike other SDK commands, scanning is
performed by the trapxsdk.Scanner class . You'll still need to provide an instance of the
trapxsdk.API class to the scanner.
To scan:
1. Instantiate the trapxsdk.API class. For example:
api = trapxsdk.API()
2. Instantiate the trapxsdk.Scanner class. Arguments (required) are:
• api : The API instance
• nmap_path : Nmap executable
For example:
scanner = trapxsdk.Scanner(api=api, nmap_path="\Program
Files (x86)\Nmap\nmap.exe")
3. Run the scanner instance's run method with the arguments listed below. For
example:
result =
scanner.run(appliance="{"gid":"Wilds","uid":"WildTest220"}",
apply=False, output_file=False, target=192.168.1.42,
custom_type="MyTypeName", wget_path="/usr/bin/wget")
The arguments are:

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 22

 Using CLI / Shell / SDK Commands

• appliance (required): JSON object identifying the Appliance (see Working with
DeceptionGrid Appliances on page 17), including the Appliance's gid and uid
(if apply=false - irrelevant but still required)
• One of (required):
• target and custom_type : Respectively, IP address of endpoint to be
scanned, and a descriptive name for the custom emulation type. This name
will populate the custom type's operating_system_type field, and the
custom type will appear in TSOC under that name.
• targets : JSON object with key-value pairs where keys are IP addresses and
values are custom type names. Each pair defines an endpoint to be scanned
and the name of the corresponding custom type to be created. For example:
{'ip1': 'custom_type_1', 'ip2': 'custom_type_2', ...}

• apply (boolean, optional; default is False): Whether to automatically make the

custom type available in TSOC for trap creation, with no further customization
• output_file (boolean, optional; default is False): Whether to also save results
to a local file (when scanning multiple endpoints - saves to an independent file
per scanned endpoint)
• wget_path (optional, to copy web content from the scanned endpoint's web
service): usually something like
• Linux: /usr/bin/wget
• Windows: C:\Users\Administrator\Downloads\wget.exe

Customizing Emulation Types from Provided Base Types

You can define custom emulation types (see Customizing Emulation Types on page 20) with
configuration templates that are similar to regular trap configuration objects (see Working
with Emulation Traps on page 19), 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 custom_mwtrap_templates (see
custom_mwtrap_templates on page 43). 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 retrieved using
custom_mwtrap_fingerprints (see custom_mwtrap_fingerprints on page 43).
• Set defaults and available options for OS version, hostname, domain, and enabled
services.

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 23

 Using CLI / Shell / SDK Commands

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
create_custom_trap_type (see create_custom_trap_type on page 42). To subsequently
remove it, use delete_custom_trap_type (see delete_custom_trap_type on page 43).

Mass Deploying Traps

The interactive CLI (see TSOC Interactive CLI on page 5) includes a tool for downloading,
editing, and uploading an Appliance's entire configuration of interfaces and traps. Range-
based syntax enables mass deployment, or you can specify random trap distribution.
This is one of several methods for large-scale deployment.
Using the tool, you can create and edit a JSON representation of an Appliance's entire
collection of interfaces (real and virtual) and traps. You can start from a generic template file
or from a downloaded file of the Appliance's current configuration. When you're finished
editing, the tool overwrites the Appliance's configuration, replacing it with the new
configuration. A backup of the previous configuration is saved.
The editing can be performed by an appropriate external script, enabling automation of the
data configuration.
You can leverage the tool for mass deployment in the following ways:

• Random traps: In the JSON representation, configure one or more traps without
specifying interfaces for them. These trap configurations will be distributed randomly
among configured interfaces that don't have traps.
• Name ranges: Include number ranges in an interface name (parent and/or child part)
to define multiple interfaces: Either in interface configuration name field to create
multiple interfaces, or in trap configuration interface field to apply the trap
configuration to multiple interfaces.
You can append step intervals to ranges (for example, 1-5-2 means 1, 3, and 5).
For example, setting an interface configuration type to alias, and its name to
vlan10-40-10:1-4 (with separately-configured VLAN interfaces vlan10, vlan20,
vlan30, and vlan40) will create for each of those VLAN interfaces four child
VLAN Alias interfaces, to a total of 16 such interfaces: vlan10:1, vlan10:2,… ,
vlan40:3, vlan40:4 .
In trap configuration interface field, you can use a list of ranges to apply the
same trap configuration to them. For example: ["vlan10-40-10:1-
4","eth0:1-5"] will apply trap configuration to 21 child interfaces (16
VLAN Aliases and 5 subinterfaces).

When configuring a range of interfaces, specify the IP address (unless dhcp) and gateway
for the first interface in the range; the rest will be intelligently deduced from the name
pattern. Similarly, when configuring multiple traps, either by random traps or by interface
range, the trap names and hostnames will be intelligently defined based on the provided ones
DeceptionGrid CLI / SDK Developer's Guide, © TrapX 24
 Using CLI / Shell / SDK Commands

and interface pattern. Alternatively, for the trap names you can provide a trap name template
to be used as a base for all multiple-trap configurations in the file.
Upon finishing editing, in addition to the edited file the tool saves a backup of the previous
configuration and the current detailed actual configuration of all individual interfaces and
traps as resulting from random distribution and/or range resolution.
To mass deploy traps, in the interactive CLI (see TSOC Interactive CLI on page 5) select Mass
Config and follow the prompts.

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 list_tokens
on page 49): 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
list_campaigns on page 48), including their existing assigned tokens.
To manage token assignment to campaigns, for any existing campaign you can add tokens (see
assign_tokens on page 48) or remove tokens (see delete_tokens on page 48).

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 51); you
can disable it (see fosl_disable on page 50), or query whether it is currently enabled (see
fosl_status on page 51).
You can revert it to its original state (see fosl_revert on page 51). You can manage its
credentials list by retrieving the current list (see current_fosl_credentials on page 50) or
setting the list (see configure_fosl_credentials on page 50).

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 25

 Using CLI / Shell / SDK Commands

CLI / Shell / SDK Command Reference

In This Section
Asynchronous Tasks Commands ......................................................25
Security Event Commands ...............................................................27
Event Exception Commands .............................................................29
Appliance Commands .......................................................................31
Interface Commands ........................................................................34
Emulation Trap Commands ..............................................................37
Deception Token Commands ...........................................................47
Full OS Linux Commands ..................................................................49
Other Commands .............................................................................52

Asynchronous Tasks Commands

The following commands are available for working with asynchronous tasks (see Handling
Asynchronous Commands on page 57).

In This Section
async_cancel.....................................................................................26
async_status .....................................................................................26
async_cancel

Description

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

Part of workflow for handling asynchronous commands (see Handling Asynchronous
Commands on page 57).

Payload elements
request_id

Response
request_id
status : One of

• started
• in progress
• failed
• succeeded
• cancelled

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 26

 Using CLI / Shell / SDK Commands

log

async_status

Description

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

Payload elements
request_id

Response
request_id
status : One of

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

Security Event Commands

The following commands are available for working with security events.

In This Section
delete_events ...................................................................................27
download_events .............................................................................27
delete_events

Description

Delete from TSOC all security events matching a previous search.

Part of workflow for working with events.

Payload elements

search_id: As received from initial search

Response elements
search_id

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 27

 Using CLI / Shell / SDK Commands

download_events

Retrieve recorded security events, as matching a specified event filter (a set of specified
event criteria), in a specified format (JSON or STIX2 ), and (optionally) their associated files.
This command replaces the following legacy commands, which should no longer be used:
search_events, show_events, download_files, and
cancel_events_search .

Payload elements
api_key
download_binaries : Whether the response should include events' associated binary
files
download_pcaps : Whether the response should include events' associated packet
capture files
format (optional): The requested format of events. One of:

• JSON (default)
• STIX2
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

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 28

 Using CLI / Shell / SDK Commands

• 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)
• attack_type (NIS only): One or more (in array) of
• Trojans & BotCC
• TOR
• Intelligence

Response

Results are saved to a new directory in the CLI / SDK working directory.
Events are 'paginated', with a JSON file for each set of up to 100 events (in array).
Resulting event details indicate whether or not the event has associated files, but do not
include those files themselves; instead, they are provided as separate parts of the response
(as byte sequences). The existence of an event's associated packet capture (PCAP) files (or
not) is indicated in the event details by boolean x_trapx_com_pcap ; of associated binary
files - by boolean x_trapx_com_binary . The response's files are grouped in directories
by type (binary / PCAP); each event's same-type files are included in a ZIP archive (even if only
one file), with the archive's name corresponding with the event's identifier as in event element
x_trapx_com_eventid . Archives of binaries are encrypted with password: MALICIOUS.

Event Exception Commands

The following commands are available for working with Event Exceptions (whitelisting) (see
Excepting (Whitelisting) Events on page 16).

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 29

 Using CLI / Shell / SDK Commands

In This Section
create_exception ..............................................................................29
exception_templates........................................................................30
list_exceptions ..................................................................................30
remove_exception............................................................................30
replace_exception ............................................................................31
create_exception

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

Payload elements

appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 17), including the Appliance's gid and uid
exception : Array of one or more Exception configuration objects, with fields as in
Exception templates (see exception_templates on page 30).

Response elements

None

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

Payload elements

appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 17), 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

templates : Array of Exception configuration object templates.

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 30

 Using CLI / Shell / SDK Commands

list_exceptions

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 replace_exception on page 31) or to remove
it (see remove_exception below).
Part of the workflow for Excepting events (see Excepting (Whitelisting) Events on page 16).

Payload elements

appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 17), 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

exceptions : Array of configured Exceptions, including Filter ID field.

remove_exception

Description

Delete one or more event Exceptions from a specified Appliance.

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

Payload elements

appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 17), including the Appliance's gid and uid
exception : Array of one or more Filter ID s as obtained from listed Exceptions (see
list_exceptions on page 30).

Response elements

None

replace_exception

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

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 31

 Using CLI / Shell / SDK Commands

Payload elements

appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 17), 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 list_exceptions on page 30).

Response elements

None

Appliance Commands
The following commands are available for working with DeceptionGrid Appliances (see
Working with DeceptionGrid Appliances on page 17).

In This Section
appliance_version ............................................................................31
initialize_appliance ...........................................................................32
list_appliances ..................................................................................33
remove_appliance ............................................................................33
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 17).

Payload elements

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

Response elements

List of Appliances, each including:

gid
uid
arch : The Appliance's architecture (for example: FullOS Windows x64)
version

initialize_appliance

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.

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 32

 Using CLI / Shell / SDK Commands

Note: Asynchronous (see Handling Asynchronous Commands on page 57)

Payload elements

appliance : JSON object including:

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

Response elements

Standard asynchronous task response elements (see Handling Asynchronous Commands on

page 57)

list_appliances

Description

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

Payload elements

One (not both) of:

• 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

List of Appliances, each including:

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 33

 Using CLI / Shell / SDK Commands

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

remove_appliance

Description

Remove the Appliance from TSOC.

Payload elements

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

Response elements

None

Interface Commands
The following commands are available for working with Interfaces (see Working with Network
Interfaces for Traps on page 18).

In This Section
configure_interface ..........................................................................34
create_interface ...............................................................................35
list_interfaces ...................................................................................35
mwtrap2interface.............................................................................36
remove_interface .............................................................................37
configure_interface

Description

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

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 34

 Using CLI / Shell / SDK Commands

Payload elements

appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 17), 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

All fields from request payload; In the response, interface also includes

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

create_interface

Description

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

Payload elements

appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 17), 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 18)
• parent (only for subinterface and alias):

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 35

 Using CLI / Shell / SDK Commands

• 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

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

list_interfaces

Description

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

Payload elements

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

Response elements

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

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 36

 Using CLI / Shell / SDK Commands

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

by network segments

mwtrap2interface

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

Payload elements

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

Response elements

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 .

remove_interface

Description

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

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

Payload elements

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

Response elements

All fields from request payload

Emulation Trap Commands

The following commands are available for working with emulation traps (see Working with
Emulation Traps on page 19).

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 37

 Using CLI / Shell / SDK Commands

In This Section
byot...................................................................................................38
clone_mwtrap ..................................................................................41
configure_mwtrap ............................................................................41
create_custom_trap_type ................................................................42
create_mwtrap .................................................................................42
current_mwtrap ...............................................................................42
custom_mwtrap_fingerprints ..........................................................43
custom_mwtrap_templates .............................................................43
delete_custom_trap_type ................................................................43
interface2mwtrap.............................................................................44
list_mwtraps .....................................................................................44
mwtrap2interface.............................................................................44
mwtrap_templates ...........................................................................45
remove_mwtrap ...............................................................................45
spindata_disable ..............................................................................46
spindata_enable ...............................................................................46
spindata_status ................................................................................47
supported_mwtrap ..........................................................................47
byot

You can define custom emulation types (see Customizing Emulation Types on page 20) based
on your own existing organizational endpoints' configurations.
Overview

You can scan a specified endpoint in your network and create a custom trap template
matching the scanned endpoint's OS fingerprint and relevant supported services. You can
automatically (upon scan) make the custom type available in TSOC for trap creation, or you
can customize defaults and available options and then independently make the emulation
type available (see create_custom_trap_type on page 42).
Scanning returns a customizable configuration object that is similar to a regular trap
configuration object, with an additional field for OS fingerprint. You can specify to additionally
save the results to a local file; you can specify to automatically make the custom type available
in TSOC for trap creation, with no further customization.
Requirements

On the same computer from which you're scanning, you'll need to have the following installed:

• Nmap

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 38

 Using CLI / Shell / SDK Commands

• For the scanner to also copy web content from the scanned endpoint's web service:
Wget (included in most Linux distributions)
How to Scan

CLI
You can scan from the Interactive CLI (see TSOC Interactive CLI on page 5) by selecting Build
Your Own Trap.
Shell
Scanning by shell command (see TSOC Shell Commands on page 7) uses <command> byot ,
and specifies a command configuration file differently than other commands. The
TSOC connection configuration file is specified and configured as with other commands (see
TSOC Shell Commands on page 7).
Specify the command configuration file with --config_byot_path . You can create a file
template with the interactive CLI (see TSOC Interactive CLI on page 5) (or, run command
get_byot_config_template ).
For example:
tcli --config_path config.json byot --config_byot_path
config_byot.json
Command configuration items are:

• gid, uid (required even if apply=false ): Appliance identifier (see Working with
DeceptionGrid Appliances on page 17)
• target and custom_type (required): Respectively, IP address of endpoint to be
scanned, and a descriptive name for the custom emulation type. This name will
populate the custom type's operating_system_type field, and will appear in
TSOC.
• nmap_path : Nmap executable
• apply (boolean, optional; default is False): Whether to automatically make the
custom type available in TSOC for trap creation, with no further customization
• output_file (boolean, optional; default is False): Whether to also save results to
a local file (when scanning multiple endpoints - saves to an independent file per
scanned endpoint)
• wget_path (optional, to copy web content from the scanned endpoint's web
service): usually something like
• Linux: /usr/bin/wget
• Windows: C:\Users\Administrator\Downloads\wget.exe
• debug_fast (boolean, optional; default is False): For support/PoC scenarios, can
scan fewer ports. In production should be: False
SDK

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 39

 Using CLI / Shell / SDK Commands

The scanning tool is part of the TrapX SDK (see TSOC Python SDK on page 9), enabling scanning
from inside a python interpreter. However, unlike other SDK commands, scanning is
performed by the trapxsdk.Scanner class . You'll still need to provide an instance of the
trapxsdk.API class to the scanner.
To scan:
1. Instantiate the trapxsdk.API class. For example:
api = trapxsdk.API()
2. Instantiate the trapxsdk.Scanner class. Arguments (required) are:
• api : The API instance
• nmap_path : Nmap executable
For example:
scanner = trapxsdk.Scanner(api=api, nmap_path="\Program
Files (x86)\Nmap\nmap.exe")
3. Run the scanner instance's run method with the arguments listed below. For
example:
result =
scanner.run(appliance="{"gid":"Wilds","uid":"WildTest220"}",
apply=False, output_file=False, target=192.168.1.42,
custom_type="MyTypeName", wget_path="/usr/bin/wget")
The arguments are:
• appliance (required): JSON object identifying the Appliance (see Working with
DeceptionGrid Appliances on page 17), including the Appliance's gid and uid
(if apply=false - irrelevant but still required)
• One of (required):
• target and custom_type : Respectively, IP address of endpoint to be
scanned, and a descriptive name for the custom emulation type. This name
will populate the custom type's operating_system_type field, and the
custom type will appear in TSOC under that name.
• targets : JSON object with key-value pairs where keys are IP addresses and
values are custom type names. Each pair defines an endpoint to be scanned
and the name of the corresponding custom type to be created. For example:
{'ip1': 'custom_type_1', 'ip2': 'custom_type_2', ...}

• apply (boolean, optional; default is False): Whether to automatically make the

custom type available in TSOC for trap creation, with no further customization
• output_file (boolean, optional; default is False): Whether to also save results
to a local file (when scanning multiple endpoints - saves to an independent file
per scanned endpoint)
• wget_path (optional, to copy web content from the scanned endpoint's web
service): usually something like
• Linux: /usr/bin/wget

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 40

 Using CLI / Shell / SDK Commands

• Windows: C:\Users\Administrator\Downloads\wget.exe

clone_mwtrap

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

Payload elements

appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 17), 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

None

configure_mwtrap

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

Payload elements

appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 17), 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 current_mwtrap on page 42) or modified trap template (see
mwtrap_templates on page 45) and includes the interface name to which to apply the trap
configuration.
The following web service emulation fields' values can be replaced with paths to local files for
upload: web_pages (path to ZIPped pages), ssl_cert_custom ,
ssl_key_custom (paths to certificate and key files, non-ZIP).

Response elements

configuration : One or more (in array) configuration objects representing resulting

configuration(s)

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 41

 Using CLI / Shell / SDK Commands

create_custom_trap_type

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

Payload elements

appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 17), 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

template : One or more (in array) resulting new available emulation types

create_mwtrap

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

Payload elements

appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 17), including the Appliance's gid and uid
interface : The interface name (see Working with Network Interfaces for Traps on page
18) on which to enable a trap
trap : A new name for the trap being created

Response elements

None

current_mwtrap

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

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 42

 Using CLI / Shell / SDK Commands

Payload elements

appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 17), 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

configuration : One or more (in array) trap configuration objects

custom_mwtrap_fingerprints

Description

Retrieve OS fingerprint labels supported for customizing emulation types (see Customizing
Emulation Types from Provided Base Types on page 23).

Payload elements

keywords (optional): List of strings by which to filter retrieved labels

Response elements

List of supported fingerprint labels

custom_mwtrap_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 from
Provided Base Types on page 23).

Payload elements

appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 17), 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

templates : One or more (in array) customizable templates

delete_custom_trap_type

Description

Remove one or more customizing emulation types (see Customizing Emulation Types on page
20).

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 43

 Using CLI / Shell / SDK Commands

Payload elements

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

Response elements

None

interface2mwtrap

Description

Retrieve trap names for specified interfaces.

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

Payload elements

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

Response elements

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 .

list_mwtraps

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

Payload elements

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

Response elements

traps : Array of trap names.

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 44

 Using CLI / Shell / SDK Commands

mwtrap2interface

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

Payload elements

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

Response elements

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 .

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

Payload elements

appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 17), 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

templates : Array of configuration object templates.

remove_mwtrap

Description

Remove a trap from a specified interface.

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

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 45

 Using CLI / Shell / SDK Commands

Payload elements

appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 17), including the Appliance's gid and uid
One of:

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

Response elements

None

spindata_disable

Description

Disable previously enabled (see spindata_enable below) 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 19).

Payload elements

appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 17), 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

None

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

Payload elements

appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 17), 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
DeceptionGrid CLI / SDK Developer's Guide, © TrapX 46
 Using CLI / Shell / SDK Commands

client_addr : The IP address from which an FTP client will be allowed to access the
interface

Response elements

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

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

Payload elements

appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 17), 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

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

supported_mwtrap

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

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 47

 Using CLI / Shell / SDK Commands

Payload elements

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

Response elements

traps : Array of emulation types.

Deception Token Commands

The following commands are available for working with deception tokens (see Working with
Deception Tokens on page 25).

In This Section
assign_tokens ...................................................................................48
delete_tokens ...................................................................................48
list_campaigns ..................................................................................48
list_tokens ........................................................................................49
assign_tokens

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

Payload elements

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

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.

delete_tokens

Description

Remove tokens from specified campaigns.

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

Payload elements

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

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 48

 Using CLI / Shell / SDK Commands

Response elements

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.

list_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.
Part of the workflow for managing deception tokens (see Working with Deception Tokens on
page 25).

Payload elements

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 17), including the Appliance's gid and uid,
whose tokens' campaigns to retrieve

Response elements

JSON object where each key is a campaign name, and its value is an array of the campaign's
currently assigned token ID numbers.

list_tokens

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

Payload elements

appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 17), including the Appliance's gid and uid
One of:

• interface : One or more (in array) interface names (see Working with Network
Interfaces for Traps on page 18), 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.

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 49

 Using CLI / Shell / SDK Commands

Response elements

tokens : List of token objects, each including:

• Either interface name or trap name, depending on payload

• id number of the token
• label : Token type

Full OS Linux Commands

The following commands are available for working with Appliance-hosted Full OS Linux (see
Working with Full OS Linux on page 25).

In This Section
configure_fosl_credentials ...............................................................50
current_fosl_credentials ..................................................................50
fosl_disable.......................................................................................50
fosl_enable .......................................................................................51
fosl_revert ........................................................................................51
fosl_status ........................................................................................51
configure_fosl_credentials

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

Payload elements

appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 17), 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

credentials : Resulting JSON collection of current credential pairs, each as

"username":"password"

current_fosl_credentials

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

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 50

 Using CLI / Shell / SDK Commands

Payload elements

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

Response elements

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

Payload elements

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

Response elements

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

Payload elements

appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 17), 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 18). Omit or empty for None (no access).

Response elements

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.
DeceptionGrid CLI / SDK Developer's Guide, © TrapX 51
 Using CLI / Shell / SDK Commands

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

Payload elements

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

Response elements

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

Payload elements

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

Response elements

status : Current status enable / disable

gateway_interface (if status = enable ): Current setting for outbound network
access

Other Commands
The following additional commands are available.

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 52

 Using CLI / Shell / SDK Commands

In This Section
asset_discovery ................................................................................52
asset_inventory ................................................................................53
audit_log ...........................................................................................54
departments .....................................................................................54
asset_retrieve ...................................................................................54
supported_timezones ......................................................................55
supported_versions ..........................................................................55
tsoc_shutdown .................................................................................56
tsoc_version .....................................................................................56
vm_infrastructure ............................................................................56
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

appliance : JSON object identifying the Appliance (see Working with DeceptionGrid
Appliances on page 17), 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

Current (updated) Asset Discovery settings

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:

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 53

 Using CLI / Shell / SDK Commands

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

Payload elements

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

None

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 54

 Using CLI / Shell / SDK Commands

audit_log

Description

Request TSOC audit logs.

Payload elements

None

Response

Byte sequence of a ZIP archive containing the log files (archived even if only a single file).

departments

Description

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

Payload elements

None

Response

JSON array of company / department strings

asset_retrieve

Description

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

Payload elements

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

Response

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

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 55

 Using CLI / Shell / SDK Commands

• hostname : Corresponding hostname, if resolved

• category
• fingerprint : OS fingerprint as defined in the Nmap database
• confidence : Confidence in fingerprint detection, in percent

supported_timezones

Description

Request list of recognized time zones

Payload elements

None

Response elements

All recognized time zones. Element keys are strings such as "UTC" or "Asia/Jerusalem", and
values are strings with the RFC3339 format.

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 (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

api , sdk : Supported version, or range of versions: min and max , if relevant
compatible (boolean, if relevant)

tsoc_shutdown

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

Payload elements
api_key

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 56

 Using CLI / Shell / SDK Commands

None

Response elements

Only standard response elementsNone

tsoc_version

Description

Retrieve TSOC's version.

Payload elements

None

Response elements

TSOC version (string)

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

None

Response elements

JSON array of VM infrastructure strings

Handling Asynchronous Commands

Most commands 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 CLI / Shell / SDK
Command Reference on page 25) as such, are asynchronous, meaning an initial response is
sent immediately. A subsequent command can query for the task's status.
To enable continuity between commands related to a task, the response to the initial
command 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, use async_status (see async_status on page 26) and in the payload specify
the request_id . Alternatively, to cancel the task, use async_cancel (see async_cancel on
page 26) and in the payload specify the request_id .
All responses to initial asynchronous commands, to status queries, and to task cancellation
specify the task's status, with one of the following values:

• started

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 57

 Using CLI / Shell / SDK Commands

• in progress
• failed
• succeeded
• cancelled
The response also includes a detailed log .

DeceptionGrid CLI / SDK Developer's Guide, © TrapX 58

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
• [email protected]
• 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 [email protected].

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 CLI / SDK Developer's Guide, © TrapX 59