---
title: "Rapid7 InsightVM collector"
canonical: "https://docs.devo.com/space/latest/94657046/Rapid7%20InsightVM%20collector"
format: markdown
---
> Macro (toc)
## Overview
[Rapid7 ](https://www.rapid7.com/)is a company that offers multiple tools to help you reduce risk across your entire connected environment. This goes for easily managing vulnerabilities, monitoring for malicious behavior, investigating and shutting down attacks, or just automating your operations.
This collector is focused on one of these tools, **InsightVM**, which helps us detect security risks to our environment, manage vulnerabilities, and quickly take action.
## Configuration requirements
To run this collector, there are some configurations detailed below that you need to take into account.
| **Configuration** | **Details** |
| --- | --- |
| **InsightVM port** | You will need to have a collector running machine with the Insights port (default : 3780) |
| **Server and port** | You need a server and a port, which take the following form:
```
https://{server_ip/server_name}:{InsightVM port}
```
This is typically the address used to sign into the Rapid7 instance. |
| **Permissions** | You will need to configure an user with the right permissions to get the data. Refer to the [Vendor setup ](https://docs.devo.com/space/latest/94657046#Vendor-setup)section. |
## Data sources
InsightVM works by analyzing **Assets** (Devices) grouped in Sites with several scan templates and engines from the InsightVM server, retrieving all detected vulnerabilities and allowing us to have a general view of the risks that our environment has. The collector gets this data and sends it to the Devo platform, which will categorize all information received on tables.
### InsightVM resources
Listed in the table below are the data provided by InsightsVM and how Devo treats the data:
| | | | |
| --- | --- | --- | --- |
| **Data source** | **Description** | **Dump type** | **Devo data tables** |
| **Scans** | History of processes by which the application discovers network assets and checks them for vulnerabilities. | Full dump | `vuln.rapid7.insightvm.scans` |
| **Assets** | Device/s on a network discovered during a scan. | Full dump | `vuln.rapid7.insightvm.assets` |
| **Sites** | Collection of assets that are targeted for a scan. | Full dump | `vuln.rapid7.insightvm.sites` |
| **Vulnerabilities** | Reported vulnerabilities found during a scan. | New events | `vuln.rapid7.insightvm.vulnerabilities` |
> ℹ️ **Dump type**
> ℹ️
> ℹ️ The Dump type column indicates how the collector will retrieve the data in each iteration. This is an important factor to take into account when setting the `request_period_in_seconds` field later in the configuration file.
> ℹ️
> ℹ️ - Full dump: All available data.
> ℹ️ - New events: Collector saves the retrieving status to get always the latest items detected.
> ℹ️ - Configurable: There is a field in the configuration file where you can choose the dump type.
## Vendor setup
The **InsightVM data collector** works over the installed on-premises InsightVM server, there are some requirements to run the collector, you will need to have:
- A collector running in a machine with the InsightVM port (default: `3780`).
- A user with the necessary permissions to get the data.
### Setting up user permissions
> Macro (rw-ui-steps-macro)
>
> > Macro (rw-step)
>
> Go to the I**nsightVM server **with any supported browser (*https://{server_ip/server_name}:{InsightVM port}*) and log in.
>
> > Macro (rw-step)
>
> Go to the **Administration **tab and click **Create **in the **Users **box.
>
> 
>
> > Macro (rw-step)
>
> Fill the **General **tab data with the desired values and go to the **Roles **tab.
>
> > Macro (rw-step)
>
> Configure the desired role. It must have at least the following permissions to work properly:
>
> | | |
> | --- | --- |
> |  |  |
>
> > Macro (rw-step)
>
> Go to the **Site Access** and **Asset Group Access** tabs and make sure that the **Allow this user to all sites** and **Allow this user to all asset groups** options are checked.
>
> > Macro (rw-step)
>
> Save the changes.
## Run the collector
Once the data source is configured, you can either send us the required information if you want us to host and manage the collector for you (Cloud collector), or deploy and host the collector in your own machine using a Docker image (On-premise collector).
> Macro (rw-ui-tabs-macro)
>
> > Macro (rw-tab)
>
> We use a piece of software called Collector Server to host and manage all our available collectors. If you want us to host this collector for you, [get in touch with us](https://devo.my.site.com/support/login?ec=302&startURL=%2Fsupport%2Fs%2F) and we will guide you through the configuration.
>
> > Macro (rw-tab)
>
> This data collector can be run in any machine that has the Docker service available because it should be executed as a docker container. The following sections explain how to prepare all the required setup for having the data collector running.
>
> ### Structure
>
> The following directory structure should be created for use when running the Rapid7 InsightVM collector:
>
> ```
>
> └── devo-collectors/
> └── rapid7_insightvm/
> ├── certs/
> │ ├── chain.crt
> │ ├── .key
> │ └── .crt
> └── config/
> └── config-insightvm.yaml
> ```
>
> ### Devo credentials
>
> In Devo, go to **Administration → Credentials → X.509 Certificates**, download the **Certificate**, **Private key** and **Chain CA** and save them in `/devo-collectors/rapid7_insightvm/certs`. Learn more about security credentials in Devo [here](https://devodocs.atlassian.net/wiki/spaces/latest/pages/94763701).
>
> 
>
> ### Editing the config-insightvm.yaml file
>
> In the `config-insightvm.yaml` file, replace the ``, ``, ``, ``, and `` values with the proper ones.
>
> ```
> globals:
> debug: false
> id: not_used
> name: rapid7_insightvm
> persistence:
> type: filesystem # File system persistence ON
> config:
> directory_name: state # Directory where the persistence will be saved in case of using filesystem
> outputs:
> devo_1: # Cloud Devo config EU (for US use collector-us.devo.io)
> type: devo_platform
> config:
> address: collector-us.devo.io
> port: 443
> type: SSL
> chain: chain.crt
> cert: your_domain.crt
> key: your_domain.key
> inputs:
> rapid7:
> id: # The value of this field will be used internally for having independent persistence areas
> enabled: true
> requests_per_second: 5 # Setup how many request API por second
> credentials:
> user: # InsightVM on-premises user used to retrieve the data
> password: # InsightVM on-premises user's password
> server: # InsightVM on-premises server ip or name
> port: # InsightVM on-premises server port
> services: # Services available for this collector are vulnerabilities, assets, sites and scans
> vulnerabilities:
> request_period_in_seconds: 60 # Setting up time interval between API requests. 60 sec is recommended for vulnerabilities. 86400 or more for the other services.
> page_size: 100 # OPTIONAL, retrieving pagination size, only used to improve performance
> custom_tag: "my.app.insightvm.vulnerabilities" # OPTIONAL, devo custom tag
> assets:
> request_period_in_seconds: 86400
> page_size: 100
> custom_tag: "my.app.insightvm.assets"
> sites:
> request_period_in_seconds: 86400
> page_size: 100
> custom_tag: "my.app.insightvm.sites"
> scans:
> request_period_in_seconds: 86400
> page_size: 100
> custom_tag: "my.app.insightvm.scans"
> ```
>
> > ⚠️ **Optional fields**
> > ⚠️
> > ⚠️ - `custom_tag`:Used to send retrieved data to a [custom table](https://devodocs.atlassian.net/wiki/pages/createpage.action?spaceKey=NDT5&title=Custom%20and%20union%20tables) (`my.app`). Use it only if you want to define your own synthesis, or send data to a custom parser. If this field is not present, events are sent to the default tables `vuln.rapid7.insightvm.<>`
> > ⚠️ - `page_size:` Size of the batch that is retrieved in every iteration of the collector. Use it if you need to improve your bandwidth usage.
>
> ### Download the Docker image
>
> The collector should be deployed as a Docker container. Download the Docker image of the collector as a .tgz file by clicking the link in the following table:
>
> | **Collector Docker image** | **SHA-256 hash** |
> | --- | --- |
> | [collector-rapid7_insigthvm_collector_if-docker-image-1.7.0](https://drive.google.com/file/d/1ZeR3t1gvxp6JY0wX4zVUeW-DGmYyDhoA/view?usp=drive_link) | `3a9eb286b64617add98aab572c63701ff2f8dfb637dc772459f5cfca54e69425` |
>
> Use the following command to add the Docker image to the system:
>
> ```
> gunzip -c -.tgz | docker load
> ```
>
> > ℹ️ Once the Docker image is imported, it will show the real name of the Docker image (including version info). Replace `` with a proper value.
>
> #### Docker
>
> Execute the following command on the root directory `/devo-collectors/rapid7_insightvm/`
>
> ```
> docker run
> --name collector-
> --volume $PWD/certs:/devo-collector/certs
> --volume $PWD/config:/devo-collector/config
> --volume $PWD/state:/devo-collector/state
> --env CONFIG_FILE=config.yaml
> --rm
> --interactive
> --tty
> :
> ```
>
> > ⚠️ Replace `` with a proper value.
>
> #### Docker Compose
>
> The following Docker Compose file can be used to execute the Docker container. It must be created in the `/devo-collectors//` directory.
>
> ```
> version: '3'
> services:
> collector-:
> image: :${IMAGE_VERSION:-latest}
> container_name: collector-
> volumes:
> - ./certs:/devo-collector/certs
> - ./config:/devo-collector/config
> - ./credentials:/devo-collector/credentials
> - ./state:/devo-collector/state
> environment:
> - CONFIG_FILE=${CONFIG_FILE:-config.yaml}
> ```
>
> To run the container using docker-compose, execute the following command from the `/devo-collectors//` directory:
>
> ```
> IMAGE_VERSION= docker-compose up -d
> ```
>
> > ⚠️ Replace ``, `` and `` with the proper values.
## Change log
| **Release** | **Released on** | **Release type** | **Details** | **Recommendations** |
| --- | --- | --- | --- | --- |
| `v1.7.0` | `Jul 22, 2023` | [IMPROVEMENT]
[bug fixing] | Updated the docker base image to 1.3.0
- Update DCSDK from 1.11.1 to 1.12.2:
- Added new sender for relay in house + TLS
- Added persistence functionality for gzip sending buffer
- Added Automatic activation of gzip sending
- Improved behaviour when persistence fails
- Upgraded DevoSDK dependency
- Fixed console log encoding
- Restructured python classes
- Improved behavior with non-utf8 characters
- Decreased defaut size value for internal queues (Redis limitation, from 1GiB to 256MiB)
- New persistence format/structure (compression in some cases)
- Removed dmesg execution (It was invalid for docker execution)
- DevoSDK has been updated to version 5.4.0
**Bug fixing**
- Added the yield method to tackle the vulnerabilities not ingesting issue. | `Recommended version` |
| `v1.6.0` | `Jun 19, 2023` | [IMPROVEMENT]
[bug fixing] | **Improvements**
- Updated the docker base image to 1.2.0
- **Update DCSDK from 1.10.2 to 1.11.1**:
- Updated DevoSDK to v5.1.9
- Fixed some bug related to development on MacOS
- Added an extra validation and fix when the DCSDK receives a wrong timestamp format
- Added an optional config property for use the Syslog timestamp format in a strict way
- Updated DevoSDK to v5.1.10
- Fix for SyslogSender related to UTF-8
- Enhace of troubleshooting. Trace Standardization, Some traces has been introduced.
- Introduced a mechanism to detect "Out of Memory killer" situation
**Bug fixing**
- Fixed the issue of NoneType error. | `Update` |
| `v1.5.0` | `Nov 24, 2023` | [IMPROVEMENT] | **Improvements**:
- Upgraded DCSDK from 1.9.2 to 1.10.2
- Upgrade internal dependencies
- Added input metrics
- Modified output metrics
- Updated DevoSDK to version 5.1.6
- Standardized exception messages for traceability
- Added more detail in queue statistics
- Updated PythonSDK to version 5.0.7 | `Update` |
| `v1.4.0` | `Sept 12, 2023` | [IMPROVEMENT] | **Improvements:**
- Upgraded DCSDK from 1.4.3 to 1.9.2
- Upgrade internal dependencies
- Store lookup instances into DevoSender to avoid creation of new instances for the same lookup
- Ensure service_config is a dict into templates
- Ensure special characters are properly sent to the platform
- Changed log level to some messages from info to debug
- Changed some wrong log messages
- Upgraded some internal dependencies
- Changed queue passed to setup instance constructor
- New “templates” functionality
- Functionality for detecting some system signals for starting the controlled stopping
- Input objects sends again the internal messages to devo.collectors.out table
- Upgraded DevoSDK to version 3.6.4 to fix a bug related to a connection loss with Devo
- Refactored source code structure
- Changed way of executing the controlled stopping
- Minimized probabilities of suffering a DevoSDK bug related to “sender” to be null
- Ability to validate collector setup and exit without pulling any data
- Ability to store in the persistence the messages that couldn’t be sent after the collector stopped
- Ability to send messages from the persistence when the collector starts and before the puller begins working
- Ensure special characters are properly sent to the platform
- Added a lock to enhance sender object
- Added new class attrs to the setstate and getstate queue methods
- Fix sending attribute value to the setstate and getstate queue methods
- Added log traces when queues are full and have to wait
- Added log traces of queues time waiting every minute in debug mode
- Added method to calculate queue size in bytes
- Block incoming events in queues when there are no space left
- Send telemetry events to Devo platform
- Upgraded internal Python dependency Redis to v4.5.4
- Upgraded internal Python dependency DevoSDK to v5.1.3
- Fixed obfuscation not working when messages are sent from templates
- New method to figure out if a puller thread is stopping
- Upgraded internal Python dependency DevoSDK to v5.0.6
- Improved logging on messages/bytes sent to Devo platform
- Fixed wrong bytes size calculation for queues
- New functionality to count bytes sent to Devo Platform (shown in console log)
- Upgraded internal Python dependency DevoSDK to v5.0.4
- Fixed bug in persistence management process, related to persistence reset
- Aligned source code typing to be aligned with Python 3.9.x
- Inject environment property from user config
- Obfuscation service can be now configured from user config and module definition
- Obfuscation service can now obfuscate items inside arrays
- Ensure special characters are properly sent to the platform
- Changed log level to some messages from info to debug
- Changed some wrong log messages
- Upgraded some internal dependencies
- Changed queue passed to setup instance constructor | `Updated` |
| `v1.3.0` | `Oct 31,2022` | [IMPROVEMENT] | **Improvements**:
- Events persistence improved and moved event sending to batch processing
- Devo Collector SDK version has been updated from `1.4.2` to `1.4.3`
- Added log traces for knowing the execution environment status (debug mode)
- Fixes in the current puller template version | `Update` |
| `v1.2.0` | 9/13/2022 | [IMPROVEMENT] | **Improvements:**
- Upgraded underlay IFC SDK `v1.3.0` to `v1.4.2`.
- Updated the underlying `DevoSDK` package to `v3.6.4` and dependencies, this upgrade increases the resilience of the collector when the connection with Devo or the Syslog server is lost. The collector is able to reconnect in some scenarios without running the self-kill feature.
- Support for stopping the collector when a `GRACEFULL_SHUTDOWN` system signal is received.
- Re-enabled the logging to `devo.collector.out` for Input threads.
- Improved self-kill functionality behavior.
- Added more details in log traces.
- Added log traces for knowing system memory usage. | `-` |