Creating an extended integration for Rapid7 InsightVM users

Let Oomnitza be your single source of truth!

You'll get complete visibility of your assets and users as data from Rapid7 InsightVM is automatically transformed into consumable information and actionable insights.

Connect Oomnitza and Rapid7 InsightVM in minutes

Get the information and insights that you need to reduce costs and the time that you spend on administration tasks such as:

• Configurable dashboards and list views of key user information
• Configurable reports to share information about users with your colleagues and management
• Configurable workflows that you can easily create such as: 
  • Workflows for getting asset users and getting user details 
  • Workflows for resetting user passwords and unlocking user accounts

Navigation

Setting your Rapid7 Subdomain as a global variable

Adding the credentials

Creating the user integration

Creating custom mappings

Creating workflows

Creating asset workflows with the API block

Get User Details

Reset User Password

Unlock User Account

Before you start

Best practice
For the integration with Oomnitza, create a dedicated user account.

To stream Rapid7 InsightVM asset and user data into Oomnitza, you must add your Rapid7 authentication credentials to the vault in Oomnitza. 

To create the integrations with Oomnitza, you need to know:

• The email address of a Rapid7 user with administrator privileges
• The Rapid7 port number and host name. If you don't know the Rapid7 port number and host name, contact Rapid7 Support. 

 For more information, see INSIGHTVM API (V3) 

Setting your Rapid7 API host name and port as a global variable

To save time entering information when you integrate Rapid7, you can add the API port number and API host name as global variables in Oomnitza.

1. Click Configuration > General > Global Settings.
2. Click Add new variable (+). 
3. Enter Rapid7.Rapid7 API Port as the variable name.
4. Enter the port number.
5. Click SAVE.
6. Repeat step 1 and 2.
7. Enter Rapid7.Rapid7 API Host as the variable name.
8.  Enter the host name.
9. Click SAVE.

Adding the credentials

To authorize connections between Oomnitza and Rapid7, complete these steps:

1. Click Configuration > Security > Credentials, and then click Add new credential (+).
2. Add the information details.
3. Click the AUTHORIZATION tab.
4. As authorization type, ensure that Basic Auth is selected .
5. Enter the email address and password of a Rapid7 user with administrator privileges.
6. Click CREATE. 

You use the credentials that you added to create and customize your Rapid7 integrations with Oomnitza.

Create the user integration

Info and connect details

1. Click Configuration > Integrations and then click Integrations List View .
2. On the Integrations page, scroll down to the Extended section for User Integrations.
3. Click NEW INTEGRATION.
4. In the New User Integration sidebar, click Rapid7.
5. Click APPLY  next to Rapid7 User Load, and then click NEXT twice.

Connect page

Best practice
To ensure that only live user records are streamed to Oomnitza, choose Update only as your integration preference. When you run the integration, you can check the error logs to see which user records weren't uploaded and why they weren't uploaded. You can then decide whether to upload the user records that were skipped by changing your integration preference to create and upload. See Access error logs.

1. Enter a descriptive name for the integration such as Rapid7 Users. That'll be the name of the user integration that is shown on the Integrations page.
2. From the User Selection list, select User plus SaaS User or User only.
3. If you select User plus SaaS User and you have multiple instances of the same SaaS application, select the application from the SaaS Selection list. If you have a single instance of the SaaS application, skip this step.
4. From the installation type list, select Cloud.
5. From the Credentials list, select your credentials.
6. From the Integration Preferences list, select Update only.   
7. Enter the name of the user of the integration.
8. Enter the Rapid7 API host name. The format of the URL is https://<host>:<port>/api/3 . You enter the host part of the URL.
9. Enter the Rapid7 API port number. The format of the URL is https://<host>:<port>/api/3 . You enter the number that is shown after the colon (:).
10. Click Next.

Creating custom mappings

Map the Rapid7 fields to Oomnitza fields and create custom mappings to get the user information that you need.

Complete these actions:

1. Click SMART MAPPINGS.
2. You must create a custom mapping for the Rapid7 Id field. To do this, complete these steps:
   1. Click the down arrow on the Id field.
   2. Select Add new Oomnitza users field.
   3. Change the name of the Id field to Rapid7 User ID. 
   4. Click CREATE. 
