Set up Ticketing and ServiceNow

Set up ticketing in a space to allow users in the space to keep track of security tasks and add ServiceNow incidents directly from within the Mondoo App. Ticketing setup for ServiceNow has three parts: you install the Mondoo app in your ServiceNow instance, you configure your instance to trust the tokens Mondoo signs, and then you create the integration in Mondoo.

For an overview of ticketing, read Track and Fix Findings with Ticketing.

Prerequisites

• Owner or Editor access to the Mondoo space

• A ServiceNow instance with administrator access. Creating the inbound integration requires the admin, mi_admin, or oauth_admin role.

• The Mondoo update set for ServiceNow (version 1.0.0, XML). Download it before you begin.

Install the Mondoo app in your ServiceNow instance

The Mondoo app is a scoped application with the ID x_1877227_mondooti. It provides the REST APIs that Mondoo calls to create, update, and delete incidents.

1. In your ServiceNow instance, navigate to System Update Sets > Retrieved Update Sets.

2. Select Import Update Set from XML.

3. Upload the Mondoo update set XML file.

4. Open the update set that ServiceNow imported and select Preview Update Set. Resolve any conflicts the preview reports.

5. Select Commit Update Set.

If you develop with the ServiceNow SDK and have access to the application source, you can install the source instead of the update set:

npm install -g @servicenow/cli
npx now-sdk auth --add <your-instance-url>
npx now-sdk build
npx now-sdk install

Create an OIDC inbound integration in ServiceNow

Mondoo authenticates to your instance with an OIDC ID token that it signs, so there is no shared secret to store or rotate. ServiceNow can't create OAuth entities programmatically, so you create this integration in the ServiceNow interface.

1. Navigate to Machine Identity Console > Inbound integrations.

2. Select New integration and choose the option for a third-party ID token issued by an OIDC identity provider.

3. In the details for the integration, provide these values:

   • Name: Mondoo
   • Provider name: mondoo
   • Client ID: a value of your choice, such as mondooticketing. Record this value. You need it when you create the integration in Mondoo.
   • Active: on

4. Continue to the OAuth OIDC provider section, choose to create a new configuration, and provide these values:

   • Name: Mondoo
   • OIDC metadata URL: https://us.api.mondoo.com/.well-known/openid-configuration
   • OIDC configuration cache lifespan: 1 hour
   • User claim: sub
   • User field: email
   • JTI claim: jti, with JTI verification turned on

   The metadata URL varies by region. Use https://us.api.mondoo.com for the US region or https://eu.api.mondoo.com for the EU region.

5. Continue to the auth scope section and set the scope to useraccount.

6. Return to the top of the page and select Save.

Add the Mondoo space ID field to the incident table

The Mondoo app writes the ID of the Mondoo space that created the ticket into a custom field on the incident table. Incident creation fails if the field doesn't exist.

1. Navigate to System Definition > Tables.

2. Open the incident table.

3. On the Columns tab, select New.

4. Provide these values:

   • Field name: u_space_id
   • Type: String
   • Max length: 255
   • Label: Mondoo Space ID

5. Select Save.

Add a ServiceNow integration in Mondoo

1. In the Mondoo App, navigate to the space where you want to set up ticketing and, in the side navigation bar, select Integrations.

2. Add a new integration and choose the ticketing category.

3. Select ServiceNow.

4. Enter a name for the integration. Make it a name that clearly shows this is a ServiceNow integration.

5. Enter the URL of your ServiceNow instance, such as https://mycompany.service-now.com. Any HTTPS host that reaches your instance works, including a vanity domain.

6. Enter the client ID you set on the inbound integration in ServiceNow, such as mondooticketing.

7. Create the integration.

8. On the integration detail page, copy the email address Mondoo generated for the integration. You need this address in the next section.

Create the machine user in ServiceNow

ServiceNow matches the token Mondoo sends to a user record by email address, and attributes the incidents Mondoo creates to that user.

1. Navigate to User Administration > Users.

2. Select New.

3. Provide these values:

   • User ID: a value of your choice, such as mondoo-integration
   • Email: the address you copied from the Mondoo integration detail page. It must match exactly.
   • Active: on

4. Set the identity type to Machine and flag the user as an internal integration user.

5. Leave the roles empty. Mondoo verified incident creation with a machine user that has no roles on a default instance. If your instance adds access controls to incident creation or to REST API access, grant the roles those controls require.

6. Select Submit.

Verify the setup

The Mondoo app exposes a health endpoint that needs no authentication. Replace INSTANCE with the host name of your ServiceNow instance:

curl https://INSTANCE/api/x_1877227_mondooti/mondoo_health/health

A working configuration returns "oauth_configured": true:

{
  "status": "healthy",
  "service": "Mondoo Case Management API",
  "oauth_configured": true
}

If oauth_configured is false, confirm that the inbound integration exists in the Machine Identity Console and that a user with the generated email address exists in your instance.

When you create a ticket from a Mondoo finding and send it to this integration, ServiceNow records an incident created by the machine user. The short description and the description come from the finding.

Learn more

• Create Tickets from Advisories
• Create Tickets from Checks
• Manage Ticketing
• Track and Fix Findings with Ticketing