Skip to main content
availability

Deployment: Invicti Platform on-demand

Introduction to internal site scanning

Set up internal scan agents to scan web applications inside your network that aren't reachable from the public internet. This document explains what internal scan agents are and how to install and assign them in Invicti Platform on-demand.

Why this matters​

Internal tools, staging environments, and admin panels often hold serious vulnerabilities but sit behind your firewall, where Invicti's cloud agents can't reach them. That leaves a blind spot in your security coverage. Internal scan agents run from inside your network and send results back to Invicti, so you can find and fix issues in these applications alongside your public-facing ones - without exposing them to the internet or trustlisting cloud agents.

Overview​

Invicti Platform includes an Agents feature that enables you to scan web applications that are inaccessible from the internet. You can install the internal scanning agent inside your network and manage it through Invicti to scan your internal resources. Invicti automatically uploads the scan results of your internal resources to your Invicti portal, so you can manage them together with the results of your other scans.

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 cores on a 64-bit processor
  • Memory (RAM): 6 GB available
  • Disk space: 50 GB free

Access requirements

  • Administrator privileges for command execution
  • Invicti Platform Administrator role

Trustlisting requirements

Concurrent scans and resource allocation​

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 calculates how many scans can run in parallel by dividing each available resource by its per-slot requirement and taking the lowest result. This calculation is the same whether you install the agent on Windows or Docker, so a low slot count isn't a platform-specific limit. The autoscaling agent on Kubernetes works differently - it scales scanner pods based on cluster resources and scan queue demand rather than per-host scan slots.

Resource allocation example

If the agent reports that it can run only 1 concurrent scan, it's because the host doesn't have enough free resources to run 2 at once. The agent works out how many scans each resource can support, then uses the lowest result. For example:

  • 4 CPU cores → 2 scans (4 / 2)
  • 8 GB free RAM → 1 scan (8 / 6) ← bottleneck
  • 100 GB free disk → 2 scans (100 / 50)

Result: min(2, 1, 2) = 1 concurrent scan

The agent still works when resources only allow a single scan - it just limits how many run at once. To run 2 concurrent scans, the host needs:

  • ≥ 12 GB free RAM (2 scans × 6 GB minimum)
  • ≥ 4 CPU cores (2 scans × 2 cores minimum)
  • ≥ 100 GB free disk (2 scans × 50 GB minimum)

The agent manages resources dynamically before and during scan execution. If resources drop below the required threshold, new scans don't begin until enough resources are available. If you expected more concurrent scans, check the available RAM, free disk space, and CPU on the machine.

If the defaults don't suit your environment, you can adjust these thresholds in agent.yaml (min_core_per_job, min_ram_per_job, min_disk_per_job) or override the limit with the --max-jobs flag, as described in the Override the resource limits section.

Override the resource limits​

The agent calculates the number of scan slots automatically, but you can override this in three ways. When more than one is set, the agent applies them in this order of precedence (highest first):

  1. The --max-jobs command-line flag.
  2. The jobs_override setting in agent.yaml.
  3. The automatic calculation based on the per-slot thresholds.

Adjust the per-slot thresholds

To change how much each scan slot reserves, edit the min_*_per_job values in the agent's agent.yaml file, located in the agent installation directory. Lower them to fit more slots on a host with spare capacity, or raise them if scans fail due to resource exhaustion (for example, out-of-memory errors or a full disk):

min_core_per_job: 1   # default: 2 (cores)
min_ram_per_job: 4    # default: 6 (GB)
min_disk_per_job: 25  # default: 50 (GB)

Force a fixed number of scans

To skip the automatic calculation and always allow the same number of scans regardless of available resources, add jobs_override to agent.yaml. This suits stable deployments where you know the exact capacity you need:

jobs_override: 5   # always allow up to 5 concurrent scans

Override for a single session

To override the limit when you run the agent manually in run mode, use the --max-jobs flag. A value of 0 (the default) keeps the automatic calculation:

.\invicti-agent.exe run --max-jobs 10

