Discovery¶
Discovery finds out what runs on the devices and VMs you already document, so vulnerability matching and end-of-life data work from facts instead of guesses (#451). It is off until a deployment admin and a tenant admin both turn it on, and a profile runs only after someone has written down who authorised it.
Where to find it
- Profiles, runs, Findings, Open ports: Monitoring → Discovery in
the sidebar (
/discovery), with the tabs Profiles, Findings (/discovery/findings) and Open ports (/discovery/services). Profile and run pages are under/discovery/…. - Switches, transports, nmap, deny subnets: the Host discovery
section of Monitoring → Settings (
/monitoring/settings, under Setup; also Settings → Monitoring). - The tenant switch: the Discovery card under Settings → Integrations.
- Results on a host: the Packages and Vulnerabilities tabs of a device or VM.
What it is, and what it is not¶
Discovery reads and observes. It logs in with a credential you gave it and runs a fixed list of read-only commands, or it connects to TCP ports and reads what the server says by itself. It never:
- runs
sudoor writes anything on a host; - runs a command that is not in the published list;
- tries passwords, default credentials or exploits, fuzzes, floods, or sends any other intrusive check;
- looks up what it found with a third party.
The nmap engine is the one place Danbyte starts a program it did not write, and it runs with a fixed argument list, a connect scan and no scripts.
The two kinds of profile¶
A discovery profile says what to read, when, and who authorised it. Each profile is one of two kinds, fixed when it is created:
| Package inventory | Service scan | |
|---|---|---|
| Targets | Devices and VMs, at their primary address (a device's out-of-band address when it has no primary) | Every IPAM address in scope, whether or not it belongs to a device or VM |
| How | Logs in over SSH (key or password) or WinRM over HTTPS (client certificate) | TCP connect to a port list, one greeting read or one GET / per open port |
| Needs | A credential and an accepted SSH host key (or a trusted WinRM certificate) | Nothing but network reach |
| Gives | The OS release, every installed package (Linux), the build, hotfixes and programs (Windows) | Open ports, the product and version a banner names, TLS certificate facts, SSH host keys |
| Feeds | CVE matches, the running version, platform and application proposals, installs | Proposals only: add a service, add installed software, map a CPE |
| Reference | Package inventory, Windows hosts | Service scan |
Neither is the address discovery sweep. That one pings the addresses of enrolled prefixes and records the ones that answer as new IPs in IPAM; it logs in nowhere, has no profiles and has its own switch (Monitoring: Address discovery). Discovery reads only hosts and addresses that are already in IPAM.
How the data flows¶
| Step | Package inventory | Service scan |
|---|---|---|
| 1. Resolve | The profile's scope becomes a list of hosts, inside the profile's tenant, when the run starts. Exempt hosts, deny subnets, maintenance and the target policy remove hosts before any connection (Scope and safety). | The same, for addresses. |
| 2. Read | Fixed commands over SSH or WinRM. | Connect, read the greeting, close. |
| 3. Store | OS facts (one row per host) and packages (one row per package), as machine data. | Observed services (one row per open port). |
| 4. Feed | The host's running version; installs of applications whose package names match; findings (Set platform, Add application, Link packages). | Findings (Add service, Add software, Map to CPE). |
| 5. Match | Vulnerability matches Via: Package (Linux, from OSV advisories) and Via: OS build (Windows, from Microsoft's data). | None. A banner never creates a CVE match. |
Nothing in steps 4 and 5 changes your documented data without a person, except two things Discovery owns: the running version it writes with source Discovery, and the installs it creates for applications that name their packages. Everything a person accepts from Findings is a normal object in the change log.
Terms used across these pages:
| Term | Meaning |
|---|---|
| OSV | The Open Source Vulnerabilities database (osv.dev). Its Debian, Ubuntu, Alpine, Rocky Linux, AlmaLinux and Red Hat advisories list the fixed package version per distribution release. |
| CPE | Common Platform Enumeration, NVD's naming of products (cpe:2.3:a:f5:nginx). |
| purl | A package URL (pkg:deb/debian/openssl@3.0.15-1~deb12u1), the standard name of one package version. |
| UBR | Update Build Revision, the last part of a Windows build (2849 in 10.0.20348.2849). It moves with each monthly update. |
What it needs from you¶
- A deployment admin allows Discovery for the deployment, and a tenant admin turns it on for the tenant (Getting started).
- For package inventory: a login per host - the host's own credential or a shared credential - and each host's SSH key reviewed and accepted.
- A profile with a scope and a written Authorisation: who said yes to reading those hosts.
- For CVE results: vulnerability data turned on, and in upload or browser mode someone who fetches the advisories after a read.
- For a host Danbyte cannot reach: an Outpost at that site.
These pages¶
| Page | What it answers |
|---|---|
| Getting started | From a fresh install to a first package list and a first scan, step by step. |
| Package inventory | The exact commands, what is stored, limits, the Packages tab, versions, platforms, applications. |
| Windows hosts | SSH and WinRM on Windows, what is read, matching against Microsoft's data. |
| Service scan | Ports, probes, fingerprints, Findings, the nmap engine. |
| Credentials and host keys | Which login a host gets, host-key review, accept on first use. |
| Scope and safety | Scope kinds, authorisation, every skip rule, limits, permissions, privacy. |
| On an Outpost | Running a profile from an Outpost, and what it never does. |
| Settings | Every environment variable and switch, the queue and the timer, upgrade notes. |
| API | Every endpoint, its permission and its fields. |
| Troubleshooting | Every run and host status, and the common situations. |
Sections that moved¶
These pages used to be two long pages. Old links land here; follow the one you need.