URL: https://workbench.expel.io/api/v2

The Workbench Public API gives organizations the means to access and manipulate their Expel Workbench data using custom API clients. Want to extract information into your reporting system? Use this API! Have some innovative data science idea for analyzing Expel alert evidence? Use this API! Want to write your own custom browser plugin to make your team's analysts more efficient? Use this API!

The majority of the Workbench API implements the jsonapi spec.

jsonapi-server Post Processing

Only the routes that do not follow the JSON:API spec have been defined in the 'CUSTOM ROUTES' section below.

User authentication is accomplished using the /login API route. This route is used to pass user authentication credentials to the API. If authentication is successful, the /login returns a temporary (default: 13 hours) Bearer Token (access_token) that can be used to access the API.

The request body requires a flat json document with three properties: username, password, and an otp.

    curl 'https://workbench.expel.io/auth/v0/login' \
        -X POST \
        -H 'Content-Type: application/json' \
        --data-binary '{ "username": "sample_user@expel.io", "password": "secret", "otp": "123456" }'
    {
      "access_token": "<access_token>",
      "created_at": 1532537770,
      "expires_in": 46800,
      "token_type": "bearer",
      "user_id": "0796cba8-3c96-4984-8d51-22222381f870",
      "username": "sample_user@expel.io",
      "role": "expel_admin",
      "organization_id": "2ca75135-5a84-4298-b8ba-b5e0fd6fb576",
      "realm": "public"
    }

Note: as an alternative to the otp property, you can pass an X-ExpelInc-Otp http request header with the otp token. This is useful when interfacing with single login frameworks

The otp property or X-ExpelInc-Otp header must be populated with the correct 6 digit two-factor authentication code (e.g. Google Auth code) for authentication to succeed. If the Workbench API is not given an OTP token, authentication will fail with a 401 with the response header X-ExpelInc-Otp set to required.

After authentication, the rest of the API may be accessed using the Bearer Token returned in the access_token field. Pass that token back to the API in the Authorization header using Bearer as the credential type.

    curl 'https://workbench.expel.io/api/v2/expel_alerts' \
        -H 'Authorization: Bearer <access_token>'

Browser authentication uses the same user authentication mechanism described in the previous sections of this document. However, if you wish for the Workbench API to set a browser cookie in addition to a Bearer Token, you can pass the optional X-Accepts-Auth-Cookie http request header set to true.

   curl 'https://workbench.expel.io/auth/v0/login' \
       -D - -o /dev/null \
       -X POST \
       -H 'Content-Type: application/json' \
       -H 'X-Accepts-Auth-Cookie: true' \
       --data-binary '{ "username": "sample_user@expel.io", "password": "secret", "otp": "123456" }'
   . . .
   Set-Cookie: token=<access_token>; Path=/; Expires=Thu, 26 Jul 2018 06:05:41 GMT; HttpOnly; Secure
   . . .

That cookie will then be used to authenticate all future API calls in a browser. The cookie will expire in tandem with the access_token.

API keys are obtained through your Expel Engagement Manager. The API key amounts to a Bearer access_token without an expiration that is tied to a specific API client (as opposed to a specific user). This is particularly useful for daemon services, automated scripts, ETL jobs, etc.
API key Bearer tokens are used in the same manner as the temporary user Bearer tokens as described in the previous sections of this document.

    curl 'https://workbench.expel.io/api/v2/expel_alerts' \
        -H 'Authorization: Bearer <api_key>'

See jsonapi spec for more details of request and response formatting of this request.

Use this route to query or list records of a particular resource type (e.g. investigations, expel_alerts, security_devices, etc). All common query parameters may be used on this route. See Common Query Parameters for information on the available query parameters.

    # querying the expel_alerts resource
    curl 'https://workbench.expel.io/api/v2/expel_alerts` \
        -H 'Authorization: Bearer <access_token>'

See jsonapi spec for more details of request and response formatting of this request.

Use this route to retrieve a specific document. The include query parameter may be used on this route.

    # Get a specific investigation, and include its related expel_alerts in the response.
    curl 'https://workbench.expel.io/api/v2/investigations/10e7bfac-27ff-4381-a0ec-5c479b73342b?include=expel_alerts' \
        -H 'Authorization: Bearer <access_token>'

See jsonapi spec for more details of request and response formatting of this request.

Use this route to create a new document of a particular resource type.

    # Create a new user account
    curl 'https://workbench.expel.io/api/v2/user_accounts' \
        -X POST \
        -H 'Authorization: Bearer <access_token>' \
        -H 'Content-Type: application/json' \
        --data-binary '{
            "data": {
                "type": "user_accounts",
                "attributes": {
                    "display_name": "Sample User",
                    "email": "sample_user@expel.io",
                    "role": "organization_analyst"
                }
            }
        }'

See jsonapi spec for more details of request and response formatting of this request.

Use this route to update fields and/or overwrite relationships on a specific document. The include query parameter may be used on this route to include related resources in the response.

    # Change the title of an investigation AND set (overwrite!) the expel_alerts relationship
    curl 'https://workbench.expel.io/api/v2/investigations/155901f0-d5b1-4158-a1a1-85370c6db07f' \
        -X PATCH
        -H 'Authorization: Bearer <access_token>' \
        -H 'Content-Type: application/json' \
        --data-binary '{
            "data": {
                "type": "investigations",
                "attributes": {
                    "title": "Sample Investigation"
                },
                "relationships": {
                    "expel_alerts": {
                        "data": [
                            { "id": "d3d4edaa-8acc-40f5-bc0a-5d40c910cac0", "type": "expel_alerts" },
                            { "id": "80f72c0f-6f03-421c-8436-61fc9ca6c356", "type": "expel_alerts" }
                        ]
                    }
                }
            }
        }'

See jsonapi spec for more details of request and response formatting of this request.

Use this route to delete a specific document.

    # Delete a timeline entry
    curl 'https://workbench.expel.io/api/v2/timeline_entries/ddd488d8-d0e4-4cbe-bfba-aa3e75a9d103' \
        -X DELETE
        -H 'Authorization: Bearer <access_token>'

