cnasikas commented 2 years ago

Summary

A new connector for ServiceNow ITOM will be created. The connector will offer the minimum functionality needed, namely to add an event [1] to the Event Table in ServiceNow. If needed, the connector will be enhanced in future releases to support more functionality.

The connector will be available only for Alerts and not for Cases.

Technical details

An alert, created from a rule execution, can execute in turn actions with the use of connectors. When the ITOM connector is configured with a rule then for each alert execution an event to the Event table (em_table) will be created.

Event fields

Event fields that should be populated are [2]:

Variable	Description
Source	The name of the event source type. For example, SCOM or SolarWinds.
Source Instance (event_class)	Specific instance of the source. For example, SCOM 2012 on 10.20.30.40
node	The node field should contain an identifier for the Host (Server/Switch/Router/etc.) that the event was triggered for. The value of the node field can be one of the following identifiers of the Host: Name FQDN IP Mac Address If it exists in the CMDB, this value is also used to bind the event to the corresponding ServiceNow CI.
resource	If the event refers to a device, such as, Disk, CPU, or Network Adapter, or to an application or service running on a Host, the name of the device or application must be populated in this field. For example, Disk C:\ or Nic 001 or Trade web application.
em_event.metric_name	Name of the metric that triggered the alert. For example, Used Memory or Total CPU utilization.
type	The type of event. This type might be similar to the metric_name field, but is used for general grouping of event types.
message_key	This value is used for de-duplication of events. For example, there might be two events for the same CI, where one event has CPU of 50% and the next event has CPU of 99%. Where both events must be mapped to the same ServiceNow alert, they should have the same message key. The field can be left empty, in which case the field value defaults to source+node+type+resource+metric_name. The message_key should be populated only when there is a better identifier than the default.
severity	Severity of the event. ServiceNow values for severity range from 1 – Critical to 5 – OK, with the severity of 0 – Clear. Original severity values should be sent as part of the additional information.
additional_info	This field is in JSON key/value format, and is meant to contain any information that might be of use to the user. It does not map to a pre-defined ServiceNow event field. Examples include IDs of objects in the event source, event priority (if it is not the same as severity), assignment group information, and so on. Values in the Additional information field of an Event that are not in JSON key/value format are normalized to JSON format when the event is processed.
time_of_event	Time when the event occurred on the event origin. The format is: yyyy-MM-dd HH:mm:ss. The specified time must be according to GMT.
resolution_state	Optional – To indicate that an event has been resolved or no longer occurring, some event monitors use ‘clear’ severity, while other event monitors use a ‘close’ value for severity. This field is used for those monitors proffering the latter. Valid values are New and Closing.

All fields are of type string and optional.

Add event to the Event table [2]

Request

Method: POST URL: api/global/em/jsonv2 Body:

{
    "records": [
        {
            "source": "SCOM",
            "event_class": "SCOM 2007 on scom.server.com",
            "resource": "C:",
            "node": "name.of.node.com",
            "metric_name": "Percentage Logical Disk Free Space",
            "type": "Disk space",
            "severity": "4",
            "description": "The disk C: on computer V-W2K8-dfg.dfg.com is running out of disk space. The value that exceeded the threshold is 41% free space.",
            "additional_info": "{\"test\": \"yo\"}"
        }
    ]
}

Response:

Status: 200 Data:

{
    "result": {
        "Default Bulk Endpoint": "1 events were inserted"
    }
}

References

[1] Event Management - What is an Event and dealing with events [2] Event collection to the instance using web service API

elasticmachine commented 2 years ago

Pinging @elastic/security-threat-hunting-cases (Team:Threat Hunting:Cases)