Installing scan agents on Windows

This document is for:

Invicti Enterprise On-Demand, Invicti Enterprise On-Premises

To scan a website located on your internal network that is not accessible from the internet, you can install and configure a scan agent on your network. The agent will conduct the actual scan job and then report the results back to Invicti Enterprise.

In addition to the scan agent, you can add an authentication verifier agent that will verify the form authentication on your website. For more information, refer to Installing Authentication Verifier Agents.

Installing a scan agent

There are three stages to this process:

Download and configure the internal agent
Run the agent on your local network where it can reach the internal website you want to scan
Define and scan your internal website

NOTE: You can also install internal agents on Linux and Docker. For more information, refer to Installing a scan agent on Linux or Installing a scan agent via Dockerization.

Downloading and configuring the internal agent

First, you need to download the installation files of the agent and install them on a machine in your internal network.

Prerequisites

Software requirements	Windows Server 2016 or above (Windows Server 2019 recommended)
Hardware requirements	1.4 GHz Processor (2.0 GHz or faster recommended) 4 GB RAM or higher recommended 10 GB Free Disk space for each internal agent
Network requirements	Agent should be configured so that it can reach your internal website through HTTP/HTTPS Agent needs to be able to access the Invicti Enterprise Application Server’s HTTP(S) (443) port
Allowlisting requirements	www.invicti.com netsparker.com r87.me Allowlist the following addresses according to your region: US region: 54.85.169.114, 3.232.155.177, netsparkercloud.com, s3.us-east-1.amazonaws.com EU region: 3.122.90.89, 3.71.172.17, eu.netsparker.cloud, s3.eu-central-1.amazonaws.com CA region: 15.223.111.146, 3.99.19.87, 3.96.72.255, ca.netsparker.cloud, s3.ca-central-1.amazonaws.com
Access requirements	User(s) must have administrator privileges to run the required commands and agent service.

NOTE: If you select TLS 1.3 as a security protocol from the Scan Policy, make sure you have Windows 11 or Windows Server 2022 or higher versions.

How to download and configure the scan agent

Log in to Invicti Enterprise.
From the main menu, go to Agents > Manage Agents > Configure New Agent.

From the Agent section, select Windows to download the Invicti Enterprise Scanner Agent. Your Agent Token is also displayed.

Extract the contents of the zip file to C:\NC_Agent. (You can use another location, but these instructions will use this path.)
Open the C:\NC_Agent\appsettings.json file with your preferred text editor.
You need to edit the following attributes before running the agent, listed under AgentInfo:

AgentName: This can be anything you want. This text will be displayed when you are starting a new scan. (If you are going to install more than one instance of the agent, you must set a unique agentName value for each instance, something you will use later.)
ApiToken: In Invicti Enterprise, the Agent Token is displayed in the Configure New Agent window. Copy the value into the apiToken.

Save and close the C:\NC_Agent\appsettings.json file.

TIP: You can change the default location where the scan agent saves its data. For more information, refer to Changing the default data folder for the scan agent.

NOTE: To detect out-of-band vulnerabilities via Invicti Hawk, you need to whitelist 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.

Setting the agent as a Windows Service

An internal agent should be configured as a Windows service, so that it can poll the Invicti Enterprise servers regularly and can take the scan initiation command from the server.

How to set the agent as a Windows Service

Open a command prompt in Administrator mode and navigate to the agent's folder.
Run the following command to install the Invicti Enterprise scan agent as a Windows Service:

Netsparker.Cloud.Agent.exe -i

Press Windows+R, type 'services.msc', then press Enter.
Find 'Netsparker Cloud Scanning Service - [YOUR_AGENT_NAME]'.
Right-click on it and select Properties.
Make sure the Startup type is set to Automatic, then click Start.

IMPORTANT: Note that although this service is set to start automatically, it may not restart until the PC is restarted too.

Select Apply and OK, then exit the Properties window.