See jsonapi spec for more details of request and response formatting of this request.

Use this route to query or list records related to a particular known record. All common query parameters may be used on this route. See Common Query Parameters for information on the available query parameters.

    # querying all expel_alerts related to investigation with the id of 6e8def26-a645-49b6-9688-ed2fd5385726
    curl 'https://workbench.expel.io/api/v2/investigations/6e8def26-a645-49b6-9688-ed2fd5385726/expel_alerts` \
        -H 'Authorization: Bearer <access_token>'

This route is used to query actual related resource records and only offers a GET method. It's behavior is similar to the GET /:resource route. If you are looking to get information about (or modify) the actual relationship links between records, see the various GET|POST|PATCH|DELETE /:resource/:id/relationship/:relationship routes.

See jsonapi spec for more details of request and response formatting of this request.

Use this route to return the meta information about a specific relationship. This route does NOT return the actual related records (see GET /:resource/:id/:relation for that). You can use the ?include=<relation> query parameter to get the records returned in this call, but this is not recommended as the include query parameter is resource intensive, is not paginated, and does not support filtering/sorting. Instead, use this route to discover links and meta information about the relationship.

    # querying information about the vendor_alerts relationship of a specific expel_alert
    curl 'https://workbench.expel.io/api/v2/expel_alerts/27340b1e-6f3f-43f1-9ba5-d7c1d9d0dcae/relationships/vendor_alerts` \
        -H 'Authorization: Bearer <access_token>'

See jsonapi spec for more details of request and response formatting of this request.

Use this route to append new records to an existing relationship on a specific resource.

    # see what expel_alerts are related to a specific investigation
    curl 'http://workbench.expel.io/api/v2/investigations/70f5c8c9-5b7f-4295-a1e6-0e6e4dfa8c6e/expel_alerts?fields%5Bexpel_alerts%5D=id' \
        -H 'Authorization: Bearer <access_token>' \
        | jq '.data[] | .id'
    "a61863e5-e15f-4586-9612-a40bf7e2ab64"
    "20bce40b-654a-4830-91a2-701524b0668a"

    # Append two new expel_alerts to an investigation
    curl 'https://workbench.expel.io/api/v2/investigations/70f5c8c9-5b7f-4295-a1e6-0e6e4dfa8c6e/relationships/expel_alerts' \
        -X POST \
        -H 'Authorization: Bearer <access_token>' \
        -H 'Content-Type: application/json' \
        --data-binary '{
            "data": [
                { "type": "expel_alerts", "id": "6ff0cc08-23b2-4afd-9e98-6aa072c621d5" },
                { "type": "expel_alerts", "id": "6084b93c-506e-4594-87e9-1c0198045b55" }
            ]
        }'

    # check to see if the relationships were appended.  Note that the expel_alerts that were already related to this
    # investigation are still there.
    curl 'http://workbench.expel.io/api/v2/investigations/70f5c8c9-5b7f-4295-a1e6-0e6e4dfa8c6e/expel_alerts?fields%5Bexpel_alerts%5D=id' \
        -H 'Authorization: Bearer <access_token>' \
        | jq '.data[] | .id'
    "a61863e5-e15f-4586-9612-a40bf7e2ab64"
    "20bce40b-654a-4830-91a2-701524b0668a"
    "6ff0cc08-23b2-4afd-9e98-6aa072c621d5"
    "6084b93c-506e-4594-87e9-1c0198045b55"

See jsonapi spec for more details of request and response formatting of this request.

Use this route to overwrite a relationship of a specific resource.

    # see what expel_alerts are related to a specific investigation
    curl 'http://workbench.expel.io/api/v2/investigations/70f5c8c9-5b7f-4295-a1e6-0e6e4dfa8c6e/expel_alerts?fields%5Bexpel_alerts%5D=id' \
        -H 'Authorization: Bearer <access_token>' \
        | jq '.data[] | .id'
    "a61863e5-e15f-4586-9612-a40bf7e2ab64"
    "20bce40b-654a-4830-91a2-701524b0668a"

    # Overwrite the expel_alerts related to this investigation
    curl 'https://workbench.expel.io/api/v2/investigations/70f5c8c9-5b7f-4295-a1e6-0e6e4dfa8c6e/relationships/expel_alerts' \
        -X PATCH \
        -H 'Authorization: Bearer <access_token>' \
        -H 'Content-Type: application/json' \
        --data-binary '{
            "data": [
                { "type": "expel_alerts", "id": "6ff0cc08-23b2-4afd-9e98-6aa072c621d5" },
                { "type": "expel_alerts", "id": "6084b93c-506e-4594-87e9-1c0198045b55" }
            ]
        }'

    # check to see if the relationships were appended.  Note that the expel_alerts that were already related to this
    # investigation have been overwritten!
    curl 'http://workbench.expel.io/api/v2/investigations/70f5c8c9-5b7f-4295-a1e6-0e6e4dfa8c6e/expel_alerts?fields%5Bexpel_alerts%5D=id' \
        -H 'Authorization: Bearer <access_token>' \
        | jq '.data[] | .id'
    "6ff0cc08-23b2-4afd-9e98-6aa072c621d5"
    "6084b93c-506e-4594-87e9-1c0198045b55"

This route can also be used to set parent relationships. Note that when setting a parent relationship like this, "data" is NOT an array, since there can only ever be a single value.

    # Establish a parent security_device for an existing security_device (self-referencing m:1 relationship)

    curl 'https://workbench.expel.io/api/v2/security_devices/4819bb1e-bad4-4b9b-a154-7a9aac9654a2/relationships/parent_security_device' \
        -X PATCH \
        -H 'Authorization: Bearer <access_token>' \
        -H 'Content-Type: application/json' \
        --data-binary '{
            "data": { "type": "security_device", "id": "1dd4ee04-792a-4052-9968-66cf347fe1b7" }
        }'

See jsonapi spec for more details of request and response formatting of this request.

