# Network discovery

> What an SNMP sweep reads, the discovery policy that limits it, and how to start, schedule and review sweeps.

A network sweep asks an agent to find the SNMP devices in address ranges you
allow, profile each one, and upload what it finds to Blueprintr. The agent
sweeps only the ranges in the `discovery` block of its own configuration.
Blueprintr can narrow a sweep to some of them but never widen it, and the SNMP
credentials stay on the agent. An agent with no `discovery` block sends no SNMP
at all.

## The discovery policy

```json
"discovery": {
  "cidrs": ["10.0.10.0/24", "10.0.20.0/23"],
  "exclude": ["10.0.10.250"],
  "credentialSets": [
    { "name": "netops", "version": "3", "user": "netops", "securityLevel": "authPriv",
      "authProtocol": "sha256", "authPassphrase": "env:SNMP_NETOPS_AUTH",
      "privProtocol": "aes128", "privPassphrase": "env:SNMP_NETOPS_PRIV" },
    { "name": "dc", "version": "2c", "community": "file:/etc/continuum-local/dc-community",
      "cidrs": ["10.0.20.0/24"] }
  ],
  "credentialTrial": "sequential",
  "collectors": { "deny": ["arp", "fdb"] },
  "collectContact": false,
  "packetsPerSecond": 50
}
```

| Setting | Default | What it limits |
| --- | --- | --- |
| `cidrs` | none (no sweeps without it) | The addresses a sweep may probe. IPv4 only, in plain dotted-decimal: `010.0.20.5` and similar spellings are refused |
| `exclude` | none | Addresses or blocks a sweep never probes |
| `maxSweepPrefix` | `22` | The largest block allowed in `cidrs`, as a prefix length. It can never be set below 16 |
| `maxHosts` | `65534` | Addresses in one sweep |
| `packetsPerSecond` | `50` | SNMP packets a second, shared by every sweep and probe the agent runs. 1 to 5000 |
| `concurrency` | `16` | Devices profiled at once. 1 to 256 |
| `timeoutMs`, `retries` | `1500`, `1` | Per request |
| `deviceBudgetMs` | `60000` | Time allowed per device, every collector included |
| `port` | `161` | The SNMP port |
| `maxRowsPerTable`, `maxVlanWalks` | `20000`, `64` | Rows read from one table on one device, and VLANs walked one by one on switches that keep a forwarding table per VLAN |

An SNMP probe of one device is the exception to `cidrs` and `exclude`: it may
also reach a host in its integration's `allowedHosts`, on the port the probe
gives, and tries each credential set that applies to that host. A set without
its own `cidrs` applies to every host, host names included.

## SNMP credentials

Use SNMPv3 with `authPriv` wherever your devices support it. SNMPv1 and v2c
send the community string in clear text in every request, so anything on the
path, and any device the sweep reaches, can read it. SNMPv3 `authPriv`
authenticates and encrypts each request.

| Version | Needs |
| --- | --- |
| `"1"`, `"2c"` | `community` |
| `"3"` | `user` and `securityLevel` (`noAuthNoPriv`, `authNoPriv` or `authPriv`), then as the level requires `authProtocol` (`md5`, `sha`, `sha224`, `sha256`, `sha384`, `sha512`) with `authPassphrase`, and `privProtocol` (`des`, `aes128`, `aes192`, `aes256`, or `aes192b` and `aes256b` for devices using the Blumenthal key extension) with `privPassphrase`. Optional `contextName` |

Passphrases must be at least 8 characters. Any community or passphrase can be an
`env:NAME` or `file:/path` reference instead of the value.

Give each credential set the ranges it belongs to with its own `cidrs`, each
inside `discovery.cidrs`. A set with `cidrs` is only tried against those
addresses.

`credentialTrial` sets how the sets that apply to an address are tried:

- `"parallel"` (the default) sends every applicable set at once. A dead address
  costs one timeout, but every applicable community reaches every address.
- `"sequential"` tries them one at a time, in the order written, and stops at
  the first that answers. Communities are not sprayed, and a dead address costs
  one timeout per set.

Communities and passphrases never appear in a request from Blueprintr or in a
result, and are masked in the agent's logs. Blueprintr does not keep which
credential set or SNMP version a device answered.

## What your network sees

- UDP from the agent's host to port 161 (or `port`) on addresses in the ranges:
  SNMP GET, GETNEXT and GETBULK requests. A probe of one device may also send
  them to a host in its integration's `allowedHosts`, on the port the probe
  gives. SNMPv3 opens each device with the standard engine discovery request,
  which has an empty user name.
- At most `packetsPerSecond` packets a second across everything the agent sends
  over SNMP.
- The agent does not send ICMP, scan ports or open raw sockets, and needs no
  root access.
- On older Cisco IOS switches, walks of the per-VLAN forwarding table use
  `community@vlan`, or with SNMPv3 the `vlan-N` context, which the switch must
  permit for that user.

A device that logs or traps SNMP authentication failures does so for each
credential set that does not match it. Tell whoever watches your intrusion
detection before the first sweep, and add the agent's address to any device
that limits SNMP to named managers.

## What a sweep collects

Each responding device is classified before any table is walked: `sysObjectID`
gives the vendor, `sysDescr` the operating system, version and model, and one
request for a dozen objects shows whether it bridges, routes, prints, runs on
batteries or is a general-purpose host. The class picks which collectors run,
so a core switch is walked for neighbours, VLANs and forwarding tables while a
printer is asked for its supplies. Every device is also asked for its system
group: name, description, uptime, location and, unless `collectContact` is
`false`, contact.

