Skip to content

Agent discovery reporting (opt-in)

Editions: OSS, Cloud, Enterprise

preloop agents discover scans the local machine for known agent tools (Claude Code, Cursor, Codex CLI and the rest). By default the scan stays on the machine: it only reads GET /api/v1/agents to mark which agents are already enrolled. Discovery reporting is the opt-in way to tell Preloop which agent tools exist on workstations that were never onboarded, so they show up in the console under Agents > Not yet governed.

For the per-OS distinction between installed, configured, observed active and governed, read the coverage guide. Its collector data and retention inventory includes DPIA inputs and the limits of report-only credentials. Reported devices appear on Device fleet, which can alert when an enrolled agent goes quiet or an expected control is no longer seen.

Turning it on

Either pass the flag or set the environment variable:

preloop agents discover --report --json --no-onboard-prompt
PRELOOP_DISCOVERY_REPORT=1 preloop agents discover --json --no-onboard-prompt

Without one of them nothing about the scan leaves the machine. With --json the report confirmation goes to stderr so stdout stays valid JSON.

Device-scoped token for scheduled runs

Reporting needs the report_discovery permission. Owner and admin roles have it, as does any role that holds the control-plane bundle. For an MDM job that runs on every workstation, create an API key whose only scope is report_discovery:

curl -X POST https://preloop.example.com/api/v1/auth/api-keys \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "workstation discovery", "scopes": ["report_discovery"]}'

Such a key can call GET /api/v1/agents/discovery-salt and POST /api/v1/agents/discovery-reports and nothing else: every other REST route and every console WebSocket refuses it with 403 api_key_scope_denied. Run the job with PRELOOP_TOKEN=<key> and PRELOOP_DISCOVERY_REPORT=1.

Here, the scope limits API access; it does not itself bind the key to one workstation fingerprint. Provision a distinct credential per device and check any additional device restrictions supplied by your deployment. See the stolen collector key threat.

What is sent

Field Content
workstation_fingerprint HMAC-SHA256 of the OS machine id or explicit --device-ref, keyed with a per-account salt the server issues. The raw identifier is not sent. Different account salts produce different references; these remain pseudonymous, not anonymous.
cli_version The CLI version.
os OS family only: darwin, linux, windows or other.
candidates[].agent_kind The product kind, for example cursor or claude_code.
candidates[].config_path_hash For current-user discovery, HMAC-SHA256, same salt, of the config path with the home directory replaced by ~. All-user reports use a separate keyed profile/app context hash, described below.
candidates[].mcp_server_count How many MCP servers the config defines. A count, not names.
candidates[].enrolled Whether the CLI already saw an enrollment for it.

The API also accepts optional candidates[].agent_version; the current CLI report builder does not populate it. Optional evidence fields and the exact hash inputs are documented in the collector field inventory.

The machine id is /etc/machine-id on Linux, IOPlatformUUID on macOS and MachineGuid on Windows. When none is available current-user reporting generates a random id once and keeps it in the CLI config directory. All-user reporting reuses an existing fallback or requires --device-ref; it does not create an identity file.

What is never sent

The shipped report serializers omit user names, hostnames, home or config paths in clear, prompts, API keys or other credentials, environment variables, MCP server names, URLs, commands or arguments. The server rejects unknown fields and constrains hashes, enums, counts and agent-kind/version strings. This validates shape, not the truth or sensitivity of an arbitrary client's schema-valid values. The narrow report body does not establish what HTTP access logs, session records or downstream webhook recipients retain. See the DPIA boundaries.

What the server keeps

One discovered_agent_candidate row per (account, workstation fingerprint, agent kind, config path hash), with first_seen_at, last_seen_at and a status: new, onboarded or ignored.

  • A new row fires the agent.discovered webhook once. A re-report of the same tool only moves last_seen_at and emits nothing.
  • For current-user discovery, every enrollment write for an agent from the same workstation (applied, validated or failing validation, for any agent kind including MCP-only and IDE-config agents) carries the same two hashes, and the matching candidate becomes onboarded, linked to the managed agent. A restore carries no link. When no report was ever sent for that install, the enrollment records an onboarded candidate itself (the two hashes plus the OS family and CLI version, nothing else), so onboarding alone places the agent on its device in the device fleet. Re-onboarding updates the same row.
  • Agents enrolled by an older CLI have no such link. The fleet map and the agent page then place the agent on a device by evidence already held, never rewriting it: first a runner-reported harness of the agent's kind on a device its owner uses, when exactly one managed agent fits; otherwise the agent's enrollment hostname, when exactly one device has that hostname (compared case-insensitively, ignoring .local or a domain, with -, _ and spaces alike) and the agent's owner, when known, uses that device. Ambiguous matches stay unplaced.
  • Mark ignored in the console hides a candidate. Copy onboard command copies preloop agents onboard <kind> to run on that workstation.
  • Candidates nobody has reported for 90 days are deleted by a daily purge, except onboarded candidates still linked to a managed agent: those are the agent's device link. Deleting the agent clears the link and makes a stale candidate eligible for a later purge. The retention table distinguishes expiry from actual deletion and other data stores.

