xMatters

Details

ID	`xMatters`
Provider	Thoma Bravo
Category	Utilities
From Version	5.5.0
Docker Image	`demisto/python3:3.12.13.10116658`
Supported Modules	Agentix XSIAM

README

This is an integration for using xMatters.
This integration was integrated and tested with version 1 of xMatters

Configure xMatters in Cortex

Parameter	Description	Required
instance	Your xmatters instance base URL. (i.e. acme.xmatters.com)	True
insecure	Trust any certificate (not secure)	False
proxy	Use system proxy settings	False
username	Username for your xMatters instance.	True
password	Password for your xMatters instance.	True
url	URL of an HTTP trigger in a flow.	True
fetch_type		True
status	Fetch alerts with status (ACTIVE, SUSPENDED)	False
priority	Priority of events to fetch	False
isFetch	Fetch incidents	False
incidentType	Incident type	False
property_name		False
property_value		False
first_fetch	First fetch timestamp (`<number>` `<time unit>`, e.g., 12 hours, 7 days)	False
max_fetch		False

Commands

You can execute these commands from the CLI, as part of an automation, or in a playbook.
After you successfully execute a command, a DBot message appears in the War Room with the command details.

xm-trigger-workflow

sends the event to xMatters

Base Command

xm-trigger-workflow

Input

Argument Name	Description	Required
recipients	Recipients of the xMatters Message	Required
subject	Subject of the xMatters Message	Optional
body	Body of the xMatters Message	Optional
incident_id	Incident ID of Incident referenced	Optional
close_task_id	Id of task to close in playbook. Requires an incident_id as the investigation id.	Optional

Context Output

Path	Type	Description
xMatters.Workflow.request_id	string	Request ID from xMatters

Command Example

!xm-trigger-workflow recipients="Joey" subject="Major Emu Issue" body="The emu has escaped!"

Context Example

{
    "request_id": "93e6b331-2108-424d-872b-8200b476907b"
}

Human Readable Output

Successfully sent a message to xMatters.

xm-get-events

Get events from xMatters.

Base Command

xm-get-events

Input

Argument Name	Description	Required
request_id	The UUID returned from triggering a workflow.	Optional
status	Status of the event.	Optional
priority	Priority of the event.	Optional
from	A date in UTC format that represents the start of the time range you want to search.	Optional
to	A date in UTC format that represents the end of the time range you want to search.	Optional
workflow	The name of the workflow the event is tied to.	Optional
form	The name of the form the event is tied to.	Optional
property_name	An event property name to filter the events	Optional
property_value	An event property value to filter the events	Optional

Context Output

Path	Type	Description
Events	unknown	Events from xMatters.

Command Example

!xm-get-events status=ACTIVE

Context Example

{
    "Events": [
        {
            "Created": "2020-10-13T21:35:07.725+0000",
            "FormName": "Incident",
            "Incident": "7a63abc3-5abf-41ca-969b-80eb678fbf72",
            "Name": "Major Emu Issue\n",
            "PlanName": "Cortex XSOAR",
            "Prioity": "MEDIUM",
            "Properties": null,
            "Status": "ACTIVE",
            "SubmitterName": "admin",
            "Terminated": null
        },
        {
            "Created": "2020-10-13T21:33:58.444+0000",
            "FormName": "Incident",
            "Incident": "388884f1-410b-4eb8-a38e-4973e7151b89",
            "Name": "Major Emu Issue\n",
            "PlanName": "Cortex XSOAR",
            "Prioity": "MEDIUM",
            "Properties": null,
            "Status": "ACTIVE",
            "SubmitterName": "admin",
            "Terminated": null
        }
    ]
}

Human Readable Output

Retrieved Events from xMatters.

xm-get-event

Get a single event from xMatters.

Base Command

xm-get-event

Input

Argument Name	Description	Required
event_id	Unique identifier of the event	Required

Context Output

Path	Type	Description
Event	unknown	Event from xMatters.