The Invicti Enterprise scan agent is now running on your network, shortly it will be registered to Invicti Enterprise.

You can uninstall the Windows Service by specifying the -u argument instead of the -i argument used during the installation process.

Multiple scan agents on Windows

This section explains how to install and uninstall multiple scan agents on Windows.

How to install multiple scan agents on Windows

Copy all files from the default scan agent’s folder to the new agent’s folder. For this example, the path is: C:\Invicti Enterprise Agent. If you decided to use Agent-2 as the new agent name, you could use this command to copy all files to a new agent’s folder:

xcopy "C:\Invicti Enterprise Agent\*.*" "C:\Invicti Enterprise Agent-2" /yie

This creates a new directory in C:\Invicti Enterprise Agent-2 and copies in all the required files.

Locate the new agent’s folder and open the appsettings.json file with a text editor. Set the new agent’s name.
Open a command prompt in Windows with Administrator rights and install the new agent as a Windows Service using these commands:

This command changes the current folder to the new Agent’s folder:

cd C:\Invicti Enterprise Agent-2

This command installs the new Agent as a Windows Service:

Netsparker.Cloud.Agent.exe -i

Press Windows+R, type 'services.msc' and press Enter.
Find 'Netsparker Enterprise Scanning Service - [YOUR_AGENT_NAME]'.
Right-click on it and select Properties.
Make sure Startup type is set to Automatic, then select Start.

How to uninstall the scan agent

Open a command prompt in Administrator mode and navigate to the agent's folder.
Run the following command to stop and delete the Invicti Enterprise scan agent as a Windows Service:

sc stop "Netsparker Cloud Scanning Service - YourAgentName"

sc delete "Netsparker Cloud Scanning Service - YourAgentName"

This command will delete the verifier agent service. If required, you can delete the related folder.

Auto-Update support for scan agents

When a new agent version has been published, you can update your agents manually using installation files on the machines on which agents are installed.

Alternatively, you can update agents manually by clicking Update Agent (visible only when Enable Auto Update is not configured and a new version of the agent is available).

While the update is in progress, the State field will display 'Updating'.

Another alternative is to enable Auto Update. This means that when the new version of the Invicti Enterprise scan agent is available, the target agent will update itself as soon as possible when it’s idle.

How to enable automatic agent updates

From the main menu, select Agents > Manage Agents.
Next to the relevant Agent, select the Command drop-down, then Enable Auto Update.

How to disable automatic agent updates

From the main menu, select Agents > Manage Agents.

Next to the relevant Agent, select the Command drop-down, then Disable Auto Update.

Setting a proxy for scan agents

Setting a proxy for the scan agent in Invicti Enterprise requires entering proxy settings manually into the appsettings.json file with your preferred text editor. Invicti supports Basic Authentication but not Digest and NTLM.

This table lists and explains the entries in the proxy settings.

Field	Description
Proxy Mode	Enter your proxy settings if you want the agent to use or not to use the proxy. There are three modes: NoProxy: The agent does not use a proxy even if you configure the server's proxy settings. SystemProxy: The agent uses the system proxy that was defined on the server. CustomProxy: The agent uses a custom proxy that you define in the appsettings.json file.
Use Default Credentials	Enter true if you authenticate to the proxy via the user that the agent service is defined.
Username	Enter a username for authentication.
Password	Enter a password for authentication.
Domain	Enter a domain name.
Address	Enter a proxy address. Only IP address or hostname without schema and port is allowed.
Port	Enter a port for the proxy.
Bypass on Local	Enter a value that indicates whether to bypass the proxy server for local addresses.
Bypass List	Enter the address(es) that do not use the proxy server. Enter the address(es) as RegEx. The following shows some possible bypass list expressions: "example\\.com", ";\\.example\\.com", "192\\.168\\.1\\.1", "www\\.example\\.com", "www\\.example\\.com:8080", "100\\.;\\.;\\.;

