Skip to content
DeviceQuest DeviceQuest DeviceQuest Docs User Documentation

Documentation

Host Agents

See every enrolled host agent, send it management commands, queue one-off or recurring scans, and revoke agents you no longer trust.

Overview

The DeviceQuest host agent runs on a Linux or Windows endpoint, collects inventory locally, and connects outbound to the agent gateway of the control plane. Host Agents lists every agent enrolled in your organisation with its live status, and lets you send predefined management actions to one agent: pull its configuration, update it, queue a scan that runs on the agent, schedule that scan to repeat, and revoke the agent. Agents appear here after they enroll; see Enroll an agent.

Open it from Admin → Host Agents in the sidebar. The page is for administrators: people without the admin:manage permission see the access-restricted page instead.

Screen tour

  1. Online / offline counts: how many enrolled agents are online and offline right now.
  2. Refresh: reloads the agent list. The list also refreshes itself every 60 seconds.
  3. Agent list: one entry per enrolled agent, newest heartbeat first. Each entry shows the platform (for example linux/amd64), the agent ID, when it was last seen, the agent version, and its status. Click an entry to select it.
  4. Status: the selected agent’s status: Online, Offline or Revoked. See Statuses.
  5. Revoke: disconnects the agent for good. See Revoke an agent.
  6. Agent details: the Agent ID (click Copy to copy it), the Enrollment ID, the agent Version, the Last heartbeat and when the agent was Enrolled.
  7. Tabs: Manage sends commands and queues scans, Recurring scans lists the scan schedules of this agent, and Command history shows what was sent and how it went. The tabs show how many recurring scans and commands exist.
  8. Footer: how many agents are enrolled, and the automatic refresh interval (Auto-refresh 60s).

When the selected agent is offline, the Manage tab shows when it last reported, for example This endpoint last reported 3h ago. You can still queue commands: they are delivered when the agent next checks in.

When no agent has enrolled yet, the list shows No enrolled host agents. Enroll one from Enroll an agent.

Send a management command

The Commands block of the Manage tab sends a predefined action to the selected agent.

  1. Pull config: asks the agent to fetch its current configuration from the control plane.
  2. Update agent: asks the agent to download a new agent build and install it.
  3. Version (optional): the agent version to install with Update agent, for example 1.8.3. Leave it empty to install the latest released version.
  4. Scanner: the scanner the agent runs. See Scanner types.
  5. Target: what to scan: an IP address, a hostname or a CIDR range.
  6. Credential ID: the ID of a scan credential, for scanners that log in to the target.
  7. Params JSON: extra scan parameters as a JSON object.
  8. Queue scan: sends the scan to the agent now.
  9. Make recurring: opens the panel that turns the scan above into a recurring scan.
  10. Name: the name of the recurring scan.
  11. Every (hours): how often the scan runs.
  12. Create schedule: saves the recurring scan.
  1. Select the agent in the list.
  2. On the Manage tab, click Pull config, or enter an optional version and click Update agent.
  3. A confirmation such as Queued pull config for linux/amd64. appears, and the command is added to Command history with the status Pending.

The agent receives the command over its outbound connection. While any command of the selected agent is pending, dispatched or in progress, the page checks for updates every 5 seconds, so you can watch the status change on the Command history tab.

Queue a scan

A scan queued here runs on the agent itself, so it reaches networks and hosts that only the agent can see. Its results are ingested like any other scan.

  1. Select the agent and open the Manage tab.
  2. Under Queue a scan, enter the Scanner, for example sweep.
  3. Enter the Target, for example 10.20.0.0/24.
  4. For scanners that log in (ssh, wmi, snmp, vmware), enter the Credential ID of a scan credential. You find the IDs on Scan credentials; click Scan Credentials under the field to open it. The control plane resolves the credential when it sends the scan, so the secret never appears in the command.
  5. Optionally enter Params JSON, for example {"port_range": "22,443"}.
  6. Click Queue scan.

Queue scan and Make recurring stay disabled until you enter a scanner and a target. Params JSON is checked when you leave the field: it must be a JSON object whose values are all strings, otherwise the field shows Scan params must be a JSON object or Scan params values must be strings.

Scanner types

