Scanner groups and tasks

A scanner never takes work directly. It belongs to a scanner group, groups are assigned to zones, and a zone's configuration is what decides what gets scanned and when. That indirection is what lets you add or replace a scanner without touching any zone.

Scanner groups

A group is a set of scanners that share an assignment. One group can serve several zones, and a zone draws on the group assigned to it, so capacity and scope stay independent of each other.

Group scanners by something that reflects where they can reach:

• Network position - DMZ, Internal, Cloud-East
• Geography - US-East, EU-West
• Function - separating heavy vulnerability scanning from light discovery

Avoid Group1 or Default. A group name appears wherever a scanner does, and its job is to tell you what that scanner can see.

Create a group

Create the group before deploying scanners into it: the link command you need at the end of a scanner install comes from the group.

1. Open Scanner Groups.
2. Click Add, give the group a name, and submit.
3. Click the copy icon on the new group to copy its link command.

Screenshot pending

SCREENSHOT: a scanner group row with the copy icon that yields the link command.

That command carries your API hostname, the group ID and your organization ID already filled in.

Add scanners to a group

Run the copied command on each scanner. Adding a second scanner to a group is the same command, unchanged:

sudo scanner-link -url https://<your-api-hostname>/ -scanner_group_id <group-id> -organization_id <organization-id>

Copy the command, do not retype it

Two details are easy to get wrong and both fail confusingly.

The flag is -organization_id, not -org_id. An unrecognized flag means the value never reaches the link request.

The -url is your API hostname, not the address you use in a browser. The command appends /api/v1/scanner_communication/link to whatever you give it, so pointing it at the UI host produces a 404 rather than a clear error.

Scanners linked to the same group work the same queue, so adding one adds capacity rather than duplicating scans.

Assign a group to a zone

1. Open Zones and select or create a zone.
2. Assign the scanner group.

Scanners in that group now perform discovery and testing within the zone's scope. Until a group is assigned to at least one zone, its scanners are linked and idle - a common reason a healthy scanner appears to do nothing.

See Zones, subnets, URLs, and tags for defining that scope.

Scanner tasks

Every piece of scanner work is a task. Scanner Tasks shows them with their status, so it is where you confirm work is actually flowing rather than inferring it from results.

The path a task takes:

1. The platform queues it for a zone.
2. A scanner in the assigned group collects it, polling every 30 seconds.
3. The scanner runs it and reports the result back.

Which means a task that never leaves the queue is a different problem from one that starts and never finishes:

What you see	Where to look
Tasks queued, never collected	No scanner group assigned to the zone, or every scanner in it is down or in maintenance mode
Tasks collected, never completed	scanner-client-completed-tasks on the scanner
Tasks failing quickly	The scanner cannot reach the target - check the zone's scope against what the scanner can route to

Troubleshooting works through each of these.

Public scanner pools

Service providers can offer a shared pool of scanners rather than one per customer. A scanner joins a public pool with -public_scanner_group_id in place of -scanner_group_id:

sudo scanner-link -url https://<your-api-hostname>/ -public_scanner_group_id <pool-id> -organization_id <organization-id>

This is a provider-side feature. If you administer a single organization, use ordinary scanner groups.

Next

• Scanners - deploying a scanner to put in a group
• Zones, subnets, URLs, and tags - what a zone scans