Network Discovery

Scope

Discovery should clarify the environment instead of creating another doubtful asset list. This guide keeps the operator-facing discovery model and excludes private scanning mechanics.

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 host – a managed endpoint running the Cadres agent inside your network. The probe host 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 host’s network interfaces to determine which subnets it can reach 3. If the subnet has no existing probe, elects the newly registered agent as the probe 4. 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): - SSH/WinRM credential: Dropdown populated from PAM vault identities. Required for ssh and winrm discovery types. - SNMP credential: Separate dropdown for SNMP v2c/v3 identities. When set, hosts discovered with SNMP-capable ports are automatically provisioned as SNMP devices.

Probe host selection (UI): - Searchable dropdown of online agent hosts 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, hosts, 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 host must be configured and have an active agent (400 error) - SSH/WinRM jobs must have a credential configured (400 error)

Managing Discovered Hosts

Lifecycle States

Each discovered host progresses through lifecycle states. The UI displays lifecycle_state as the primary status indicator with color-coded badges:

State	Badge Color	Meaning
discovered	Blue	Newly found on network
linked	Cyan	Matched to existing host by IP/hostname/MAC
managed_pending_agent	Yellow	Promoted, awaiting agent registration
deploying_agent	Accent (teal/cyan)	Agent deployment in progress
managed	Green	Agent registered, fully managed
ignored	Gray	Excluded from review/promotion
stale	Red	Not seen in recent scans

Promoting Hosts

Request body options:

• deploy_agent (default: false): Automatically deploy Cadres agent via SSH/WinRM

The UI defaults deploy_agent to checked for server-class OS types.

Probe selection during deploy: When deploy_agent=true, the system selects the best probe to reach the target host: 2. Subnet registry probe – matches the target host’s IP against known subnet CIDRs and selects the probe assigned to the most-specific matching subnet 3. Discovery job’s configured probe host 4. Any online agent in the same organization

Lifecycle History

Returns the complete transition history with from_state, to_state, reason, confidence_score, triggered_by, and timestamp. In the UI, expand a discovered host’s detail panel to view the full lifecycle history timeline.

Other Actions

Ignored hosts are excluded from future dashboard counts and promotion suggestions. Use to revert.

Permanently removes the discovered host record and its lifecycle history. Cannot be undone. An explicit confirmation dialog is shown in the UI before deletion. Does not affect any linked managed host record.

Bulk Operations

Select multiple hosts using the checkboxes in the hosts table, then click “Bulk Ignore”. All selected hosts that are in a valid state (not already managed) will be transitioned to ignored. The response includes a count of successes and any failures.

The UI shows an explicit confirmation dialog listing how many hosts will be ignored before the request is submitted.

Select multiple ignored hosts and click “Bulk Unignore” to revert them to discovered state.

Both endpoints validate org access per host and return detailed results. The UI shows the same explicit confirmation pattern before bulk unignore runs.

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 hosts 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 host queries.

Host Scope and Organization Visibility

Users see discovery resources based on their organization access:

• Org-scoped users: See only discovery jobs and hosts belonging to their assigned organizations. The dashboard shows aggregate stats only for accessible orgs.

Permissions Reference

Permission	Operations
discovery.view	List/view discovery jobs, discovered hosts, lifecycle history, dashboards
discovery.manage	Create/update/delete discovery jobs; run scans; promote/ignore/unignore hosts; 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
host_count	Number of hosts 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

• SNMP device management: See snmp.md for credential management, device registration, and polling
• Active Directory management: See active-directory.md for forest management and AD operations
• Jobs & Scripts: See jobs-scripts.md for general job dispatch and monitoring
• PAM Vault: See pam.md for credential management used by discovery