Use this route to unlink specific records in a relationship. Note that unlike traditional HTTP DELETE calls, this call requires a body. Only the records listed in the body will be removed from the relationship.

Tip: If you want to remove all records from the relationship, use PATCH /:resource/:id/relationships/:relation with an empty array!

    # see what expel_alerts are related to a specific investigation
    curl 'http://workbench.expel.io/api/v2/investigations/70f5c8c9-5b7f-4295-a1e6-0e6e4dfa8c6e/expel_alerts?fields%5Bexpel_alerts%5D=id' \
        -H 'Authorization: Bearer <access_token>' \
        | jq '.data[] | .id'
    "a61863e5-e15f-4586-9612-a40bf7e2ab64"
    "20bce40b-654a-4830-91a2-701524b0668a"
    "6ff0cc08-23b2-4afd-9e98-6aa072c621d5"
    "6084b93c-506e-4594-87e9-1c0198045b55"

    # Remove two expel_alerts from this investigation
    curl 'https://workbench.expel.io/api/v2/investigations/70f5c8c9-5b7f-4295-a1e6-0e6e4dfa8c6e/relationships/expel_alerts' \
        -X DELETE \
        -H 'Authorization: Bearer <access_token>' \
        -H 'Content-Type: application/json' \
        --data-binary '{
            "data": [
                { "type": "expel_alerts", "id": "6ff0cc08-23b2-4afd-9e98-6aa072c621d5" },
                { "type": "expel_alerts", "id": "6084b93c-506e-4594-87e9-1c0198045b55" }
            ]
        }'

    # check to see if the relationships were appended.  Note that the expel_alerts that were already related to this
    # investigation are still there.
    curl 'http://workbench.expel.io/api/v2/investigations/70f5c8c9-5b7f-4295-a1e6-0e6e4dfa8c6e/expel_alerts?fields%5Bexpel_alerts%5D=id' \
        -H 'Authorization: Bearer <access_token>' \
        | jq '.data[] | .id'
    "a61863e5-e15f-4586-9612-a40bf7e2ab64"
    "20bce40b-654a-4830-91a2-701524b0668a"

Syntax: ?include=<relation>[,<relation>[...]]

The include query parameter allows you to specify which relationship records you want included in the response. This is useful when you are querying for a record, and want to resolve specific relationship data without making multiple calls.

    # request a specific investigation, and include that investigation's organization and create/update actors in the response.
    curl 'http://workbench.expel.io/api/v2/investigations/aa8492a2-b1f2-4ccb-a4dd-ff76d4903ee9?include=organization,created_by,updated_by' \
        -H 'Authorization: Bearer <access_token>'

Using the include query parameter will have the following effects on the API's response:

1. The data element of the included 1:m ("has many") relationships will be populated with the array of id's

   {
     "data": {
       "attributes": {},
       "relationships": {
         "<relation>": {
           "data": [
             { "type": "<resource>", "id": "<uuid>" },
             { "type": "<resource>", "id": "<uuid>" }
           ]
         }
       }
     },
     "included": []
   }
   

2. The included array at the top level of the response will include the records references in the relationships sections across all returned records.

   {
     "data": {},
     "included": [
       {
         "type": "<resource>",
         "id": "<uuid>",
         "attributes": {},
         "relationships": {}
       },
       {
         "type": "<resource>",
         "id": "<uuid>",
         "attributes": {},
         "relationships": {}
       }
     ]
   }
   

Important performance limitations

• The include query parameter can be resource intensive.
• The records returned by the include query parameter cannot be paginated. It's all or nothing.
• The records returned by the include query parameter cannot be filtered or sorted.

Because of these limitations, it is not recommended to use include when listing multiple records (GET /:resource) that are likely to have a large number of related records (e.g. /investigations?include=expel_alerts or /expel_alerts?include=vendor_alerts). Instead, in cases like these, it may be more efficient to query the relationships you're interested in using separate calls or using includes only for specific records.

    # query all investigations and return all their expel_alerts (NOT RECOMMENDED!  all expel_alerts associated with all
    # investigations returned for each page will be returned without pagination)
    curl 'http://workbench.expel.io/api/v2/investigations?include=expel_alerts
                -H 'Authorization: Bearer <access_token>'

    # query all expel alerts for a specific investigation using includes (warning, no pagination on the expel_alerts)
    curl 'http://workbench.expel.io/api/v2/investigations/aa8492a2-b1f2-4ccb-a4dd-ff76d4903ee9?include=expel_alerts
            -H 'Authorization: Bearer <access_token>'

    # query all expel alerts for a specific investigation using relationships (with pagination, filtering, and sorting available)
    curl 'http://workbench.expel.io/api/v2/investigations/aa8492a2-b1f2-4ccb-a4dd-ff76d4903ee9/expel_alerts
                -H 'Authorization: Bearer <access_token>'

Syntax: ?sort=[+|-]<field>[,[+|-]<field>[...]]

The sort query parameter allows you to sort by a particular attribute of a resource. Each field may be prefixed by a + or - to signify ascending or descending sorts respectively.

    # sort investigations ascending by created_at date.
    curl 'http://workbench.expel.io/api/v2/investigations?sort=created_at' \
        -H 'Authorization: Bearer <access_token>'

    # sort investigations descending by created_at date
    curl 'http://workbench.expel.io/api/v2/investigations?sort=-created_at' \
        -H 'Authorization: Bearer <access_token>'

    # sort investigations by title, and then descending by created_at date
    curl 'http://workbench.expel.io/api/v2/investigations?sort=title,-created_at' \
        -H 'Authorization: Bearer <access_token>'

Note:

• Some columns are aggregates or are derived from data in other upstream systems. These columns may not be sortable.
• There is currently no default sort on any resource, so sorting is highly recommended when paginating data.ing

Syntax: ?page[limit|offset]=<value>

Pagination in the Workbench API uses an limit/offset system. For most resources, the limit is defaulted to 50 if not supplied.

The limit may be set to zero. This is useful if your api client needs a count of records without needing to retrieve the actual content of those records.

