Installing scan agents via Docker

This document is for:

Invicti Enterprise On-Demand, Invicti Enterprise On-Premises

You can install the Invicti Enterprise scan agent on any operating system that has Docker Linux installed. Using Docker eliminates the need to install unnecessary files, such as drivers or operating system kernels, and removes the hassle of manually managing dependencies, ensuring a smoother installation process.

This document provides guidance on installing and running the scan agent using Docker. It includes a list of environment variables and explains how to retrieve scanner agent logs.

Our documentation assumes that Docker and Docker Compose Plugin are installed on your system. While deploying agents without Docker Compose is possible, it requires manually converting the docker-compose.yml configuration into equivalent docker run commands. This process may involve replicating environment variables, volume mappings, network settings, and other parameters defined in the Compose file. Refer to the official Docker documentation for more information.

Detecting out-of-band vulnerabilities

To detect out-of-band vulnerabilities via Invicti Hawk, ensure you allowlist the following ports on your agent server:

TCP 80 and 443
UDP 53

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 two steps. Ensure your system meets the prerequisites listed below, then follow the instructions outlined in each step.

PREREQUISITES:

You already have a Docker host deployed, including Docker compose plugin.
Ensure that the user you use to log in to the Docker host is a member of the Docker group or you have sudo rights.
Docker - to verify Docker installation on your OS, run the 'docker --version' command in Terminal. If you have Docker, Terminal shows the version information. Otherwise, it shows an error message. For more information about installing Docker, refer to the Docker website.
4 GB RAM or higher is recommended per agent.
2 CPU cores per agent as a minimum.

Step 1: Pulling the Docker scan agent from the Invicti 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.

To update the agent to the latest available version, update the Docker compose file to have the latest available version tag and run 'docker compose pull' and 'docker compose up -d'.

Step 2: Deploying the scanner agent

Create a folder for the agent configuration and navigate to the folder in Terminal.

user@debian:~$ mkdir ~/docker_agent

user@debian:~$ cd ~/docker_agent

user@debian:~/docker_agent$

Create a compose.yml file in the folder (using a text editor like nano) with the following contents. Ensure that you adjust the values for:

ApiRootUrl (the URL for your web application)
ApiToken (retrieved from the Configure New Agent page)
AgentName (this needs to be unique per scanner agent)
image (version number retrieved from the Configure New Agent page)

services:

ie-agent:

restart: always

volumes:

- scannerAgent:/app/Logs

environment:

ApiRootUrl: http://172.18.130.52

ApiToken: qIa/aRdWSUdV7K7sb5k9ABWkxxxxxxxxxxxxxxxxxxxx

AgentName: "Docker Agent - 01"

AgentMode: Scanner

IgnoreSslCertificateErrors: "false"

ClamAvServiceAddress: clamav

ClamAvServicePort: 3310

networks:

- invicti-network

image: registry.invicti.com/ie-agent:24.10.0

clamav:

restart: always

image: clamav/clamav:latest

networks:

- invicti-network

ports:

- "3310:3310"

volumes:

scannerAgent: null

networks:

invicti-network: {}

Start your Docker scanner agent using the command below. If you encounter a permission error, ensure that the user you are using belongs to the Docker user group or run the command with sudo.

user@debian:~/docker_agent$ docker compose up -d

[+] Running 16/16

✔ clamav Pulled

✔ 43c4264eed91 Pull complete

✔ 7e06825977fd Pull complete

✔ a97bdb33fade Pull complete

✔ a40f28dbbbea Pull complete

✔ 7e788dc85b38 Pull complete

✔ f01867f141a1 Pull complete

✔ f0d441b80d89 Pull complete

✔ ie-agent Pulled

✔ 762bedf4b1b7 Pull complete

✔ 911a7a843dda Pull complete

✔ 6443a1eb4a90 Pull complete

✔ ab95a2327b33 Pull complete

✔ 5c752ad9826e Pull complete

✔ e10569dbe7d1 Pull complete

✔ 3bbcfbf04dfe Pull complete

[+] Running 4/4

✔ Network docker_agent_invicti-network Created

✔ Volume "docker_agent_scannerAgent" Created

✔ Container docker_agent-clamav-1 Started

✔ Container docker_agent-ie-agent-1 Started

user@debian:~/docker_agent$

In the Invicti Enterprise web application, select Agents > Manage Agents from the left-side menu.
Look for the new agent to confirm that it has started. Depending on the resources available to the Docker and web application machines, this may take a few minutes.

Environment variables

For Docker agents, the appsettings.json file is not used and will be ignored.

The sample compose.yml file includes an environment section with a minimal set of variables required to start the container. You can add other variables as needed. Refer to the following list for some additional variables you can configure:

Variable	Description	Example
ProxyMode	Proxy mode for the agent.	SystemProxy (for a Docker agent, the effect is the same as for NoProxy) NoProxy CustomProxy
ProxyAddress	IP/Hostname for the proxy.	172.18.130.254
ProxyDomain	Authentication domain for the proxy.	Workgroup
ProxyPort	Port number for the proxy.	8080
ProxyUserName	The username for the proxy.	user
ProxyPassword	Password for the proxy.	Use a strong password that avoids using names, common words, or predictable patterns.
ProxyUseDefaultCredentials	A setting that specifies whether to use the system's default credentials when authenticating to a proxy.	false true
ProxyByPassList	Proxy bypass list as a JSON string
ProxyByPassOnLocal	A setting that specifies whether the proxy should or should not use local network requests.	false true
IgnoreSslCertificateErrors	A setting that specifies whether the agent should trust TLS certificates that are not valid.	false true
RequiresHttpRequester	A setting that specifies whether to use HTTPRequester.	false true

Obtaining scanner agent logs

You can view the scanner agent logs directly by running the following command. Replace <container_id> with the ID or name of the container running the scanner agent.

docker logs <container_id>

NOTE: To find the exact ID or name, use 'docker ps' to list all running containers or 'docker ps -a' if the agent is not currently running.