Create or update an external incident | Elastic Security Solution [7.15]

IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

› › ›

« Update connector Endpoint management API »

Create or update an external incidentedit

Creates a new or updates an existing external incident from a Elastic Security case.

The Kibana Console supports only Elasticsearch APIs. Console doesn’t allow interactions with Kibana APIs. You must use curl or another HTTP tool instead. For more information, refer to Console.

You can only send cases to external systems after you have created a connector.

Request URLedit

POST <kibana host>:<port>/api/actions/connector/<connector ID>/_execute

URL partsedit

The URL must include the connector ID. Call Get current connector to retrieve the currently used connector ID, or Find connectors to retrieve all connectors IDs.

Request bodyedit

A JSON object with these fields:

Name	Type	Description	Required
`params`	params	Contains the Elastic Security case details for which you are opening or updating an external incident.	Yes

params schema

Name	Type	Description	Required
`subAction`	String	The action to be performed. When opening or updating cases in external systems, must be: `pushToService`.	Yes
`subActionParams`	subActionParams	Case details to send to external systems.	Yes

subActionParams schema

Name	Type	Description	Required
`incident`	incident	The incident.	Yes
`comments`	Object[]	Array containing case comments: `commentId` (string, required): The comment ID. `comment` (string, required): The comment text.	No

incident schema

Name	Type	Description	Required
`alertId`	String	The alert ID.	No. Valid only for Swimlane connectors.
`caseId`	String	The case ID.	No. Valid only for Swimlane connectors.
`caseName`	String	The case name.	No. Valid only for Swimlane connectors.
`dest_ip`	String	A comma separated list of destination IPs.	No. Valid only for ServiceNow SecOps connectors.
`description`	String	The case description.	No
`externalId`	String	The external incident/issue ID.	No, only required when updating an existing issue.
`impact`	String	ServiceNow ITSM incident impact.	No. Valid only for ServiceNow ITSM connectors.
`incidentTypes`	String	IBM Resilient incident types.	No. Valid only for IBM Resilient connectors.
`issueType`	String	Jira issue type.	No. Valid only for Jira connectors.
`labels`	String	Jira issue labels.	No. Valid only for Jira connectors.
`malware_hash`	String	A comma separated list of malware hashes.	No. Valid only for ServiceNow SecOps connectors.
`malware_url`	String	A comma separated list of malware URLs.	No. Valid only for ServiceNow SecOps connectors.
`name`	String	IBM Resilient organization incident name.	Yes. Valid only for IBM Resilient connectors.
`parent`	String	Jira issue parent.	No. Valid only for Jira connectors.
`priority`	String	Jira issue priority.	No. Valid only for Jira and ServiceNow SecOps connectors.
`ruleName`	String	The name of the alert’s rule.	No. Valid only for Swimlane connectors.
`severity`	String	ServiceNow ITSM incident severity.	No. Valid only for ServiceNow ITSM and Swimlane connectors.
`severityCode`	String	IBM Resilient incident severity code.	No. Valid only for IBM Resilient connectors.
`short_description`	String	ServiceNow incident name.	Yes. Valid only for ServiceNow connectors.
`source_ip`	String	A comma separated list of source IPs.	No. Valid only for ServiceNow SecOps connectors.
`summary`	String	Jira issue title.	Yes. Valid only for Jira connectors.
`urgency`	String	ServiceNow ITSM incident urgency.	No. Valid only for ServiceNow ITSM connectors.

When updating an existing case, call Get case or Find cases to retrieve the externalId. In the case JSON object, the externalId value is stored in the external_service field.

Example requestsedit

Creates a new ServiceNow incident:

POST api/actions/connector/7349772f-421a-4de3-b8bb-2d9b22ccee30/_execute
{
  "params": {
    "subAction": "pushToService",
    "subActionParams": {
      "comments": [
        {
          "commentId": "dda30310-732a-11ea-a0b2-c51ea50a58e2",
          "comment": "That is nothing - Ethan Hunt answered a targeted social media campaign promoting phishy pension schemes to IMF operatives.",
        }
      ],
      "description": "James Bond clicked on a highly suspicious email banner advertising cheap holidays for underpaid civil servants. Operation bubblegum is active.",
      "short_description": "This case will self-destruct in 5 seconds"
    }
  }
}

Updates an existing ServiceNow incident:

POST api/actions/connector/7349772f-421a-4de3-b8bb-2d9b22ccee30/_execute
{
  "params": {
    "subAction": "pushToService",
    "subActionParams": {
      "comments": [
        {
          "commentId": "8ef6d660-732f-11ea-a0b2-c51ea50a58e2",
          "comment": "That is nothing - Ethan Hunt answered a targeted social media campaign promoting phishy pension schemes to IMF operatives.",
        }
      ],
      "externalId": "cc6ef44bdb7300106ba884da0b9619cf",
      "short_description": "This case will self-destruct in 5 seconds"
    }
  }
}

Response codeedit

200: Indicates a successful call.

Response payloadedit

A JSON object with the ID and the URL of the external incident.

Example responseedit

{
  "status": "ok",
  "actionId": "61787f53-4eee-4741-8df6-8fe84fa616f7",
  "data": {
    "title": "INC0010012",
    "id": "62dc3c8bdb7300106ba884da0b9619ea",
    "pushedDate": "2020-03-31T09:01:33.000Z",
    "url": "https://dev78437.service-now.com/nav_to.do?uri=incident.do?sys_id=62dc3c8bdb7300106ba884da0b9619ea",
    "comments": [
      {
        "commentId": "dda30310-732a-11ea-a0b2-c51ea50a58e2",
        "pushedDate": "2020-03-31T09:01:34.000Z"
      }
    ]
  }
}

« Update connector Endpoint management API »