The record offset is defaulted to 0 if not supplied.

    # paginate the first 25 records using page[limit]=25&page[offset]=0
    curl 'http://workbench.expel.io/api/v2/investigations?page%5Blimit%5D=25&page%5Boffset%5D=0' \
        -H 'Authorization: Bearer <access_token>'

    # paginate the next 25 records using page[limit]=25&page[offset]=25
    curl 'http://workbench.expel.io/api/v2/investigations?page%5Blimit%5D=25&page%5Boffset%5D=25' \
        -H 'Authorization: Bearer <access_token>'

    # get a count of investigations without actually returning any investigation records (using page[limit]=0).
    curl 'http://workbench.expel.io/api/v2/investigations?page%5Blimit%5D=0' \
            -H 'Authorization: Bearer <access_token>' \
        | jq '.meta.page.total'

Syntax: ?filter[<field>]=[<operator>]<value>

• <field>: The field you want to filter against, surrounded by square brackets ([])
• <operator character>: A single character operator.
• <value>: The operand value.

Workbench supports filtering on most attributes and relationships on most of the resources it serves.

Available Operators

By default (i.e. if no operator is provided), the case-sensitive equals operator is used.

Note: Because the Workbench API only supports a single character operator (long story...), we had to get a bit clever with unicode characters to support certain operators as the API's operator support grew. Remember that the operators will need to be URL Encoded when actually sent to the Workbench API. For brevity, the following examples are NOT url encoded.

Filtering Attributes

Each model has attributes as detailed in the resources documentation. Most attributes on most resources are filterable.

Examples:

• filter[source_reason]=!HUNTING
• filter[created_at]=>2019-02-28T00:00:00.000Z

Filtering Relationship Attributes

Each object may contain relationships. The relationships exist in response.data[].relationships. You can filter based on relationship attributes.

I.e. The investigation model contains the lead_expel_alert relationship containing an expel_alert. The expel_alert model has the attribute created_at. You can filter attributes of a relationship from the investigations API endpoint.

Examples:

• filter[lead_expel_alert][id]=␀
• filter[lead_expel_alert][created_at]=>2019-02-28T00:00:00.000Z

Combining filters

You can apply multiple filters in a single request. All filters are joined using an AND operation with the exception of the equals operator. Multiple equals filters on the same field will be joined using an OR operation.

Examples:

• remediation_actions?filter[status]=CLOSED&filter[status]=IN_PROGRESS : filter for remediation actions where status IN (CLOSED, IN_PROGRESS)
• remediation_actions?filter[status]=CLOSED&filter[status]=IN_PROGRESS&filter[action]=^SomeValue : filter for remediation actions where status IN (CLOSED, IN_PROGRESS) AND action ILIKE 'SomeValue%'
• investigations?filter[lead_expel_alert][id]=␀false&filter[title]=:SomeValue : filter for investigations where lead_expel_alert.id IS NOT NULL AND title ILIKE '%SomeValue%'

Performance

While many of the most commonly filtered attributes in the API's underlying data sources have been optimized and indexed, please keep in mind that there may be attributes that, when filtered, result in slower API response times. This is especially true of nested filters (filters on relationship values) and also on unanchored text search operators (e.g. :/contains)

Examples

    # find investigations where the analyst severity is CRITICAL or HIGH created on or after January 1, 2020.
    curl 'http://workbench.expel.io/api/v2/investigations?filter%5Banalyst_severity%5D=CRITICAL&filter%5Banalyst_severity%5D=HIGH&filter%5Bcreated_at%5D=%3E2020-01-01T00%3A00%3A00Z' \
        -H 'Authorization: Bearer <access_token>'

    # find investigations that have a lead_expel_alert with an expel_name that contains `Windows` (case insensitive)
    curl 'http://workbench.expel.io/api/v2/investigations?filter%5Blead_expel_alert%5D%5Bexpel_name%5D=%3AWindows' \
            -H 'Authorization: Bearer <access_token>'

Syntax: ?flag[<variable>]=<value>

In addition to filter query parameter, as specified by the jsonapi spec, our API supports a custom API query parameter of flags that allows callers to pass variables to the backend. Flags are defined on a resource by resource basis, and will alter the behavior of a given API call.

Scopes

Syntax: ?flag[scope]=<scope_name>

The scope flag enables callers to specify scopes for resources backed by Sequelize. When adding a scope that should be accessible from the API, after adding the scope to the scopes object in the resource model definition, add the scope's name to the api_scopes array to allow it to be accessible via API. You can specify the scope as a comma-delimited string (e.g. flag[scope]=firstScope,secondScope) or as an array (e.g. flag[scope][]=firstScope&flag[scope][]=secondScope).

Examples

• remediation_actions?flag[scope]=assigned_to_expel_but_no_user_assigned: Remediation actions where the assigned_to_org_id === EXPEL_ORGANIZATION_ID && assigned_to_user_id IS NULL.
• expel_alerts?flag[scope]=assigned_to_expel_but_no_user_assigned: Expel alerts where assigned_to_org_id === EXPEL_ORGANIZATION_ID && assigned_to_user_id IS NULL.
• investigations?flag[scope]=assigned_to_expel_but_no_user_assigned: Investigations where assigned_to_org_id === EXPEL_ORGANIZATION_ID && assigned_to_user_id IS NULL.
• investigative_actions?flag[scope]=assigned_to_expel_but_no_user_assigned: Investigative actions where assigned_to_org_id === EXPEL_ORGANIZATION_ID && assigned_to_user_id IS NULL. Will check analysis_assigned_to_org_id/analysis_assigned_to_user_id if the status of the action is in an analysis state (e.g. !RUNNING).

Other scopes