Command Example

!xm-get-event event_id=33999001

Context Example

{
    "Event": {
        "Created": "2020-10-13T20:50:24.520+0000",
        "FormName": "Integration Builder: Integration Problem",
        "Incident": "99a7692b-30df-40c4-9a20-edc495ae91f9",
        "Name": "Your xMatters integration has a problem",
        "PlanName": "Integration Builder Notifications",
        "Prioity": "MEDIUM",
        "Properties": null,
        "Status": "ACTIVE",
        "SubmitterName": "xm-support",
        "Terminated": null
    }
}

Human Readable Output

Retrieved Event from xMatters.

Configuration parameters

instance — Your xmatters instance base URL. (i.e. acme.xmatters.com) (required)
insecure — Trust any certificate (not secure)
proxy — Use system proxy settings
username — Username for your xMatters instance. (required)
password — Password for your xMatters instance. (required)
url — URL of an HTTP trigger in a flow. (required)
fetch_type — Fetch Type (required)
status — Fetch alerts with status (ACTIVE, TERMINATED, SUSPENDED)
priority — Priority of events to fetch
isFetch — Fetch incidents
incidentType — Incident type
incidentFetchInterval — Incidents Fetch Interval
property_name — Property Name
property_value — Property Value
first_fetch — First fetch timestamp (<number> <time unit>, e.g., 12 hours, 7 days)
max_fetch — Maximum number of incidents to fetch

Commands (3)

xm-get-event
Get a single event from xMatters.
xm-get-events
Get events from xMatters.
xm-trigger-workflow
sends the event to xMatters.

Source

xMatters.py xMatters_test.py xMatters.yml command_examples.txt xMatters_description.md

Download History Raw

# from xMatters import Client
# from typing import Any, Dict, Tuple, List, Optional, cast
# import unittest


def test_xm_trigger_workflow_command(requests_mock):
    """Tests trigger workflow command

    :param requests_mock:
    :return:
    """
    from xMatters import Client, xm_trigger_workflow_command

    # '7a161a3f-8d53-42de-80cd-92fb017c5a12'
    mock_response = {"requestId": "I GOT ONE!"}

    recipients = "bonnieKat"
    subject = "This glass is offending me."
    body = "I shall push it off the table"
    incident_id = "437"
    close_task_id = "3"

    base_url = (
        "https://acme.xmatters.com/?"
        + "&recipients="
        + recipients
        + "&subject="
        + subject
        + "&body="
        + body
        + "&incident_id="
        + incident_id
        + "&close_task_id="
        + close_task_id
    )

    requests_mock.register_uri("POST", base_url, json=mock_response)

    client = Client(base_url=base_url, verify=False, headers={"Authentication": "Bearer some_api_key"})

    results = xm_trigger_workflow_command(
        client,
        recipients=recipients,
        subject=subject,
        body=body,
        incident_id=incident_id,
        close_task_id=close_task_id,
    )

    assert results.readable_output == "Successfully sent a message to xMatters."


