Breadth-First Scanning¶

The purpose of this scanning mode is to distribute the load on the infrastructure when scanning a large number of targets simultaneously. With this approach, all active scans progress steadily, and the time to obtain results becomes more predictable for the user.

Scan Modes¶

Standard mode — a mode in which, for scans running simultaneously, resource allocation priority is given to the scan whose identifier has the lowest value.
Breadth-first scanning mode — a mode in which resources for scans running simultaneously and the jobs of those scans are distributed so as to obtain initial results as quickly as possible.

How It Works¶

A resource budget is assigned to a group. A token is a unit of the resource budget.
For each scan job, it is possible to set the cost of processing a single element (resource, endpoint, or tag) in tokens.
Before processing, a job requests the required cost from the resource budget.
- If the budget contains a sufficient number of tokens, the job receives them, and the budget is reduced by the specified amount.
- If the budget does not contain enough tokens, the job remains in a waiting state until other active jobs return tokens to the budget.
After processing an element, the job returns the tokens it used to the budget.
For jobs, you can set the maximum number of tokens occupied (max_token_concurrency). Upon reaching the specified value, tokens will not be allocated beyond that limit even if they are available in the budget, and processing of subsequent elements within the job will not begin until the job releases its tokens.

Configuring¶

You need to roughly estimate the volume to be scanned and set the parameters accordingly. In the following instructions, the parameter values are provided as examples and may differ from your own.

In the fuchsiad configuration file, set a value for the concurrency field (e.g., concurrency: 100). This allows the fuchsiad service to run up to 100 scan jobs simultaneously.
Create a token budget with a size of 100.
```
fuchsiactl create_scangroup 100
```
For modules launched via fuchsia-franzisrunner and for the static web crawling module, specify the token_cost parameter (the cost of processing a resource or endpoint in tokens) and max_token_concurrency (the maximum number of tokens occupied by the module) in the YAML configuration files.
- For modules that use a browser, specify token_cost: 10; for the rest, token_cost: 1.
- For the static web crawling module, specify max_token_concurrency: 1; for the other modules, set the number indicated in the -concurrency flags for the corresponding modules.

At this point, the configuration is complete, and you can proceed to scanning the desired group.

Usage¶

Breadth-first scanning mode is available via the fuchsiactl console client.

Creating a scan group with the specified number of scans.
```
fuchsiactl create_scangroup <capacity>
```

Launching a scan for the specified group.

fuchsiactl scan --scangroup <scangroup_id>

Retrieving the list of scans for the specified group.
```
fuchsiactl get_scangroup <scangroup_id>
```

Retrieving the list of scan groups.
```
fuchsiactl list_scangroups
```

Retrieving token budget distribution metrics for a group.
```
fuchsiactl get_tokenbudget_metrics <id>
```