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 ValueDescriptionExample
latestThe most recent product and content release version available.latest
product versionThe product release version.6.6.188
product and content versionThe 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 pointDescription
/opt/rapid7/nexpose/nse/scansThe 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/confThe 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/keystoresThe 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/logsThe 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 VariableDescription
CONNECT_TO_ADDRESSThis is the IP address where the Security Console will wait for connections from the Containerized Scan Engine.
CONNECT_TO_SHARED_SECRETIf 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_ADDRESSThis IP address will be used by the Security Console to connect to the Containerized Scan Engine.
ACCEPT_FROM_SHARED_SECRETIf 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:

CommandDescription
docker pull rapid<br>7<br>/insightvm_scan_engine<br>:<br>latestPulls 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>latestStarts 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>latestStarts 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>latestStarts a container with external mount points

Running containers with Docker Compose

You can run the following commands with Docker Compose:

CommandDescription
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:

  1. Run the container: docker run --name first_engine rapid7/insightvm_scan_engine:latest.
  2. 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"
  1. List the Docker networks using docker network and ls.
  2. Inspect the bridge network using docker inspect bridge.
  3. 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.

  1. Run the container.
    • docker run --env CONNECT_TO_ADDRESS=<address> --env CONNECT_TO_SHARED_SECRET=<shared_secret> rapid7/insightvm_scan_engine:latest
  2. Navigate to a new terminal window and copy the container ID.
    • docker ps
  3. 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"
  4. Run the following docker exec command to open the Docker container's interactive shell:
    • docker exec -it <container_id> sh
  5. Navigate to the conf directory in the container.
    • cd /opt/rapid7/nexpose/nse/conf
  6. Change the log level in the logging.xml file. The container logs will now output the logs at the level you want.
    • vim logging.xml
  7. To exit the interactive shell without interrupting the container's process, enter Ctr + P > Ctr + Q.