DeepSurface: Rapid7 InsightVM API
DocumentationInstallation GuideOverviewLet DeepSurface Host For YouGetting StartedSystem RequirementsSelf Hosted Quick Start - Installing to Cloud PlatformsSelf Hosted - Installation Using an OVARegistration, Package Installation, and InitializationFirst Steps After Initialization of the ConsoleDeployment OptionsMain and Subordinate ConsolesAgent-Based DeploymentUser Managed Scan DeploymentCredentialed Scanning DeploymentMixed EnvironmentDeployment ToolsActive Directory Group PolicyMicrosoft Endpoint Configuration Manager (part of InTune)Tanium DeployHCL BigFixIvantiVirtual MachinesVMWareVirtual BoxVirtualBox Guest AdditionsAWS EC2 (BYOL)AWS EC2 (Usage Based)Azure CloudGoogle CloudAdditional Items to ConsiderMain Console Server CertificatesLDAPTOFUClock SyncDeepSurface CommandsMultiple Vulnerability SourcesAPI DocumentationUser GuideReportingDashboardsExportsRisk InsightHostsPatchesVulnerabilitiesVulnerability InstancesUsersRemediation Workflow ManagerPlansSettingsIntegrationsWorkflowExportingAccepted Risk PlansAccepted Risk WorkflowExploreModelPathsActivityTasksConfiguration AlertsScan LogsNotification SettingsScanningStatusAgentsUser ManagedCredentialed Scanning SettingsCredentialsScan GroupsGeneral SettingsCloud ScanningNetwork ConnectivitySubordinatesVulnerability SourcesSetupSensitive Assets: PolicesSensitive Assets: ManualAdmin SettingsSMTP SettingsCertificatesOutbound ProxyAuthentication ProvidersUsersTagsIntegrations GuideVulnerability SourcesCrowdStrike SpotlightSentinelOneCarbon Black CloudMicrosoft Defender for EndpointWazuhLansweeper CloudNessus APITenable.io APISecurity Center/Tenable.sc APIRapid7 InsightVM APIQualys APINozomi GuardianEclypsiumAWS InspectorRemediationJira SoftwareTanium (BETA)Authentication ProvidersLDAP (Active Directory)SAML (Azure Active Directory)SAML (Google)SAML (Okta)PAMCyberArkDelinea (Thycotic)Microsoft LAPSSecurity GuideFirewall ConfigurationBase Network RequirementsAgent Network RequirementsCredentialed Scanning Network RequirementsAPI Network RequirementsHow DeepSurface Scans WorkDomain (LDAP) ScanningHost Scanning RoutineReasons for the Administrative Access RequirementEndpoint Protection ConsiderationsOther ItemsScope of Data Storage and RetentionIPS/IDS ConsiderationsLoggingResetting the DSADMIN passwordProduct InformationChangelogsOpen source LicensesEnd User License Agreement (EULA)
DeepSurface supports syncing vulnerability scan results from Rapid7 InsightVM. To enable this integration, add InsightVM as a third-party vulnerability source, either via API or manual file imports. For API access you'll need the InsightVM server IP or hostname, port, username, and password.
Creating a User for InsightVM API
DeepSurface can use any account with at least the Asset Owner role. To create a user, connect to the InsightVM console and log in as a Global Administrator.
- Select Administration from the home page.
- Select the Create link in the Users panel.
- Fill out the required information in the General tab. Make a note of the username and password that you select, these are the credentials that you will need for the DeepSurface console.
- Ensure that Account enabled is checked.
- Select the Roles tab and grant the user the Asset Owner role.
- DeepSurface requires the user to be an Asset Owner or higher in order to create reports within the InsightVM that are used for processing vulnerability data.
- Select the Site Access tab and allow this user to access all sites.
- Select the Asset Group Access tab and allow this user to access all asset groups.
Setting Up InsightVM API
You will need the following pieces of information:
- Rapid7 InsightVM hostname or IP address
- Rapid7 InsightVM port
- Asset Owner username and password
Connect to your DeepSurface console and log in.
- Navigate to Scanning > Settings > Vuln. Scanners.
- Create a new vulnerability scanner, select Rapid7 InsightVM API, and fill in the hostname or IP, port, username and password.
- Save!
Setting Up InsightVM Manual Import
Manual imports are not recommended. When you use the Rapid7 InsightVM API, DeepSurface gathers extra host information to better identify and properly associate vulnerabilities with hosts that DeepSurface has scanned. While we will be able to match some hosts, the overall accuracy of the model will be degraded. Here you can find Rapid7's documentation for general report creation.
To generate the Rapid7 XML report that DeepSurface needs to import, you will need to connect to the InsightVM console and log in as a Global Administrator.
Select Reports from the home page
Create a new Audit Report in the Document tab of the Template section
Select XML Export 2.0 in the Export tab of the Template section
Select Sites, Assets, Asset Groups, or Tags in the Scope section
Select all the sites you would like to import. Make sure the upper left checkbox is not checked
Expand Advanced Settings and select how you like to receive the report. You can email it with Distribution or retrieve it from the InsightVM console by configuring Report File Storage. You can see both methods below:
If you use local file storage, the path will likely be /opt/rapid7/nexpose/nsc/reports/{username}/{report_name}/report.xml
You can now save and run the report. Retrieve the report using the method you've chosen and switch to DeepSurface.
At this step, you should have a report.xml from InsightVM with the hosts that are being scanned by DeepSurface.
- Navigate to vulnerability scanners as you would for the Rapid7 API.
- Create a new vulnerability scanner, select Rapid7 InsightVM Manual Imports, and save.
- Select the Upload Vulnerability Scanner icon
Testing Your Integration
Press the import button to perform a test import. If there are problems, error messages and warnings will appear on the screen.