[DOCS] ServiceNow ITSM & SecOps Connector and Application Docs

[nastasha-solomon]

Related issues

• https://github.com/elastic/security-team/issues/1454
• [Connectors] ServiceNow ITSM & SIR Application kibana#105440

Description

Architectural changes to the way Kibana integrates with ServiceNow have been introduced in 7.16. Because of this, there are new requirements for creating and using the ServiceNow ITSM and SecOps connectors with Security rules and cases. ServiceNow ITSM and SecOp connectors that were created prior to 7.16 will be marked as deprecated and missing the correlation ID field.

Along with the aforementioned changes, the ServiceNow SecOps connector has been added to the list of action types (connectors) users can choose from when creating a rule. The same requirements to using this connector type apply (i.e., the Elastic application must be installed on the user's SN instance before creating and using the SN SecOps connector).

In the sections below, I’ll be outlining what users need to know if they want to create new ServiceNow connectors in 7.16 or plan to continue using their “old” connectors after they upgrade. The sections will cover:

• Requirements for integrating Kibana with ServiceNow after upgrading to 7.16
• Creating new ServiceNow ITSM and SecOps connectors for rules and cases
• Working with deprecated ServiceNow connectors
• Updating deprecated ServiceNow connectors

Requirements for integrating Kibana with ServiceNow after upgrading to 7.16

As a pre-requisite to creating new ServiceNow ITSM and SecOps connectors in 7.16, users will need to install the new Elastic applications on their ServiceNow instance. If they don't do this, an error message displays and the user is unable to save the new connector.

The Elastic applications can be downloaded from the ServiceNow app store and ServiceNow provides documentation for installing a ServiceNow application. Users who want to create and use the SN SecOps connector will need to install the Elastic SecOps application from the SN store. To use the SN ITSM connector, they'll need to install the Elastic for Security Operations (SecOps) application on their instance.

NOTE: Messaging within the connector flyout will point to the download page in the ServiceNow store if the application hasn't been installed on the user's SN instance.

Creating new ServiceNow ITSM and SecOps connectors

The steps to creating new ServiceNow ITSM and SecOps connectors for Security rules and cases have not changed.

Working with deprecated ServiceNow connectors

ServiceNow ITSM and SecOp connectors that were created prior to 7.16 will be marked as deprecated when viewing them in the Security app. In the images below, the deprecated connectors have the yellow icon to the right of the connector type and name.

Deprecated connectors will continue to function with the rules and cases they were added to, but will be missing the correlation ID field.

Deprecated connectors also cannot be assigned to a new rule or case, before or after either is created. If the user chooses the deprecated connector for a new rule or case they are creating, an error message displays within the connector and they are unable to save it. The error message indicates that the user will need to create a new connector to update the existing on and links to docs for both (TBD).

Adding a deprecated connector to a new rule

Adding a deprecated connector to a new case

Updating deprecated ServiceNow connectors

Deprecated connectors display a deprecation message that contains an option to update the connector.[Screenshot incoming]

Clicking the upgrade button prompts the Update ServiceNow connector to flyout to appear, which walks the user through the steps to update the connector. Those are:

1. Install the Elastic app from the ServiceNow store.
2. Provide the URL to the user's SN instance.
3. Provide us/ps creds for basic authentication.
4. Click Save to save the connector.

Docs

Docs will need to be added to the Kibana and Security docsets.

Kibana

• Add a section to the following Kibana topics detailing pre-reqs to using the connector:
  (Note to self: Create a doc issue and PR in the kibana-docs repo to track doc updates.)
  • ServiceNow ITSM
  • ServiceNow SecOps
  • ServiceNow ITOM
• Might need to update the description for the correlation ID field and or provide a diagram detailing potential use cases or workflows outside of the default use case.

Security

• Screenshot in step 1 of the Set up alert notifications.
• Most of the Configure external connections topic.

Test Instances

• ServiceNow Cloud Test Environment: IP
• 7.16 Test Environment:
  • URL: https://7c3184f8660145d281e1c9da24aa6117.eastus2.staging.azure.foundit.no:9243/
  • username: nastasha
  • pass: EaFQVOCzdKLP9V4Gp9MbkEvWqfygMPEI

Draft:

https://docs.google.com/document/d/1-wX1s864TU9OhnRZyMGIhMcqxSutAtyFxz748nhp0jc/edit?usp=sharing

[nastasha-solomon]

Merged #1188 and elastic/kibana#117117.