Skip to main content
this document is for:

Deployment: Invicti Platform on-demand

Install internal agent with proxy settings

Internal agents integrate with Invicti Platform, enabling scans within your environment for targets not publicly accessible from the internet or when you do not want to trustlist Invicti cloud agents.

This document shows you how to install the Invicti internal agent with proxy settings on Windows and Docker to connect to Invicti Platform.

Limitations for internal agents

When the site is internal, and you prefer using internal agents for the scan, you cannot create a new Login Sequence Record (LSR) or Business Logic Record. However, you can import them. For further information about recording and downloading an LSR, refer to the Standalone login sequence recorder overview.

Prerequisites​

System requirements

To run scans successfully, the agent requires sufficient system resources. The agent only initiates a new scan if the following minimum resources are available:

  • CPU: 2 free core CPU 64-bit processor
  • Memory (RAM): 6 GB available
  • Disk Space: 50 GB of free disk space

Access requirements

  • Administrator privileges for command execution
  • Invicti Platform Administrator role

Trustlisting requirements

Resource allocation behavior

When the agent starts, it checks the available system resources and allocates scan slots accordingly. Each scan slot requires:

  • 6 GB of available RAM
  • 2 CPU cores
  • 50 GB of free disk space

The agent determines how many scans can run in parallel based on these requirements.

info

If a machine has 15 GB RAM, 5 CPU cores, and 500 GB free disk space, the agent allocates 2 scan slots. This means up to 2 scans can run simultaneously, while any additional scans remain queued until a slot becomes available.

The agent dynamically manages resources before and during scan execution. If system resources drop under the required threshold, new scans aren't going to begin until sufficient resources are available.

Install an internal agent with proxy settings on Windows​

  1. Select Scans > Agents from the left-side menu.

  2. Click Agent Installation Instructions.

  3. Select Windows.

  4. Enter a name for your internal agent.

  5. Create a folder where you save the internal agent.

  6. Click Download Windows Agent. When the invicti-agent.exe file is downloaded, move it to the folder created in the preceding Step 5.

  7. Copy the command from Step 5 in the Agent Installation Instructions.

  8. Paste the command in a place where you can edit the content, for example, in Notepad.

  9. Edit the command to add -p http://username:pass@proxy_server:port at the end (after the registration token). Ensure that you replace username, pass, proxy_server, and port with your actual proxy settings.

    .\invicti-agent.exe register --url app.invicti.com --agentname "newagent" --registration-token aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee -p http://username:pass@proxy_server:port

  10. As a user without administrative privileges, open Terminal and navigate to the folder where you saved the downloaded invicti-agent.exe file. Alternatively, right-click the folder with the file and select 'Open in Terminal.'

  11. Copy and paste the edited command from Step 9 above to your Terminal window and execute the command.

  12. Copy the command from Step 6 in the Agent Installation Instructions.

  13. As a user with administrative privileges, open Terminal and navigate to the folder where you saved the downloaded invicti-agent.exe file. Alternatively, right-click the folder with the file and select 'Open in Terminal.'

  14. Paste and run the command copied in Step 12 above. This installs the agent as a service so that it is ready to start executing scans.

Your internal agent is now installed. You can view your internal agents in Invicti by going to the Scans > Agents page.

You can now assign targets to the installed internal agent and commence testing your website.

Install an internal agent with proxy settings using Docker​

note

Ensure Docker Desktop is installed on your host OS by verifying with the command docker -v in Terminal. If version information is displayed, you're all set. Otherwise, refer to the Docker support documentation for installation guidance.

  1. Select Scans > Agents from the left-side menu.

  2. Click Agent Installation Instructions.

  3. Select Docker.

  4. Enter a name for your internal agent.

  5. Copy the command from Step 3 in the Agent Installation Instructions.

  6. Paste the command in a place where you can edit the content, for example, in Notepad.

  7. Edit the command to add -e INVICTI_AGENT_HTTP_PROXY=http://username:pass@ip:port after the name parameter. If the proxy doesn't have any authentication, then use -e INVICTI_AGENT_HTTP_PROXY=http://ip:port instead.

    Ensure that you replace username, pass, ip, and port with your actual proxy settings.

    docker run -d --name "my-agent" -e INVICTI_AGENT_HTTP_PROXY=http://username:pass@ip:port invicti/internal-agent --url platform.invicti.com --agentname "agent-name" --registration-token XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

  8. Copy the full text of your newly edited command.

  9. Open Terminal and paste the command. Press Enter to execute the command.

Your internal agent is now installed. You can view your internal agents in Invicti by going to the Scans > Agents page.

You can now assign targets to the installed internal agent and commence testing your website.

Import a certificate within Docker​

To import a certificate within Docker, follow the steps below:

  1. Create a new folder. For example, C:\users\name\my_agent

  2. Copy the certificate you would like to import to this new folder. For example, C:\users\name\my_agent\my_certificate.pem

  3. Navigate to this folder: C:\users\name\my_agent

  4. Create the following Dockerfile and name it 'Dockerfile':

    FROM invicti/internal-agent
    USER root
    COPY my_certificate.pem /usr/local/share/ca-certificates/my_certificate.crt
    RUN update-ca-certificates
    USER invicti
    ENTRYPOINT ["/usr/local/bin/invicti-agent","register-r]

  5. Run the command docker build -t my_agent . to build the image

  6. Run the following command to start the agent with the new certificate and proxy. Note that '-p' is used for the agent proxy.

    docker run -d --env REQUESTS_CA_BUNDLE=/etc/ssl/certs/ --name "dockeragent" my_agent --url app.invicti.com --agentname "dockeragent" --registration-token XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX -p http://myproxy

Explanation of parameters​

Below is a table detailing the parameters necessary to configure a Docker container for installing an internal agent.

ParameterDescription
-dThis indicates detached mode, allowing the container to operate in the background.
--nameAssigns a name to the container.
-eSets the environment parameters to add the proxy.
--urlSpecifies the Invicti URL.
--agentnameDefines the agent name in the Invicti UI, changeable later. If installing multiple agent instances, assign a unique agent name for each instance. (Max 50 characters)
--registration-tokenObtain from Invicti Agents menu > Agent Installation > Docker > Your registration token is displayed in Step 2: Get your token.

Need help?​

If you need help with this document or have questions about the installation process, please contact the Support team through the Invicti Help Center.

Was this page useful?