This document is for:

Invicti Enterprise on-demand, Invicti Enterprise on-premises

Install scan agents via Docker

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.

The 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.

Installing and running a scan agent via Docker has two steps. Ensure your system meets the prerequisites listed below, follow the instructions outlined in each step, and refer to our trustlisting guidelines to ensure uninterrupted operation:

Trustlist guidelines

Refer to these documents to trustlist the correct IP addresses based on your region:

• Trustlist requirements for Invicti Enterprise on-demand - US region
• Trustlist requirements for Invicti Enterprise on-demand - US-2 region
• Trustlist requirements for Invicti Enterprise on-demand - EU region
• Trustlist requirements for Invicti Enterprise on-demand - CA region
• Trustlist requirements for Invicti Enterprise on-premises

Prerequisites

• Docker and the Docker Compose plugin are installed on your Docker host. To verify, run docker --version and docker compose version in your terminal. For installation instructions, refer to the Docker website.
• Your user account has Docker group membership or sudo rights on the Docker host.
• Your Docker host has at least 2 CPU cores and 4 GB RAM per agent.

Setting up Docker on Windows

Docker requires a Linux environment. On Windows, you can use Windows Subsystem for Linux (WSL2):

1. Open Command Prompt and verify WSL2 is installed:

   wsl --version

2. Install Ubuntu (or another Linux distro):

   wsl --install -d Ubuntu

   When prompted, create a username and password for your Linux environment.
3. Launch Ubuntu:

   wsl -d Ubuntu

4. Inside Ubuntu, add Docker's official repository and install Docker:

   sudo apt-get update
   sudo apt-get install -y ca-certificates curl
   sudo install -m 0755 -d /etc/apt/keyrings
   sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
   sudo chmod a+r /etc/apt/keyrings/docker.asc
   echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
   sudo apt-get update
   sudo apt-get install -y docker.io docker-compose-plugin

5. Add your user to the Docker group so you can run Docker without sudo:

   sudo usermod -aG docker $USER

   Close and reopen your terminal for the change to take effect.
6. Verify the installation:

   docker --version
   docker compose version

Steps 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 above, then follow the instructions outlined in each step.

Step 1: Import the scan agent Docker image

There are two options for importing the scan agent image:

• Option 1 - Pull directly from the Invicti registry. This requires an internet connection and credentials from the Configure new agent page.
• Option 2 - Download the image file from the web application and load it manually. Use this if your Docker host has no internet access.

Option 1: Pull the Docker scan agent from the registry

1. In Invicti Enterprise, select Agents  > Manage Agents from the left-side menu
2. Click the + Configure New Agent button
3. Copy and retain the following information for later use on your docker host:
   • the docker login command for the registry at registry.invicti.com
   • your password for the registry
   • the docker pull command to pull the image from the registry into your docker host
4. On your docker host:
   • From your console, login to the registry (command copied earlier):

     docker login -u <your email address> registry.invicti.com

   • At the prompt, enter the password you copied earlier.
   • Pull the image from the registry (command copied earlier):

     docker pull registry.invicti.com/ie-agent:25.2.0

     note

     Replace 25.2.0 with the version shown on the Configure new agent page in Invicti Enterprise.

Option 2: Download the Docker image from the web application

1. In Invicti Enterprise, select Agents  > Manage Agents from the left-side menu
2. Click the + Configure New Agent button
3. At the bottom of the Agent section, click the Docker link to download the Agent image file
4. Copy the Agent image file to your docker host into your home folder
5. On your docker host, import the image:

   docker load < Invicti_Enterprise_Docker_Scanner_Agent_{version}.tar.gz

Step 2: Deploy the scanner agent

1. On your docker host, create a folder for the agent configuration and navigate to it:

   mkdir ~/docker_agent
   cd ~/docker_agent

   Your terminal prompt should now show ~/docker_agent$.

2. Create a compose.yml file using a text editor. For example, with nano:

   nano compose.yml

   Ensure that you adjust the following values:

   Parameter	Description
   ApiRootUrl	The URL for your web application
   ApiToken	Retrieved from the Configure new agent page
   AgentName	Must be unique per scanner agent
   image	Pre-configured for Option 1 (registry) - update the version number to match the Configure new agent page. If using Option 2, comment out the registry line and uncomment # image: agent:latest instead.

   services:
     ie-agent:
       container_name: dsa01
       restart: always
       volumes:
         - dsa01vol:/app/Logs
       environment:
         ApiRootUrl: https://ie.invicti.com
       # uncomment if ApiRootUrl: https://www.netsparkercloud.com
         ApiToken: abcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcd=
         AgentName: "dsa01"
         AgentMode: Scanner
         IgnoreSslCertificateErrors: "false"
         ClamAvServiceAddress: dav01
         ClamAvServicePort: 3310
       networks:
         - net01
       # Option 1 (registry): active by default — update the version number to match the Configure New Agent page
       image: registry.invicti.com/ie-agent:25.2.0
       # Option 2 (downloaded image file): comment out the line above and uncomment the line below
       # image: agent:latest
   
     clamav:
       container_name: dav01
       restart: always
       image: clamav/clamav:latest
       networks:
         - net01
       ports:
         - "3310:3310"
   
   volumes:
     dsa01vol: null
   
   networks:
     net01:
       name: net01

