---
title: "Network discovery"
description: "Turn on network discovery, decide which networks are trusted, review the devices your agents find, push the agent to them, and get alerts for new devices."
url: "https://support.outpostplatform.com/endpoints/network-discovery/"
product: "depot"
type: "how-to"
status: "draft"
ai_summary: "Outpost network discovery: agents list devices on trusted networks and one elected agent per network runs a rate-limited sweep. Turning it on, trust rules, the Suggestions, Seen, Unmanaged, Ignored, and Networks tabs, push install over SMB, WinRM, or SSH, SNMP with vault credentials, discovery alerts, discovery.* settings, and permissions."
availability:
  plans: ["home-lab", "essentials", "enterprise", "msp"]
  permission: "discovery:read"
  preview: false
source: "https://gitlab.com/outpostplatform/docs/-/edit/main/src/content/docs/endpoints/network-discovery.md"
license: "CC BY 4.0"
---

# Network discovery

Network discovery has your agents list the other devices on the networks they
sit on: computers without an agent, printers, phones, cameras, and network
gear. Outpost suggests the computers that could take an agent, and you can push
the agent to them from the console. Devices you choose to track become
[unmanaged devices](/endpoints/unmanaged-devices/). What discovery finds is
also what the [network map](/network-maps/) is drawn from.

Discovery is on every plan. It is off until you turn it on.

## How discovery works

- **Only trusted networks are recorded.** Outpost keeps device data for a
  network only while that network is trusted. On an untrusted network, agents
  report the network itself and nothing about the devices on it.
- **A network becomes trusted on its own** when two agents report it, or one
  desktop or server does, within 30 days. A laptop alone does not make a
  network trusted, because laptops visit networks you do not own. You can also
  trust or deny a network by hand.
- **Most of what agents find costs little traffic.** Agents read what their
  own network tables already hold, and listen for devices that answer
  multicast discovery queries such as mDNS and SSDP.
- **One agent per network sweeps it.** Outpost elects one scanning agent per
  trusted network, preferring servers, then desktops, then laptops. It runs a
  slow, rate-limited sweep once a day by default.
- **Fragile devices are never probed.** Printer and industrial control ports
  are left alone. Your profiles can add ports to that list but cannot remove
  the built-in ones.
- **Device data stays in your Outpost**, in the database of the client it
  belongs to.

Each agent checks every sweep and every push install against its own policy
before it acts.

## Before you begin

| Task | Permission |
| --- | --- |
| See networks, devices, suggestions, and push install jobs | `discovery:read` |
| Trust or deny networks, start scans, ignore, track, and remove devices | `discovery:manage` |
| Push the agent to a device | `discovery:deploy` |
| Push with a saved credential | `vault:use` as well |

Among the built-in roles, the Owner, Support Manager, Field Technician, and
Support Rep can see discovery. The Owner and Support Manager can manage it. The
Owner, Support Manager, and Field Technician can push installs.

## Turn on network discovery

Discovery is turned on by assigning the built-in **Network Discovery** profile
to your whole organization. There are three ways to do it:

- **During first-run setup**, on the **Network discovery** step, select
  **Allow**.
- **On the MSP plan, when you create a client**, select **Turn on network
  discovery**.
- **At any time**, assign the **Network Discovery** profile under
  **Profiles**. See [Profiles](/automation/profiles/).

The profile turns on `discovery.enabled` and `discovery.network_scan_enabled`.
To turn discovery on for only some endpoints, assign it to a site or a device
group instead.

Networks appear on **Endpoints** > **Discovery** > **Networks** once agents
check in. Devices appear once a network is trusted.

## Review your networks

**Endpoints** > **Discovery** > **Networks** lists every network your agents
report, with its **Trust**, **Scanning agent**, **Last scan**, and counts of
**Agents**, **Devices**, and **Suggested** devices.

| Control | What it does |
| --- | --- |
| **Trust** | Trusts the network by hand, whatever the automatic rule says. |
| **Deny** | Untrusts the network until you select **Decide automatically**. Its seen, suggested, and ignored devices are deleted. |
| **Decide automatically** | Clears a manual trust or denial and lets the automatic rule decide. |
| **Scan now** | Asks the scanning agent to sweep the network. Refused within 5 minutes of the network's last sweep. |

## Review discovered devices

**Endpoints** > **Discovery** has a tab for each list:

| Tab | Shows |
| --- | --- |
| **Suggestions** | Devices that look like a Windows, Linux, or BSD computer without an agent. These can take an agent. |
| **Seen** | Every device found on a trusted network, except ignored ones. Filter by **Status** to narrow it. |
| **Unmanaged** | Devices you are tracking. See [Track unmanaged devices](/endpoints/unmanaged-devices/). |
| **Ignored** | Devices you chose to ignore. |
| **Networks** | The networks your agents report. |

