What Oleria discovers
Once connected, Oleria continuously discovers and maps the following from your Rapid7 organization:- Accounts - every user in your Rapid7 organization, with their name, email address, whether they’re active, and when they last signed in. Oleria marks users who sign in through your identity provider (federated users) as requiring single sign-on. Platform Admins are marked as administrators.
- User groups - every user group and its members.
- Roles and permissions - every Rapid7 role, the roles each user holds directly, and the roles each user group grants. Oleria also records the feature permissions each role carries, such as SIEM Core with View Only.
- Product access - each Rapid7 product your organization licenses, and which users and user groups can use it, with the permissions their roles grant.
- API keys - the user API keys and organization API keys in your organization, as non-human identities. Oleria records each key’s name and when it was generated. A user API key is linked to the person who owns it and shown as acting as that person. Oleria never reads or stores the key values themselves.
- Activity - events from the Rapid7 platform audit log, such as sign-ins, user changes, role changes, product access changes, and API key changes. Activity needs audit logging turned on in Rapid7 - see Prerequisites. Support for audit-log activity is new: if you turn audit logging on and don’t see activity after a sync, contact us.
Oleria doesn’t import detections, investigations, assets, vulnerabilities, or log data. This integration covers identity and access governance for the Rapid7 Command Platform only.
Prerequisites
- A Rapid7 Command Platform organization. Note its data region (for example
us,us2,eu). You can find it on Platform Home. - A Rapid7 Platform Admin who signs in and generates the user API key themselves. A user API key acts as the user who generated it, so the Platform Admin who generates it is the user that owns it.
- Optional: audit logging turned on in Rapid7, to collect activity. A Platform Admin turns it on under Administration > Company Settings > Audit Log. Audit logging isn’t available in InsightGovCloud. Oleria reads the audit log from the data region you connect, so store the audit log in the same region as your organization.
- Admin access to the Oleria workspace.
Create a user API key in Rapid7
1
Sign in as the owner
Sign in to the Rapid7 Command Platform as the Platform Admin that will own the key.
2
Open user API keys
Go to Administration > API Key Management > User API Keys.
3
Generate the key
Generate a new user API key. If Rapid7 asks which organization the key is for, select the organization you want to connect, because Oleria connects to the organization the key belongs to. Name the key so you recognize it later, for example
Oleria.4
Copy the key
Copy the key right away. Rapid7 shows it only when you create it. You need it to connect Rapid7 to Oleria.
The exact location of these settings can change over time. If the steps above don’t match what you see, refer to Rapid7’s own documentation.
Permissions Oleria needs
A user API key has the permissions of the user who owns it. The owner must be a Platform Admin.Connect Rapid7 to Oleria
1
Open the integration
Go to your Oleria workspace, select Integrations -> select Rapid7.
2
Complete the connection form
Select Continue and provide the following:
3
Confirm the connection
Select Authenticate. Oleria checks that the key can read your Rapid7 organization before it saves anything. Find the newly connected organization on the Connected tab of your Oleria Integrations page.
When you edit the integration, you can change the API key and the data region. Leave API key blank to keep the stored key. If you change only the key, Oleria keeps the stored region.
Verify the integration
Confirm the Rapid7 organization appears on the Connected tab of your Oleria Integrations page with a status of Healthy. After the first sync completes, check that users and user groups appear in your Oleria workspace, that your Platform Admins are marked as administrators, and that your API keys appear as non-human identities. If you turned on audit logging, allow at least one more sync for activity to appear.Remediation actions
Oleria can take these actions in Rapid7. Each one runs with the permissions of the Platform Admin who owns the API key:- Add a user to a user group and remove a user from a user group.
- Assign a role to a user and remove a role from a user. These actions change a user’s directly assigned roles.
- Revoke a user’s product access. In Oleria this action is labeled Disable account. Rapid7 has no way to disable a user, so Oleria revokes the user’s direct access to each Rapid7 product instead.
- Oleria reads the user or group before it changes anything. If the user is already in the requested state, Oleria makes no change.
- After a change, Oleria reads the state again to check that Rapid7 applied it. If Rapid7 reports an error but the change did go through, the action still succeeds and can be reverted.
- Reverting an action undoes only the change that action made. If an action changed nothing, reverting it does nothing.
- Revoking product access removes only direct grants. Rapid7 also gives access through user groups, and a grant from a group can’t be removed from the user. If every product comes through a group, the action fails without changing anything and names the group. If some products are direct and some come through a group, Oleria revokes the direct ones and then reports the action as failed, naming the groups. Those revocations can’t be reverted from Oleria, because a failed action keeps no revert record: re-grant the products in Rapid7 if you need to. Remove the user from the groups to finish. When every product is direct, the action succeeds, and reverting restores the direct grants and roles it captured.
- Oleria won’t act on a Platform Admin. This protects the user who owns the API key and your organization owner, and means you can’t change another Platform Admin from Oleria.
- Oleria can’t disable, delete, or create users, and can’t change group or role definitions.
- Oleria can’t disable or revoke an API key. Rapid7 only lets you delete a key, which can’t be undone, so Oleria doesn’t offer it.
Known limitations
- Activity needs audit logging turned on. Without it, Oleria doesn’t import activity. Oleria skips events whose actor isn’t a user or API key it knows about, such as a user who has since been deleted. Changes Oleria makes through its own actions appear as activity from the key’s owner.
- No multi-factor authentication status. Rapid7’s API doesn’t report per-user multi-factor settings or your organization’s single sign-on policy. Oleria marks only federated users as signing in through single sign-on.
- No account creation date or last password change. Rapid7’s API doesn’t report them.
- No last-used date or expiry for API keys. Rapid7’s API doesn’t report when a key was last used or when it expires, so Oleria can’t flag unused or expiring keys.
- Product access includes access from groups. For each user, Rapid7 reports the products they can use whether the access is direct or through a user group. Oleria shows the same effective access on the user, and the user group’s own access separately.
- Resource sets and resource groups aren’t imported. Oleria shows product-level access only.
- Organization keys aren’t supported. Rapid7 doesn’t let them read users, user groups, or roles.
- One data region per integration. To connect a second region, add another integration.
- Large organizations sync more slowly. Oleria reads each user’s and each group’s access separately, so the first sync of a large organization takes longer.