3. Start your Docker scanner agent using this command:

docker compose up -d

Permission error

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.

This is what should see in cmd:

user@debian:~/docker_agent$ docker compose up -d
[+] Running 3/3
 ✔ Volume "dsa01_vol01"  Created    0.0s
 ✔ Container dav01       Started    0.6s
 ✔ Container dsa01       Started    0.6s
user@debian:~/docker_agent$

4. 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.

Update agent images

If you are pulling Docker images from a registry, update the version tag in your Docker Compose file to the latest available version, then run docker compose pull followed by docker compose up to update the agent to the latest version.

Environment variables

For Docker agents, the appsettings.json file isn't used and is going to 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	Comma-separated list of hostnames, domains, or IP addresses that bypass the proxy and connect directly.	example\.com,192.168.1.1
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
TerminateOnExit	When set, the agent calls the Invicti API to mark itself as terminated when the container stops. Useful when running the agent as a short-lived container.	true 1
Headless	Enables or disables headless mode for the browser used during authentication verification. Can be set to false for debugging to see what the browser is doing.	true false
LoadTimeout	Form authentication navigation load timeout in milliseconds. This is not the total authentication process timeout.	30000 (30 seconds)
RequiresHttpRequester	Determines whether the auto-authenticator requires HTTP requester. If set to false, the browser handles HTTP requests instead.	true false
UseNetClient	When enabled, the agent uses the SignalR client for communication.	true false
UseFrameHub	When enabled, screen cast frames are sent through an isolated hub, which can improve performance when UseNetClient is false.	true false
HttpTransportType	Specifies the transport type for HTTP communication. Use LongPolling or ServerSentEvents if WebSocket communication is blocked in your environment.	None (default, uses WebSockets) WebSockets ServerSentEvents LongPolling
FrameInterval	Interval in milliseconds between screen cast frames. Increasing this value reduces network load in slow network environments.	3000 (3 seconds)
BlockedExtensionWildcards	Semicolon-delimited list of URLs or patterns to block during the authentication process. Can reduce loading time by blocking unnecessary resources.	*.gif;*.png

Optional parameters for custom certificates

To inject custom certificates into the Docker agent, add the following parameters when creating the container:

-v <cert path on Docker host>:/home/invicti/certificates
-e “CERT_1_PATH=/home/invicti/certificates/<certificate_name>.cer”
-e “CERT_1_PASSWORD=<password>”

Parameter	Description
-v <cert path on Docker host>:/home/invicti/certificates	Mounts the certificate directory from your Docker host into the container. Replace <cert path on Docker host> with the path to your certificates on the Docker host, for example /etc/pki/tls/certs.
CERT_1_PATH	Path to the certificate inside the container. Replace <certificate_name>.cer with the actual certificate file name.
CERT_1_PASSWORD	Password for the certificate. Omit this parameter entirely if the certificate has no password.

To inject multiple certificates, increment the index for each additional certificate:

-e “CERT_2_PATH=/home/invicti/certificates/<certificate_name_2>.cer”
-e “CERT_2_PASSWORD=<password>”
-e “CERT_3_PATH=/home/invicti/certificates/<certificate_name_3>.cer”

note

The CERT_* environment variables configure the certificate for use by the agent application. However, they do not add the certificate to the container's operating system trust store. In environments that use internal Certificate Authorities, TLS inspection, or API gateways signed by enterprise CAs, TLS validation may still fail if the certificate is not trusted at the OS level. This can result in TLS handshake failures, authentication failures (for example, OAuth2 flows), or scan connectivity issues.

To ensure the certificate is trusted by the container OS, build a custom image that installs the certificate into the system trust store:

FROM registry.invicti.com/ie-agent:25.2.0

COPY company-root-ca.crt /usr/local/share/ca-certificates/company-root-ca.crt
RUN update-ca-certificates

Optional parameters for an outbound proxy

To route agent traffic through an outbound proxy, add the following parameters when creating the container:

-e “ProxyAddress=<domain name or IP address of the proxy server>”
-e “ProxyPort=<proxy port>”
-e “ProxyMode=CustomProxy”

Parameter	Description
ProxyAddress	The domain name or IP address of the proxy server.
ProxyPort	The port number of the proxy server.
ProxyMode	The proxy mode. CustomProxy: routes traffic through the proxy defined by ProxyAddress and ProxyPort. SystemProxy: uses the system proxy. NoProxy: disables the proxy.

For proxy authentication and additional options, refer to the proxy-related variables in the Environment variables table above.

note

In Docker deployments, proxy configuration is often handled at the container runtime or host level rather than through agent-specific settings. As a result, proxy settings passed via agent environment variables may not appear in agent logs and may not modify appsettings.json. This differs from Windows-based internal agents, where proxy usage is explicitly logged.

If your environment requires proxy configuration at the container level, set the standard Docker proxy environment variables in your compose.yml:

environment:
  HTTP_PROXY: http://<proxy>:<port>
  HTTPS_PROXY: http://<proxy>:<port>

Obtain scanner agent logs

You can view the scanner agent logs by running the following command. Replace <container_id> with the ID or name of the container, for example dsa01 as defined in your compose.yml.

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 isn't currently running.

---

Need help?

Invicti Support team is ready to provide you with technical help. Go to Help Center