Installing scan agents via Docker
You can install the Invicti Enterprise scan agent on any operating system that has Docker. Using Docker means you don't need to install redundant files such as drivers or operating system kernels. This document explains how to install and run the scan agent using Docker.
Detecting out-of-band vulnerabilities To detect out-of-band vulnerabilities via Invicti Hawk, ensure you allowlist the following ports on your agent server:
For more information about Invicti Hawk, refer to How Invicti Hawk finds vulnerabilities. |
How to install a scan agent via Docker
Installing and running a scan agent via Docker has four steps. Ensure your system meets the prerequisites listed below, then follow the instructions outlined in each step.
PREREQUISITES:
|
Step 1: How to pull the Docker scan agent from the registry
- In Invicti Enterprise, select Agents > Manage Agents from the left-side menu.
- Click + Configure New Agent.
- The information needed for the remaining steps in this section is now visible in the Docker CLI & Openshift section.
- Click the copy to clipboard icon next to the first step in the Docker CLI & Openshift instructions.
- Open Terminal and paste the command you copied from Invicti Enterprise in the previous step.
docker login -u <your email address> registry.invicti.com |
- Terminal will now ask for a password.
- Click the copy to clipboard icon next to the second step in the Docker CLI & Openshift instructions, then paste the password into Terminal.
- You are now logged in to the Invicti registry.
- Click the copy to clipboard icon next to the third step For Docker Agent, then paste the command into Terminal.
- The latest version of Invicti Enterprise will now be pulled from the Invicti registry into Docker.
Pulling a previous version: You can adjust the command to pull a previous version of Invicti Enterprise rather than the latest available version. For example, the command in the image above pulls version 24.10.1. If you wanted to pull version 24.10.0, you would change the end of the command as follows: docker pull registry.invicti.com/ie-agent:24.10.0 |
Step 2: How to prepare the scan agent
- Using the commands below, create a user and a group called “invicti”. These are required, as the Docker scan agent runs with a non-root user. Then, add this new user to the Docker group.
groupadd -g 1001 invicti |
useradd -u 1001 -r -g 1001 -d /home/invicti -s /bin/bash invicti |
mkdir -p /home/invicti > create home directory for user |
chown -R invicti:invicti /home/invicti |
usermod -aG docker invicti |
- Switch to the invicti user and create a directory to save the logs consistently in the same path.
su - invicti mkdir invictiLogs # creates a folder to store agent logs |
Step 3: How to install ClamAV for the Docker scan agent (optional)
ClamAV is required if you want the Invicti Enterprise Docker scan agent to run malware analysis. If you do not, you can skip this section and go to step 4.
- To pull and run the latest ClamAV image, run the following command:
docker run --name clamav -d -p 3310:3310 clamav/clamav:latest |
Step 4: How to run the Docker scan agent
The final step is to run a container. The table below lists and explains the parameters required to configure the container.
Parameter | Description |
-d: | This denotes daemon mode. The container will work in the background. |
–name: | This gives a name to the container. |
–user | This instructs the container to run with this user. |
–restart=always: | This makes the container start automatically when the Docker service starts. |
–volume: | The parameters mount a directory in the container with a directory in the host. This setting allows you to see agent reports. |
-e: | This parameter is used to set the environment variable for the container. The ApiToken, ApiRootUrl, and AgentName settings will be used by the scanner agent. AgentName: This can be anything you want. It will be displayed when you start a new scan. If you plan to install more than one instance of the agent, make sure you set a unique AgentName value for each instance, as it will be needed later. ApiToken: In Invicti Enterprise, this is displayed on the Configure New Agent page. From the main menu, go to Agents > Manage Agents > + Configure New Agent. In the Agent Token field, click the copy to clipboard icon. Paste this value into the ApiToken field when creating a container. ApiRootUrl: This is the URL of Invicti Enterprise On-Demand or the URL of your Invicti Enterprise On-Premises instance. The URL changes according to region:
ScanDataFolderPath: This is your scan data folder. (This is optional). If you want to change the default folder for saving the scan data, add the following parameter before running the container: -e "ScanDataFolderPath={Scan data folder}"\ IgnoreSslCertificateErrors: This ignores any SSL certificate errors on the scan target website. ClamAvServiceAddress: This is the IP Address of the ClamAV container host. (This is optional). ClamAvServicePort: This is the port number that ClamAV listens to. (This is optional). |
agent:{tag}: | This is the image name from which the container will be created. The name of the image is agent, whereas {tag} is the version number of the image. |
- Execute the following command to create a container. Replace all curly bracketed {} content with the relevant information using the table above for guidance.
docker run -d --name {container name} --restart=always \ --volume "$(pwd)/invictiLogs:/app/Logs" \ -e "ApiRootUrl={api url}" \ -e "ApiToken={api token}" \ -e "AgentName={agent name}" \ -e "AgentMode=Scanner" \ -e "IgnoreSslCertificateErrors=false" \ -e "ClamAvServiceAddress={ClamAV container Host IP}" \ -e "ClamAvServicePort=3310" \ registry.invicti.com/ie-agent:{tag} |
- After the command is executed, the container is created. To view the result, execute the following command:
docker container ls |
The scan agent container is now installed. To check its status in Invicti Enterprise, go to Agents > Manage Agents. The scan agent will be listed on the Agents page.
You can now start a scan using the installed scan agent. Navigate to Scans > New Scan and select a target that has the agent mode as Internal. Configure the other settings that are required to start a scan and select which agent will be used to scan the target.