Restart the internal agent service for any agent.yaml change to take effect.

Step 1: Install the internal scan agent​

Internal scanning agents can be installed on Windows or via Docker Desktop. Customers using Linux should install the agent through Docker Desktop. For agent installation instructions, refer to the following documentation:

info

When the entire Kubernetes cluster hosting the scalable agent is shut down and then restarted, the platform registers a new scalable agent instance. For more information, refer to the Install autoscaling agent using K8s document.

Step 2: Assign internal scan agent to targets​

After installing an internal scan agent, you need to assign the agent to a target to start scanning an internal site. You can do this either from the Scans > Agents page (where you can view a list of your internal agents) or the Targets page.

tip

You need to add your internal target to Invicti before you can assign an internal scan agent to the target. For information about adding targets, refer to Configuring Targets.

From the Scans > Agents page:

  1. Choose an internal agent from the list of internal agents.
  2. Click the Targets tab from the drawer that slides out.
  3. Click + Assign target.
  4. Use the drop-down menu to choose an internal target, then click Submit.

From the Inventory > Targets page:

  1. Select an internal target from the list of targets.
  2. Use the three-dot menu (⋮) to open the menu and select Edit target.
  3. In the Default agent section, use the drop-down list to choose an internal agent.
  4. If required, select Enable proxy and enter your proxy server details.
  5. Configure the other target settings as necessary, then click Save target configuration.

The internal scan agent is now assigned to an internal target. Invicti uses the internal agent the next time you launch a scan for that target.

tip

When using internal agents with targets that require a login sequence, you can record the login sequence from the target's Authentication settings or use the standalone Login Sequence Recorder (LSR). For more information, refer to Record a login sequence and the Standalone login sequence recorder overview.

Troubleshooting​

The agent doesn't appear on the Agents page, or shows as offline

A newly installed agent can take a short time to register and appear. If it doesn't show up or stays offline, confirm that the agent service is running and that the host can reach Invicti Platform - internal agents need outbound access to the platform URL, and your network must allow it (see the trustlisting requirements). For installation-specific startup errors, refer to the Troubleshooting section of the relevant install document: Windows, Docker, or proxy.

The agent runs only one scan at a time, or the logs show "max 1 jobs allowed"

This isn't a fixed limit, and it isn't specific to any platform. The agent calculates how many scans it can run in parallel from the available CPU, RAM, and disk space, then uses the lowest result. A log entry like this one means the host currently has only enough free resources for a single scan:

INFO  concurrent scan max:1
INFO  Currently running 0 of max 1 jobs allowed

RAM is the most common bottleneck, because each scan needs 6 GB. To run more scans at once, either free up or add resources so the host meets the requirements for an extra slot, or lower the per-slot thresholds in agent.yaml. For details, refer to Concurrent scans and resource allocation.

The INVICTI_AGENT_AUTO_SCALE_ENABLED=false value in the logs is expected for a standard internal agent. Autoscaling applies only to the autoscaling agent on Kubernetes and doesn't affect how many scans a single-host agent runs.

Scans stay queued and don't start, even though the agent is online

The agent checks system resources before and during every scan. If free RAM, CPU, or disk space drops below the per-slot threshold - for example, because other processes on the host are using them - the agent doesn't start a new scan until enough resources are available again. Check the available RAM, free disk space, and CPU on the machine, and close or move other workloads if needed.

You changed agent.yaml but the new limits aren't applied

The agent reads agent.yaml when it starts. Restart the internal agent service after editing the file so the new min_*_per_job or jobs_override values take effect.

You set --max-jobs but the agent still uses the automatic limit

The --max-jobs flag only applies when you start the agent yourself with the run command. An agent that runs as a managed service - for example, the Windows service or a Docker container - is started a different way, so the flag isn't passed to it. This applies on any platform, not just Windows. To set a fixed limit for a service-managed agent, use jobs_override in agent.yaml instead, then restart the agent. For details, refer to Override the resource limits.

Need help?​

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

Last updated on
Was this page useful?