diff --git a/docs/management/connectors/action-types/servicenow-itom.asciidoc b/docs/management/connectors/action-types/servicenow-itom.asciidoc index ea21cb72248f7..2dc6266745336 100644 --- a/docs/management/connectors/action-types/servicenow-itom.asciidoc +++ b/docs/management/connectors/action-types/servicenow-itom.asciidoc @@ -31,7 +31,7 @@ image::management/connectors/images/servicenow-itom-connector-oauth.png[{sn-itom [[servicenow-itom-connector-configuration]] ==== Connector configuration -{sn-itom} connectors have a name and the following configuration properties: +{sn-itom} connectors have the following configuration properties: Client ID:: The client identifier assigned to your OAuth application. diff --git a/docs/management/connectors/action-types/servicenow-sir.asciidoc b/docs/management/connectors/action-types/servicenow-sir.asciidoc index 30ea222aa4e14..da2b37dc1f558 100644 --- a/docs/management/connectors/action-types/servicenow-sir.asciidoc +++ b/docs/management/connectors/action-types/servicenow-sir.asciidoc @@ -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 <> 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 <> 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 <>: . Install https://store.servicenow.com/sn_appstore_store.do#!/store/application/2f0746801baeb01019ae54e4604bcb0f[Elastic for Security Operations (SecOps)] from the {sn} Store. +. <>. . <>. . <>. . If you use open authorization (OAuth), you must also: .. <>. .. <>. +[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 @@ -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 <>. .. 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 <> 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 <> 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*. \ No newline at end of file diff --git a/docs/management/connectors/action-types/servicenow.asciidoc b/docs/management/connectors/action-types/servicenow.asciidoc index db0b9b3183a6f..ab4e18a0ff5b3 100644 --- a/docs/management/connectors/action-types/servicenow.asciidoc +++ b/docs/management/connectors/action-types/servicenow.asciidoc @@ -32,7 +32,7 @@ image::management/connectors/images/servicenow-connector-oauth.png[ServiceNow co [[servicenow-connector-configuration]] ==== Connector configuration -{sn-itsm} connectors have a name and the following configuration properties: +{sn-itsm} connectors have the following configuration properties: Client ID:: The client identifier assigned to your OAuth application. @@ -73,6 +73,8 @@ 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. @@ -83,8 +85,6 @@ 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. Impact:: @@ -135,34 +135,40 @@ from the {sn} store. ==== Assign cross-scope privileges The Elastic for ITSM app requires specific cross-scope privilege records to run successfully. -In particular, you must have a privilege record for the `Elastic for ITSM` application and source scope with a `global` target scope for each of the following targets: +In particular, you must have a privilege record for the `Elastic for ITSM` application with the status set to `Allowed` for each of the following targets: |=== -|Target name, type|Operation|Status +|Target scope|Name|Type|Operation -|GlideRecord.insert, Scriptable +|Global +|GlideRecord.insert +|Scriptable |Execute API -|Allowed -|GlideRecord.setValue, Scriptable +|Global +|GlideRecord.setValue +|Scriptable |Execute API -|Allowed -|GlideRecordSecure.getValue, Scriptable +|Global +|GlideRecordSecure.getValue +|Scriptable |Execute API -|Allowed -|Incident, Table +|Global +|Incident +|Table |Read -|Allowed -|ScriptableServiceResultBuilder.setBody, Scriptable +|Global +|ScriptableServiceResultBuilder.setBody +|Scriptable |Execute API -|Allowed -|ScopedGlideElement, Scriptable +|Global +|ScopedGlideElement +|Scriptable |Execute API -|Allowed |=== To access the cross scope privileges table: diff --git a/docs/management/connectors/images/servicenow-sir-connector-basic.png b/docs/management/connectors/images/servicenow-sir-connector-basic.png index 95cefce154494..1404526f6418d 100644 Binary files a/docs/management/connectors/images/servicenow-sir-connector-basic.png and b/docs/management/connectors/images/servicenow-sir-connector-basic.png differ diff --git a/docs/management/connectors/images/servicenow-sir-connector-oauth.png b/docs/management/connectors/images/servicenow-sir-connector-oauth.png index 3b02087b5a49a..8cac0f7361890 100644 Binary files a/docs/management/connectors/images/servicenow-sir-connector-oauth.png and b/docs/management/connectors/images/servicenow-sir-connector-oauth.png differ diff --git a/x-pack/test/screenshot_creation/apps/response_ops_docs/stack_connectors/index.ts b/x-pack/test/screenshot_creation/apps/response_ops_docs/stack_connectors/index.ts index 5b9afd0ffd32d..a638ab36805d8 100644 --- a/x-pack/test/screenshot_creation/apps/response_ops_docs/stack_connectors/index.ts +++ b/x-pack/test/screenshot_creation/apps/response_ops_docs/stack_connectors/index.ts @@ -65,6 +65,7 @@ export default function ({ loadTestFile, getService }: FtrProviderContext) { loadTestFile(require.resolve('./server_log_connector')); loadTestFile(require.resolve('./servicenow_itom_connector')); loadTestFile(require.resolve('./servicenow_itsm_connector')); + loadTestFile(require.resolve('./servicenow_sir_connector')); loadTestFile(require.resolve('./slack_connector')); loadTestFile(require.resolve('./tines_connector')); loadTestFile(require.resolve('./webhook_connector')); diff --git a/x-pack/test/screenshot_creation/apps/response_ops_docs/stack_connectors/servicenow_sir_connector.ts b/x-pack/test/screenshot_creation/apps/response_ops_docs/stack_connectors/servicenow_sir_connector.ts new file mode 100644 index 0000000000000..4ffb6141875aa --- /dev/null +++ b/x-pack/test/screenshot_creation/apps/response_ops_docs/stack_connectors/servicenow_sir_connector.ts @@ -0,0 +1,48 @@ +/* + * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one + * or more contributor license agreements. Licensed under the Elastic License + * 2.0; you may not use this file except in compliance with the Elastic License + * 2.0. + */ + +import { FtrProviderContext } from '../../../ftr_provider_context'; + +export default function ({ getService, getPageObjects }: FtrProviderContext) { + const commonScreenshots = getService('commonScreenshots'); + const screenshotDirectories = ['response_ops_docs', 'stack_connectors']; + const pageObjects = getPageObjects(['common', 'header']); + const actions = getService('actions'); + const testSubjects = getService('testSubjects'); + + describe('servicenow secops connector', function () { + beforeEach(async () => { + await pageObjects.common.navigateToApp('connectors'); + await pageObjects.header.waitUntilLoadingHasFinished(); + }); + + it('servicenow secops connector screenshots', async () => { + await pageObjects.common.navigateToApp('connectors'); + await pageObjects.header.waitUntilLoadingHasFinished(); + await actions.common.openNewConnectorForm('servicenow-sir'); + await testSubjects.setValue('nameInput', 'ServiceNow SecOps test connector'); + await testSubjects.setValue('credentialsApiUrlFromInput', 'https://dev123.service-now.com'); + await testSubjects.click('input'); + await commonScreenshots.takeScreenshot( + 'servicenow-sir-connector-oauth', + screenshotDirectories, + 1920, + 1600 + ); + await testSubjects.click('input'); + await testSubjects.setValue('connector-servicenow-username-form-input', 'testuser'); + await testSubjects.setValue('connector-servicenow-password-form-input', 'testpassword'); + await commonScreenshots.takeScreenshot( + 'servicenow-sir-connector-basic', + screenshotDirectories, + 1920, + 1400 + ); + await testSubjects.click('euiFlyoutCloseButton'); + }); + }); +}