Each device shows its **Type** with how sure Outpost is, its **Vendor**,
**Network**, **Status**, the state of any push install under **Deploy**, and
**Last seen**. A device using a private, randomly generated MAC address is
marked **Private MAC address** and is never suggested. On the MSP plan, a
device that is an endpoint in another client is marked **Managed in** that
client.

A device's status is one of **Seen**, **Suggested**, **Deploying**,
**Managed**, **Tracked**, or **Ignored**. A device that becomes an endpoint
moves to **Managed** on its own. A seen or suggested device not found for 30
days is removed, and a seen device with a private MAC address after 7 days.

The endpoint list shows a banner with **Review suggestions** when there are
suggestions to look at.

### Detect hypervisors

Discovery recognizes Proxmox VE as a hypervisor from its web page title or
certificate evidence on port 8006. Enable port scanning in discovery settings
with `discovery.port_scan_enabled` for hypervisor detection. Port scanning is
off by default.

### Ignore a device

1. Select **Ignore** on the device, or select several and use **Ignore** above
   the list.
2. Choose **90 days, then suggest it again if it is still there**, or
   **Permanently, until someone unignores it**.

Select **Unignore** on the **Ignored** tab to bring a device back to **Seen**.

## Push the agent to a device

You can install the agent on a Windows, Linux, or BSD computer from the
console. The scanning agent, or another endpoint on the same network, connects
to the device and runs the installer.

| Target | Methods |
| --- | --- |
| Windows and Windows Server | **SMB (Windows file sharing)**, **WinRM** |
| Linux and BSD | **SSH** |

SMB and WinRM need a Windows endpoint to deploy through. macOS devices cannot
be pushed to.

1. On **Suggestions** or **Seen**, select **Deploy** on a device, or select
   several devices on the same network and select **Deploy agent**.
2. Under **Method**, choose how to connect.
3. Under **Deploy through**, choose **The network's scanning agent**, or
   **Another endpoint on the same network**. The other endpoint must have
   reported the network in the last 15 minutes.
4. Under **Sign in to the devices with**, choose the credential:

   | Choice | Use it when |
   | --- | --- |
   | **The scanning computer's own account** | The devices trust the domain the deploying endpoint belongs to. SMB only. |
   | **A saved credential** | A credential in your vault works on the devices. Needs `vault:use`. |
   | **A username and password for this deploy only** | Neither of the above. Outpost does not store it, and the deploying endpoint must be online. Enter **Username** as `DOMAIN\user`, `user@domain`, or a local account name. |

5. Select **Deploy**.

The **Deploy** column follows each device through **Queued**, **Checking**,
**Installing**, **Waiting to enroll**, and **Managed**. Select **Cancel** to
stop a job that has not finished. An install that finishes but never enrolls
fails after 2 hours.

On Linux and BSD targets, the account signs in over SSH and elevates as root,
with `sudo`, or with `doas`, whichever the target has. Outpost never changes
the target's security settings to make an install work.

### When a push install fails

| Message | What to do |
| --- | --- |
| **The port for this method is closed or filtered on the target.** | Open the port (445 for SMB, 5985 for WinRM, 22 for SSH), or choose another method. |
| **The target refused the credential.** | Check the username and password. |
| **The target refused the scanning computer's own account. Use a credential.** | Choose a saved credential or a one-time username and password. |
| **Windows blocked remote admin for this local account. Use a domain account or the built-in Administrator.** | Use a domain account or the built-in Administrator account. |
| **The account cannot run sudo on the target.** | Use an account that can elevate with `sudo` or `doas`. |
| **Legacy NTLM is disabled by policy.** | WinRM is turned off by `discovery.disable_legacy_ntlm`. Use SMB or SSH. |
| **The scanning agent cannot use this method. Pick another agent or method.** | Deploy SMB and WinRM through a Windows endpoint. |
| **The target's operating system has no Outpost installer.** | The target cannot run the agent. |
| **The install finished but the device never enrolled.** | Check that the device can reach your Outpost address. |
| **The scanning agent stopped responding.** | Make sure the deploying endpoint is online, and try again. |

## Monitor a device over SNMP

You can read a device's model, firmware, and interface data, and set up SNMP
monitors, from its page. Open a device, and use the **SNMP monitoring**
section.

- Testing and browsing SNMP needs `discovery:manage`.
- SNMP uses a shared credential from your vault, chosen in **Shared SNMP
  credential**. Versions 1, 2c, and 3 are supported. Saving a credential choice
  needs `discovery:manage` and `vault:use`.
- **Test saved connection**, **Detect again**, **Preview saved monitors**, and
  **Browse OIDs** work on any discovered device.
- **Enable scheduled monitoring** needs the device to be tracked first. Polling
  runs every 300 seconds by default and keeps 30 days of history.
- Monitors can raise alerts when a reading crosses a threshold you set.

The **Monitoring window (UTC)** limits polling to set hours. Leave both times
blank for continuous monitoring.

## Discovery alerts

