browser_inventory

How it works

browsers and profiles are two independent read-only actions, dispatched and gated separately, so a failure in one never blocks the other. Each one answers with a status|<action>|... row first (supported, or constrained plus a reason), then its data rows, so a consumer never mistakes silence for “nothing was checked”.

• browsers checks three fixed system-wide binary paths (/opt/google/chrome/chrome, /opt/microsoft/msedge/msedge, /usr/lib/chromium/chromium) and emits one row per candidate, 1 when a regular file is there and 0 when not. The version column is always -; no version or channel is probed.
• profiles walks the home directories under /home and the /root home, opens each of ~/.config/google-chrome, ~/.config/chromium and ~/.config/microsoft-edge, and reads exactly one file in each: Local State. It emits one row per entry in that file’s profile.info_cache. No profile directory is opened and no file inside one (Preferences, History, Cookies and so on) is ever read.
• It is deliberately not a browser-activity source: no row carries history, cookie, bookmark, extension or last-used information, and Firefox and Safari are not covered. Every directory is opened without following links, and every walk is bounded (4096 home entries, 1 MiB for Local State).
• Both actions need the Forensics securable at admin-or-approval level, run against a single named device only, and stay refused until an operator enables the plugin’s server-side kill switch.

flowchart LR
  OP[Operator / workflow<br/>dispatches definition] --> SRV[Server<br/>authz: Forensics.Read<br/>AdminOrApproval · single-target only<br/>kill switch must be enabled]
  SRV -- gRPC mTLS --> HOST[Agent plugin host]
  HOST --> EX[browser_inventory.execute]
  EX --> BR[browsers leg<br/>binary presence check]
  EX --> PR[profiles leg<br/>Local State JSON read]
  BR & PR --> ROWS[rows + typed result status] --> RS[(ResponseStore)] --> API[REST /api/responses]

Privacy contract. No row on any action or OS ever carries a browsing-account identifier, browsing history, cookies or bookmarks: no gaia_id, no e-mail address, no Chromium user_name or gaia_name. The first three are structural: the row model in browser_inventory_parsers.hpp (BrowserProfileRow) has no field for them. E-mail addresses are removed by value: profile_dir (a signed-in Edge profile is often keyed by its account e-mail) and display_name are replaced whole with [redacted-email] when they contain an e-mail-shaped substring (looks_like_email_address), including decorated or multiple addresses. That filter is a coarse shape check that over-matches on purpose; an address in an unusual shape such as user@localhost is not caught, and it is not a general personal-data detector.

Two exceptions are accepted and stated plainly. First, each profiles row starts with the local OS account name whose home holds the profile; it tells apart several users of one machine and is added by the Linux row builder, never by the parser. Second, a display_name that contains no e-mail-shaped text is emitted as-is, and Chromium-family browsers often fill it with the signed-in person’s real name, so it can be a personal name.

Why Forensics, not Inventory. The rows describe per-user browser profile state for one named machine, the kind of evidence that could be used to profile a specific person’s activity. The plugin therefore shares the Forensics:Read and admin-or-approval boundary of execution_artifacts and app_usage; the rationale is recorded in plugin_action_catalogue_browser_inventory.hpp.

What you can decide with it

A constrained status with a permission_denied reason means at least one home or browser directory could not be entered, so the list may be incomplete; rows that were readable are still returned. A clean OK with zero profiles rows means every home the walk reached had no readable Local State with profiles, which is not proof that no browser data exists in a place the walk does not look.

Diagrams

Profile discovery

flowchart TD
  H["Enumerate homes: /home entries (cap 4096) and /root"] --> C{"Open .config and each browser dir without following links"}
  C -- "absent" --> N["Nothing for that browser, not a failure"]
  C -- "refused or other error" --> K["Record a constraint token, skip that home"]
  C -- "opened" --> L{"Read Local State, regular file up to 1 MiB"}
  L -- "unreadable, oversized or bad JSON" --> K
  L -- "ok" --> P["One row per info_cache key"]
  P --> E["Redact e-mail-shaped profile_dir or display_name, escape fields, prefix the OS account name"]
  E --> R["profile rows"]
  K --> S["status row: constrained plus joined reason"]
  R --> T["status row: supported, when no constraint was recorded"]

