Skip to main content

Discovery pipeline

A scan can tell you that a MAC address answered at an IP and that port 3000 looks like Grafana. It cannot know whether the device belongs in your inventory, whether its name is intentional, or whether an old relationship should be removed.

The pipeline preserves observations, generates suggestions, compares them with accepted inventory, and routes the differences through a review policy.

Pipeline stages​

Evidence reinforces other evidence. A product string can identify an application; that application can support a device classification; the classification can improve a name candidate. The inference stage therefore repeats until nothing changes, with a maximum of three iterations.

Execution is bounded by limits on subjects, facts, candidates, and emitted artifacts. Rules use typed conditions rather than arbitrary code. The same input, rule versions, and inventory state should produce the same recommendation.

The current rule families​

MiniPAM ships four groups of rules:

  • Application recognition uses endpoint product, service, port, certificate, banner, CPE, and inferred-role evidence. Current examples recognize Grafana, Home Assistant, Proxmox VE, TrueNAS, Pi-hole, AdGuard Home, and other common small-network software.
  • Device classification combines topology, operating-system, product, application, hostname, and vendor evidence. A configured gateway address is strong evidence; OS or product details can suggest a switch, firewall, NAS, printer, phone, UPS, camera, or other built-in type. Hostname-only clues are deliberately weaker.
  • Device naming prefers a directly observed FQDN, then corroborated mDNS. A recognized application may provide a lower-confidence fallback name.
  • Review policy decides whether the resulting operation is eligible to apply or must wait for a person.

The recognition and classification definitions are packaged, versioned YAML. Operators and developers can inspect app-server/src/services/discovery/builtin_rules.yml and the ordered pipeline in builtin_pipelines.yml; the generated app-server/docs/discovery-configuration-reference.md lists the complete current contract.

What applies automatically today​

The built-in review policy is intentionally conservative:

  • removals and unlinks require review;
  • creation of a new inventory resource requires review;
  • only a safe update to an existing Managed value may auto-apply, and only with at least 0.90 confidence from direct or corroborated evidence;
  • everything else falls back to review.

Hard guards still apply after the policy result. A rule cannot use an auto_apply result to bypass ownership, conflict, or safety protections.

Discovery review queue grouping suggestions by device with readiness and evidence warnings

The queue groups proposed changes by discovered device and displays evidence status.

Customize review policy​

Review-policy rules are in Discovery → Review queue → Rules & help. Keep fallback. Test policy changes against a queued recommendation before enabling broader automation.

The older observed-import.rules-paths configuration is separate. It extends legacy scored import heuristics; it is not the discovery-intelligence recognition/classification pipeline described here.

Last updated on