Discovery raises alerts in the **Network discovery** category. See
[Alerts](/service-desk/alerts/).

| Alert | Severity | When |
| --- | --- | --- |
| **New device on a trusted network** | Set by `discovery.new_device_alert_severity`, **info** by default | A new device has been on a trusted network for 10 minutes. Private MAC addresses and devices on `discovery.new_device_allowlist` do not alert. |
| **Unapproved DHCP server** | Critical | A DHCP server not on `discovery.dhcp_server_allowlist` answered in the last 15 minutes. |
| **Multiple devices claim the same IP** | Warning | Two devices report the same IP address. |
| **Tracked device is no longer seen** | Warning | A tracked device was missed by later sweeps. |
| **Tracked device changed** | Info | A tracked device's IP address, firmware, or open ports changed. |

:::caution
Add every DHCP server you run to `discovery.dhcp_server_allowlist`. With an
empty allowlist, any DHCP server Outpost sees raises a critical **Unapproved
DHCP server** alert, including your own.
:::

## Discovery profile settings

These are the settings most often changed. They are in the **discovery**
category of a profile. See [Profiles](/automation/profiles/).

| Setting | Default | Effect |
| --- | --- | --- |
| `discovery.enabled` | Off | Master switch. Off means the agent records no devices, runs no sweeps, and pushes nothing. |
| `discovery.network_scan_enabled` | Off | Whether the endpoint may sweep its network. Off anywhere wins. |
| `discovery.scanner_role` | `auto` | `always` prefers this endpoint as its network's scanning agent, `auto` takes part in the election, `never` never scans. |
| `discovery.scan_interval_seconds` | `86400` | How often the scanning agent sweeps. Sweeps run at most every 15 minutes, whatever this says. |
| `discovery.scan_intensity` | `normal` | `light`, `normal`, or `aggressive`. The lightest wins. |
| `discovery.scan_window_start`, `discovery.scan_window_end` | Empty | A daily window for scheduled sweeps, as `HH:MM` in the endpoint's local time. Empty means any time. |
| `discovery.scan_subnets` | Empty | Ranges the sweep may cover. A network of /16 or larger is swept only when it is listed here. |
| `discovery.scan_excluded_ranges` | Empty | Ranges never swept. |
| `discovery.port_scan_enabled` | Off | Whether the sweep checks open TCP ports. |
| `discovery.max_hosts_per_scan` | `1024` | The most addresses one sweep may touch. |
| `discovery.fragile_ports` | Printer and industrial ports | Ports never probed. You can add to the list. |
| `discovery.passive_listeners` | On | Whether agents send mDNS and SSDP discovery queries and listen for the answers. Off anywhere wins. |
| `discovery.link_neighbor_collection` | Off | Whether agents record the switch and port at the other end of their own links, from LLDP and CDP. The [network map](/network-maps/) draws these links. |
| `discovery.snmp_credential` | Empty | The vault credential used for SNMP during discovery. |
| `discovery.auto_track_types` | Empty | Device types to track automatically. See [Track unmanaged devices](/endpoints/unmanaged-devices/). |
| `discovery.new_device_alert_severity` | `info` | `off`, `info`, `warning`, or `critical`. |
| `discovery.new_device_allowlist` | Empty | MAC or IP addresses that never raise a new device alert. |
| `discovery.dhcp_server_allowlist` | Empty | MAC or IP addresses of your approved DHCP servers. |
| `discovery.disable_legacy_ntlm` | Off | Refuses WinRM push installs, which authenticate with NTLM. SMB and SSH are unaffected. On anywhere wins. |

## Differences by operating system

| | Windows | Linux | macOS (Preview) |
| --- | --- | --- | --- |
| Address sweep | ARP | ARP | ICMP, then the neighbor table |
| Push install through this endpoint | SMB, WinRM, SSH | SSH | SSH |
| Sends a DHCP probe to find DHCP servers | No | Yes | Yes |
| Switch neighbor detection (LLDP and CDP) | Yes | Yes, when the agent runs as root | Yes, when the agent runs as root |

## Verify

On **Endpoints** > **Discovery** > **Networks**, your office network shows
**Trusted** and a **Scanning agent**. After the first sweep, **Seen** lists the
devices on it.

## If something goes wrong

| Symptom | Cause | Fix |
| --- | --- | --- |
| A network shows **Not trusted** | Only laptops report it. | Select **Trust**, or enroll a desktop or server on it. |
| **Scan now** is unavailable | The network has no scanning agent yet. | Make sure an endpoint on the network is online with `discovery.network_scan_enabled` on. |
| No devices appear | Discovery is off for the client, or no network is trusted. | Assign the **Network Discovery** profile, and check **Networks**. |

## Next steps

- [Track unmanaged devices](/endpoints/unmanaged-devices/)
- [Network maps](/network-maps/)
- [Install and enroll the agent](/agent/install-and-enrollment/)
- [Wake-on-LAN](/endpoints/wake-on-lan/)