ScannerWhat the agent doesCredential ID
localCollects inventory of the host the agent runs on. Use localhost as the target.Not used
sweepDiscovers live hosts and open ports in an IP range.Not used
sshLogs in to Linux, Unix and BSD hosts over SSH.Required
wmiQueries Windows hosts over WMI and WinRM. Runs on Windows agents.Required
snmpReads network devices over SNMP.Required
vmwareReads a vCenter or ESXi host.Required

The sweep scanner accepts two parameters in Params JSON: port_range (default 22,80,443,3389,8080) and max_probes (default 100).

Create a recurring scan

A recurring scan queues the same scan on the agent at a fixed interval.

  1. Fill in the scan form on the Manage tab as described in Queue a scan.
  2. Click Make recurring. The panel Runs the scan configuration above on a fixed interval. opens.
  3. Enter a Name. If you leave it empty, the name is the scanner and the target, for example sweep 10.20.0.0/24.
  4. Enter Every (hours): a whole number from 1 to 720. The default is 24.
  5. Click Create schedule.

The first run is one interval after you create the schedule. The control plane checks for due recurring scans every minute and queues each one as a scan command for the agent.

Recurring scans

  1. Name: the name of the recurring scan.
  2. Cadence: the interval, for example 24h.
  3. Next run: when the scan is queued next.
  4. Last run: when it was last queued, or Never.
  5. Delete: removes the recurring scan after you confirm.

To delete a recurring scan, click Delete, read the message Delete “…”? Its next run on … will be cancelled., and click Confirm, or Cancel to keep it. Scans already queued are not affected.

Command history

  1. Refresh history: reloads the list.
  2. Action: Scan, Pull config or Update.
  3. Status: where the command is. See Command statuses.
  4. Error message: when a command fails, the agent’s error appears under the action. Long messages are shortened; click Show details to read all of it, and Hide details to shorten it again.
  5. Queued: when the command was queued.
  6. Duration: how long the agent took to run the command, in milliseconds or seconds. A dash means the command has not finished.

The tab shows the 20 most recent commands of the selected agent, newest first. When the agent has none, it shows No commands yet.

Revoke an agent

Revoke an agent when a host is retired, reinstalled or no longer trusted.

  1. Revoke linux/amd64?: the confirmation, which explains what revoking does.
  2. Revoke: revokes the agent.
  3. Cancel: closes the confirmation without changes. Esc does the same.
  1. Select the agent and click Revoke next to its status.
  2. Read the confirmation and click Revoke.

The agent’s access token is deleted, so the agent is disconnected on its next check-in and can no longer send data or receive commands. Its status changes to Revoked, the Manage tab disables all actions, and the agent stays in the list for reference. Revoking cannot be undone: to bring the host back, re-run the install command on it with a new bootstrap credential from Enroll an agent.

Queued commands, created and deleted recurring scans, and revoked agents are recorded in the Audit log.

Fields

FieldDescriptionRules
Version (optional)Agent version for Update agent.At most 64 characters. Empty installs the latest version.
ScannerScanner type the agent runs.Required. 1–40 lowercase letters, digits, _ or -. One of the scanner types.
TargetIP address, hostname or CIDR range.Required. At most 256 characters.
Credential IDID of a scan credential.Required for ssh, wmi, snmp and vmware. At most 120 characters.
Params JSONExtra scan parameters.A JSON object with string values. At most 20 entries; keys 1–64 characters, values at most 256 characters.
NameName of a recurring scan.Optional. At most 120 characters.
Every (hours)Interval of a recurring scan.Whole number from 1 to 720. Default 24.

Statuses

Agent statuses

StatusMeaningNext possible status
OnlineThe agent sent a heartbeat in the last 2 minutes.Offline, Revoked
OfflineNo heartbeat for more than 2 minutes. Commands wait until the agent checks in again.Online, Revoked
RevokedAn administrator revoked the agent. It can no longer connect.—

Command statuses

StatusMeaningNext possible status
PendingQueued, waiting for the agent to connect.Dispatched, Cancelled
DispatchedSent to the agent.In Progress, Completed, Error, Timeout
In ProgressThe agent is running the command.Completed, Error, Timeout
CompletedThe agent ran the command successfully.—
ErrorThe command failed. The error message appears under the action.—
CancelledThe command was cancelled before it finished.—
TimeoutThe command did not finish in time.—

Keyboard shortcuts

KeyAction
← / →On the tabs, move to the previous or next tab.
Home / EndOn the tabs, move to the first or last tab.
EscClose the revoke confirmation.
TabIn the revoke confirmation, move between Revoke and Cancel.