The walk treats a missing directory as normal and anything else that stops a read as a recorded constraint, so a refused home produces a constrained status instead of a silently shorter list. Rows from homes that could be read are still returned alongside the constrained status.

What is emitted and what is never read

flowchart LR
  subgraph READ["Read from disk"]
    A["Binary path presence, three fixed paths"]
    B["Local State: profile.info_cache keys, name, last_used flag"]
  end
  subgraph EMIT["Emitted in a row"]
    D["Browser id, present 1 or 0"]
    F["OS account name, profile directory name, display name"]
  end
  subgraph NEVER["Never opened or emitted"]
    G["Preferences, History, Cookies, bookmarks, extensions"]
    I["gaia_id, user_name, gaia_name, e-mail addresses"]
  end
  A --> D
  B --> F

Only the profile registry in Local State is read, and only its directory keys and display names are carried into rows. Account identifiers and everything inside a profile directory stay out of the plugin’s reach.

OS capability

Declared limits per leg (descriptor fallback text, verbatim):

• browsers / Windows — follows as its own PR
• browsers / macOS — follows as its own PR
• browsers / Linux — presence-only; no version/channel detection in this package
• profiles / Windows — follows as its own PR
• profiles / macOS — follows as its own PR

Privileges and prerequisites

No external binaries, no subprocesses and no network access: every call is an in-process filesystem read and JSON parse. The plugin performs no authorization of its own; Forensics:Read, admin-or-approval and single-target enforcement happen at the server dispatch layer, and every dispatch is additionally refused while the server-side plugin-config kill switch (PluginConfigStore::seed_kill_switch_default_off) is off.

Data contract

Inputs

Neither action takes parameters.

Outputs

Pipe-delimited rows. Every action’s stream leads with a status|<action>|<supported|constrained|unsupported>|<reason> row (CC-07 typed-status pairing; unsupported is the macOS and Windows placeholder, <os>:planned), followed by zero or more data rows discriminated by their own leading tag (browser|..., profile|...); every untrusted string field (usernames, profile directory and display names) is escaped through safe_output_field. A directory or file that cannot be opened or read anywhere in the walk (ConstraintAccumulator) sets the action’s status row to constrained with the accumulated reason — a genuinely absent browser install or user directory is never treated as a failure, only as fewer rows.

crossplatform.browser_inventory.browsers — row_kind|field_1|field_2|field_3

crossplatform.browser_inventory.profiles — row_kind|field_1|field_2|field_3|field_4

Result status

Where the data goes

