Incidents Endpoint

Introduction

Incidents are a key resource in the Cisco Cloudlock application. They are triggered by the Cloudlock policy engine when a policys detection criteria results in a match in object (document, field, folder, post, or file). Incidents in the Cloudlock application can be changed manually by a user (by updating incidents fields such as status or severity) or automatically as objects or events are reevaluated by the policy engine. Depending on the incident type, different incident information may be available.

Key information about an incident
Summary - Basic incident information and status
Details - Information about the relevant object(s) associated with this incident
Entity - Information about the object related to the incident
Matches - Matches represent the actual hits within the content (for content type policies)

Incident Resource

Field ID
Type
Description

id

integer

The id is the internal Cloudlock incident id, which can be used to call or update a specific incident

customer_key

string

An empty field to be used as a system ID (a customer can set this or leave it empty)

incident_status

enum

Status of the incident. Possible values: NEW, RESOLVED, IN PROGRESS, DISMISSED

severity

enum

Severity of the incident. Possible values: INFO, WARNING, CRITICAL, ALERT

created_at

timestamp

Incident creation time, in UTC

updated_at

timestamp

Incident last upate time, in UTC

match_count

integer

Total number of matches

extra

list

Additional information related to the incident

entity

resource

Information about the object relating to this incident. See the entity general resource

policy

resource

The policy that triggered the incident. See the policy general resource

matches

resource

List of matches for the incident. See the matches general resource

Incident Filters

Filter
Usage
Example

limit

Determine how many incidents are returned

offset

Indicate the item number to start the result set from

incident_type

Filter based on the incident type

severity

Filter based on the incident severity

policy_id

Filter based on the policy id

created_before

Highly Recomended if you have a large number of incidents: Filter based on incidents created before a given date

created_after

Highly Recomended if you have a large number of incidents: Filter based on incidents created after a given date

updated_before

Highly Recomended if you have a large number of incidents: Filter based on incidents updated before a given date

updated_after

Highly Recomended if you have a large number of incidents: Filter based on incidents updated after a given date

incident_status

Filter based on the incident status

vendor

Filter based on the platform (i.e. google, salesforce etc¦)

customer_key

Filter based on the customer_key field

fields

Return only the selected parent fields. For example you can return only the id and entity fields

Incident Sorting

Filter
Usage
Example

created_at

Sort by the date the incident was created at (- denotes descending order)

flat

Flatten the output to simplify ingestion of data by tabular systems

Incident Endpoint Examples

List Multiple Incidents

[/incidents{?severity}{?policy_id}{?incident_status}{?created_before}{?created_after}{?ext_costumer_id}{?entity_id}{?order}]
List all Incidents [GET]

  • Parameters
    • severity (optional, options, INFO ) ¦ based on the 'severity' Enum.
    • created_before (optional, date, ``) ¦ Created on start date look up period.
    • created_after (optional, date, 2014-02-01 ) ¦ Created on end date look up period.
    • order (optional, date, created_at )
  • Sample Response:
Response 200 (application/json)                
{
 "limit": 2,
 "offset": 0,
 "total": 1783,
 "results": 2,
 "items": [
  {
   "id": "320831601",
   "customer_key": "",
   "incident_status": "IN PROGRESS",
   "severity": "WARNING",
   "created_at": "2014-08-08T05:09:53.218594+00:00",
   "updated_at": "2014-08-08T05:09:52.930752+00:00",
   "match_count": 1,
   "entity": {
    "id": "GM46KpY7xO",
    "name": "Gautum Trentson",
    "mime_type": "",
    "owner_email": "jane@cloudlock.com",
    "owner_name": "Jane Demo",
    "origin_id": "00Qi00000088wrBEAQ",
    "origin_type": "document",
    "direct_url": "https://na15.salesforce.com/00Qi00000088wrBEAQ",
    "vendor": {
     "name": "salesforce"
    },
    "extra": {
     "origin_type_label": "Lead",
     "origin_type_label_plural": "Leads"
    }
   },
   "policy": {
    "id": "eyaznBzYKv",
    "name": "PCI"
   },
   "matches": [
    {
     "created_at": "2014-08-08T05:09:53.218594+00:00",
     "text": "XXXXXXXXXXXX6966",
     "ctx_after": ") -- can we use this on the up",
     "ctx_before": "ard number on an old invoice (",
     "field_name": "Description"
    }
   ]
  },
  {
   "id": "320831602",
   "customer_key": "",
   "incident_status": "IN PROGRESS",
   "severity": "WARNING",
   "created_at": "2014-08-08T05:09:58.861954+00:00",
   "updated_at": "2014-08-08T05:09:58.572845+00:00",
   "match_count": 1,
   "entity": {
    "id": "vXxjnWAexL",
    "name": "Feed Item by John Demo",
    "mime_type": "",
    "owner_email": "demoUser@cloudlockdemo.com",
    "owner_name": "John Demo",
    "origin_id": "0D5i000000jY0GvCAK",
    "origin_type": "document",
    "direct_url": "https://na15.salesforce.com/0D5i000000jY0GvCAK",
    "vendor": {
     "name": "salesforce"
    },
    "extra": {
     "origin_type_label": "Feed Item",
     "origin_type_label_plural": "Feed Items"
    }
   },
   "policy": {
    "id": "Bdb475zMDK",
    "name": "SSN"
   },
   "matches": [
    {
     "created_at": "2014-08-08T05:09:58.861954+00:00",
     "text": "XXX XX 7502",
     "ctx_after": " 638 1\\n",
     "ctx_before": "UPS Tracking Number: 1Z W18 ",
     "field_name": "Body"
    }
   ]
  }
 ]
}

