Skip to content
Prepare my pentest

Install the relay

Declare a site, install the Docker agent on a machine of the network with the commands the application provides, see it appear ready, check reachability and keep it available during tests.

How-to guide · Technical readers3 min read

Markdown versionOpen in ChatGPTOpen in Claude

Prerequisites#

  • Internal scans enabled by SpectrAI on your space (see Internal scans).
  • A session verified by a second factor: adding a site, an agent or an authorisation requires it.
  • Docker on a machine of the site: Linux, macOS or Windows with Docker Desktop. The machine stays on during tests.
  • Outbound HTTPS access to the SpectrAI gateway, direct or through the company proxy. The agent opens no inbound port.
  • Network access from that machine to the applications to test.

1. Declare the site#

  1. Open Sites and agents in the client space.
  2. Choose Add a site, name it (for example "Lyon head office") and declare its private IPv4 ranges: 1 to 16 CIDR ranges within 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 or 100.64.0.0/10.

Declaring ranges does not authorise scanning them: the mandate authorises an application.

2. Enrol an agent#

  1. In the site, choose Add an agent, then Generate the token and the commands.
  2. Copy the commands shown right away: the single-use token is shown only once and expires after 15 minutes.
  3. Run the commands on the machine of the site. The installer downloads the signed image, checks its digest and signature, asks you for the enrolment code, starts the agent and sets it to restart with the machine.
  4. At the end, the installer shows the agent's identifier: the one that appears in the site's agent list.

Behind a company proxy, add --proxy http://proxy:port at the end of the command. On Linux, prefix it with sudo if your account has no access to Docker.

3. Check that the agent is ready#

The agent appears in the site's list without reloading the page, ready in under a minute. It is ready when it has connected within the last 90 seconds; its row shows its enrolment date and last contact. If no agent is connected, check that the machine is on and the container is running, read its logs, or enrol a new agent.

4. Authorise testing#

Then grant the mandate: see The testing mandate. Without a current mandate, no test goes through the site.

5. Check reachability#

Once an agent is ready and a mandate is current, Check reachability asks the agent to open a single TCP connection to the host and port of an address covered by the mandate. Nothing is sent to the application and no test is launched. The result (reachable, unreachable, refused, expired) and its explanation stay in the site's history.

Keeping the relay up#

  • Keep the machine on and the container running for the whole duration of a scan.
  • If the agent disconnects during a scan, partial results are kept and the resume is offered once the agent is back.
  • Several agents can be enrolled on the same site; the list shows how many are ready.

Removing an agent#

Stop and remove the container on the machine. An agent that no longer connects is no longer ready; without a ready agent, no test goes through the site.