Resolvers
Resolvers are the worker identity kind that performs reverse-DNS (PTR) lookups for discovered hosts. A resolver is provisioned, enrolled in mTLS, monitored and revoked exactly like a scanner — it is the same binary and the same identity lifecycle — but its role is fixed at creation: a resolver never receives port-scan work and a scanner never performs DNS. Every resolver belongs to exactly one resolver group (its DNS vantage point). Once a resolver is installed for a group, it claims and works the DNS jobs queued for that group: lookups run, evidence is recorded. Hostnames and a per-host DNS status appear on the scan's results page (click a hostname cell for the evidence drawer), the Hostname column on Port State Changes carries the same names, and each DNS job's signed receipt is listed on Execution Proof.
Inputs
| Name | Description | Allowed values | Default |
|---|---|---|---|
Name | Unique identity name | Letters, numbers, hyphens and underscores; 1–100 characters; unique across scanners AND resolvers | — |
Resolver group | The vantage point this resolver joins — its members must see the same DNS | An existing resolver group | — |
Description | Optional note about where the resolver runs | Any text | Empty |
IP binding mode | How strictly the identity is tied to its source address | IP, subnet, ASN or none | IP |
Fields & columns
| Name | Description |
|---|---|
Name | Editable inline — the identity name |
Resolver Group | Editable inline — pick another group from the dropdown to move the resolver (saved immediately) |
Description | Editable inline — optional note about where the resolver runs |
Status | Pending (never registered), Active (heartbeating), Offline (missed heartbeats) or Disabled |
mTLS | Enrollment state of the identity certificate, as for scanners |
Binding | IP binding mode and the bound address |
Rate Limit | Max probes per second — carried by the shared identity row, unused by a resolver |
Active Errors | Open job-error alarms attributed to this identity |
Created By | The user who provisioned the resolver |
Created | When the identity was provisioned |
How to
Add a resolver to a vantage point
- Create the resolver group first (Config › Resolver Groups) if it does not exist.
- Click "Add Resolver", name it, pick the resolver group and save — you receive a one-time install command: the same install.sh a scanner uses, plus --role resolver.
- Run the command on a host inside that network segment — the same host can already run a scanner (each role gets its own system user, state directory, env file and systemd unit; they share only the installed binary). The host enrolls, heartbeats, and starts claiming DNS jobs queued for this resolver group.
Gotchas
- Row actions live behind one "Actions" button per row. It opens a side panel listing Configure Binding, Regenerate Token, Rotate API Key, Enroll mTLS (Re-enroll mTLS once the identity is Required), Enable or Disable, and Delete, each with a sentence on what it does; Delete is marked as destructive, and "Confirm identity" marks the ones that ask you to re-enter your password or code first. Choosing an action opens the same confirmation or dialog as before.
- The installer enrolls the identity in mTLS during provisioning. Use the row's enrollment-token action only to re-enroll an existing host, exactly as you would for a scanner.
- Lookups run once a resolver is installed and heartbeating for a group: an execution that requests reverse DNS gets lookup tasks bundled into jobs for its resolver group, and any online resolver in that group claims and works them, submitting observation batches and a signed receipt per job. A resolver group with no online member still closes its lookups incomplete on schedule — the port scan itself is never delayed either way.
- What a resolver finds is visible: the scan results page shows a Hostnames column and a per-host DNS Status, and clicking a hostname cell opens an evidence drawer listing every lookup attempt for that host; Port State Changes shows the hostname from the execution each change row belongs to; Execution Proof lists the signed DNS receipt for every DNS job. Health › Services › Resolvers shows the live queue and backlog for this fleet.
- The role is fixed by the identity, not by the binary: the same mipo-scanner build runs as a resolver when its identity says so, and refuses to start if its unit's declared role disagrees with that identity. install.sh --role resolver gives a resolver its own system user, state directory, env file and systemd unit, so one host can run a scanner and a resolver side by side, sharing only the installed binary.
- A resolver identity is invisible on the Scanners page and cannot be driven through the scanner API — a scanner id is likewise invisible here. Every row action here writes to the resolver mount, so the same action on the wrong page answers 404 rather than touching another fleet.
- Release Binding is the one scanner-only action: it is not offered here, because the release-binding route exists only on the scanner mount. Change the binding mode instead.
- Add, delete, disable, enable, the binding-mode change and every token or key action require step-up re-authentication (the same trust tier as scanners); the inline name, description and resolver-group edits do not.
- Moving a resolver to another group (the dropdown in the Resolver Group column) changes which executions it may serve from then on; executions already started keep the group they snapshotted. A move is refused while the resolver holds assigned DNS work.
API calls (10)
| Method | Path | Description |
|---|---|---|
| GET | /api/config/resolvers | List resolver identities with their resolver group |
| POST | /api/config/resolvers | Create a resolver and mint a one-time provisioning token (requires resolverGroupId) |
| PUT | /api/config/resolvers/:id | Update name, description, rate limit or resolver group |
| PATCH | /api/config/resolvers/:id | Change the IP binding mode |
| POST | /api/config/resolvers/:id/disable | Disable a resolver (revokes its live certificates) |
| POST | /api/config/resolvers/:id/enable | Re-enable a disabled resolver |
| POST | /api/config/resolvers/:id/regenerate-token | Issue a fresh provisioning token |
| POST | /api/config/resolvers/:id/rotate-key | Rotate the API key with a 24-hour grace period |
| POST | /api/config/resolvers/:id/enrollment-token | Mint a one-time mTLS enrollment token |
| DELETE | /api/config/resolvers/:id | Delete a resolver identity |
Related
- Resolver Groups — The vantage point a resolver belongs to
- Scanners — The same identity lifecycle, for the port-scan role
- Nameserver Groups — The servers a resolver may be told to query
- Health > Services > Resolvers — Live reverse-DNS queue health and per-group backlog for this fleet
- Results — Where the hostnames and per-host DNS status a resolver produces are shown
- Scanner Job Dispatch — The pull-based job protocol, including the reverse-DNS job routes a resolver uses