def test_xm_get_events_command(requests_mock):
    from xMatters import Client, xm_get_events_command

    hostname = "https://acme.xmatters.com"
    mock_response = {
        "count": 1,
        "total": 1,
        "data": [
            {
                "id": "116f41dc-395c-4bba-a806-df1eda88f4aa",
                "name": "An customer-reported issue with Monitoring Tool X requires attention",
                "eventType": "USER",
                "plan": {"id": "c56730a9-1435-4ae2-8c7e-b2539e635ac6", "name": "Cat Facts!"},
                "form": {"id": "b593c84c-497d-461d-9521-7d9a2d09a4f3", "name": "Send Fact"},
                "floodControl": False,
                "submitter": {
                    "id": "c21b7cc9-c52a-4878-8d26-82b26469fdc7",
                    "targetName": "bonnieKat",
                    "firstName": "bonnie",
                    "lastName": "Kat",
                    "recipientType": "PERSON",
                    "links": {"self": "/api/xm/1/people/c21b7cc9-c52a-4878-8d26-82b26469fdc7"},
                },
                "priority": "HIGH",
                "incident": "INCIDENT_ID-981006",
                "overrideDeviceRestrictions": False,
                "otherResponseCountThreshold": 2,
                "otherResponseCount": 1,
                "escalationOverride": False,
                "bypassPhoneIntro": False,
                "requirePhonePassword": False,
                "revision": {
                    "id": "34c384ba-eaa4-4278-9ebb-94726232b063",
                    "at": "2019-08-09T16:59:38.371Z",
                    "seq": "21866402165008",
                },
                "eventId": "981006",
                "created": "2016-10-31T22:37:35.301+0000",
                "terminated": "2016-10-31T22:38:40.063+0000",
                "status": "TERMINATED",
                "links": {"self": "/api/xm/1/events/116f41dc-395c-4bba-a806-df1eda88f4aa"},
                "responseCountsEnabled": False,
                "properties": {"Customer reported": True, "Customers affected": 100, "Country#en": "USA"},
            }
        ],
        "links": {"self": "/api/xm/1/events?priority=HIGH&offset=0&limit=100"},
    }

    requests_mock.register_uri("GET", hostname + "/api/xm/1/events?priority=HIGH", json=mock_response)

    client = Client(base_url=hostname, verify=False, headers={"Authentication": "Bearer some_api_key"})

    results = xm_get_events_command(client, priority="HIGH")
    assert results.readable_output.startswith("Retrieved Events from xMatters:")


def test_xm_get_event_command(requests_mock):
    from xMatters import Client, xm_get_event_command

    hostname = "https://acme.xmatters.com"
    mock_response = {
        "id": "116f41dc-395c-4bba-a806-df1eda88f4aa",
        "name": "A family of raccoons has moved into the datacenter. They are pretty good cable runners",
        "eventType": "USER",
        "plan": {"id": "c56730a9-1435-4ae2-8c7e-b2539e635ac6", "name": "DC Monitoring"},
        "form": {"id": "b593c84c-497d-461d-9521-7d9a2d09a4f3", "name": "User Submitted"},
        "floodControl": False,
        "submitter": {
            "id": "c21b7cc9-c52a-4878-8d26-82b26469fdc7",
            "targetName": "bonnieKat",
            "firstName": "bonnie",
            "lastName": "Kat",
            "recipientType": "PERSON",
            "links": {"self": "/api/xm/1/people/c21b7cc9-c52a-4878-8d26-82b26469fdc7"},
        },
        "priority": "HIGH",
        "incident": "INCIDENT_ID-981006",
        "overrideDeviceRestrictions": False,
        "otherResponseCountThreshold": 2,
        "otherResponseCount": 1,
        "escalationOverride": False,
        "bypassPhoneIntro": False,
        "requirePhonePassword": False,
        "revision": {"id": "34c384ba-eaa4-4278-9ebb-94726232b063", "at": "2019-08-09T16:59:38.371Z", "seq": "21866402165008"},
        "eventId": "981006",
        "created": "2016-10-31T22:37:35.301+0000",
        "terminated": "2016-10-31T22:38:40.063+0000",
        "status": "TERMINATED",
        "links": {"self": "/api/xm/1/events/116f41dc-395c-4bba-a806-df1eda88f4aa"},
        "responseCountsEnabled": False,
        "properties": {"Customer reported": True, "Customers affected": 100, "Country#en": "USA"},
    }

    requests_mock.register_uri("GET", hostname + "/api/xm/1/events/34111", json=mock_response)

    client = Client(base_url=hostname, verify=False, headers={"Authentication": "Bearer some_api_key"})

    results = xm_get_event_command(client, event_id="34111")
    assert results.readable_output.startswith('Retrieved Event "34111" from xMatters')