• expel_alerts
  • assigned_to_organization: Expel alerts where assigned_to_org_id === organization_id.
  • assigned_to_organization_user: Expel alerts where assigned_to_org_id === organization_id AND assigned_to_user_id IS NOT NULL.
  • assigned_to_organization_but_no_user_assigned: Expel alerts where assigned_to_org_id === organization_id AND assigned_to_user_id NOT NULL.
  • assigned_to_expel: Expel alerts where assigned_to_org_id === EXPEL_ORGANIZATION_ID.
  • assigned_to_user_account: Expel alerts where assigned_to_org_id === EXPEL_ORGANIZATION_ID AND assigned_to_user_id IS NOT NULL.
  • assigned_to_expel_but_no_user_assigned: Expel alerts where assigned_to_org_id === EXPEL_ORGANIZATION_ID AND assigned_to_user_id NOT NULL.
  • assigned_to_user: Expel alerts assigned to the calling user (e.g. "Assigned to me")
• investigations
  • assigned_to_organization: Investigations where assigned_to_org_id === organization_id.
  • assigned_to_organization_user: Investigations where assigned_to_org_id === organization_id AND assigned_to_user_id IS NOT NULL.
  • assigned_to_organization_but_no_user_assigned: Investigations where assigned_to_org_id === organization_id AND assigned_to_user_id NOT NULL.
  • assigned_to_expel: Investigations where assigned_to_org_id === EXPEL_ORGANIZATION_ID.
  • assigned_to_user_account: Investigations where assigned_to_org_id === EXPEL_ORGANIZATION_ID AND assigned_to_user_id IS NOT NULL.
  • assigned_to_expel_but_no_user_assigned: Investigations where assigned_to_org_id === EXPEL_ORGANIZATION_ID AND assigned_to_user_id NOT NULL.
  • assigned_to_user: Investigations assigned to the calling user (e.g. "Assigned to me")
  • open : Investigations where decision null (open)
  • closed: Investigations where decision is not null (closed)
• remediation_actions
  • assigned_to_organization: Actions where assigned_to_org_id === organization_id.
  • assigned_to_organization_user: Actions where assigned_to_org_id === organization_id AND assigned_to_user_id IS NOT NULL.
  • assigned_to_organization_but_no_user_assigned: Actions where assigned_to_org_id === organization_id AND assigned_to_user_id NOT NULL.
  • assigned_to_expel: Actions where assigned_to_org_id === EXPEL_ORGANIZATION_ID.
  • assigned_to_user_account: Actions where assigned_to_org_id === EXPEL_ORGANIZATION_ID AND assigned_to_user_id IS NOT NULL.
  • assigned_to_expel_but_no_user_assigned: Actions where assigned_to_org_id === EXPEL_ORGANIZATION_ID AND assigned_to_user_id NOT NULL.
  • assigned_to_user: Actions assigned to the calling user (e.g. "Assigned to me")
• investigative_actions
  • completed_auto_actions: Actions that have result_task_id IS NOT NULL
  • assigned_to_organization: Actions where assigned to an organization.
  • assigned_to_organization_user: Actions where assigned to an organization and a user.
  • assigned_to_organization_but_no_user_assigned: Actions assigned to an organization but not yet assigned to a user.
  • assigned_to_expel: Actions where assigned to EXPEL_ORGANIZATION_ID.
  • assigned_to_user_account: Actions where assigned to EXPEL_ORGANIZATION_ID and a user.
  • assigned_to_expel_but_no_user_assigned: Actions assigned to EXPEL_ORGANIZATION_ID but not yet assigned to a user.
  • assigned_to_user: Actions assigned to the calling user (e.g. "Assigned to me")
  • is_assigned_to_a_user: Actions where current_assigned_actor.actor_type === "user" .
  • is_assigned_to_an_organization: Actions where current_assigned_actor.actor_type === "organization".

With the exception of non-jsonapi resources and tasking resources, you can upload csv files to the jsonapi resources exposed by this API.

There are two ways to import csv:

• Option A: text/csv

  If you POST with Content-Type of text/csv, the request body must contain the csv text. Note that field overrides are NOT supported when posting directly as text/csv

• Option B: multipart/form-data

  This is useful for browsers. Create an HTML form with a file input field with the name csv. NOTE: You can add other fields to the form, and these fields will override the values of the csv import (useful for establishing relationships), but these fields MUST COME SEQUENTIALLY BEFORE THE csv FIELD.

The csv MUST contain field headers in the first row. The field headers should match the attribute and relationship names documented in the API; However; the csv upload is more forgiving in its syntax. The field names when uploading a csv are case-insensitive, and spaces MAY be used in lieu of underscores.

Example: Both of the following evaluate to the same field names

• event,comment,is_selected,event_date,investigation
• Event, Comment, Is Selected, Event Date, Investigation

Field mapping

Sometimes a 3rd party csv doesn't have headers that match the headers the API expects. To resolve these issues, the request body can contain an attribute called fields. The value must be formatted as a JSON array of strings and/or objects. If provided, then the only fields explicitly added to the fields array will be included in the import. All other fields will be ignored. To map custom csv field names to API field names, use an object in the format of {"from": "csvField", "to": "apiField"}, The fields request field MUST COME SEQUENTIALLY BEFORE THE csv FIELD.

Example: adding the fields attribute will rename the incoming csv fields to fields accepted by the API

• fields=[ "event", { "from": "message", "to":"comment" }, { "from": "datetime", "to": "event_date"} ]

If there are conflicts (i.e. two csv fields map to the same API field name), then the "winner" will be determined by the order of the fields in the field map, with the first one "winning". NOTE: Only the headers of the csv are checked... the API does NOT check the value of individual rows.

Example: In this example, the message_1 field will be mapped to the event API field. The message_2 field will be ignored. This is because message_2 comes after the message_1 fields map. If the csv had not included a "message_1" header, then the "message_2" header would be used. Think of "message_2' as a "fallback".

• fields=[ { "from": "message_1", "to":"event" }, { "from": "message_2", "to": "event"} ]

  message_1,message_2
  "i win", "i lose"
  

For relationships, use the relationship name as the field name.

• Values for Belongs To (aka Many-To-One) relationships should contain a single guid.
• Values for Has Many (aka One-To-Many or Many-To-Many) relationships are a semi-colon delimited list of guids.

