Skip to content

Commit

Permalink
[8.12] [Connectors][ServiceNow ITSM, SecOps] Automate screenshots, ad…
Browse files Browse the repository at this point in the history 
…d cross-scope privileges (#172533, #173941) (#174560)
  • Loading branch information
@lcawl
lcawl authored Jan 11, 2024
1 parent a50d386 commit 9554793
Show file tree
Hide file tree
Showing 10 changed files with 436 additions and 145 deletions.
4 changes: 1 addition & 3 deletions docs/management/connectors/action-types/servicenow-itom.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,10 +37,8 @@ Client ID::
The client identifier assigned to your OAuth application.
Client secret::
The client secret assigned to your OAuth application.
JWT key ID::
JWT verifier key ID::
The key identifier assigned to the JWT verifier map of your OAuth application.
Connector name::
The name is used to identify a connector in the management UI connector listing or in the connector list when configuring an action.
Password::
The password for HTTP basic authentication.
Private key::
Expand Down
255 changes: 186 additions & 69 deletions docs/management/connectors/action-types/servicenow-sir.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,18 +12,202 @@ The {sn-sir} connector uses the
https://developer.servicenow.com/dev.do#!/reference/api/sandiego/rest/c_ImportSetAPI[import set API]
to create {sn} security incidents. You can use the connector for rule actions and cases.

[float]
[[define-servicenow-sir-ui]]
=== Create connectors in {kib}

You can create connectors in *{stack-manage-app} > {connectors-ui}*
or as needed when you're creating a rule. You must choose whether to use OAuth for authentication.

[role="screenshot"]
image::management/connectors/images/servicenow-sir-connector-basic.png[{sn-sir} connector using basic auth]
// NOTE: This is an autogenerated screenshot. Do not edit it directly.

[role="screenshot"]
image::management/connectors/images/servicenow-sir-connector-oauth.png[{sn-sir} connector using OAuth]
// NOTE: This is an autogenerated screenshot. Do not edit it directly.

[float]
[[servicenow-sir-connector-configuration]]
==== Connector configuration

{sn-sir} connectors have the following configuration properties:

Client ID::
The client ID assigned to your OAuth application.
Client Secret::
The client secret assigned to your OAuth application.
JWT verifier key ID::
The key identifier assigned to the JWT verifier map of your OAuth application.
Password::
The password for HTTP basic authentication.
Private key::
The RSA private key that you created for use in {sn}.
Private key password::
The password for the RSA private key.
This value is required if you set a password for your private key.
{sn} instance URL::
The full {sn} instance URL.
Use OAuth authentication::
By default, basic authentication is used instead of open authorization (OAuth).
User identifier::
The identifier to use for OAuth type authentication.
This identifier should be the user field you selected during setup.
For example, if the selected user field is `Email`, the user identifier should be the user's email address.
Username::
The username for HTTP basic authentication.

[float]
[[servicenow-sir-action-configuration]]
=== Test connectors

You can test connectors with the <<execute-connector-api,run connector API>> or
as you're creating or editing the connector in {kib}. For example:

[role="screenshot"]
image::management/connectors/images/servicenow-sir-params-test.png[{sn-sir} params test]

{sn-sir} actions have the following configuration properties.

Additional comments::
Additional information for the client, such as how to troubleshoot the issue.
Category::
The category of the incident.
Correlation display::
A descriptive label of the alert for correlation purposes in {sn}.
Correlation ID::
Connectors using the same correlation ID will be associated with the same {sn} incident.
This value determines whether a new {sn} incident will be created or an existing one is updated. Modifying this value is optional; if not modified, the rule ID and alert ID are combined as `{{ruleID}}:{{alert ID}}` to form the correlation ID value in {sn}.
The maximum character length for this value is 100 characters.
+
--
NOTE: Using the default configuration of `{{ruleID}}:{{alert ID}}` ensures that {sn} will create a separate incident record for every generated alert that uses a unique alert ID.
If the rule generates multiple alerts that use the same alert IDs, {sn} creates and continually updates a single incident record for the alert.
--

Description::
The details about the incident.
Priority::
The priority of the incident.
Short description::
A short description for the incident, used for searching the contents of the knowledge base.
Subcategory::
The subcategory of the incident.

[float]
[[servicenow-sir-connector-networking-configuration]]
=== Connector networking configuration

Use the <<action-settings, Action configuration settings>> to customize connector networking configurations, such as proxies, certificates, or TLS settings. You can set configurations that apply to all your connectors or use `xpack.actions.customHostSettings` to set per-host configurations.

[float]
[[configuring-servicenow-sir]]
=== Configure {sn-sir}

{sn} offers free https://developer.servicenow.com/dev.do#!/guides/madrid/now-platform/pdi-guide/obtaining-a-pdi[Personal Developer Instances], which you can use to test incidents.

[float]
[[servicenow-sir-connector-prerequisites]]
=== Prerequisites
==== Prerequisites
After upgrading from {stack} version 7.15.0 or earlier to version 7.16.0 or later, you must complete the following within your {sn} instance before creating a new {sn-sir} connector or <<servicenow-sir-connector-update, updating an existing one>>:

. Install https://store.servicenow.com/sn_appstore_store.do#!/store/application/2f0746801baeb01019ae54e4604bcb0f[Elastic for Security Operations (SecOps)] from the {sn} Store.
. <<servicenow-sir-connector-privileges,Assign cross-scope privileges for the Elastic for Security Operations app>>.
. <<servicenow-sir-connector-prerequisites-integration-user,Create a {sn} integration user and assign it the appropriate roles>>.
. <<servicenow-sir-connector-prerequisites-cors-rule,Create a Cross-Origin Resource Sharing (CORS) rule>>.
. If you use open authorization (OAuth), you must also:
.. <<servicenow-sir-connector-prerequisites-rsa-key,Create an RSA keypair and add an X.509 Certificate>>.
.. <<servicenow-sir-connector-prerequisites-endpoint,Create an OAuth JWT API endpoint for external clients with a JWT Verifiers Map>>.

[float]
[[servicenow-sir-connector-privileges]]
==== Assign cross-scope privileges

The Elastic for Security Operations app requires specific cross-scope privilege records to run successfully.
In particular, you must have a privilege record for the `Elastic for Security Operations` application with the status set to `Allowed` for each of the following targets:

|===
|Target scope|Name|Type|Operation

|Global
|Glide API: string utilities
|Scriptable
|Execute API

|Global
|GlideRecord.insert
|Scriptable
|Execute API

|Global
|GlideRecord.setValue
|Scriptable
|Execute API

|Global
|GlideRecordSecure.getValue
|Scriptable
|Execute API

|Global
|RESTAPIRequest
|Scriptable
|Execute API

|Global
|RESTAPIRequestBody
|Scriptable
|Execute API

|Global
|ScopedGlideElement
|Scriptable
|Execute API

|Global
|ScriptableServiceResultBuilder.setBody
|Scriptable
|Execute API

|Security incident response
|sn_si_incident
|Table
|Read

|Threat intelligence support common
|sn_ti_m2m_task_observable
|Table
|Create

|Threat intelligence support common
|sn_ti_m2m_task_observable
|Table
|Read

|Threat intelligence support common
|sn_ti_observable
|Table
|Create

|Threat intelligence support common
|sn_ti_observable
|Table
|Read

|Threat intelligence support common
|sn_ti_observable_type
|Table
|Read
|===

To access the cross scope privileges table:

1. Log into {sn} and set your application scope to Elastic for Security Operations.
2. Click *All* and search for `sys_scope_privilege`.

For more details, refer to the https://docs.servicenow.com/[{sn} product documentation].


[float]
[[servicenow-sir-connector-prerequisites-integration-user]]
==== Create a {sn} integration user
Expand Down Expand Up @@ -93,71 +277,4 @@ To update a deprecated connector:
.. Install https://store.servicenow.com/sn_appstore_store.do#!/store/application/2f0746801baeb01019ae54e4604bcb0f[Elastic for Security Operations (SecOps)] from the {sn} Store and complete the <<servicenow-sir-connector-prerequisites, required prerequisites>>.
.. Enter the URL of your {sn} instance.
.. Enter the username and password of your {sn} instance.
. Click *Update*.

[float]
[[define-servicenow-sir-ui]]
=== Create connectors in {kib}

You can create connectors in *{stack-manage-app} > {connectors-ui}*
or as needed when you're creating a rule. You must choose whether to use OAuth for authentication.

[role="screenshot"]
image::management/connectors/images/servicenow-sir-connector-basic.png[{sn-sir} connector using basic auth]

[role="screenshot"]
image::management/connectors/images/servicenow-sir-connector-oauth.png[{sn-sir} connector using OAuth]

[float]
[[servicenow-sir-connector-configuration]]
==== Connector configuration

{sn-sir} connectors have the following configuration properties:

Name:: The name of the connector.
Is OAuth:: The type of authentication to use.
URL:: {sn} instance URL.
Username:: Username for HTTP Basic authentication.
Password:: Password for HTTP Basic authentication.
User Identifier:: Identifier to use for OAuth type authentication. This identifier should be the *User field* you selected during setup. For example, if the selected *User field* is *Email*, the user identifier should be the user's email address.
Client ID:: The client ID assigned to your OAuth application.
Client Secret:: The client secret assigned to your OAuth application.
JWT Key ID:: The key ID assigned to the JWT verifier map of your OAuth application.
Private Key:: The RSA private key generated during setup.
Private Key Password:: The password for the RSA private key generated during setup, if set.

[float]
[[servicenow-sir-action-configuration]]
=== Test connectors

You can test connectors with the <<execute-connector-api,run connector API>> or
as you're creating or editing the connector in {kib}. For example:

[role="screenshot"]
image::management/connectors/images/servicenow-sir-params-test.png[{sn-sir} params test]

{sn-sir} actions have the following configuration properties.

Short description:: A short description for the incident, used for searching the contents of the knowledge base.
Priority:: The priority of the incident.
Category:: The category of the incident.
Subcategory:: The subcategory of the incident.
Correlation ID:: Connectors using the same Correlation ID will be associated with the same {sn} incident. This value determines whether a new {sn} incident will be created or an existing one is updated. Modifying this value is optional; if not modified, the rule ID and alert ID are combined as `{{ruleID}}:{{alert ID}}` to form the Correlation ID value in {sn}. The maximum character length for this value is 100 characters.

NOTE: Using the default configuration of `{{ruleID}}:{{alert ID}}` ensures that {sn} will create a separate incident record for every generated alert that uses a unique alert ID. If the rule generates multiple alerts that use the same alert IDs, {sn} creates and continually updates a single incident record for the alert.

Correlation Display:: A descriptive label of the alert for correlation purposes in {sn}.
Description:: The details about the incident.
Additional comments:: Additional information for the client, such as how to troubleshoot the issue.

[float]
[[servicenow-sir-connector-networking-configuration]]
=== Connector networking configuration

Use the <<action-settings, Action configuration settings>> to customize connector networking configurations, such as proxies, certificates, or TLS settings. You can set configurations that apply to all your connectors or use `xpack.actions.customHostSettings` to set per-host configurations.

[float]
[[configuring-servicenow-sir]]
=== Configure {sn-sir}

{sn} offers free https://developer.servicenow.com/dev.do#!/guides/madrid/now-platform/pdi-guide/obtaining-a-pdi[Personal Developer Instances], which you can use to test incidents.
. Click *Update*.
Loading

0 comments on commit 9554793

Please sign in to comment.