Deployment: Invicti Platform on-demand, Invicti Platform on-premises
Choose between the Docker and Windows internal agent
Pick the right internal agent for each of your internal targets, so scans authenticate on the first attempt instead of failing with 401 responses you have to chase down. This document explains what the Docker and Windows internal agents have in common, the authentication methods only the Windows agent supports, and how to run both when your estate needs both. For what internal agents are and how to assign them, refer to the Introduction to internal site scanning document.
Both agents run the same scanning engine and report the same vulnerabilities against the same target. Invicti Platform recommends the Docker agent for most deployments. The Windows agent is the right choice where a target depends on something only a Windows host can provide, such as Kerberos authentication or a smart card.
Why this matters
The choice only affects one thing: whether the agent can authenticate to your target. Get it wrong and a scan crawls a login page instead of the application behind it, so you see a clean report for an application that was never actually tested. Choosing per target up front means every internal application gets scanned authenticated, and you avoid maintaining Windows hosts for targets that don't need them.
Quick decision
Install the Windows agent if any of the following applies to a target this agent scans. None of these work on Linux, which is what the Docker agent runs.
- The target authenticates with Kerberos or Negotiate.
- The target uses NTLM and you can't supply a username and password, because the agent has to authenticate as its own account.
- The target is IIS with Extended Protection set to Required.
- The target authenticates with a smart card or another PKCS#11 hardware token.
For everything else, use the Docker agent. If some targets fall on each side, run both. Refer to Run both agent types.
The autoscaling agent on Kubernetes runs the same Linux container image as the Docker agent, so the same authentication limits apply to it. For more information, refer to the Install an autoscaling agent using Kubernetes document.
Authentication support
Authentication is the only place the two installations differ.
| Authentication method | Docker agent | Windows agent |
|---|---|---|
| HTTP Basic and Digest authentication | Yes | Yes |
| NTLM with a username and password | Yes | Yes |
| NTLM as the agent's own account (single sign-on) | No | Yes |
| Kerberos and Negotiate | No | Yes |
| IIS Extended Protection set to Required (channel binding) | No | Yes |
| Client certificates supplied as a file (PEM, PFX) | Yes | Yes |
| Smart card and hardware token certificates (PKCS#11) | No | Yes |
| Recorded logins, form logins, OAuth | Yes | Yes |
Scanning behavior itself is identical. Crawling, JavaScript execution, API scanning, and the vulnerability checks run the same code and produce the same findings on both agents.
Why the Docker agent is the default recommendation
The environment around the engine is pinned. Both agents bundle their own browser, JavaScript runtime, and TLS library, so the engine is consistent either way. What the image adds is everything around them: the system libraries, the certificate bundle, the fonts, and the locale all ship in the image and are the same wherever you run it. The host still provides the kernel, the CPU, and whatever resource limits you set, so this isn't a promise of identical timing. What it removes is the class of problem where a scan behaves differently because two machines were built and configured differently.
Nothing else on the host can interfere. Endpoint protection, group policy, machine-wide proxy settings, per-user certificate stores, and pending reboots all sit outside the container. On a Windows host, these are the usual reason a scan behaves differently from one machine to the next.
Every run starts clean. Restarting the container discards whatever the previous scan left behind, so one scan can't influence the next.
Upgrades are a tag change. Pull the new image and restart the container. There's no installer, no service account to preserve, and no in-place upgrade of a running agent.
It scales sideways. Run as many agents as you need, size them with ordinary container CPU and memory limits, and remove them when demand drops.
It leaves no footprint. You don't need a permanent installation on a domain-joined machine, or a service account holding standing access to your network.
When you need the Windows agent
The following scenarios require the Windows agent because the authentication methods involved depend on Windows-specific platform features that aren't available on Linux.
Kerberos and Negotiate
The engine implements Negotiate through the Windows security provider. There's no equivalent on Linux, and the Linux build ignores a Negotiate challenge rather than falling back to something weaker. If a target answers with WWW-Authenticate: Negotiate and offers nothing else, only the Windows agent can authenticate to it.
The agent authenticates as the identity of its service, so run the invicti-scanning-agent service as a domain account that has access to the target. Invicti doesn't use the credentials of whoever installed the agent or is logged in at the console.
NTLM single sign-on
Both agents handle NTLM when the scan configuration carries a username and password. Only the Windows agent can authenticate as its own account without credentials stored in the scan. The same service account requirement applies.
IIS Extended Protection set to Required
Extended Protection binds the authentication exchange to the TLS session using a channel binding token. The Windows agent produces one automatically. The Docker agent doesn't, so authentication fails even when the credentials are correct.
If you'd rather keep the target on a Docker agent, changing the site's Extended Protection setting from Required to Accept allows clients that don't send a channel binding token.
Smart cards and hardware tokens
Smart card authentication uses PKCS#11 to talk to the token, and the Windows agent supports it. Use the Windows agent for any target that authenticates with a smart card, a YubiKey, or another hardware security token.
This doesn't apply to certificates supplied as a file. A PEM or PFX client certificate works the same on both agents, so only physical tokens decide the question.
Reasons that don't require the Windows agent
These come up often, and none of them should push you to Windows.
| Reason you might expect to need Windows | Why the Docker agent handles it |
|---|---|
| The target runs Windows, IIS, or ASP.NET | The scanner is a black box HTTP client. The target's operating system is irrelevant, apart from the authentication schemes listed above. |
| The target is internal and isn't reachable from the internet | That's a question of where you place the agent, not which operating system it runs. A container in the same network segment reaches exactly the same targets. |
| You use client certificates | Certificates supplied as files work identically on both agents. |
| You use a recorded login, a form login, or OAuth | The bundled browser handles all three, and it behaves the same on both agents. |
| You scan APIs | The same code parses OpenAPI, GraphQL, SOAP, and Postman collections on both agents. |
Run both agent types
Most organizations that need Windows need it for a handful of targets, not for the whole estate. The pattern that works is Docker agents as the default pool, plus a small Windows pool reserved for targets that need integrated authentication or a card reader. Assign each target to an agent that can authenticate to it, as described in the Introduction to internal site scanning document.
The same engine produces the findings either way, so results stay comparable across the fleet and you're not maintaining two sets of expectations.
Once you've decided, the host requirements and installation steps are in the Install an internal agent using Docker and Install an internal agent on Windows documents. If your agents need a proxy to reach Invicti, refer to Install an internal agent with proxy settings.
Troubleshooting
Scans of an internal target return 401 responses and only crawl the login page
Check what the target offers in its WWW-Authenticate response header. If it offers Negotiate and nothing else, a Docker agent can't authenticate to it, no matter what credentials you configure. Move the target to a Windows agent and run the invicti-scanning-agent service as a domain account with access to the target. Refer to Kerberos and Negotiate.
NTLM credentials are correct but authentication still fails on an IIS target
Check the site's Extended Protection setting in IIS. When it's set to Required, IIS expects a channel binding token that only the Windows agent produces. Either move the target to a Windows agent, or change the setting to Accept so clients without a channel binding token can authenticate. Refer to IIS Extended Protection set to Required.
The Windows agent authenticates as the wrong account
The agent authenticates as the identity of its service, not as the account that installed it or the account signed in at the console. Open Services, check which account runs invicti-scanning-agent, and change it to the domain account that has access to the target. Restart the service after the change.
Files disappear from the Windows agent directory, or scans stop part way through
Endpoint protection is quarantining the agent's files. The scanner writes payloads and request data that look malicious to a scanner-unaware security product. Add exclusions for the agent's installation and working directories, then restore any quarantined files and restart the service.
You need Windows for a few targets but don't want to install it everywhere
You don't have to standardize on one agent type. Keep Docker agents as your default pool, add a small Windows pool for the targets that need integrated authentication or a card reader, and assign each target to an agent that can authenticate to it. Refer to Run both agent types.
Need help?
Invicti Support team is ready to provide you with technical help. Go to Help Center