API

Method and path Permission
GET /api/v1/agents/discovery-salt report_discovery
POST /api/v1/agents/discovery-reports report_discovery
GET /api/v1/agents/discovery-candidates?status=new view_agents
PATCH /api/v1/agents/discovery-candidates/{id} ({"status": "ignored"}) manage_agents

GET /api/v1/agents/discovery-candidates returns {items, total, truncated}. items is the newest 500 matching rows. total counts every match, and truncated is true when the fleet is larger than that page, so the console can say it is showing the first 500.

Harness inventory from runners

Separately from this opt-in report, a connected runner publishes the harnesses installed on its host with its registration and heartbeat. It is stored on the runner (harness_inventory) and shown on the Runners page. Every entry has these fields:

Field Content
harness copilot_cli, cursor_cli, claude_code, codex_cli, opencode, gemini_cli, claude_desktop or vscode_copilot.
display_name Product name.
version Harness version, when the runner could read it. Visible to the runner owner and account admins only.
login_state signed_in, signed_out, unknown or not_applicable. Never a token or user name.
login_source env (a token variable is set; only its name was checked), stored, cli_status, none or unknown.
account_host Host of the account (for example github.com), GitHub harnesses only. Visible to the runner owner and account admins only.
governance governed (Preloop hooks and approval hook), partial (usage hooks or MCP only), ungoverned or unknown.
support_level flows_and_sessions, flows_only or presence_only.
enabled False when the host turned the harness off in runner.json. Disabled harnesses are still listed.
sessions_enabled Set on the host only.
session_mode resume, stream, replay or none.
billing seat (subscription, not metered by the gateway), metered or unknown.
models[] Up to 64 {id, source} pairs; source is probed, configured, static or observed.
generated_profile Name of the host execution profile the runner generated (copilot, cursor), or null when a hand-written profile wins.
capabilities Host execution capability flags.

The inventory carries at most 32 entries and a sha256: hash of its entries. Executable paths, arguments, environment values and user names never leave the host. Each change is audited as runner.harness_inventory_changed.

Versioned source observations

The existing report accepts an optional evidence envelope with schema_version: 1 or 2. An installed evidence service consumes it within the same report transaction; without that service the extension returns 503, while legacy reports continue unchanged. No second collector endpoint is introduced.

Observations preserve enumerated scan scope/errors, timezone-aware collection windows, completeness, safe app/version facts and independent control assertions. Exact replay is idempotent per authenticated source and workstation; changed replay conflicts. Sources and collection windows remain separate, including empty scans. Retention is 90 days from receipt; the always-on discovery sweeper purges expired observations even if the evidence plugin is disabled or the source stops reporting. None of these records prove device identity, app runtime enforcement or use. Collector assertions cannot carry effective or successful runtime-verification fields.

All-user profile reports

Use preloop agents discover --all-users --report from an elevated process (root on Linux/macOS, administrator on Windows). --all-users requires an explicit --report or --inventory; the environment variable alone does not select all-user reporting. The elevated process needs the reporting token or login. For an offline scan, use --all-users --inventory; this makes no network calls and prints a preloop.inventory.v2 envelope. Both modes print safe inventory JSON and do not onboard agents.

The scan enumerates local profiles from /Users on macOS, /home and /root on Linux, or Windows ProfileList. It covers the known application registry, not every possible install location or network/directory-service profile. It scans at most 64 profiles, reads at most 4 MiB per configuration file, and reports at most 100 application contexts. Symlinks, hard-linked configurations, special files and unsafe configuration paths are refused. Configuration files are opened relative to the selected profile with link checks at open time; the collector never executes a discovered application or reads its credential store. Reaching a limit or failing to read a profile leaves the coverage incomplete rather than treating that scope as an empty successful scan.

All-user reports send evidence.schema_version: 2 on the existing report endpoint. Version 1 reports remain supported. Version 2 adds:

