Sensu Go ServiceNow Handler

Table of Contents

• Overview
• Usage
  • ServiceNow CMDB Registration
  • ServiceNow CMDB Discovery
  • ServiceNow Incident Management
  • ServiceNow Event Management
• Configuration
  • Asset registration
  • Pipeline definition
  • Environment variables
  • Annotations
  • Templates
  • Proxy support

Overview

The Sensu Go ServiceNow handler is a Sensu Event Pipeline that provides deep integration between Sensu and ServiceNow, including:

• CMDB Registration — keep the ServiceNow CMDB up-to-date with your Sensu entity inventory
• CMDB Discovery — keep Sensu Entities up-to-date with ServiceNow CMDB properties
• Incident Management — create and resolve ServiceNow Incidents for Sensu monitoring events
• Event Management — send Sence monitoring event data to ServiceNow for reporting and analysis

Usage

Sensu Go integraiton for ServiceNow CMDB, Incident Management, and Event Management

Usage:
  sensu-servicenow-handler [flags]
  sensu-servicenow-handler [command]

Available Commands:
  help        Help about any command
  version     Print the version number of this plugin

Flags:
  -h, --help                                  help for sensu-servicenow-handler
  -U, --url string                            ServiceNow URL (e.g. https://yourcompany.service-now.com:443)
  -u, --username string                       ServiceNow username
  -p, --password string                       ServiceNow password
      --timeout string                        ServiceNow timeout (default "10s")
      --api-key string                        Sensu API Key (only used when --cmdb-discovery is enabled)
      --api-url string                        Sensu API URL (only used when --cmdb-discovery is enabled) (default "http://127.0.0.1:8080")
      --cmdb-registration                     Enable ServiceNow CMDB registration
      --cmdb-table string                     ServiceNow CMDB table name (default "cmdb_ci")
      --cmdb-key string                       ServiceNow CMDB key field name (used for looking up & updating existing CMDB records) (default "name")
      --cmdb-name string                      ServiceNow CMDB CI name used for looking up & updating existing CMDB records (supports handler templating) (default "{{ .Entity.Name }}")
      --cmdb-asset-tag string                 ServiceNow CMDB CI asset tag (supports handler templating) (default "sensu/{{ .Entity.Namespace }}/{{ .Entity.Name }}")
      --cmdb-properties string                Comma-separated list of ServiceNow CMDB table properties to manage
      --cmdb-discovery                        Enable ServiceNow CMDB discovery (Sensu entity enrichment)
      --cmdb-discovery-subscriptions string   Comma-separated list of fieldnames; for use with ServiceNow CMDB discovery (only used when --cmdb-discovery is enabled)
      --cmdb-discovery-labels string          Comma-separated list of label=fieldname pairs; for use with ServiceNow CMDB discovery (only used when --cmdb-discovery is enabled) (default "servicenow_sys_id=sys_id,servicenow_sys_class_name=sys_class_name")
      --cmdb-discovery-annotations string     Comma-separated list of annotation=fieldname pairs; for use with ServiceNow CMDB discovery (only used when --cmdb-discovery is enabled)
      --incident-management                   Enable ServiceNow Incident Management
      --incident-table string                 ServiceNow Incident table name (default "incident")
      --incident-key string                   ServiceNow Incident key field name used for looking up & updating existing incidents (default "short_description")
      --incident-description string           ServiceNow Incident description (supports handler templating) (default "{{ .Check.State }}")
      --incident-work-notes string            ServiceNow Incident Work Notes (supports handler templating) (default "{{ .Check.Output }}")
      --incident-comments string              ServiceNow Incident Additional Comments (supports handler templating)
      --incident-properties string            Comma-separated list of ServiceNow Incident table properties to manage
      --event-management                      Enable ServiceNow Event Management
      --event-table string                    ServiceNow Event table name (default "em_event")
      --event-additional-info string          ServiceNow Event Additional Info (supports handler templating)
      --event-properties string               Comma-separated list of ServiceNow Event table properties to manage

      --property-annotation-prefix string     Sensu annotation prefix for custom ServiceNow Table properties (default "servicenow/table")

Use "sensu-servicenow-handler [command] --help" for more information about a command.

ServiceNow CMDB Registration

Servicenow CMDB registration is enabled with the --cmdb-registration argument.

Example

---
type: Handler
api_version: core/v2
metadata:
  name: servicenow-cmdb
spec:
  type: pipe
  command: >-
    sensu-servicenow-handler
    --cmdb-registration
    --cmdb-properties asset_tag
  runtime_assets:
    - sensu/sensu-servicenow-handler:3.0.0
  env_vars:
    - SERVICENOW_URL=https://example.servicenow.com
  secrets:
    - name: SERVICENOW_USERNAME
      secret: servicenow_username
    - name: SERVICENOW_PASSWORD
      secret: servicenow_password
  timeout: 10

The available configuration parameters for CMDB registration are:

• --cmdb-table

  Configures which ServiceNow table to use for managing Configuration Items.

  Default: cmdb_ci

• --cmdb-key

  Configures which fieldname Sensu should use to lookup Configuration Items; effectively used as a "primary key".

  Default: name

• --cmdb-name

  Configures the Configuration Item name to be created or updated.
  The --cmdb-name flag supports Sensu handler templates.

  Default: {{ .Entity.Name }}

• --cmdb-asset-tag

  Configures the Configuration Item "Asset Tag".
  The --cmdb-asset-tag flag supports Sensu handler templates.

  Default: sensu/{{ .Entity.Namespace }}/{{ .Entity.Name }}

• --cmdb-properties

  Configures a list of custom ServiceNow CMDB table properties to populate (if provided via custom property annotations).

  Custom CMDB properties can be populated via custom property annotations following the <property-annotation-prefix>/cmdb/<property-name> syntax (NOTE: the default --property-annotation-prefix is servicenow/table/).

  If the "--cmdb-properties asset_tag,store_id" flag was set, Sensu would check for matching annotations and populate the corresponding fields in the ServiceNow CMDB CI table.
  The --cmdb-properties flag is best used with Sensu Entity annotations (e.g. setting annotations in agent.yml):

  annotations:
    servicenow/table/cmdb/asset_tag: i-42424242
    servicenow/table/cmdb/store_id: 1234
  

ServiceNow CMDB Discovery

ServiceNow CMDB discovery is enabled with the --cmdb-discovery argument.

NOTE: valid Sensu --api-url and --api-key configuration is required for CMDB Discovery (see below for more information on setting these as environment variables).
The Sensu ServiceNow Handler uses this configuration to authenticate with the Sensu API and update Sensu Entity properties (e.g. labels, annotations, and/or subscriptions).
ServiceNow CMDB discovery is incompatible with Sensu Agents that are configured with --agent-managed-entity=true, as any Sensu Entity API updates will be overwritten by the agent.

Example

---
type: Handler
api_version: core/v2
metadata:
  name: servicenow-discovery
spec:
  type: pipe
  command: >-
    sensu-servicenow-handler
    --cmdb-discovery
    --cmdb-discovery-labels servicenow_sys_id=sys_id
    --cmdb-discovery-annotations servicenow_sys_class_name=sys_class_name
  runtime_assets:
    - sensu/sensu-servicenow-handler:3.0.0
  env_vars:
    - SERVICENOW_URL=https://example.servicenow.com
    - SENSU_API_URL=http://127.0.0.1:8080
  secrets:
    - name: SERVICENOW_USERNAME
      secret: servicenow_username
    - name: SERVICENOW_PASSWORD
      secret: servicenow_password
    - name: SENSU_API_KEY
      secret: sensu-api-key
  timeout: 10

CMDB discovery can also be used with CMDB registration:

---
type: Handler
api_version: core/v2
metadata:
  name: servicenow-cmdb
spec:
  type: pipe
  command: >-
    sensu-servicenow-handler
    --cmdb-registration
    --cmdb-properties asset_tag
    --cmdb-discovery
    --cmdb-discovery-labels servicenow_sys_id=sys_id
    --cmdb-discovery-annotations servicenow_sys_class_name=sys_class_name
  runtime_assets:
    - sensu/sensu-servicenow-handler:3.0.0
  env_vars:
    - SERVICENOW_URL=https://example.servicenow.com
    - SENSU_API_URL=http://127.0.0.1:8080
  secrets:
    - name: SERVICENOW_USERNAME
      secret: servicenow_username
    - name: SERVICENOW_PASSWORD
      secret: servicenow_password
    - name: SENSU_API_KEY
      secret: sensu-api-key
  timeout: 10

The available configuration parameters for CMDB discovery are:

• --cmdb-table

  Configures which ServiceNow table to use for managing Configuration Items.

  Default: cmdb_ci

• --cmdb-key

  Configures which fieldname Sensu should use to lookup Configuration Items; effectively used as a "primary key".

  Default: name

• --cmdb-discovery-labels

  Configures which Configuration Item fields should be synchronized as Sensu Labels, defined as a comma-separated list of label=fieldname pairs.

  Default: servicenow_sys_id=sys_id,servicenow_sys_class_name=sys_class_name

• --cmdb-discovery-annotations

  Configures which Configuration Item fields should be synchronized as Sensu Annotations, defined as a comma-separated list of annotation=fieldname pairs (e.g. a custom ServiceNow CMDB CI field named store_id could be syncrhonized via --cmdb-discovery-annotations servicenow_store_id=store_id).

• --cmdb-discovery-subscriptions

  Configures which Configuration Item fields should be syncrhonized as Sensu Subscriptions, defined as a comma-separated list of fieldnames (e.g. a custom ServiceNow CMDB CI field named store_id could be synchronized via --cmdb-discovery-subscriptions=store_id).

ServiceNow Incident Management

ServiceNow Incident Management integration is enabled with the --incident-management argument.

Example

---
type: Handler
api_version: core/v2
metadata:
  name: servicenow-incidents
spec:
  type: pipe
  command: >-
    sensu-servicenow-handler
    --incident-management
    --incident-properties category
  runtime_assets:
    - sensu/sensu-servicenow-handler:3.0.0
  env_vars:
    - SERVICENOW_URL=https://example.servicenow.com
  secrets:
    - name: SERVICENOW_USERNAME
      secret: servicenow_username
    - name: SERVICENOW_PASSWORD
      secret: servicenow_password
  timeout: 10

Incident Management can also be used with CMDB registration (and even CMDB discovery):

---
type: Handler
api_version: core/v2
metadata:
  name: servicenow-incidents
spec:
  type: pipe
  command: >-
    sensu-servicenow-handler
    --incident-management
    --incident-properties category
    --cmdb-registration
    --cmdb-properties asset_tag
  runtime_assets:
    - sensu/sensu-servicenow-handler:3.0.0
  env_vars:
    - SERVICENOW_URL=https://example.servicenow.com
  secrets:
    - name: SERVICENOW_USERNAME
      secret: servicenow_username
    - name: SERVICENOW_PASSWORD
      secret: servicenow_password
  timeout: 10

The available configuration parameters for Incident Management are:

• --incident-table

  Configures which ServiceNow table to use for managing Incidents.

  Default: incident

• --incident-key

  Configures which fieldname Sensu should use to lookup Incidents; effectively used as a "primary key".

  Default: short_description

• --incident-description

  Configures the ServiceNow Incident "short description" suffix.
  The --incident-description flag supports Sensu handler templates.

  Default: {{ .Check.State }}

  NOTE: All ServiceNow Incident short descriptions are prefixed with the Sensu namespace and entity name (i.e. {{ .Entity.Name }}/{{ .Check.Name }}: ).
  In practice the default value for ServiceNow Incident short descriptions is:

  {{ .Entity.Name }}/{{ .Check.Name }}: {{ .Check.State }}
  

  Setting --incident-description provides the ability to replace {{ .Check.State }} with some other value.

• --incident-work-notes

  Configures the ServiceNow Incident work notes (incident content).
  The --incident-work-notes flag supports Sensu handler templates.

  Default: {{ .Check.Output }}

• --incident-comments

  Appends additional comments to the ServiceNow Incident.
  The --incident-comments flag supports Sensu handler templates.

• --incident-properties

  Configures a list of custom ServiceNow Incident table properties to populate (if provided via custom property annotations).

  Custom Incident properties can be populated via custom property annotations following the <property-annotation-prefix>/incident/<property-name> syntax (NOTE: the default --property-annotation-prefix is servicenow/table/).

  If the "--incident-properties category,example" flag was set, Sensu would check for matching annotations and populate the corresponding fields in the ServiceNow Incident table.
  The --incident-properties flag is best used with Sensu Check annotations (e.g. setting annotations in your check definitions).

  Example:

  annotations:
    servicenow/table/incident/category: software
    servicenow/table/incident/example: hello, world
  

ServiceNow Event Management

ServiceNow Event Management is enabled with the --event-management argument.

Example

coming soon

The available configuration parameters for Event Management are:

• --event-table

  Configures which ServiceNow table to use for managing Events.

  Default: em_event

• --event-additional-info

  Configures the ServiceNow Event "additional info" content.

• --event-properties

  Configures a list of custom ServiceNow Event table properties to populate (if provided via custom property annotations).

  Custom Incident properties can be populated via custom property annotations following the <property-annotation-prefix>/event/<property-name> syntax (NOTE: the default --property-annotation-prefix is servicenow/table/).

  If the "--event-properties foo,bar" flag was set, Sensu would check for matching annotations and populate the corresponding fields in the ServiceNow Incident table.
  The --event-properties flag is best used with Sensu Check annotations (e.g. setting annotations in your check definitions).

  Example:

  annotations:
    servicenow/table/incident/foo: hello
    servicenow/table/incident/bar: world
  

Configuration

Asset registration

Sensu Assets are the best way to make use of this plugin. If you're not using an asset, please
consider doing so! If you're using sensuctl 5.13 with Sensu Backend 5.13 or later, you can use the
following command to add the asset:

sensuctl asset add sensu/sensu-servicenow-handler

If you're using an earlier version of sensuctl, you can find the asset on the Bonsai Asset Index.

Pipeline definition

---
type: Pipeline
api_version: core/v2
metadata:
  name: servicenow
spec:
  workflows:
    - name: servicenow-incidents
      filters:
        - api_version: core/v2
          type: EventFilter
          name: is_incident
      handler:
        api_version: core/v2
        type: Handler
        name: servicenow-incidents
    - name: servicenow-cmdb
      filters:
        - api_version: core/v2
          type: EventFilter
          name: is_registration
      handler:
        api_version: core/v2
        type: Handler
        name: servicenow-cmdb
---
type: Handler
api_version: core/v2
metadata:
  name: servicenow-incidents
spec:
  type: pipe
  command: >-
    sensu-servicenow-handler
    --incident-management
    --incident-properties category
    --cmdb-registration
    --cmdb-properties asset_tag
  runtime_assets:
    - sensu/sensu-servicenow-handler:3.0.0
  env_vars:
    - SERVICENOW_URL=https://example.servicenow.com
  secrets:
    - name: SERVICENOW_USERNAME
      secret: servicenow_username
    - name: SERVICENOW_PASSWORD
      secret: servicenow_password
  timeout: 10
---
type: Handler
api_version: core/v2
metadata:
  name: servicenow-cmdb
spec:
  type: pipe
  command: >-
    sensu-servicenow-handler
    --cmdb-registration
    --cmdb-properties asset_tag
    --cmdb-discovery
    --cmdb-discovery-labels servicenow_sys_id=sys_id
    --cmdb-discovery-annotations servicenow_sys_class_name=sys_class_name
  runtime_assets:
    - sensu/sensu-servicenow-handler:3.0.0
  env_vars:
    - SERVICENOW_URL=https://example.servicenow.com
    - SENSU_API_URL=http://127.0.0.1:8080
  secrets:
    - name: SERVICENOW_USERNAME
      secret: servicenow_username
    - name: SERVICENOW_PASSWORD
      secret: servicenow_password
    - name: SENSU_API_KEY
      secret: sensu-api-key
  timeout: 10
---
type: Handler
api_version: core/v2
metadata:
  name: registration
spec:
  type: pipe
  command: >-
    sensu-servicenow-handler
    --cmdb-registration
    --cmdb-properties asset_tag
    --cmdb-discovery
    --cmdb-discovery-labels servicenow_sys_id=sys_id
    --cmdb-discovery-annotations servicenow_sys_class_name=sys_class_name
  runtime_assets:
    - sensu/sensu-servicenow-handler:3.0.0
  env_vars:
    - SERVICENOW_URL=https://example.servicenow.com
    - SENSU_API_URL=http://127.0.0.1:8080
  secrets:
    - name: SERVICENOW_USERNAME
      secret: servicenow-username
    - name: SERVICENOW_PASSWORD
      secret: servicenow-password
    - name: SENSU_API_KEY
      secret: sensu-api-key
  timeout: 10
---
type: EventFilter
api_version: core/v2
metadata:
  name: is_registration
spec:
  action: allow
  expressions:
    - event.check.name == "keepalive"
    - event.check.status == 0
    - event.check.occurrences == 1
---
type: Secret
api_version: secrets/v1
metadata:
  name: servicenow-username
spec:
  provider: env
  id: SENSU_SERVICENOW_USERNAME
---
type: Secret
api_version: secrets/v1
metadata:
  name: servicenow-password
spec:
  provider: env
  id: SENSU_SERVICENOW_PASSWORD
---
type: Secret
api_version: secrets/v1
metadata:
  name: sensu-api-key
spec:
  provider: env
  id: SENSU_ENTITY_MANAGER_API_KEY

Environment variables

All arguments for this handler are available to be set via environment variables. However, any
arguments specified directly on the command line override the corresponding environment variable.

Security Note: Care should be taken to not expose the username/password for this handler by specifying them on the command line. It is suggested to make use of secrets management to surface them as environment variables. The handler definition above references them as secrets. Below are example secrets definitions that make use of the built-in env secrets provider.

---
type: Secret
api_version: secrets/v1
metadata:
  name: servicenow-username
spec:
  provider: env
  id: SERVICENOW_USERNAME
---
type: Secret
api_version: secrets/v1
metadata:
  name: servicenow-password
spec:
  provider: env
  id: SERVICENOW_PASSWORD

Annotations

All arguments for this handler are tunable on a per entity or check basis based on annotations.
The annotations keyspace for this handler is servicenow/config.
Any such annotations take precedence over environment variables and command line arguments.

NOTE: Due to check token substituion, supplying a template value such
as for description-template as a check annotation requires that you place the
desired template as a golang string literal (enlcosed in backticks)
within another template definition. This does not apply to entity annotations.

Templates

This handler provides options for using templates to populate the values
provided by the event in the event or incident records created in ServiceNow.
More information on template syntax and format can be found in the documentation

Proxy Support

This handler supports the use of the environment variables HTTP_PROXY,
HTTPS_PROXY, and NO_PROXY (or the lowercase versions thereof). HTTPS_PROXY takes
precedence over HTTP_PROXY for https requests. The environment values may be
either a complete URL or a "host[:port]", in which case the "http" scheme is assumed.