• Upload using Content-Type text/csv with a Many-To-One column included.

  curl -X POST 'http://localhost:7550/api/v2/timeline_entry' -H 'Content-Type: text/csv' --data-binary @- <<-EOF
  event,comment,is_selected,event_date,investigation
  "Lateral movement","Type 3 Network Logon",true,"2018-01-15T21:14:35.000Z",c7195a33-7e66-49d3-a59c-2810f224d03e
  "Exploit execution","Process: ""powershell.exe""",true,"2018-01-15T21:14:36.000Z",c7195a33-7e66-49d3-a59c-2810f224d03e
  "Beacon deployment","C:\Users\admin\appdata\local\temp\payload.exe",false,"2018-01-15T20:14:35.000Z",c7195a33-7e66-49d3-a59c-2810f224d03e
  "MIMIKATZ","C:\Users\admin\appdata\local\temp\1.exe",true,"2018-01-15T20:14:35.000Z",c7195a33-7e66-49d3-a59c-2810f224d03e
  EOF
  

• Upload using Content-Type text/csv with a Many-To-Many column included.

  curl -X POST 'http://localhost:7550/api/v2/expel_alerts' -H 'Content-Type: text/csv' --data-binary @- <<-EOF
  alert_type,expel_name, Vendor Alerts
  CLOUD,Test Alert 1,7962ae2-8b8c-4371-9fc8-376300d3d6e0;1b842323-8f54-4958-b14c-af384dd345cf;
  NETWORK,Test Alert 2,
  SIEM,Test Alert 3,
  ENDPOINT,Test Alert 4,
  EOF
  

• Upload using Content-Type multipart/form-data, overriding the investigation relationship via a form field.

     <!DOCTYPE html>
     <html lang="en">
     <head>
         <meta charset="UTF-8">
         <title>Upload Example</title>
     </head>
     <body>
  
     <!-- NOTE there are loads of libraries that do this stuff for you, but this example is shown in raw HTML5 and
          javascript to as a proof of concept -->
  
     <!-- start with an input field so that the user can select a file -->
     <input type="file" name="csv" id="csv" accept=".csv">
  
     <button id="go">Submit</button>
  
     <script>
         document.getElementById('go').onclick = function () {
  
             const csv = document.getElementById('csv');
  
             // using XHR2 and FormData to send the file so that we can set the authorization headers before
             // sending the file.
             const fd = new FormData();
             // NOTE: field overrides MUST BE appended BEFORE the file field is appended.
             // in this case, we'll override the investigation_id on all imported records so that
             // all the timeline entry rows are associated with with my investigation.
             fd.append("investigation", "c7195a33-7e66-49d3-a59c-2810f224d03e");
  
             // now we can append the file!
             fd.append("csv", csv.files[0]);
  
             const xhr = new XMLHttpRequest();
             xhr.open('POST', '/api/v2/timeline_entry', true);
             // Set headers after request is open
            // replace the <mytoken_here> placeholder with an actual token
             xhr.setRequestHeader('Authorization', 'Bearer <mytoken_here>');
             // Send the form. Bask in the glory of a successfully uploaded csv file!
             xhr.send(fd);
         };
  
     </script>
     </body>
     </html>
  

• Upload using Content-Type multipart/form-data, overriding the fields AND applying a field map (using curl).

   curl -X POST \
      http://localhost:7550/api/v2/timeline_entry \
      -H 'authorization: Bearer ...' \
      -F 'fields=[ "event", { "from": "message", "to":"event" }, { "from": "datetime", "to": "event_date"} ]' \
      -F investigation=cc916c39-d099-4761-a4a8-3d7790d88a93 \
      -F created_by=d5758a91-4f09-4f77-886c-959983e9a533 \
      -F csv=@entries.csv
  

You can also download csv files from some resource endpoints. We currently only support exporting from vendor_alerts and investigations. The signature for exporting csv is GET /api/v2/[resource]/export. The endpoint also supports query filter params: to (datetime), from (datetime) and organization_id (guid) which can be used to further narrow down the result set.

• Exporting resources

  curl -X GET 'http://localhost:7550/api/v2/vendor_alerts/export'
  curl -X GET 'http://localhost:7550/api/v2/investigations/export'
  

• Exporting with filter params

  curl -X GET 'http://localhost:7550/api/v2/vendor_alerts/export?filter[to]=2015-01-01'
  curl -X GET 'http://localhost:7550/api/v2/investigations/export?filter[from]=2011-01-13'
  curl -X GET 'http://localhost:7550/api/v2/vendor_alerts/export?filter[organization_id]=c7195a33-7e66-49d3-a59c-2810f224d03e'
  

Remediation actions include one or more associated remediation action assets. This is because there can be more than one item per remediation action (for example, do CONTAIN_HOSTS action against two HOST assets of value "host-a" and "host-b").

A remediation action asset defines something like the target host (for example, host-a) and/or the target device (for example, Crowdstrike Falcon). Remediation action asset's asset_type field indicates the type of asset it is (for example, HOST, DEVICE, IP_ADDRESS). Assets also have their own status field, which can be open or completed.

Below is the mapping between remediation action_type and the asset_type they support:

• BLOCK_COMMAND_AND_CONTROL_COMMUNICATIONS - Block malicious domains, subdomains, and IPs (for MDR only)

  • DOMAIN_NAME - Domain name that should be blocked or sinkholed
  • IP_ADDRESS - IP address that should be blocked

• BLOCK_KNOWN_BAD_HASHES - Block known bad hashes

  • HASH - A hash object with value containing information about the file to block; specifically the file hash, its hash type, and optional its filename (e.g. {"hash": "<file hash>", "type": "<type of hash (md5, sha1, sha256, sha512)>", "filenames": ["<file name 1>"]})
  • DEVICE - A label for the security device that the host we recommend block hash belongs to (e.g. Crowdstrike Falcon on East Coast, or Microsoft Defender on East Coast). Used for display purposes. The label normally matches the security device "name" field in the security devices model.