Here is an example illustration of how to bypass targetwebsite.com with all subdomains and 122.178.1.1.

"ProxySettings": {

"ProxyMode": "CustomProxy",

"UseDefaultCredentials": true,

"Username": "",

"Password": "",

"Domain": "",

"Address": "invicti.proxy.com",

"Port": "8080",

"ByPassOnLocal": false,

"ByPassList": [";*\\.targetwebsite\\.com","targetwebsite\\.com","122\\.178\\.1\\.1"]

}

IMPORTANT: Any changes in the appsetting.json file, such as proxy settings and changing the API Token, require restarting the service so that the changes can take effect.

Using a proxy auto-configuration file

You can use a proxy automatic configuration (PAC) to configure your proxy. A PAC file lets you describe the proxy configuration in a file using JavaScript, so you can manage your proxy settings.

NOTE: To use a PAC file you must set the proxy mode to System Proxy in the appsetting.json file. For more information about proxy settings, refer to Setting a proxy for scan agents.

How to use a proxy auto-configuration file on Windows

Go to Settings > Network & Internet > Proxy.
Turn on the Use setup script toggle.
In the Script address field, enter the PAC file's URL address.

Select Save.

How to use a proxy auto-configuration file in Linux (Debian Distribution)

Go to Settings > Network > Network Proxy.
From the Network Proxy window, select Automatic.
In the Configuration URL field, enter the PAC file's URL address.

Close the window.

TIP: Malware analysis with ClamAV
If you want an Invicti Enterprise scan agent to carry out malware analysis you need to download and install ClamAV. For more information, refer to Malware analysis with ClamAV in Invicti Enterprise.

Changing the default scan data folder for the scan agent

You can change the default location where the scan agent saves its data. This helps you avoid running out of free space due to accumulating scan data.

By default, the scan agent saves the scan data to the C:/Invicti Enterprise folder. However, you can choose to save the scan data in a different location to prevent filling up your free space.

The following instructions explain how to change the location where the scan agent saves its scan data. These instructions are valid for new agents or existing agents.

How to change the default scan data folder

Navigate to the agent’s folder that you want to change to the default folder.
Open appsettings.json file with your preferred text editor.
Add the following attribute listed under AgentInfo:

"ScanDataFolderPath": "FullPath"

IMPORTANT: Write the full path as shown in the following example:

C:\\Users\\[User]\\Documents\\ScanData

Save and exit.

If you modified the existing agent's configuration file, you need to restart the agent service. So, Open services.msc, find 'Netsparker Cloud Scanning Service - [YOUR_AGENT_NAME]', and restart the agent service.

This restart does not affect your saved scan data. To move the existing data, you need to copy the data and paste it into the new folder.

If this is a new agent, continue following these instructions: Setting the agent as a Windows Service.

Defining and scanning an internal website in Invicti Enterprise

Now that you have installed a scan agent into your infrastructure, you need to configure Invicti Enterprise to let it know which websites should be scanned with an internal agent rather than with the built-in agents.

How to define an internal website in Invicti Enterprise

Log in to Invicti Enterprise.
From the main menu, select Websites > New Website.
Enter your internal website details (refer to Adding a website or API).
From the Agent mode field, select Internal.
Click Save.

How to scan an internal website with an agent

Log in to Invicti Enterprise.
From the main menu, select Scans > New Scan.
From the Target URL field, select your Internal Website (if the field is not already populated).
The Preferred Agent field is already selected by default. Your newly installed scanning Agent is displayed as an option. If you installed more than one instance, select the one that can access your internal website. If any of them can access your internal website, select the default option Any of the available agents. By selecting this, one of the idle agents will scan your website.

Select Launch. (For simplicity, optimization and other settings are ignored in this procedure.)

Your scan has been started in the Queued state. Shortly, you will see that its status changes to Scanning. Once it is completed, you will be able to explore the vulnerabilities found on your website.