Runners and private networks

Cloud or private — picking the execution location

The choice is mechanical: can the target be reached from the public internet, or does it live in a network only your team can route to? If it is on the internet, cloud execution is the right answer and there is nothing to deploy. If it is internal, you need a private runner.

• Cloud execution — public domains, public hosts, internet-facing apps and APIs, external exposure checks, first discovery on a public target.
• Private runner — internal RFC1918 subnets, VPN-only apps, corporate intranet systems, private APIs, internal Windows or Linux hosts, staging systems reachable only inside your network, machine pentesting.

What a private runner is

A private runner is a small worker process you deploy on a Docker-capable host inside a network you control. It connects outbound to NullSquare, registers itself, and waits for assessment work. When a run executes against an internal target in a scope this runner is attached to, the runner is the network position the agent operates from.

You do not have to expose anything inbound. The runner makes outbound connections only. Everything the agent does — discovery, probes, tests — happens from inside your network, originating from the runner host.

Before you deploy

• A host with Docker installed and running (Linux, macOS, or Windows with Docker Desktop).
• Outbound network access from that host to NullSquare.
• Network reachability from that host to the internal targets you intend to test (this is the most commonly missed prerequisite).
• Permission to run the runner in that environment.

Deploy a runner

The app generates a one-line install command tied to your organization. Run it on the chosen host and the runner registers itself within seconds.

1. 1Open Runners.
2. 2Click Deploy runner.
3. 3Give the runner a name that describes its network position (e.g., "corp-vpn-east", "staging-vpc-1").
4. 4Copy the install command and run it on the chosen host.
5. 5Wait for the runner to report online — usually under thirty seconds.
6. 6Open the runner detail page to confirm heartbeat and platform info.

Attach a runner to a scope

A runner is not automatically used. You attach it to the scope or scopes whose internal targets it can reach. Once attached, runs in that scope can choose private-runner execution.

1. 1Open the scope.
2. 2Open the Runner configuration section.
3. 3Pick an online private runner from the list.
4. 4Save the assignment.
5. 5Confirm the runner shows online or busy on the scope page.

Internal network and machine pentesting — end-to-end

Internal pentests need three things in alignment: authorization (the CIDR is in scope), reachability (the runner can route to it), and execution context (the run uses private-runner execution). Miss any of the three and the assessment cannot proceed.

1. 1Add an internal CIDR target to the scope, for example 10.10.20.0/24 or 10.10.20.15/32.
2. 2Deploy a runner on a host that can route to that subnet.
3. 3Attach the runner to the scope.
4. 4Optional: add credentials for authenticated host, service, or app testing.
5. 5Launch a discovery run, selecting private-runner execution.
6. 6Review the internal hosts and services the run found.
7. 7Promote important hosts to managed assets, fill profile fields, and launch a targeted follow-up against the highest-value machines.

Safety on internal networks

Internal testing has more impact potential than external testing — you can interact with production databases, identity providers, file shares, and infrastructure that has no public counterpart. The rules of engagement on a private-runner scope deserve extra care.

• Set a conservative rate limit (e.g., 2–5 req/s) until you understand how internal services tolerate the load.
• Exclude critical infrastructure (identity providers, primary databases, message brokers) unless they are explicitly the target.
• Schedule testing windows that align with on-call coverage.
• Identify a clear escalation contact in case the agent surfaces something high-severity.

Troubleshooting

Almost every "runner is not working" issue is one of three things: process not running, no outbound to NullSquare, or no reachability to the target. Walk this list in order.

• Runner offline — confirm the Docker process is running and that the host has outbound network access.
• Docker not running — start Docker Desktop or the docker daemon and rerun the install command.
• Runner not attached — open the scope and confirm an online runner is assigned.
• Target unreachable — check VPN, routes, firewall rules, DNS, and segmentation from the runner host. If a person on that host cannot reach the target, the agent cannot either.
• Token rotated — redeploy with the updated install command from the runner detail page.
• Automation queued — a scheduled run is waiting because the attached runner is offline. Bring it back online or switch to another available runner.