Field Content
evidence.profiles[].profile_ref A keyed reference scoped to the account and workstation. It identifies profile scope without sending a profile name or home path.
evidence.profiles[].completeness complete, partial or failed, including profiles that yielded no application rows.
evidence.profiles[].error_code Absent for complete scope; otherwise profile_unavailable, profile_unreadable or probe_incomplete.
evidence.applications[].profile_ref The reference of the profile in which this app context was observed; omitted for machine-level managed configuration.
evidence.applications[].config_scope user_config (default) or managed_config.
evidence.applications[].controls[] Allowlisted axis, adapter support, configured state, and configuration source. No execution or verification claim.

All-user reporting also inspects the standard Claude Code system managed-settings.json on Linux, macOS and Windows. It reports the presence or absence of the exported Preloop PreToolUse hook as a separate machine-level application context with a salted config-path hash and managed_config scope. The absence of the file or hook is configuration evidence only. Unreadable or malformed files mark managed configuration incomplete and the control unknown. evidence.scope_completeness keeps the original user-config scan status separate from the managed-config status. The overall report retains its most severe state and accumulated error codes. This does not inspect higher managed sources or establish the effective policy in the app. Commands, file contents, environment values and credentials are never sent. Offline profile inventory remains limited to profile configuration.

Offline v2 output also associates probe results with profile_ref. Its fresh per-run random salt makes profile references unrelated across offline runs. Reported references use the account salt and workstation context instead.

If no profiles can be enumerated, the inventory has completeness: failed and scope.error_code: profiles_unavailable. An unreadable Windows ProfileList entry produces its own hashed failed profile, and collection continues for other profiles. Unsafe registry paths (including network paths, alternate data streams and traversal) also produce a failed profile without being opened. If enumeration returns readable profiles alongside an error, those profiles are scanned and the inventory is partial with profiles_unavailable. On Linux, /root is still scanned when /home cannot be enumerated. A profile limit produces partial inventory with scope.error_code: profile_limit. The report retains enumerated profile states even when no apps were readable; its evidence records partial or failed completeness and an unavailable error. A report truncated at 100 apps is also partial. Incomplete scope never proves absence of agents.

All-user candidates represent aggregate profile/app contexts. Their config_path_hash uses the preloop-profile-app:v2: namespace, while current-user enrollment uses preloop-config-path:v1:. Consequently these candidates do not automatically become onboarded when a current-user agent is later enrolled, and their emitted enrolled: false means enrollment was not observed. Automatic linking requires a future profile-aware enrollment contract. App presence and configuration observations do not prove runtime enforcement or use.

Administrative device identifiers

For a fleet roster with an explicit administrative identifier, use preloop agents discover --report --device-ref synthetic-device. This replaces OS machine-id discovery for the report fingerprint. The identifier is stripped of surrounding whitespace, then hashed with the same account salt and preloop-workstation:v1: namespace; the raw value is never sent. It does not turn reporting on without --report or the existing opt-in environment flag. Matching hashes correlate administrative identifiers and do not attest a device, its executable identity or effective governance. Candidate-only reports establish receipt history, not collection completeness or trusted control verification.

--all-users --report --device-ref synthetic-device uses this same identifier for both the workstation fingerprint and its profile references. All-user reporting never creates a fallback identity file: if the OS identifier is unavailable, it reuses an existing CLI workstation id or fails with a request to supply --device-ref. Offline inventory does not look up machine identity. macOS identity lookup uses the fixed system ioreg path, and Windows reads MachineGuid directly from the registry, so inherited PATH cannot select a program to execute with collector privileges.

Deployment and coverage

See the MDM recipes for staged delivery and separate credential provisioning, the threat model for bypass risks, and planned work for features that must not be treated as shipped coverage.

Extensions

V3 reports distinguish extension collection coverage from runtime probes through extension_completeness. Unverified runtime usage does not make an otherwise complete extension inventory partial. Unreadable profiles, bounded scans and failed extension probes still report incomplete coverage.

preloop agents discover --inventory emits preloop.inventory.v3, including installed extensions for Claude Code and Codex CLI. --report sends the same metadata on each candidate, bound to the matching app's hashed config context. Servers continue accepting v1 and v2. A v3 CLI retries once with extensions removed when an older server specifically rejects evidence schema version 3.

Extension identifiers (plugin, skill, command and hook event names, versions, and marketplace names) are sent in clear. Marketplace and git URLs, hook commands, file contents and paths are not. Local/git identifiers containing a profile login or home path segment, and project identifiers with that personal information, become hash:<16 hex characters> with id_hashed: true. Marketplace plugin identifiers remain unchanged. Source locations are represented only by SHA-256 hashes; project references use the config-path hashing scheme (keyed with the account salt when reporting).

