Sensu Go ServiceNow Handler

Table of Contents

• Overview
• Usage examples
  • Example scenarios
• Configuration
  • Asset registration
  • Handler definition
  • Environment Variables
  • Annotations
• Installation from source
• Contributing

Overview

The Sensu Go ServiceNow handler is a Sensu Event Handler that creates or updates a ServiceNow incident and/or event.

Usage Examples

This handler creates a ServiceNow incident and/or event.

The incident or event can optionally be associated to a configuration item based on the Sensu event's entity.metadata.name attribute.

If a Configuration Item for the Sensu Entity doesn't exist in ServiceNow, this handler will create one automatically.

The Sensu Go handler for managing ServiceNow Configuration Items, Incidents, and Events

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:
  -c, --cmdbCiTable string                    The ServiceNow CMDB CI table
  -C, --configurationItemDescription string   The template for the ServiceNow Configuration Item Description
  -a, --eventAdditionalInfo string            The template for the ServiceNow Event's Additional Info
  -e, --eventTable string                     The ServiceNow Event table
  -h, --help                                  help for sensu-servicenow-handler
  -H, --host string                           The ServiceNow host
  -b, --incidentBodyNotes string              The template for the ServiceNow Incident Body Notes
  -i, --incidentTable string                  The ServiceNow Incident table
  -p, --password string                       The ServiceNow password
  -u, --username string                       The ServiceNow username

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

The records created/updated in ServiceNow are dependent on which arguments are provided to this handler,
whether via the command line specifications above, environment variables, or
annotations. If the appropriate table is not specified then records are not created there.

Example scenarios:

Note: In the examples below, the command given is a snippet of what would be defined for the handler
for the given scenario, in yaml multiline format. Also, the ServiceNow username and password are assumed
to be set as environment variables.

ServiceNow Incident Management

1. Specifying only the Incident table (--incidentTable) will create a ServiceNow incident not associated with
   a CMDB configuration item.

   spec:
     command: >-
       sensu-servicenow-handler
       --host sn-instance.service-now.com
       --incidentTable incident
   

2. Specifying both the Incident table (--incidentTable) and CMDB CI table (--cmdbCiTable) will create a
   ServiceNow incident associated with a CMDB configuration item (and create the CMDB configuration item
   if it does not already exist).

   spec:
     command: >-
       sensu-servicenow-handler
       --host sn-instance.service-now.com
       --cmdbCiTable cmdb_ci
       --incidentTable incident
   

3. Same as above, but also specifying what Sensu event fields are used to populate the ServiceNow
   Incident Body Notes.

   spec:
     command: >-
       sensu-servicenow-handler
       --host sn-instance.service-now.com
       --cmdbCiTable cmdb_ci
       --incidentTable incident
       --incidentBodyNotes "Check: {{ .Check.Name }}\nEntity: {{ .Entity.Name }}\n\nDescription: {{ .Check.Output }}\n\nSensu URL: https://sensu.mycompany.com:3000/{{ .Check.Namespace }}/events/{{ .Entity.Name }}/{{ .Check.Name }}"
   

ServiceNow Event Management

1. Specifying only the Event table (--eventTable) will create a ServiceNow event not associated with a
   CMDB configuration item.

   spec:
     command: >-
       sensu-servicenow-handler
       --host sn-events.service-now.com
       --eventTable em_events
   

2. Same as above, but also specifying what Sensu event fields are used to populate the ServiceNow Event
   Additional Info field.

   spec:
     command: >-
       sensu-servicenow-handler
       --host sn-events.service-now.com
       --eventTable em_events
       --eventAdditionalInfo "Check: {{ .Check.Name }}\nEntity: {{ .Entity.Name }}\n\nDescription: {{ .Check.Output }}\n\nSensu URL: https://sensu.mycompany.com:3000/{{ .Check.Namespace }}/events/{{ .Entity.Name }}/{{ .Check.Name }}"
   

3. Specifying both the Event table (--eventTable) and CMDB CI table (--cmdbCiTable) will create a
   ServiceNow event associated with a CMDB configuration item (and create the CMDB configuration item
   if it does not already exist).

   spec:
     command: >-
       sensu-servicenow-handler
       --host sn-events.service-now.com
       --eventTable em_events
       --cmdbCiTable cmdb_ci
   

ServiceNow Inventory Management

When used in a registration handler, you can have Sensu create ServiceNow CMDB configuration items.

1. Specifying the CMDB CI table (--cmdbCiTable) will create a CMDB configuration for the entity.

   spec:
     command: >-
       sensu-servicenow-handler
       --host sn-events.service-now.com
       --cmdbCiTable cmdb_ci
   

2. Same as above, but also specifying what Sensu event fields are used to populate the ServiceNow
   Configuration Item Description.

   spec:
     command: >-
       sensu-servicenow-handler
       --host sn-events.service-now.com
       --cmdbCiTable cmdb_ci
       --configurationItemDescription "Entity: {{ .Entity.Name }}\nOS: {{ .Entity.System.OS }}"
   

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.

Handler definition

---
type: Handler
api_version: core/v2
metadata:
  name: sensu-servicenow-handler
  namespace: default
spec:
  command: sensu-servicenow-handler
  type: pipe
  runtime_assets:
  - sensu/sensu-servicenow-handler
  filters:
  - is_incident
  secrets:
  - name: SERVICENOW_USERNAME
    secret: servicenow_username
  - name: SERVICENOW_PASSWORD
    secret: servicenow_password

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

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.

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 sensu.io/plugins/sensu-servicenow-handler/config. Any such
annotations take precedence over environment variables and command line arguments.

Examples

To change the ServiceNow host for a particular entity, in that agent's agent.yml file add the following:

annotations:
  sensu.io/plugins/sensu-servicenow-handler/config/host: "mycompany-nonprod.service-now.com"

To change the incident body notes template for a particular check, for that checks's metadata add the following:

type: CheckConfig
api_version: core/v2
metadata:
  annotations:
    sensu.io/plugins/sensu-servicenow-handler/config/incidentBodyNotes: "Check: {{ .Check.Name }}\nEntity: {{ .Entity.Name }}\n\nDescription: {{ .Check.Output }}\n\nSensu URL: https://sensu.mycompany.com:3000/{{ .Check.Namespace }}/events/{{ .Entity.Name }}/{{ .Check.Name }}"
[...]

Installation from source

The preferred way of installing and deploying this plugin is to use it as an Asset. If you would
like to compile and install the plugin from source or contribute to it, download the latest version
or create an executable script from this source.

From the local path of the sensu-servicenow-handler repository:

go build

Contributing

See https://github.com/sensu/sensu-go/blob/master/CONTRIBUTING.md