Skip to main content

Discovery rules and 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, and the classification can improve a name candidate. The inference stage therefore repeats until nothing changes, at most three times.

Rules are typed conditions, not code, and each run is bounded in how many devices, facts, and candidates it looks at. The same input, rule versions, and inventory state 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.

Manual and Managed fields​

Every device field that discovery can fill, such as name, hostname, OS, and device type, is either Manual or Managed:

  • Manual means the value is yours. Discovery never changes it by itself, not even with a custom auto-apply rule; a different value can only reach you as a suggestion in the review queue.
  • Managed means MiniPAM may keep the value current as evidence changes. Only Managed values can update automatically.

How a field gets its mode:

  • A field MiniPAM has never managed is Manual.
  • When you accept a suggestion that creates a device, its filled fields start Managed. A value you edit before accepting, such as the name, starts Manual.
  • When you accept a change to a Manual field, you choose per field: Apply once — remain Manual, or Apply and let MiniPAM manage, which makes it Managed.
  • When you edit a device's name, hostname, or OS yourself, that field goes back to Manual.

What applies automatically​

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.

How the pipeline runs​

The pipeline works on one discovered device (a subject) at a time:

  1. An observation, such as a netscan result, updates the subject's facts. Only a real change marks the subject as changed; seeing the same thing again does not.
  2. A subject is processed again when it changed since it was last processed, or when the pipeline or recognition rules changed. An upgrade that changes the built-in rules therefore reprocesses every device.
  3. The review policy is resolved for the subject's site, built-in rules plus that site's own rules.
  4. Right after a subject is processed, its auto-apply suggestions are applied. Each one is previewed again first, and one that is no longer ready is left in the queue.
  5. If processing fails, the error is stored on the subject and the subject is retried on the next run.

Timing:

  • A netscan's or device scan's (nmap enrichment) subjects are processed as soon as the scan finishes.
  • system.discovery.process_dirty is the backstop for anything left over. It runs every 60 seconds and processes up to 100 subjects per run, oldest change first.
  • Schedules start 30 seconds after the server starts. Runs missed while the server was down are skipped.

Customize review policy​

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

Last updated on