Resilient REST API

The Resilient Incident Response Platform is built on the REST API. It provides comprehensive access to platform capabilities: to read and write incident data, and to perform a wide range of administrative functions. The REST API is supported by documentation, client libraries and example code for Python, .NET and Java.

Typical use cases include incident escalation — creating a new incident based on an external event — and enrichment, automation, and reporting. This API gives you access to all the incident data, including tasks, data tables, notes, milestones, artifacts and file attachments.

REST Services, URLs and Data Types

The REST API follows a very regular pattern. Each resource (incident, task, artifact, etc.) is addressed by a unique URL. The structure of the URL usually indicates that one resource is contained within another. For example, the path to organization ID 201 is https://server/rest/orgs/201, and the URL to incident 2345 in this organization is https://server/rest/orgs/201/incidents/2345.

When you GET a resource, the server returns a JSON representation of the value. (We refer to these JSON documents as DTOs, Data Transfer Objects). To create a new object within the resource, POST a JSON document to the parent URL. For example, to create a new artifact within the incident, you should POST the representation of an artifact to https://server/rest/orgs/201/incidents/2345/artifacts. See below for some working examples in Python.

There are two ways to update a resource. The first is to PUT a new version, which directly replaces the previous version. The second, PATCH, allows a partial update to incidents where only specific fields are replaced; this is recommended over PUT, since it reduces conflicts, and provides some explicit ways to declare how conflicts should be handled if they do occur.

Exploring the REST API with gadget

The Python SDK. It is a very simple wrapper for the Resilient REST API, with commands that

  • List incidents
  • Read and write incident data using GET, POST, PUT, PATCH and DELETE
  • Query and search
  • Access other REST endpoints such as phases and tasks, types, users and groups.

To see the ID and name of each incident,

gadget --list

To get the JSON representation of incident number 12345, use the command below.

gadget --get /incidents/12345?handle_format=names

To get a JSON array of the incident’s artifacts:

gadget --get /incidents/12345/artifacts?handle_format=names

To see the properties of a single artifact with ID 789:

gadget --get /incidents/12345/artifacts/789?handle_format=names

Accessing the REST API with Python

Resilient REST API is accessed by importing the Resilient module, with a SimpleClient class that provides methods to access the platform. Here is simple code that connects to the Resilient platform by reading the connection details from your configuration file:

# Use the Resilient API module
import resilient

# Read connection parameters from your configuration file, supplemented from the command-line
parser = resilient.ArgumentParser(config_file=resilient.get_config_file())

opts = parser.parse_args()


# Connect and authenticate to the Resilient organization, to get a SimpleClient
client = resilient.get_client(opts)

It is possible to construct a SimpleClient directly, instead of using the resilient.get_client() helper method. See the Multi-Org Escalation example for how this can be done. For most use cases, you should use the configuration file approach above.

The SimpleClient object then allows us to work with incident data:

# Get a single incident
inc_id = 12345
uri = "/incidents/{}?handle_format=names".format(inc_id)
inc = client.get(uri)

# What is the incident id?
assert(inc_id == inc["id"])

# Print the incident data structure as nicely-formatted JSON
import json
print(json.dumps(inc, indent=2))

Exploring the schema with finfo

The finfo utility, installed with the Python SDK, uses the /types REST API to list the fields and other data types from your Resilient platform. It is a very useful command-line tool for exploring and documenting your Resilient customizations.

The basic usage shows the names of all incident fields. (The output below is for illustration — you will have more fields than this!). Required fields are marked with an asterisk. Required-for-close fields are shown with ‘c’ in the first column. The fields preceded with “properties.” are custom fields, not part of the default system configuration.

$ finfo
Fields:
  city
* discovered_date
  id
  members
* name
  owner_id
  properties.attack_vector
  properties.cyber_kill_chain
  properties.data_breach_type
c resolution_id
c resolution_summary
  severity_code
  start_date
  state
  zip

To list all the field definitions in CSV format, including much more information about each field (its display name, data type, etc.):

finfo --csv

The Resilient data model includes incidents, which contain tasks, notes and other objects; each of these has a type definition. To list all the types:

finfo --types

If you have a customized Resilient platform with a data table named “assets”, you can list the fields of that type:

finfo --type assets