| Collector | Reads |
| --- | --- |
| `interfaces` | Name, description, type, speed, MTU, MAC address, state, and traffic, error and discard counters |
| `addresses` | The device's own IP addresses and masks |
| `entity` | Model, serial number, hardware, firmware and software revisions, and stack members |
| `lldp`, `cdp` | Neighbours, from LLDP and from Cisco's CDP |
| `bridge` | Which bridge port is which interface |
| `vlans` | VLANs and the ports in each |
| `fdb` | The forwarding table: which MAC address is behind which switch port |
| `arp` | The ARP table: the MAC address behind each IP address |
| `routes` | The routing table, up to 5,000 routes |
| `health` | CPU, memory, temperature, load and sessions, where the device reports them |
| `hostResources` | Storage, memory, processor load, users and processes on servers |
| `vmware` | The ESXi version, and each virtual machine's name, guest OS, memory, power state and CPUs |
| `printer` | Supplies and their levels |
| `ups` | Battery state |

Choose collectors with `"collectors": { "allow": [...] }` or
`{ "deny": [...] }`. A name that is not a collector stops the agent at start.

### Personal data

The ARP table (which address each laptop and phone has), the forwarding table
(which switch port each device is behind) and the contact field identify people
rather than network equipment. If your data protection review rules them out,
deny `arp` and `fdb`, and set `"collectContact": false`, which stops the agent
asking for the contact field at all.

With any of those off, an SNMP probe Blueprintr sends for named objects or a
subtree returns only the objects the permitted collectors read. The IPv6
neighbour cache and vendor tables with the same kind of data are withheld too,
and a request that could return nothing else is refused before a packet is
sent. Denying `bridge` or `vlans` leaves forwarding table rows without port and
VLAN names.

Blueprintr drops a device's contact field before storing a sweep, whatever
these settings say.

## Running a sweep

Sweeps are in **Network sweeps**, below the Continuum Local panel in
**Settings → Continuum** on the organisation or team. You need
`continuum_integrations.manage` there, and the organisation that owns the agent
needs an Enterprise plan.

> [!STEPS]
>
> === Choose an agent
>
> Only agents that are online, report discovery ranges and are not already
> sweeping are offered. The others are listed with the reason. An agent reports
> its ranges from version 0.2.0.
>
> === Choose ranges
>
> Pick from the ranges the agent reported, or type smaller ones inside them.
> Choosing none sweeps all of them.
>
> === Set limits
>
> **Time limit** is the agent's default (one hour), or 15 minutes to 4 hours.
> **Stop after (hosts, optional)** sweeps only the first that many addresses in
> the ranges.
>
> === Start sweep
>
> The run appears under **Recent sweeps** as **Waiting for the agent**, then
> **Running**.

An agent runs one sweep at a time, for 5.5 hours at most. It uploads results as
it finds them and reports progress every five minutes, and a run that hears
nothing from its agent for 20 minutes is marked **Agent stopped reporting**. A
sweep that runs out of time, or whose agent stops, keeps everything uploaded
before then.

To stop one, choose **Cancel**, then **Stop it**. Everything already uploaded is
kept. The agent is told at its next upload and stops probing there.

### Schedules

Under **Schedules**, choose **Add a schedule**, then the agent, **How often**
(**Every day** or **Every week**), **First run (your time)**, **Time limit** and
the ranges, and **Save schedule**. **Pause** and **Resume** stop and restart a
schedule. A scheduled sweep that comes round while its agent is offline or
already sweeping is skipped, and the next one runs as normal. Missed sweeps are
not run later.

## Reading the results

**Watch** opens a running sweep, whose page updates every few seconds, and
**View results** opens a finished one. The page shows who started it, or that a
schedule did, the ranges and any warnings, then two sections:

| Section | Shows |
| --- | --- |
| **Devices** | Name, class, vendor, model, management address, version, interfaces up and down, and addresses learned. Search by name, address, vendor or model, and select a name to open the device. A switch opens as a front panel of its ports and the addresses learned on each. |
| **Links** | Connections between two devices the sweep reached, from LLDP and CDP, with the port at each end. Links arrive at the end of a sweep. Neighbours outside the ranges, such as phones and access points, are counted but not listed. |

The page never shows which SNMP credential or version a device answered.
Nothing puts sweep results on a diagram or a stratum: they appear only on these
pages.

A sweep that finds no devices usually means the credentials in the agent's
`discovery` block do not match the devices, or a firewall blocks UDP port 161
between the agent and them.

## What Blueprintr keeps

| Question | Answer |
| --- | --- |
| What | The devices, ports and links each sweep finds, and the MAC and IP addresses those devices have learned. Never a device's contact field or anything about the SNMP credentials |
| Why | To show your estate on the results page |
| Who can see it | People who can manage Continuum integrations for the organisation or team. Blueprintr staff see only how many sweeps ran |
| How long | 90 days from when a sweep starts, except that the latest complete sweep from each agent is kept until a newer one completes. Deleting an agent deletes its sweeps |

## Testing on one host first

On the agent's host, `continuum-local probe` profiles one device and prints its
class and the collectors it would run, and `continuum-local discover` sweeps
the policy's ranges and prints a report without sending anything to Blueprintr.
On the Linux packages, run them with `sudo`: they then run as the
`continuum-local` account, with the service's environment file.