Set up Device Security and XSOAR for Rapid7 InsightVM Integration
Focus
Focus
Device Security

Set up Device Security and XSOAR for Rapid7 InsightVM Integration

Table of Contents

Set up Device Security and XSOAR for Rapid7 InsightVM Integration

Set up Device Security and Cortex XSOAR to integrate with Rapid7 for vulnerability scanning.
Where Can I Use This?What Do I Need?
  • Device Security (Managed by Strata Cloud Manager)
  • (Legacy) IoT Security (Standalone portal)
One of the following subscriptions:
  • Device Security subscription for an advanced Device Security product (Enterprise Plus, Industrial OT, or Medical)
  • Device Security X subscription
One of the following Cortex XSOAR setups:
  • A free, cohosted, limited-featured Cortex XSOAR instance
    AND
    A Cortex XSOAR Engine (on-premises integration)
  • A full-featured Cortex XSOAR server
To set up Device Security to integrate through Cortex XSOAR with an Rapid7 InsightVM management system, you must add a Cortex XSOAR engine to your network.
Also configure the Rapid7 InsightVM integration instance in XSOAR. To do this, you need the URL of your Rapid7 management system, the port number on which it listens for connection requests, and the username and password of the Rapid7 user account for XSOAR to use when forming a secure connection with it.

Cortex XSOAR Engine Installation

When the Rapid7 management system is on premises, you must install a Cortex XSOAR engine to initiate connections to the Rapid7 management system and to Cortex. The XSOAR engine provides the means through which these two systems communicate with each other. Although it's possible to install an XSOAR engine on machines running Windows, macOS, and Linux operating systems, only an engine on a Linux machine supports Device Security integrations. For more information about operating system and hardware requirements, see the Cortex Administrator’s Guide.
We recommend downloading the Cortex XSOAR engine using the shell installer script and installing it on a Linux machine. This simplifies the deployment by automatically installing all required dependencies and also enables remote engine upgrades.
When placing the XSOAR engine on your network, make sure it can form connections to your Rapid7 management system on the TCP port on which it’s listening for connection requests. The default port number is 3780.
The on-premises firewall must allow the Cortex XSOAR engine to form HTTPS connections on TCP port 443 to the Cortex cloud at https://<your-domain>.iot.demisto.live/. You can see the URL of your Cortex XSOAR instance when you log in to Device Security and click Integrations and then click Launch Cortex XSOAR. It’s visible in the address bar of the web page displaying the Cortex XSOAR interface.
To create an Cortex XSOAR engine, access the Cortex XSOAR interface (from Device Security, click Integrations and then click Launch Cortex XSOAR). In the Cortex XSOAR UI, click SettingsEngines+ Create New Engine. Choose Shell as the type.
For Cortex XSOAR engine installation instructions, see Engine Installation.
For help troubleshooting Cortex XSOAR engines, including installations, upgrades, connectivity, and permissions, see Troubleshoot Engines and Troubleshoot Integrations Running on Engines.