Agent Kind Known locations below the profile home Collected metadata
Claude Code Plugin .claude/plugins/store/*.json, .claude/plugins/known_marketplaces.json, .claude/plugins/marketplaces/<marketplace>/plugins/<name>/.claude-plugin/plugin.json Name and marketplace, manifest version (falling back to record version), source hash, enabled state
Claude Code Skill .claude/skills/<name>/SKILL.md Directory name and file SHA-256
Claude Code Hook hooks in .claude/settings.json; JSON event mappings in .claude/hooks/ Event, command count, one aggregate hash
Claude Code Command .claude/commands/*.md File stem and file SHA-256
Codex CLI Plugin .codex/plugins/<marketplace>/<name>/plugin.json Name, marketplace, version when present
Codex CLI Skill .codex/skills/<name>/ Directory name and SKILL.md SHA-256 when present
Codex CLI Hook .codex/hooks.json, [hooks] in .codex/config.toml Event, command count, one aggregate hash

For the current user, project roots already listed in .claude.json are also scanned for .claude/skills/, .claude/commands/, .claude/hooks/, and .claude/settings.json. Unknown projects are not searched. A project's explicit plugin setting overrides the user's setting in a project-scope record; absence of a setting means unknown. All-users inventory scans profile-local locations only. Plugin-bundled skills, hooks and commands are represented by the plugin, not duplicated as standalone extensions.

{
  "kind": "plugin",
  "id": "reviewer@claude-plugins-official",
  "version": "1.4.0",
  "source_kind": "official_marketplace",
  "source_ref_hash": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "scope": "user",
  "enabled": "true",
  "id_hashed": false
}

Optional fields are project_ref_hash, content_hash, event and count (the last two occur only on hooks). enabled is the string true, false or unknown. Sources are official_marketplace, third_party_marketplace, git, local, builtin or unknown. Only Claude's claude-plugins-official and Codex's openai-curated-remote are classified as official marketplaces.

A skill hash covers SKILL.md; a command hash covers the command file. A plugin hash, when available, covers canonical JSON of its manifest, not its entire installation. For hooks the collector hashes each command locally, sorts the sha256:<hex> values, joins them with newlines (no trailing newline), then hashes that string. Neither commands nor intermediate hashes leave the device. These hashes are inventory metadata; approval is by name and does not pin content.

At most 200 extensions are emitted per app context, with a 4 MiB per-file cap, 64 profiles and 100 app contexts. Directory enumeration is bounded to 256 entries. Symlinks are refused, discovered agents are never executed, and --inventory remains offline without writes. Exceeding a bound, unreadable/malformed metadata, or a standalone hook script with no declared event makes the scan partial and emits a fixed error code. Unbound scripts are not assigned invented events.

The server reconciles each device/profile/agent only after a complete scan of its extension locations. Missing extensions become present=false and leave the default lists; partial scans preserve previously observed rows. Historical v1/v2 reports do not reconcile extensions. Discovery retention removes inventory with its source observation after 90 days; account approval decisions survive.

GET /api/v1/agents/discovery-extensions lists present inventory, with filters fingerprint, agent_kind, state, and source_kind. group=extension returns account aggregates with distinct device counts, versions and source kinds. GET /api/v1/agents/extension-approvals lists durable decisions. Both use limit (default 50, maximum 500) and an opaque cursor, returning next_cursor until all results have been read. Approval is unknown when no decision exists.

GET /api/v1/agents/extension-approvals/{agent_kind}/{extension_kind}/{extension_id} reads one decision with view_agents permission, or returns 404 when no decision exists. The console uses this lookup to preserve notes and version constraints without scanning the account's approval list.

PUT /api/v1/agents/extension-approvals/{agent_kind}/{extension_kind}/{extension_id} requires manage_agents and accepts approval_state (approved, unapproved, unknown), optional note, and optional version_constraint. A constraint is an exact version or a prefix ending in .*; null means any version. The list shows the stored name decision, not a claim that a particular version complies. Approvals apply account-wide, not per device. Inventory and approvals do not block an extension from loading or running.

In the console, the Agents page's Extensions tab lists distinct extensions with device counts and versions seen. Device detail shows per-profile inventory, source/project hash prefixes, scope and enabled state. Both views filter by approval state and source. Users with manage_agents can change an approval; other viewers see the decision without an editor. The table warns when collection is partial or unknown, and Load more follows the server's cursor.