Network Discovery

Scope

How discovery scans run from a probe endpoint inside your network, and how to review and promote the devices they find.

Understanding the Probe-Based Model

Cadres is a cloud-hosted SaaS platform and cannot directly reach devices on your network. All discovery scans are executed by a probe endpoint – a managed endpoint running the Cadres agent inside your network. The probe endpoint must:

• Have an active Cadres agent installed and registered
• Be on the same network segment as the devices you want to discover
• Be online and reachable by the Cadres backend

Automatic Subnet Discovery and Probe Election

When an agent registers, Cadres automatically:

1. Reads the endpoint’s network interfaces to determine which subnets it can reach
2. If the subnet has no existing probe, elects the newly registered agent as the probe
3. If auto-bootstrap is enabled (default), creates a weekly discovery job for the subnet

This means discovery often requires zero manual configuration – just install agents.

To check which subnets are registered and their probe assignments:

To disable auto-bootstrap for an organization:

• Create or update a DiscoveryPolicy for the org with auto_bootstrap_enabled=false

Creating a Manual Discovery Job

Discovery types:

• network_scan – Ping sweep + port scan. No credentials required.

Credential selection (UI):

• SNMP credential: Separate dropdown for credentials tagged relay.snmp_v2c or relay.snmp_v3. When set, endpoints discovered with SNMP-capable ports are automatically provisioned as SNMP devices.

Where scan credentials live

Every discovery credential lives in the Portal vault (PETE’S RULINGS #1, 2026-08-22). Relay stores an opaque Portal credential id — never a secret — and reveals the secret only at the moment it dispatches a scan. Three consequences an operator needs:

1. Credential ids are opaque strings. Relay compares and passes them through; it never interprets or renumbers them.

2. Set the credential’s target_ref to relay:organization:<id> to scope it to one organization. A credential marked for a different organization is refused. A credential with no marker is usable anywhere in the account.

3. approval_required must be off. An unattended scan cannot wait for a human to approve a checkout, and Relay says so rather than hanging.

Do not point a scan at an administrator’s personal privileged account. Give the scan its own credential, tagged with the relay.* kind for the transport it uses.

When a scan cannot get its credential

A scan without its credential authenticates nowhere, so Relay fails the job rather than scanning anyway. The job goes to failed and last_error says which of three things happened:

last_error says	What happened	What to do
Portal is rate-limiting credential reveals	The tenant exceeded Portal’s ceiling (~10 checkouts/reveals per minute)	Nothing — the next cycle recovers. If it persists, use fewer distinct credentials per cycle or lengthen the schedule.
Portal could not be reached, retry once reachable	Vault outage or transport failure	Retry once Portal is back. The credential is fine.
The credential does not exist / re-select	Portal answered “no such credential”	Re-select a credential on the job. This is the only case where the credential is the problem.
The account has no Portal tenant link, or its tenant has no Portal service client (portal_integration_not_provisioned)	Provisioning is incomplete; Portal was not contacted	An administrator links the account or provisions the service client (SaaS Portal manual, “Portal integration states”), then retry.

A scheduled cycle reveals each distinct credential once, no matter how many due jobs share it, which is what keeps a large fleet inside the rate limit.

Probe endpoint selection (UI):

• Searchable dropdown of online agent endpoints in the selected organization.
• Server-side search by hostname/FQDN — no silent truncation at scale.
• When target ranges are entered, probes whose registered subnet covers the target are ranked first and labelled “(subnet match)”.
• The probe should be on the same network as the target ranges for the scan to reach the targets. The UI provides subnet-aware ranking hints but does not enforce reachability.

Network organization context (UI):

• The Network Discovery workspace includes a Network Organization selector.
• Jobs, endpoints, and subnet views are scoped to the selected organization.
• New jobs default to that same selected organization, so probe/credential choices stay tenant-bound.

Schedule format: Standard 5-field cron expression (UTC). Leave null for manual-only jobs.

Running a Discovery Scan

Preconditions:

• Probe endpoint must be configured and have an active agent (400 error)
• SSH/WinRM jobs must have a credential configured (400 error)

Audit trail: every run attempt writes one discovery_job.run audit entry. A recorded as a failure with the refusal reason and leaves the job unchanged. A dispatch that fails after the checks (for example a probe in another organization, or a scan credential Portal cannot serve) marks the job failed, returns 500 with the job’s last_error, and records a failure entry with the same reason.

Dashboard

Shows total jobs, active scheduled jobs, and three breakdown panels:

• By Lifecycle State: Full 7-state breakdown (discovered/linked/managed_pending_agent/deploying_agent/managed/ignored/stale) with color-coded bars
• By OS Type: Linux, Windows, Unknown counts
• Recent Discoveries: Last 10 endpoints with lifecycle state badges

Organization scope: Org-restricted users see only data from their assigned organizations. Account admins see all organizations. The dashboard applies perms.get_org_filter() to both job and endpoint queries.

Permissions Reference

Permission	Operations
discovery.view	List/view discovery jobs, discovered endpoints, lifecycle history, dashboards
discovery.manage	Create/update/delete discovery jobs; run scans; promote/ignore/unignore endpoints; retry deploy; bulk ignore/unignore

Subnet Visibility

Lists all registered subnets for accessible organizations. Each entry includes:

Field	Description
cidr	Subnet CIDR (e.g. 192.168.1.0/24)
gateway	Gateway IP address
endpoint_count	Number of endpoints assigned to this subnet (accurate COUNT query)

Use this endpoint to verify which subnets have been auto-detected, confirm probe assignments, and identify subnets without active probes.

Requires: discovery.view permission.

Cross-References