• Instruction result only. Rows travel over the agent’s mTLS gRPC channel as the command response, land in the ResponseStore, and are queryable at /api/responses/{id} — single-target only; fleet or scope targeting is refused at the server dispatch layer before this plugin ever runs. Rows written by this plugin are served only to callers holding Forensics:Read on the stored-response read paths (REST legacy and v1, MCP, the dashboard including the executions drawer and the hardware result poll) and in the server’s own consumers of them (bundle collation, result-set membership, policy checks, the live output stream); other readers see them as absent, so an empty result does not imply that no data exists. A read that serves them is audited as response.forensics.read, in addition to the ordinary read row where the surface writes one (the dashboard results fragment writes only the forensics row; bundle collation writes this row too, with surface=bundle, next to its own bundle.collate row). Only the plugin name is stored with a row, so the filter works per plugin, not per action. A command’s failure text is reduced to a short machine token in the server’s derived copies of it (execution record, event outbox and stream, failure notification, analytics event, webhook and offload payload); the stored response row keeps the plugin’s own message and is served through the tier. The tier is decided by the plugin the server recorded when it dispatched the command, not by the command id the agent echoes back; a response with no server dispatch record is stored ~unverified and is served under the same tier.
• Not consumed by daily-sync inventory, the Echo warehouse, DEX, or metrics. Nothing here runs on a schedule; each action dispatches only when an operator or workflow explicitly requests it, and only once the plugin-config kill switch is enabled.
• Sensitivity. profiles rows name a real local OS username and a browser-supplied display_name that MAY be the signed-in account’s real name (see the two accepted exceptions in the privacy contract above) for a single named machine — they let a reader reconstruct which browsers and profiles a specific person on that machine uses, and potentially who that person is, which is exactly the kind of per-user fingerprint an unauthorized reader could misuse. No gaia_id, e-mail address, browsing history or cookie is ever included.
• Siblings: execution_artifacts and app_usage are the other Forensics-gated, default-off evidence sources in the catalogue; none share a store or a format with this plugin.
• MCP / REST. Discover: discover_plugins (summary) → yuzu://plugin-docs (this page as data) → discover_instructions / get_definition("crossplatform.browser_inventory.profiles"). Run: execute_instruction {definition_id, parameters} (single explicit agent_id required). Read: /api/responses/{id}.

Sample output

Linux — captured: linux Debian GNU/Linux 13 (trixie) aarch64 · container · 2026-09-22 · euid 0 · leg-hash 66c026fa18f1

== action=browsers
status|browsers|supported|-
browser|chrome|0|-
browser|edge|0|-
browser|chromium|0|-
[result_status] OK / FULL

== action=profiles
status|profiles|supported|-
[result_status] OK / FULL

Caveats and known gaps

1. Linux only, Chromium-family only. On macOS and Windows every action returns the fixed status|<action>|unsupported|<os_tag>:planned row and UNAVAILABLE; those legs, Safari, Firefox and a per-profile extensions action are planned and not implemented. An operator cannot use this plugin to inventory browsers on those systems.
2. An unprivileged agent sees little. profiles opens each home under /home plus /root, and a denied open is reported as a constraint rather than skipped, so on a host where the service account cannot enter other users’ homes (the common default) the status is CONSTRAINED with permission_denied and rows appear only for readable homes. Treat CONSTRAINED as the normal outcome there and read the rows that are present, not the status alone.
3. Fixed paths, presence only. browsers probes three exact binary paths and profiles three exact config directories, so browsers installed through Snap or Flatpak, in a user-local directory or under another name read as 0 or as no profiles. The Local State profile list is a registry, not evidence of use: a listed profile may no longer have a directory, and no timestamps are read.
4. Off until an operator turns it on. Neither action dispatches until PUT /api/v1/plugin-config/browser_inventory/kill-switch {"enabled":true}; on a fresh install the server refuses the dispatch before the plugin runs, which is not reported as a plugin failure.

Source and tests

• Plugin: agents/plugins/browser_inventory/src/browser_inventory_legs.hpp · agents/plugins/browser_inventory/src/browser_inventory_linux.cpp · agents/plugins/browser_inventory/src/browser_inventory_linux_parsers.hpp · agents/plugins/browser_inventory/src/browser_inventory_macos.cpp · agents/plugins/browser_inventory/src/browser_inventory_parsers.hpp · agents/plugins/browser_inventory/src/browser_inventory_plugin.cpp · agents/plugins/browser_inventory/src/browser_inventory_win.cpp
• Definitions: content/definitions/browser_inventory.yaml
• Capability rows: server/core/src/capability_decls/plugin_action_catalogue_browser_inventory.hpp
• Tests: tests/unit/test_browser_inventory_linux_parsers.cpp · tests/unit/test_browser_inventory_local_dispatcher.cpp · tests/unit/test_browser_inventory_parsers.cpp
• Privilege row: docs/agent-privilege-model.md