github-mirrors/kibana
1
0
Fork 0
mirror of https://github.com/elastic/kibana.git synced 2025-04-23 01:13:23 -04:00
Code Issues Projects Releases Packages Wiki Activity

[Connectors][ServiceNow SecOps] Automate screenshots, add cross-scope privileges (#173941)

Browse source
This commit is contained in:
Lisa Cawley 2024-01-09 12:53:38 -08:00 • committed by GitHub
parent aa1950f655
commit 2614e92c4c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
7 changed files with 259 additions and 87 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/management/connectors/action-types/servicenow-itom.asciidoc
View file

@ -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.

255
docs/management/connectors/action-types/servicenow-sir.asciidoc
View file

@ -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
@ -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*.

40
docs/management/connectors/action-types/servicenow.asciidoc
View file

@ -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:

BIN
docs/management/connectors/images/servicenow-sir-connector-basic.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 222 KiB

After

Width:  |  Height:  |  Size: 248 KiB

Before After
Before After

BIN
docs/management/connectors/images/servicenow-sir-connector-oauth.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 205 KiB

After

Width:  |  Height:  |  Size: 304 KiB

Before After
Before After

1
x-pack/test/screenshot_creation/apps/response_ops_docs/stack_connectors/index.ts
View file

@ -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'));

48
x-pack/test/screenshot_creation/apps/response_ops_docs/stack_connectors/servicenow_sir_connector.ts Normal file
View file

@ -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');
});
});
}