• BLOCK_MALICIOUS_DOMAINS_AND_IPS - Block malicious domains, subdomains, URLs, and IPs (for Phishing only)

  • DOMAIN_NAME - Domain name that should be blocked or sinkholed
  • IP_ADDRESS - IP address that should be blocked

• BLOCK_SENDER_ADDRESS - Block sender address (for Phishing only)

  • ACCOUNT - The sender address that should be blocked

• BLOCK_SENDER_DOMAIN - Block sender domain (for Phishing only)

  • DOMAIN_NAME - Domain name that should be blocked

• CONTAIN_HOSTS - Contain hosts (for MDR only)

  • HOST - The recommended host to contain (e.g. host-my-machine)
  • DEVICE - A label for the security device that the host we recommend containment belongs to (e.g. Crowdstrike Falcon on East Coast, or Microsoft Defender on East Coast). Used for display purposes. The label normally matches the security device "name" field in the security devices model.

• CONTAIN_INFECTED_REMOVABLE_MEDIA - Contain infected removable media (for MDR only)

  • HASH - A hash object with value containing information about the removable media to contain (e.g. {"mountedAs": "<removable media file path (e.g. E:)>", "deviceSerialNumber": "<device serial number>"})

• DELETE_MALICIOUS_FILES - Delete malicious files

  • HASH - A hash object with value containing information about the malicious file to remove and the hostname containing the file (e.g. {"hostname": "<host name>", "file": "<file path>"})

• KILL_PROCESS - Kill process

  • HASH - A hash object with value containing information about the process to kill and the hostname running the process (e.g. {"hostname": "<host name>", "process_id": "<process ID>", "process_path": "<absolute process path>"})

• DISABLE_AND_MODIFY_AWS_ACCESS_KEYS - Disable and modify AWS access keys (for MDR only). Deprecated in favor of two separated out DISABLE_AWS_ACCESS_KEYS and ROTATE_AWS_ACCESS_KEYS actions.

  • ACCESS_KEY - The recommended compromised access key to disable or modify

