Incidents Endpoint

Introduction

Incidents are a key resource in the Cisco Cloudlock application. They are triggered by the Cloudlock policy engine when a policy detection criteria result in a match in an 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	https://callapi.cloudlock.com/incidents?limit=40
offset	Indicate the item number to start the result set from	https://callapi.cloudlock.com/incidents?offset=20
incident_type	Filter based on the incident type	https://callapi.cloudlock.com/incidents?incident_type=COMPLIANCE
severity	Filter based on the incident severity	https://callapi.cloudlock.com/incidents?severity=CRITICAL
policy_id	Filter based on the policy id	https://callapi.cloudlock.com/incidents?policy_id=rNP3Dd3By0
created_before	Highly Recomended if you have a large number of incidents: Filter based on incidents created before a given date	https://callapi.cloudlock.com/incidents?created_before=2018-01-18T16:55
created_after	Highly Recomended if you have a large number of incidents: Filter based on incidents created after a given date	https://api.cloudlock.com/pi/v2/incidents?created_after=2018-01-18T16:55
updated_before	Highly Recomended if you have a large number of incidents: Filter based on incidents updated before a given date	https://callapi.cloudlock.com/incidents?updated_before=2018-01-18T16:55
updated_after	Highly Recomended if you have a large number of incidents: Filter based on incidents updated after a given date	https://api.cloudlock.com/pi/v2/incidents?updated_after=2018-01-18T16:55
incident_status	Filter based on the incident status	https://callapi.cloudlock.com/incidents?incident_status=RESOLVED
vendor	Filter based on the platform (i.e. google, salesforce etc¦)	https://callapi.cloudlock.com/incidents?vendor=google
customer_key	Filter based on the customer_key field	https://callapi.cloudlock.com/incidents?customer_key=123 abc
fields	Return only the selected parent fields. For example you can return only the id and entity fields	https://callapi.cloudlock.com/incidents?fields=id,entity

Incident Sorting

Filter	Usage	Example
created_at	Sort by the date the incident was created at (- denotes descending order)	https://callapi.cloudlock.com/incidents?order=created_at
flat	Flatten the output to simplify ingestion of data by tabular systems	https://callapi.cloudlock.com/incidents?flat=true

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 lookup period.
created_after (optional, date, 2014-02-01 ) ¦ Created on end date lookup 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": "[email protected]",
    "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": "[email protected]",
    "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": "[email protected]",
  "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": "[email protected]",
  "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": ""
  }