Single Incident

[/incidents/{id}]
You can update 3 fields (descriptions and possible values can be found in the Incident Resource table): 'incident_status', 'severity' and the 'customer_key'.
Retrieve a specific Incident [GET]

  • Parameters
    • id (required, integer, 320831601 )
  • Sample Response:
Response 200 (application/json) 
{
 "id": "320831601",
 "customer_key": "",
 "incident_status": "IN PROGRESS",
 "severity": "WARNING",
 "created_at": "2014-08-08T05:09:58.861954+00:00",
 "updated_at": "2014-08-08T05:09:58.572845+00:00",
 "match_count": 1,
 "entity": {
  "id": "vXxjnWAexL",
  "name": "Feed Item by John Demo",
  "mime_type": null,
  "owner_email": "demoUser@cloudlockdemo.com",
  "owner_name": "John Demo",
  "origin_id": "0D5i000000jY0GvCAK",
  "origin_type": "document",
  "direct_url": "https://na15.salesforce.com/0D5i000000jY0GvCAK",
  "vendor": {
   "name": "salesforce"
  },
  "extra": {
   "origin_type_label": "Feed Item",
   "origin_type_label_plural": "Feed Items"
  }
 },
 "policy": {
  "id": "Bdb475zMDK",
  "name": "SSN"
 },
 "matches": [
  {
   "created_at": "2014-08-08T05:09:58.861954+00:00",
   "text": "XXX XX 7502",
   "ctx_after": " 638 1\n",
   "ctx_before": "UPS Tracking Number: 1Z W18 ",
   "field_name": "Body",
   "policy_criteria": {
    "id": 23
   }
  }
 ]
}

Update a Specific Incident

Update an incident by ID [PUT]

  • Request (application/json)
{ "incident_status": "RESOLVED" }
  • Parameters: id (required, integer, 320831601 )
    Sample Response:
Response 200 (application/json)
{
 "id": "320831601",
 "customer_key": "ExternalID",
 "incident_status": "RESOLVED",
 "severity": "WARNING",
 "created_at": "2014-08-08T05:10:00.326727+00:00",
 "updated_at": "2018-06-16T17:29:39.697785+00:00",
 "match_count": 1,
 "entity": {
  "id": "1MxyLjlA4B",
  "name": "Feed Item by Jane Demo",
  "mime_type": null,
  "owner_email": "jane@cloudlock.com",
  "owner_name": "Jane Demo",
  "origin_id": "0D5i000000XWpE0CAL",
  "origin_type": "document",
  "direct_url": "https://na15.salesforce.com/0D5i000000XWpE0CAL",
  "vendor": {
   "name": "salesforce"
  },
  "extra": {
   "origin_type_label": "Feed Item",
   "origin_type_label_plural": "Feed Items"
  }
 },
 "policy": {
  "id": null,
  "name": "Confidential/Password Regular Expression24",
  "state": null,
  "created_at": null,
  "updated_at": null
 },
 "matches": [
  {
   "text": "Confidential",
   "created_at": "2014-08-08T05:10:00.326727+00:00",
   "field_name": "Body",
   "ctx_after": ".",
   "ctx_before": ""
  }