3. Create custom mappings to map any other field that you want to add to Oomnitza:
   1. Click the down arrow on the field that you want to map.
   2. Select Add new Oomnitza users field.
   3. Change the name of the field.
   4. Click CREATE. 
4. Assign a sync key to the Email field.
5. Click NEXT. 

Tracking information for asset integration  

When the integration is run, you can track the name of the credentials that were used and the source of the data. To do this, you map the following fields to Oomnitza:   

• Connect: Credentials
• Connect: Rapid7 API Host
• Connect: Rapid7 API Port

Custom mappings

The following Rapid7 fields can be mapped to Oomnitza:

Authentication Type
Connector Sync Time
Email
Id
Is Enabled
Is Locked
Is Password Reset On Login
Is Role All Asset Groups
Is Role All Sites
Is Role Superuser
Locale Default
Locale Reports
Login
Name
Password
Role Id

Want to map more fields to Oomnitza?
Contact Support, or see Mapping extended connectors.

When you've completed mapping the Rapid7 to Oomnitza fields, click NEXT.

Schedule

By default, user data is streamed to Oomnitza once every day.

You can configure the schedule to meet your needs such as changing the interval or changing the time so that the data is streamed when your system isn't busy.

1. Configure your schedule.
2. Click FINISH.

Result

A new tile is created for the integration on the Integrations page. 

What to do next

If you want to see the information that is collected now, click the tile on the Integrations page and click RUN.

Figure: Mock-up for illustration purposes

If you want to change the integration settings, you can click a navigation link on the page, such as 4 Mappings, and edit the settings. 

Creating workflows

Creating user workflows with the API block

To reduce your workload and automate complex and repetitive tasks, you can create user workflows with the API block by following the steps in Creating user workflows with the API block. To locate the available presets, enter Rapid7 in the Select Preset search field. Select your preset of choice and for every preset enter the following information in the Configure section:

• Your Rapid7 API host name and port number, which is derived from the global variable Rapid7.Rapid7 API Host and Rapid7.Rapid7 API Port that you configured in Setting your Rapid7 Subdomain as a global variable. Alternatively, you can enter this information manually.
• You credentials, which you created in Adding the credentials.

The Rapid7 API block workflow comes with the following presets for users:

Get User Details
Reset User Password
Unlock User Account

Using the Rapid7 Get User Details preset

The Get User Details preset returns the details of a user. You can use the Advanced Mode to map the API response. To do this, complete the following steps:

1. In the API block window, click the Advanced Mode button located in the upper right of the window.
2. Select the Response tab. You can map the entire response by placing {{response}} in the Response field and mapping it to a custom long text Oomnitza field, such as API Response. For further information on how to map an API response, see Mapping Response variables

For further information see Rapid7 REST API documentation: Users.

Using the Rapid7 Reset User Password preset

The Reset User Password preset resets the users password to a new password that is provided as input. When constructing a workflow that uses this preset, the New Password field is required. You can use the Advanced Mode to configure the message payload. To do this, complete the following steps:

1. In the API block window, click the Advanced Mode button located in the upper right of the window.
2. In the Information tab, you will notice that the Rapid7 User ID is referenced in the field {{rapid7_user_id}}that you created in Creating custom mappings.  If this is not correct, you can replace the variable {{rapid7_user_id}} in the URL field with the correct variable or user id. 
3. Select the Response tab. You can map the entire response by placing {{response}} in the Response field and mapping it to a custom long text Oomnitza field, such as API Response. For further information on how to map an API response, see Mapping Response variables.

For further information see Rapid7 REST API documentation: Password Reset.

Using the Rapid7 Unlock User Account preset

The Unlock User Account preset unlocks a user account that has been locked by the system due to too many failed password attempts. Disabled accounts may not be unlocked. You can follow the steps in Using the Rapid7 Get User Details preset to configure the message payload.

For further information see Rapid7 REST API documentation: Unlock Account.

For further information on workflows see:
 Understanding workflows
Enhanced API Block
Mapping Response variables

Unleash the power of Oomnitza

To get valuable actionable insights that help you manage your users, learn how to:

• Configure dashboards for your users and software
• Configure custom reports about your users and software
• Create workflows to automate tasks

See  Getting started for more information.

Did you know
You can also create extended connector integrations for Rapid7 assets.
Creating an extended integration for Rapid7 assets