• DISABLE_AWS_ACCESS_KEYS - Deactivate AWS access key (for MDR only).

  • ACCESS_KEY - A hash object with value containing information about the recommended compromised access key to deactivate (e.g. {"access_key_id": "<access key id>")

• ROTATE_AWS_ACCESS_KEYS - Rotate AWS access keys (for MDR only).

  • ACCESS_KEY - A hash object with value containing information about the recommended compromised access key to delete after creation of a different access key (e.g. {"access_key_id": "<access key id>")

• DISABLE_USER_ACCOUNT - Disable accounts (for MDR only)

  • ACCOUNT - The recommended account name to disable (e.g. my-user-account)
  • DEVICE - A label for the security device that the host we recommend disabling account belongs to (e.g. Office 365 on East Coast). Used for display purposes. The label normally matches the security device "name" field in the security devices model.

• MITIGATE_VULNERABILITY - Mitigate vulnerability (for MDR only)

  • HASH - A hash object with value containing information about the vulnerability to mitigate and an optional description (e.g. {"name": "<vulnerability name>", "description": "<description of vulnerability>"})

• OTHER_REMEDIATION - Any custom free-form remediation title (for MDR only)

  • DESCRIPTION - Custom description for this free-form remediation

• REMOVE_AND_BLOCK_EMAIL_FORWARDING_ADDRESS - Remove and block email forwarding address(es) (for MDR only)

  • EMAIL - The compromised email address
  • FORWARDING_ADDRESS - Forwarding address

• REMOVE_COMPROMISED_SYSTEMS_FROM_NETWORK_AWS - Delete compromised instances

  • HASH - A hash object with value containing information about the instance to delete and optional connected cloud account ID (e.g. {"cloudAccount": "<cloud account id>", "compromisedInstances": "<instance id>"})

• REMOVE_COMPROMISED_SYSTEMS_FROM_NETWORK_OTHER - Reimage compromised hosts (for MDR only)

  • HOST - The recommended host to reimage (e.g. host-my-machine)

• REMOVE_INBOX_RULES_FOR_KNOWN_COMPROMISED_ACCOUNTS - Remove inbox rules for known compromised accounts (for MDR only)

  • HASH - A hash object with value containing information about the inbox rule to remove for a given compromised email address (e.g. {"compromisedEmail": "<compromised email address>", "inboxRuleNames": "<inbox rule name>"})

• REMOVE_MALICIOUS_EMAIL - Remove malicious email (Phishing only)

  • HASH - A hash object with value containing information about the sender, subject, and submission date for the email that should be removed (e.g. {"sender": "<sender email address>", "subject": "<email subject>", "submissionDate": "<submission timestamp>"})

• REMOVE_TAP_THREAT_ID - Remove emails using Proofpoint ThreatIDs (Phishing only)

  • HASH - A hash object with value containing information about the thread IDs whose linked emails should be removed (e.g. "623cba1fa44ae31976ea010fdb2c897dcb9c40aa9b4eaa3d6d2a89e1acc86836")

• RESET_CREDENTIALS_* (RESET_CREDENTIALS_AWS, RESET_CREDENTIALS_AZURE, RESET_CREDENTIALS_GCP, RESET_CREDENTIALS_GSUITE, RESET_CREDENTIALS_O365, RESET_CREDENTIALS_OKTA, RESET_CREDENTIALS_OTHER, RESET_CREDENTIALS_SALESFORCE) - Reset credentials

  • ACCOUNT - The recommended affected (category “AFFECTED_ACCOUNT”) or compromised (category “COMPROMISED_ACCOUNT”) to reset credentials for

Server sent events are a means to stream events from the API server to a client application (such as a browser) over an persistent tcp connection (see EventSource spec for more details).

If you are connecting to an sse stream from a browser, there are some shortcomings in the EventSource spec that require the use of a polyfill (Mainly, that the EventSource implementation on most browsers do not support setting headers). To allow API clients to subscribe to events relevant to their organization scope, a polyfill is required that supports setting request headers (specifically, the Authorization header). In our testing, we used the polyfill provided by https://github.com/EventSource/eventsource.

Also, please note that each SSE connection will consume one of the 3 to 10 total http connections allocated to each distinct domain by each of the major browsers. As an alternative, the Workbench API also supports websockets. See Websockets below.

Subscribing to events is as simple as calling GET /api/v2/sse with the proper Authorization headers.

1. GET /api/v2/sse

   In a browser (using the eventsource polyfill)

   <script src="eventsource-polyfill.js"></script>
   <script>const evtSrc = new EventSourcePolyfill(`/api/v2/sse`, { headers: { Authorization: 'Bearer <mytoken_here>' }});</script>
   

   Using curl

   curl -X POST -s  http://localhost:7550/api/v2/sse -H 'Authorization: Bearer <mytoken_here>'
   

   This request will remain open indefinitely, and will follow the specification outlined here: EventSource spec. As events are received by the server, they will be broadcast to the subscribers that are within the scope of the event. To prevent clients (specifically browsers) from timing out a connection due to inactivity in times of infrequent events, a regular heartbeat will be sent to all clients every 30 seconds. This heartbeat will not interfere with the EventSource spec.

2. If using a browser, add event listeners to subscribe to the custom events supported by the API. EventSource.onmessage WILL NOT FIRE

   i.e. do this:

   evtSrc.addEventListener('security_device_status_change', (msg) => console.log('security_device_status_change', msg));
   

   not this

   evtSrc.onmessage = (msg) => console.log(msg); // never fires because the API doesn't throw a 'message' event.
   

Currently, all events will contain a record_id, which will be the id of the record that triggered the event.

These are the supported events:

• security_device_status_change - fires when the status of a security_device changes.
• expel_alert_critical - fires when a critical severity alert is added to the system.
• expel_alert_high - fires when a high severity alert is added to the system

When using a browser EventSource instance, subscribe to these events using evtSource.addEventListener('<event>', handler); e.g.

const evt = new EventSourcePolyfill(url, { headers: { Authorization: 'Bearer <token>'}});
evt.addEventListener('security_device_status_change', (msg) => console.log('security_device_status_change', msg));

Examples

• curl

  # replace <mytoken_here> with an actual auth token
  curl -X POST -s  http://localhost:7550/api/v2/sse -H 'Authorization: Bearer <mytoken_here>'
  :connected
  :heartbeat
  id: a4124f77-1609-48a9-a05d-8b71e3fea284
  event: security_device_status_change
  data: {"record_id":"7dd20e87-9e55-488b-b559-ec0ed3b5aece","type":"UPDATE"}
  
  id: d2ed6848-fda5-457e-afc9-f79f9563bcaf
  event: expel_alert_critical
  data: {"record_id":"7dd20e87-9e55-488b-b559-ec0ed3b5aead","type":"INSERT"}
  
  :heartbeat
  :heartbeat
  :heartbeat
  :heartbeat
  :heartbeat
  

• html

  <!DOCTYPE html>
  <html lang="en">
  <head>
      <meta charset="UTF-8">
      <title>SSE Example</title>
  </head>
  <body onload="connect_sse();">
  
  <!-- NOTE there are loads of libraries that do this stuff for you, but this example is shown in raw HTML5 and
       javascript as a proof of concept -->
  
  <div>
      <ul id="out">
  
      </ul>
  </div>
  
  <!-- using https://github.com/EventSource/eventsource polyfill which supports headers. -->
  <script src="eventsource-polyfill.js"></script>
  <script>
  
      function connect_sse() {
          const out = document.getElementById('out');
          function addLine(line) {
              const li = document.createElement("li");
              li.textContent = line;
              out.appendChild(li);
          }
  
          addLine('connecting to sse stream');
          // see comment about the event source polyfill we're using. https://github.com/EventSource/eventsource
          // replace the <mytoken_here> placeholder with an actual authentication token
          const sse = new EventSourcePolyfill(`/api/v2/sse`, { headers: { Authorization: 'Bearer <mytoken_here>' }});
          sse.onopen = () => addLine('subscribed');
  
          // the sse.onmessage function just subscribes to the 'message' event, which we do not use.
          // instead, subscribe to our custom events.
          sse.addEventListener('security_device_status_change', msg => addLine(`security_device_status_change: ${msg.data}`));
          sse.addEventListener('expel_alert_critical', msg => addLine(`expel_alert_critical: ${msg.data}`));
          sse.addEventListener('expel_alert_high', msg => addLine(`expel_alert_high: ${msg.data}`));
      }
  </script>
  </body>
  </html>
  

The Workbench API supports Websockets using the socket.io javascript library. Currently, the only websocket namespace supported by the API is /sse, which will emit the same events as are emitted by Server Sent Events (/api/v2/sse).

Example

    <!DOCTYPE html>
    <html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>Socket.io Test Page</title>
    </head>
    <body onload="connect_socketio()">
        <h1>Socket.io Test Page</h1>
        <div>
            <input type="text" id="token" />
            <button id="reset">Reset</button>
        </div>
        <div>
            <ul id="out"></ul>
        </div>

        <script>
            function connect_socketio() {
                const out = document.getElementById('out');
                const token = document.getElementById('token');
                const reset = document.getElementById('reset');

                function addLine(line) {
                    const li = document.createElement("li");
                    li.textContent = line;
                    out.appendChild(li);
                }

                let socket;

                function doReset() {
                    if (socket) { socket.disconnect(); }
                    socket = io('/sse', { query: { 'token': token.value }, path: '/api/v2/socket.io' });

                    socket.on('error', err => addLine(`error: ${err.toString()}`));
                    socket.on('connect', () => addLine('connected'));
                    socket.on('disconnect', () => addLine('disconnected'));

                    socket.on('security_device_status_change', msg => addLine(JSON.stringify(msg)));
                    socket.on('expel_alert_critical', msg => addLine(JSON.stringify(msg)));
                    socket.on('expel_alert_high', msg => addLine(JSON.stringify(msg)));
                }

                reset.onclick = doReset;
                doReset();
            }
        </script>
        <script src="./socket.io.dev.js"></script>
    </body>
    </html>