Installing scanner agents using Docker (CLI)
If you want to scan a website in a demilitarized zone (DMZ), internal networks that are not publicly accessible, you can install Invicti scanner agents in your network. You can install the Invicti Enterprise scanner agent on any operating system that has Docker. Using Docker means you don't need to install redundant files like drivers or operating system kernels, for example.
This topic explains how to install the Invicti Enterprise scanner agent on Windows, Linux, or macOS via docker using the command line interface (CLI). Except for the steps for installing Docker, the steps are the same for each operating system.
Detecting out-of-band vulnerabilities To detect out-of-band vulnerabilities via Invicti Hawk, please allowlist the following ports on your agent server: TCP 80 and 443, UDP 53. For further information about Invicti Hawk, refer to How Invicti Hawk Finds Vulnerabilities. |
Prerequisites:
- Docker installed. To find out if your host OS has Docker installed, type the following code in the terminal: docker -v (If you have Docker, terminal shows the version information. Otherwise, it shows error messages. For further information about installing Docker, refer to the Docker website)
- 4 GB RAM or higher is recommended
- Administrator privileges to run the required commands.
Downloading and installing the agent
There are four steps for downloading and running the docker scanner agent using the command line interface.
- Pulling the docker scanner agent from the registry
- Preparing the agent
- (Optional) Installing ClamAV for the docker scanner agent
- Running the docker scanner agent
Step 1: How to pull the docker scanner agent from the registry
- Open Docker.
- Sign in to Invicti Enterprise, then from the main menu, select Agents > Manage Agents.
- Click + Configure New Agent. Now you will see the Docker CLI information needed for the remaining steps in this section.
- Open a terminal window.
- Enter this command into your terminal window:
docker login -u <your email address> registry.invicti.com |
Tip: You can copy and paste the command directly from step 1 of the Docker CLI section on the Configure New Agent screen in Invicti Enterprise. |
- When asked for a password, copy and paste the password from step 2 of the Docker CLI section on the Configure New Agent screen in Invicti Enterprise.
- After successful authentication, enter the following command to pull the latest version of Invicti Enterprise:
docker pull registry.invicti.com/ie-agent:latest |
Alternatively, copy and paste the command from step 3 of the Docker CLI section on the Configure New Agent screen in Invicti Enterprise.
Pulling a previous version You can pull a specific version of the docker image. For example, you can write 23.5.0 instead of the latest tag. By doing this, you pull the 23.5.0 version of the Invicti Enterprise Docker agent image. |
Step 2: How to prepare the agent to run
- Create a user and a group called “invicti”. These are required, as the docker 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: (optional) How to install ClamAV for the docker scanner agent
Tip: ClamAV is required if you want the Invicti Enterprise docker scanner 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 scanner agent
Now that the latest version of the scanner agent is installed, the next 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. This text will be displayed when you are starting 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, the Agent Token is displayed on the Configure New Agent page. Copy this value into the apiToken. (From the main menu, go to Agents > Manage Agents > + Configure New Agent. In the Agent Token field, select Copy to clipboard.) ApiRootUrl: This is the URL of Invicti Enterprise On-Demand or Invicti Enterprise On-Premises. 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. We use the latest in our case. Note that you can pull a specific version of the docker image. For example, you can write 23.5.0 instead of the latest tag. This would pull the 23.5.0 version of the Invicti Enterprise Docker agent 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:latest |
After the command is executed, the container is created. To see the result, you can execute the following command:
docker container ls |
The scanner agent container is now installed. You can check its status in Invicti Enterprise by going to the main menu and selecting Agents > Manage Agents.
Now you can start a scan through the scanner agent you just installed. To do that, go to Scans > New Scan and select a website whose agent mode is Internal. Then with other settings that are required to start a scan, you can also select which agent will be used to scan the target.
