Asset discovery

Let machines report themselves; each asset waits in a review queue.

Settings → Asset discovery

Keeps the CMDB honest by letting machines report themselves. A collector posts what it finds, and each asset lands in a review queue until someone decides whether it belongs in your service model.

Discovery proposes, you dispose

A reported asset is not a configuration item. Discovery tells you what exists on the network, which is a different claim from “this is part of the service we run”. Promoting an asset is what turns the first into the second, and that decision is recorded.

That boundary is the point. A CMDB quietly filled by a mis-configured subnet scan is worse than one with a backlog, because afterwards nobody can tell which rows a person actually vouched for.

Setting up an agent

Create one per collector under Settings → Asset discovery. Each gets its own token, so a compromised or retired collector is revoked on its own.
The token is shown once. Only a hash is stored, so it cannot be recovered — only rotated.
Rotating keeps the agent's identity, its discovered assets and its run history. It is not a delete-and-recreate.

Your collector posts batches of up to 500 assets:

POST /api/v1/public/discovery/report
Authorization: Bearer dsc_<publicId>_<secret>
Content-Type: application/json

{
  "agentVersion": "1.4.0",
  "assets": [
    {
      "sourceId": "i-0abc123",
      "name": "web-01",
      "type": "SERVER",
      "attributes": { "os": "Ubuntu 22.04", "ipAddress": "10.0.1.20" }
    }
  ]
}

sourceId is the collector's own stable identifier — hostname, instance id, ARN. Reporting the same one again updates that asset rather than creating a duplicate, which is what makes a nightly scan safe to repeat.attributes is free-form: send whatever the collector knows.

How assets are matched

External ID — the asset's source ID equals a CI's External ID. Exact and deliberate, so it wins outright.
Name and type — a fallback heuristic. Both must agree, and it refuses to guess when several CIs fit, rather than attaching reports to an arbitrary one of three machines called web-01.
Neither — the asset waits in the queue as “Needs review”.

Promoting sets the new CI's External ID to the source ID, so every later run matches exactly instead of re-running the heuristic — and the same identifier is what monitoring alerts already use to find a CI.

The four states

Needs review — found, matching nothing, waiting on you.
Changed — already linked to a CI, but the agent is now reporting different details.
Linked — backed by a configuration item. Nothing to do.
Ignored — dismissed. Later runs keep seeing it and keep leaving it alone, which is what makes the feature usable on a network full of printers and test VMs. An ignored asset stays ignored even when its details change; filter to Ignored and promote it if you want it back.

Attributes that move on every run — uptime, load average, free memory — are excluded from change detection. Without that every asset would read as Changed forever and bury the handful that genuinely did.

Auto-create, and when not to use it

An agent can be set to turn unmatched assets straight into configuration items with no review. It is off by default and worth leaving off until you trust what a collector reports — a scan pointed at the wrong subnet will happily create a hundred CIs you then have to sort out by hand.

Anyone who can create agents can mint a long-lived credential for fleet machines, which is why that sits behinddiscovery:manage rather than the ordinary CI permissions. Reading the queue only needsdiscovery:read.