def test_fetch_incidents(requests_mock):
    from xMatters import Client, fetch_incidents

    hostname = "https://acme.xmatters.com"

    client = Client(base_url=hostname, verify=False, headers={"Authentication": "Bearer some_api_key"})

    mock_response = {
        "count": 2,
        "data": [
            {
                "bypassPhoneIntro": False,
                "created": "2020-11-04T16:50:39.929+0000",
                "escalationOverride": False,
                "eventId": "9147637302",
                "eventType": "USER",
                "floodControl": False,
                "form": {"id": "75be94d8-0329-4c97-b4b6-c2da098edb06", "name": "Monitoring Alert Generator"},
                "id": "fbf2fe08-68a3-4417-94d5-e09d68d412c7",
                "incident": "INCIDENT_ID-9147637302",
                "links": {"self": "/api/xm/1/events/fbf2fe08-68a3-4417-94d5-e09d68d412c7"},
                "name": "Hang tight - your alert is on the way!",
                "overrideDeviceRestrictions": False,
                "plan": {"id": "f7836611-e18b-40f2-a435-0288b3823260", "name": "#Demo2020 Sales Engineering Demo Starter"},
                "priority": "HIGH",
                "requirePhonePassword": False,
                "responseCountsEnabled": False,
                "status": "TERMINATED",
                "submitter": {
                    "firstName": "Oscar Admin",
                    "id": "2c831e7c-b0de-433b-a5b0-879a79130c90",
                    "lastName": "Wilde",
                    "links": {"self": "/api/xm/1/people/2c831e7c-b0de-433b-a5b0-879a79130c90"},
                    "recipientType": "PERSON",
                    "targetName": "owilde",
                },
                "terminated": "2020-11-04T16:51:40.619+0000",
            },
            {
                "bypassPhoneIntro": False,
                "created": "2020-11-04T16:27:35.056+0000",
                "escalationOverride": False,
                "eventId": "9146487384",
                "eventType": "USER",
                "floodControl": False,
                "form": {"id": "75be94d8-0329-4c97-b4b6-c2da098edb06", "name": "Monitoring Alert Generator"},
                "id": "b9887e2a-90e7-49a1-8fb6-a648db5948ac",
                "incident": "INCIDENT_ID-9146487384",
                "links": {"self": "/api/xm/1/events/b9887e2a-90e7-49a1-8fb6-a648db5948ac"},
                "name": "Hang tight - your alert is on the way!",
                "overrideDeviceRestrictions": False,
                "plan": {"id": "f7836611-e18b-40f2-a435-0288b3823260", "name": "#Demo2020 Sales Engineering Demo Starter"},
                "priority": "HIGH",
                "requirePhonePassword": False,
                "responseCountsEnabled": False,
                "status": "TERMINATED",
                "submitter": {
                    "firstName": "Oscar",
                    "id": "dc4163ae-8bbf-4007-9616-0cfb6b1dadfa",
                    "lastName": "Wilde",
                    "links": {"self": "/api/xm/1/people/dc4163ae-8bbf-4007-9616-0cfb6b1dadfa"},
                    "recipientType": "PERSON",
                    "targetName": "owilde",
                },
                "terminated": "2020-11-04T16:28:35.909+0000",
            },
        ],
        "links": {"self": "/api/xm/1/events?priority=HIGH&limit=100&offset=0"},
        "total": 2,
    }

    requests_mock.register_uri("GET", hostname + "/api/xm/1/events?priority=HIGH", json=mock_response)

    next_run, incidents = fetch_incidents(client=client, priority="HIGH", first_fetch_time=1594250101)

    assert len(incidents) == 2

    mock_response = {"count": 0, "total": 0, "data": [], "links": {"self": "/api/xm/1/events?limit=100&offset=0&status=ACTIVE"}}

    requests_mock.register_uri("GET", hostname + "/api/xm/1/events?status=ACTIVE", json=mock_response)

    next_run, incidents = fetch_incidents(client=client, alert_status="ACTIVE", first_fetch_time=1594250101)

    assert len(incidents) == 0