Configure Device Security and Cortex XSOAR

  1. Log in to Device Security and from there access Rapid7 settings in Cortex XSOAR.
    1. Log in to Device Security and then click Integrations.
      Device Security uses Cortex XSOAR to integrate with Rapid7, and the settings you must configure to integrate with it are in the Cortex XSOAR interface.
    2. To access Rapid7 integration settings, click Launch Cortex XSOAR.
      The Cortex XSOAR interface opens in a new browser window.
    3. Click Settings in the left navigation menu, and search for Rapid7 to locate it among other instances.
  2. Configure the settings for the Rapid7 integration instance.
    1. Click the active integration instance settings icon (
      ), or click Add instance, to open the settings panel.
    2. Enter the following settings and leave the others at their default values:
      Name: Use the default name of the integration instance.
      Don’t change the default integration instance name. The XSOAR jobs that support vulnerability scans from the Device Details page in the Device Security portal rely on XSOAR playbooks that refer to this integration instance name specifically.
      Server URL: Enter the URL of the Rapid7 management system you noted earlier and include the port on which it’s listening for connection requests. The default port number is 3780.
      Username: Type the name of the Rapid7 account that you previously created.
      Password: Type the password associated with the Rapid7 user account.
      Optional Learn Device Software Components: Select if you want the import job to include information about software components running on the devices from Rapid7.
      Optional Rapid7 Severity Filter for Vulnerability Import: Select the severity levels for vulnerabilities that you want to import from Rapid7 to Device Security. By default, Device Security imports only vulnerabilities with a severity level of Critical.
      Optional IoT Vertical Filter for Asset Export: Select the types of device category verticals that you want to include when exporting Device Security assets to Rapid7.
      Optional Site Name for Asset Export: Select the Rapid7 site to send information to when exporting Device Security assets to Rapid7.
      Optional Last Seen: Enter the time range in days that you want to get device or vulnerability information from Rapid7. Device Security polls for all vulnerabilities or devices identified or updated in the specified time. By default, the Rapid7 jobs retrieve devices or vulnerabilities last seen in the past one day.
      Run on Single engine: When the Rapid7 management system is on premises, choose the Cortex XSOAR engine that will communicate with it from the list. If the Rapid7 management system is in the cloud, choose No engine.
    3. When finished, click Run test or Test.
      If the test is successful, a Success message appears. If not, check that the settings were entered correctly and then test the configuration again.
    4. After the test succeeds, click Save & exit to save your changes and close the settings panel.
  3. Enable the Rapid7 integration instance.
  4. Create jobs for Cortex XSOAR to send and receive information from Rapid7.
    Depending on whether you want to send device details or get vulnerability information, select the appropriate playbook when configuring the job. If you want to run multiple playbooks, you must create separate jobs, one for each playbook. You can also create multiple jobs if you have multiple integration instances.
    1. Click Jobs in the sidebar, and then click New Job to create a new Cortex XSOAR job.
    2. Configure the following settings in the New Job panel:
      • Optional Recurring: Select this if you want to periodically run the job. Clear it if you want to run the job on-demand.
      • Optional Every: If you selected Recurring, enter a number and set the interval value (Minutes, Hours, Days, or Weeks) and select the days on which to run the job. If you don't select specific days, then the job will run every day by default. This determines how often Cortex XSOAR queries Rapid7 to send and receive information.
        You can configure Queue Handling to determine what happens if a new job starts while an old job is still running.
      • Name: Enter a name for the job.
      • Playbook: Select the playbook depending on the type of job you're configuring. You can select one of the following playbooks when integrating with Rapid7:
        • Import Rapid7 InsightVM Assets to PANW IoT – Import assets from Rapid7, including hosts, scan data, agents, and scanners, to Device Security.
        • Import Rapid7 InsightVM Vulnerabilities to PANW IoT – Get all known open vulnerabilities from Rapid7.
        • Tag Rapid7 InsightVM Assets with PANW IoT Categories – Add a tag to all devices in Rapid7 with their corresponding device category verticals in Device Security. Devices can only have one category vertical tag. You can use the category vertical tag to filter devices when running vulnerability scans in Rapid7.
        • Export PANW IoT Device to Rapid7 InsightVM – Send device information from Device Security to Rapid7. If a device does not exist in Rapid7, then this job creates a new device in Rapid7 and automatically adds the device category vertical tag. By default, Device Security exports devices from all device categories unless you specify the IoT Vertical Filter for Asset Export when configuring the integration instance.
      • Integration Instance Name: Enter the instance name of the integration instance you created.
    3. Click Create new job and verify that the job appears in the Jobs list.
  5. Return to Device Security and check the status of the Rapid7 integration instance.
    An integration instance can be in one of the following four states, which Device Security displays in the Status column on the Integrations page:
    • Active — the integration was configured and enabled and is functioning properly.
      Disabled — either the integration was configured but intentionally disabled or it was never configured and a job that references it is enabled and running.
    • Error — the integration was configured and enabled but is not functioning properly, possibly due to a configuration error or network condition.
    • Inactive — the integration was configured and enabled but no job has run for at least the past 60 minutes.
    When you see that the status of an integration instance is Active, its setup is complete.