Containerized Scan Engine
The Containerized Scan Engine is a form of Distributed Scan Engine that delivers the Scan Engine as a packaged or portable application that can easily be deployed to modern infrastructure. The Containerized Scan Engine ships as a single image and includes the Scan Engine software and all required dependencies, such as the Operating System, libraries, and associated files. Information about the Containerized Scan Engine is also maintained on Rapid7’s Docker Hub page.
- Release schedule - The Containerized Scan Engine follows the regular product and content release schedule. Updates will be made on a continuous basis.
- Supported architecture - The Containerized Scan Engine supports AMD64 architecture, specifically x86_64 architecture.
Requirements
macOS supportability restriction
M1 chips are not supported.
For information about the Containerized Scan Engine's system requirements, refer to System Requirements.
Prerequisites
Before you begin, ensure that you have:
- Access to the Security Console
- The Console Shared Secret Key
- The latest engine image -
docker pull rapid7/insightvm_scan_engine:latest
TCP port
The TCP port, 40814, is used by the Security Console to communicate with the Containerized Scan Engine. However, if the Containerized Scan Engine is connected to the Security Console it does not need to be exposed.
Image tags
We provide multiple tags to help users identify the Scan Engine and content versions. The Containerized Scan Engine is updated continuously and bundled with the latest available content at the time of release. Refer to the digest of the image in order to see the correlation between tags.
| Tag Value | Description | Example |
|---|---|---|
| latest | The most recent product and content release version available. | latest |
| product version | The product release version. | 6.6.188 |
| product and content version | The content release version. | 6.6.188-content1.1.2837 |
Running the Containerized Scan Engine
Linux OS examples
The examples listed in this page are relevant to Linux users only.
Existing mount points
These are the existing mount points associated with the Containerized Scan Engine:
| Mount point | Description |
|---|---|
/opt/rapid7/nexpose/nse/scans | The scans directory is where the Containerized Scan Engine temporarily writes logs and results to. The Security Console will ask the Containerized Scan Engine to remove scan data associated with completed scans when the data associated with it is transferred to the Security Console. Though, if the Containerized Scan Engine is upgraded before all the scan data is transferred to the Security Console, and the scans directory is not a persisted volume, the scan data will be lost. This directory is recommended. The file system performance of this directory can have an impact on scan performance. |
/opt/rapid7/nexpose/nse/conf | The configuration directory stores the Containerized Scan Engine, logger configuration properties, and a list of trusted consoles. The configuration directory can be optional if auto-pairing environment variables are used, since the Containerized Scan Engine will auto-pair each time it starts. However, we do recommend that an external configuration directory be used. |
/opt/rapid7/nexpose/nse/keystores | The keystores directory stores the private identity of the Containerized Scan Engine, and is used to establish trust with the Security Console. This directory is optional if you do not intend to keep the Containerized Scan Engine up to date or paired to the Security Console. Otherwise, the keystores directory must be mounted or the Containerized Scan Engine will generate a new private identity each time it is started. |
/opt/rapid7/nexpose/nse/logs | The logs directory stores logs on an eternal volume. This directory is optional. The file system performance of this directory can have an impact on the performance of individual scans. |
Environment variables
You may encounter the following environment variables:
| Environment Variable | Description |
|---|---|
| CONNECT_TO_ADDRESS | This is the IP address where the Security Console will wait for connections from the Containerized Scan Engine. |
| CONNECT_TO_SHARED_SECRET | If a shared secret is provided, the Containerized Scan Engine will add itself to the Security Console. The shared secret must be the same as the one generated on the Containerized Scan Engine Management page in the Security Console's UI. In the event that the shared secret is not provided the Containerized Scan Engine must be added on the Containerized Scan Engine Management page under the Administration tab in the Security Console's UI. |
| ACCEPT_FROM_ADDRESS | This IP address will be used by the Security Console to connect to the Containerized Scan Engine. |
| ACCEPT_FROM_SHARED_SECRET | If a shared secret is provided, the Containerized Scan Engine will challenge the Security Console and will not trust the Security Console if the response from the Security Console is incorrect. The shared secret must be the same as the one generated on the Containerized Scan Engine Management page in the Security Console's UI. In the event that the shared secret is not provided, the Containerized Scan Engine will not challenge the Security Console and will trust the first console that connects to it using the IP address. |
Environment variable stipulations
You can use a CONNECT_TO_ADDRESS and an ACCEPT_FROM_ADDRESS at the same time, but it is not possible to use multiple addresses for CONNECT_TO_ADDRESS or ACCEPT_FROM_ADDRESS at the same time.
Running containers with Docker commands
You can run the following Docker commands:
| Command | Description |
|---|---|
docker pull rapid<br>7<br>/insightvm_scan_engine<br>:<br>latest | Pulls the latest image |
docker run --env CONNECT_TO_SHARED_SECRET=<SHARED_SECRET> --env CONNECT_TO_ADDRESS=<CONSOLE_ADDRESS> rapid<br>7<br>/insightvm_scan_engine<br>:<br>latest | Starts a container connecting to the Security Console |
docker run --env ACCEPT_FROM_ADDRESS=<CONSOLE_ADDRESS> --env ACCEPT_FROM_SHARED_SECRET=<SHARED_SECRET> -p <br>40814<br>:<br>40814<br> rapid<br>7<br>/insightvm_scan_engine<br>:<br>latest | Starts a container with accepting connection from the Security Console |
docker run --env CONNECT_TO_SHARED_SECRET=<SHARED_SECRET> --env CONNECT_TO_ADDRESS=<CONSOLE_ADDRESS> -v /var/docker/nse-container/data/rapid<br>7<br>/nexpose/nse/conf<br>:<br>/opt/rapid<br>7<br>/nexpose/nse/conf -v /var/docker/nse-container/data/rapid<br>7<br>/nexpose/nse/keystores<br>:<br>/opt/rapid<br>7<br>/nexpose/nse/keystores -v /var/docker/nse-container/data/rapid<br>7<br>/nexpose/nse/logs<br>:<br>/opt/rapid<br>7<br>/nexpose/nse/logs -v /var/docker/nse-container/data/rapid<br>7<br>/nexpose/nse/scans<br>:<br>/opt/rapid<br>7<br>/nexpose/nse/scans rapid<br>7<br>/insightvm_scan_engine<br>:<br>latest | Starts a container with external mount points |
Running containers with Docker Compose
You can run the following commands with Docker Compose:
| Command | Description |
|---|---|
version<br>:<br> <br>"3"<br><br>2<br>services<br>:<br><br>3<br> nse<br>-1<br>:<br><br>4<br> image<br>:<br> rapid<br>7<br>/insightvm_scan_engine<br>5<br> volumes<br>:<br><br>6<br> - /var/docker/nse<br>-1<br>/data/rapid<br>7<br>/nexpose/nse/conf<br>:<br>/opt/rapid<br>7<br>/nexpose/nse/conf<br>7<br> - /var/docker/nse<br>-1<br>/data/rapid<br>7<br>/nexpose/nse/keystores<br>:<br>/opt/rapid<br>7<br>/nexpose/nse/keystores<br>8<br> - /var/docker/nse<br>-1<br>/data/rapid<br>7<br>/nexpose/nse/logs<br>:<br>/opt/rapid<br>7<br>/nexpose/nse/logs<br>9<br> - /var/docker/nse<br>-1<br>/data/rapid<br>7<br>/nexpose/nse/scans<br>:<br>/opt/rapid<br>7<br>/nexpose/nse/scans<br>10<br> environment<br>:<br><br>11<br> - CONNECT_TO_ADDRESS=<CONSOLE_ADDRESS><br>12<br> - CONNECT_TO_SHARED_SECRET=<SHARED_SECRET> | Runs a single container with Docker Compose connected to the Security Console |
version<br>:<br> <br>"3"<br><br>2<br>services<br>:<br><br>3<br> nse<br>-1<br>:<br><br>4<br> image<br>:<br> rapid<br>7<br>/insightvm_scan_engine<br>5<br> ports<br>:<br><br>6<br> - <br>"40814:40814"<br><br>7<br> volumes<br>:<br><br>8<br> - /var/docker/nse<br>-1<br>/data/rapid<br>7<br>/nexpose/nse/conf<br>:<br>/opt/rapid<br>7<br>/nexpose/nse/conf<br>9<br> - /var/docker/nse<br>-1<br>/data/rapid<br>7<br>/nexpose/nse/keystores<br>:<br>/opt/rapid<br>7<br>/nexpose/nse/keystores<br>10<br> - /var/docker/nse<br>-1<br>/data/rapid<br>7<br>/nexpose/nse/logs<br>:<br>/opt/rapid<br>7<br>/nexpose/nse/logs<br>11<br> - /var/docker/nse<br>-1<br>/data/rapid<br>7<br>/nexpose/nse/scans<br>:<br>/opt/rapid<br>7<br>/nexpose/nse/scans<br>12<br> environment<br>:<br><br>13<br> - ACCEPT_FROM_ADDRESS=<CONSOLE_ADDRESS><br>14<br> - ACCEPT_FROM_SHARED_SECRET=<SHARED_SECRET> | Runs a single container with accepting connections from the Security Console |
version<br>:<br> <br>"3"<br><br>2<br>services<br>:<br><br>3<br> nse<br>-1<br>:<br><br>4<br> image<br>:<br> rapid<br>7<br>/insightvm_scan_engine<br>5<br> volumes<br>:<br><br>6<br> - /var/docker/nse<br>-1<br>/data/rapid<br>7<br>/nexpose/nse/conf<br>:<br>/opt/rapid<br>7<br>/nexpose/nse/conf<br>7<br> - /var/docker/nse<br>-1<br>/data/rapid<br>7<br>/nexpose/nse/keystores<br>:<br>/opt/rapid<br>7<br>/nexpose/nse/keystores<br>8<br> - /var/docker/nse<br>-1<br>/data/rapid<br>7<br>/nexpose/nse/logs<br>:<br>/opt/rapid<br>7<br>/nexpose/nse/logs<br>9<br> - /var/docker/nse<br>-1<br>/data/rapid<br>7<br>/nexpose/nse/scans<br>:<br>/opt/rapid<br>7<br>/nexpose/nse/scans<br>10<br> environment<br>:<br><br>11<br> - CONNECT_TO_ADDRESS=<CONSOLE_ADDRESS><br>12<br> - CONNECT_TO_SHARED_SECRET=<SHARED_SECRET><br>13<br> nse<br>-2<br>:<br><br>14<br> image<br>:<br> rapid<br>7<br>/insightvm_scan_engine<br>15<br> volumes<br>:<br><br>16<br> - /var/docker/nse<br>-2<br>/rapid<br>7<br>/nexpose/nse/conf<br>:<br>/opt/rapid<br>7<br>/nexpose/nse/conf<br>17<br> - /var/docker/nse<br>-2<br>/rapid<br>7<br>/nexpose/nse/keystores<br>:<br>/opt/rapid<br>7<br>/nexpose/nse/keystores<br>18<br> - /var/docker/nse<br>-2<br>/rapid<br>7<br>/nexpose/nse/logs<br>:<br>/opt/rapid<br>7<br>/nexpose/nse/logs<br>19<br> - /var/docker/nse<br>-2<br>/rapid<br>7<br>/nexpose/nse/scans<br>:<br>/opt/rapid<br>7<br>/nexpose/nse/scans<br>20<br> environment<br>:<br><br>21<br> - CONNECT_TO_ADDRESS=<CONSOLE_ADDRESS><br>22<br> - CONNECT_TO_SHARED_SECRET=<SHARED_SECRET><br>23<br> nse<br>-3<br>:<br><br>24<br> image<br>:<br> rapid<br>7<br>/insightvm_scan_engine<br>25<br> volumes<br>:<br><br>26<br> - /var/docker/nse<br>-3<br>/rapid<br>7<br>/nexpose/nse/conf<br>:<br>/opt/rapid<br>7<br>/nexpose/nse/conf<br>27<br> - /var/docker/nse<br>-3<br>/rapid<br>7<br>/nexpose/nse/keystores<br>:<br>/opt/rapid<br>7<br>/nexpose/nse/keystores<br>28<br> - /var/docker/nse<br>-3<br>/rapid<br>7<br>/nexpose/nse/logs<br>:<br>/opt/rapid<br>7<br>/nexpose/nse/logs<br>29<br> - /var/docker/nse<br>-3<br>/rapid<br>7<br>/nexpose/nse/scans<br>:<br>/opt/rapid<br>7<br>/nexpose/nse/scans<br>30<br> environment<br>:<br><br>31<br> - CONNECT_TO_ADDRESS=<CONSOLE_ADDRESS><br>32<br> - CONNECT_TO_SHARED_SECRET=<SHARED_SECRET> | Runs multiple engines connecting to the Security Console |
Test the Containerized Scan Engine
If you want to start a Containerized Scan Engine to test how it works, you are able to run it in daemon mode. However, the Containerized Scan Engine will not be useful if it is not connected with the Security Console.
To test the Containerized Scan Engine without connecting to the Security Console:
- Run the container:
docker run --name first_engine rapid7/insightvm_scan_engine:latest. - Verify that the container is running:
docker ps.
Run the Containerized Scan Engine and connect to the Security Console
You can choose to either standard pair or reverse pair the Containerized Scan Engine to the Security Console.
Configure a standard pair with your Security Console - docker run --env ACCEPT_FROM_ADDRESS=<CONSOLE_ADDRESS> --env ACCEPT_FROM_SHARED_SECRET=<SHARED_SECRET> -p 40814:40814 rapid7/insightvm_scan_engine:latest
You may need to use the gateway address as your CONSOLE_ADDRESS, depending on your Docker network configuration when standard pairing - docker inspect <container-id> | grep Gateway
Configure a reverse pair with your Security Console - docker run --env CONNECT_TO_SHARED_SECRET=<SHARED_SECRET> --env CONNECT_TO_ADDRESS=<CONSOLE_ADDRESS> rapid7/insightvm_scan_engine:latest
Frequently Asked Questions
Why is the Containerized Scan Engine run as root?
The Containerized Scan Engine is running as root as this is required in order to perform some checks. The Containerized Scan Engine is able to run without root but this will skip some checks. For steps on how to mitigate risk, refer to Running in Rootless Mode and Linux Post-Installation Steps for Docker Engine which have been outlined by Docker.
How to connect the Containerized Scan Engine to the Security Console on a non-default port?
The TCP port 40814 is used by the Security Console to communicate with the Scan Engine. If the Scan Engine connects to the Security Console, TCP port 40814 does not need to be exposed. Currently, this functionality is not supported on the container itself, however the user is able to map the port.
For example, run this Docker command while mapping the TCP port:
docker run --env CONNECT_TO_ADDRESS=127.0.0.1 -p 40814:40814 --env CONNECT_TO_SHARED_SECRET=<shared-secret> rapid7/insightvm_scan_engine:latest
Refer to Container Networking for more information.
Troubleshooting
Confirm which address is needed to connect for "CONNECT_TO_ADDRESS"
- List the Docker networks using
docker networkandls. - Inspect the bridge network using
docker inspect bridge. - Connect with the address listed under Gateway.
Configure log levels
Log levels can be changed using the docker exec command or using mount points.
Configure log levels using docker exec
This approach allows you to change log levels by opening the Containerized Scan Engine and manually changing the logging.xml file.
- Run the container.
docker run --env CONNECT_TO_ADDRESS=<address> --env CONNECT_TO_SHARED_SECRET=<shared_secret> rapid7/insightvm_scan_engine:latest
- Navigate to a new terminal window and copy the container ID.
docker ps
- In another terminal window run these commands in order to run vi editor inside the Docker container:
docker exec -it <container_id> sh -c "apt-get update && apt-get install -y vim"docker exec -it <container_id> sh -c "apt list --installed | grep vim"
- Run the following
docker execcommand to open the Docker container's interactive shell:docker exec -it <container_id> sh
- Navigate to the conf directory in the container.
cd /opt/rapid7/nexpose/nse/conf
- Change the log level in the
logging.xmlfile. The container logs will now output the logs at the level you want.vim logging.xml
- To exit the interactive shell without interrupting the container's process, enter Ctr + P > Ctr + Q.