> ## Documentation Index
> Fetch the complete documentation index at: https://docs.2501.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Network Discovery

> Scan your network to build host inventory automatically

Network Discovery lets 2501 scan one or more subnets and populate your host inventory without manual entry. Instead of adding hosts one at a time, you point a scan at a range of addresses and 2501 finds what's live, identifies it, and — with your approval — promotes it to a managed host. Start a scan from the **Discovery** page in Command Center.

<Note>
  Every scan runs through an **entry host** — the host the engine connects through to reach the target subnets (see [Reaching non-routable subnets](#reaching-non-routable-subnets)). To let a deep scan identify what it finds, store credentials for the hosts you expect to discover first — see [Credentials](/0.9/configure/credentials).
</Note>

## Starting a scan

Go to **Command Center** → **Discovery** and start a new scan. A scan takes these inputs:

* **Entry host** *(required)* — every scan starts from an entry host; the engine reaches the target subnets through it. To tunnel through it as a bastion, give its SSH user and key/secret credentials; leave both empty to run the scanner directly from the engine host. If the host has both a public and private IP, you also choose which one to dial.
* **Scope** *(required)* — one or more CIDRs to cover (e.g. `10.0.1.0/24`, or a comma-separated list). A CIDR must be `/16` or narrower; broader ranges are rejected to keep a single scan bounded.
* **Credential allowlist** *(optional)* — restricts which stored credentials a deep scan may try against discovered hosts. Leave it empty and all of the org's credentials are eligible; narrow it to specific credentials when you want tight control over which logins are ever attempted, such as on sensitive or fragile network segments.

### Scan depth

<Steps>
  <Step title="Scan">
    A reachability sweep only — 2501 checks which addresses in the range are live and which ports they have open. Nothing is logged into.
  </Step>

  <Step title="Deep scan">
    Everything in **Scan**, plus authenticated recon: 2501 attempts to log into each responding host with the eligible stored credentials and characterizes it (OS, services, routes, and technology stack). Deep scan is what populates a host's tags.
  </Step>
</Steps>

### Review mode

Choose how much of the scan runs without you in the loop:

* **Auto** — recon starts automatically and every host that responds is promoted to a managed host. No manual step.
* **Semi-auto** — recon starts automatically, but you confirm each host before it's created or updated.
* **Manual** — nothing fires on its own. You trigger recon and host creation yourself, node by node.

## How it works

<Steps>
  <Step title="The scan runs in an ephemeral container">
    The scanner runs inside a short-lived container, one per subnet. It probes each address in the range, then — on a deep scan — attempts to authenticate to responding hosts using the eligible stored credentials.
  </Step>

  <Step title="Discovered nodes are characterized">
    Hosts that accept a connection are characterized automatically — OS, services, routes, and technology stack are derived and attached as [tags](/0.9/core-concepts/hosts#host-tags).
  </Step>

  <Step title="Review the results">
    Discovered nodes appear in the infrastructure map as a review panel. For each node you can:

    * **Confirm** — promote it to a managed host with all derived tags applied, making it immediately available for agent assignment.
    * **Ignore** — dismiss the node without adding it to inventory.
  </Step>
</Steps>

## Credentials and characterization

On a deep scan, 2501 tries the eligible stored credentials against each responding host to identify it. Credential handling is deliberately conservative:

* 2501 only ever tries credentials already stored in the org — it never generates or guesses logins. The credential allowlist narrows this further; an empty allowlist makes every org credential eligible.
* A node is marked characterized only when a command actually proves access — not on a hopeful match.
* To protect accounts, 2501 stops using a credential after a configurable number of failed authentication attempts (**max failures per credential**).
* A host that responds but that no credential can authenticate to is still recorded as discovered, so you can supply a credential and re-run recon on it later.

## Coverage

A scan reports honest coverage per CIDR. Every subnet in scope shows what happened — swept directly, reached through the entry host, or unreachable. An unreachable subnet is recorded as such rather than silently dropped, so you always know exactly what a scan did and did not cover.

## Idempotency

Scans are idempotent. Re-scanning a subnet links newly found IPs to any hosts already in inventory rather than creating duplicates. Running a scan regularly is safe: you see new nodes without losing existing host records. A node you previously ignored can resurface on a later scan if it's still live — ignoring is a decision about one scan, not a permanent suppression.

## Reaching non-routable subnets

When the target subnets aren't reachable from the engine directly, pick an entry host that sits inside or adjacent to them and give it SSH credentials. The scanner then tunnels through that host to reach the target CIDRs — the entry host acts as the bastion. See [Hosts — Jump host](/0.9/core-concepts/hosts#jump-host-ssh-bastion) for how bastion hosts are registered.

When a node reached through an entry host is promoted, the path used to reach it is carried onto the new host's configuration, so the agent can connect to it the same way the scan did.

## After confirmation

Confirmed hosts are immediately available for agent assignment. Tags applied during discovery (OS, shell, type, technologies) are editable from the host's detail page if the characterization needs adjustment.

For bulk onboarding via a CSV file, see [Import Hosts CSV](/0.9/configure/import-hosts-csv). To manage hosts declaratively, see [Configuration as Code](/0.9/configure/configuration-as-code).