pkg_inventory

How it works

pkg_inventory reports which third-party package managers a machine has and what they installed, by reading their directories on disk. No package-manager command is ever run (no brew, dpkg, rpm, pacman, apk, snap, flatpak or winget), so it cannot change anything and cannot be fooled by a broken tool. Every action writes a status row first and then data rows.

• managers says which managers are present. On macOS it looks at the two Homebrew prefixes (/opt/homebrew on Apple silicon, /usr/local on Intel) and counts taps, formulae and casks from directory names. On Linux it checks for eight tools (dpkg, apt, rpm, dnf, pacman, apk, snap, flatpak) under /usr/bin, /usr/sbin, /bin and /sbin, and adds the counts it can read without running anything: apt source files, snap files, flatpak apps and runtimes.
• packages lists Homebrew formulae and casks on macOS, one row per version directory in Cellar and Caskroom.
• store_packages lists snaps and flatpaks on Linux. A snap is joined from its .snap file, its /snap/<name>/current link and one bounded read of snap.yaml; a flatpak comes from the app and runtime trees, with the active link giving the commit.
• On Windows all three actions report only status|<action>|unsupported|windows:planned. Linux distro packages (dpkg, rpm and the rest) and the macOS application list are deliberately not here: installed_apps owns them.

The final component of every directory path is opened without following a link (parent directories such as /var/lib are trusted) and every walk is bounded in names, rows, bytes, entries and time, so a hostile or huge tree degrades to a clearly marked partial answer rather than hanging the agent. An absent manager or store is a complete, empty answer; a location that exists but cannot be read makes the answer constrained with a token that names it. Each walk takes an injected root (production passes /) so the unit suite runs it over a committed fixture tree.

flowchart LR
  OP["Operator or workflow"] --> SRV["Server: Inventory Read"]
  SRV -->|"gRPC mTLS"| EX["pkg_inventory.execute"]
  EX --> WIN["Windows: status row only, windows:planned"]
  EX --> MAC["macOS: Homebrew Taps, Cellar, Caskroom directory names"]
  EX --> LIN["Linux: tool presence, snap and flatpak stores"]
  WIN --> ROWS["status row, then data rows"]
  MAC --> ROWS
  LIN --> ROWS
  ROWS --> RS[("ResponseStore")] --> API["REST /api/responses"]
  ROWS -.->|"all three actions, 24 h"| SYNC["installed-software daily sync"]

What you can decide with it

A clean answer proves the listed locations were read as asked; it does not prove nothing else is installed. Software installed outside these directories (a Homebrew in a custom prefix, per-user installs, tarballs, language-level packages such as pip or npm) is invisible. Manager versions are never reported (they are always -), because reading one would mean running the tool, and flatpak versions are - because a branch is a ref, not a version. For “what is installed on this Linux host overall” use installed_apps; use this plugin for the snap and flatpak stores and for knowing which managers exist.

Diagrams

Inside one bounded walk

flowchart TD
  S["Action dispatched"] --> B{"Another walk of this action still running?"}
  B -->|"yes"| BUSY["constrained: busy, no rows, retry later"]
  B -->|"no"| O["Open each directory without following links"]
  O --> R{"Location readable?"}
  R -->|"absent"| E["zero rows, still supported"]
  R -->|"refused, symlink, error"| T["constrained token: permission_denied, not_a_directory, io_error"]
  R -->|"yes"| W["Read names, bounded by entry, row, byte and time caps"]
  W --> C{"A cap hit?"}
  C -->|"yes"| P["constrained token: entry_cap, row_cap, byte_cap or walk_budget; rows so far kept"]
  C -->|"no"| I["Per-item read of a snap or flatpak fails: row kept with version dash, status stays supported"]

Constrained means the list itself may be incomplete, and that is the only thing a token is used for. A single snap or flatpak whose own metadata cannot be read still appears, with - or unknown fields, and does not constrain the action; that choice keeps one odd package from stopping the whole daily inventory.

What the daily sync takes

flowchart LR
  M["managers rows"] --> M1["homebrew presence row only; other managers read, not stored"]
  P["packages rows"] --> P1["ecosystem brew: formula as pkg, cask as app"]
  X["store_packages rows"] --> X1["active rows only: snap and flatpak"]
  M1 --> G{"Answer constrained?"}
  P1 --> G
  X1 --> G
  G -->|"managers: kept if a present manager was seen"| K["rows stored"]
  G -->|"packages or store_packages: whole cycle skipped"| Q["nothing stored this cycle"]

A partial roster would delete stored rows, so a constrained packages or store_packages answer makes the sync skip the cycle instead of sending a short list.

OS capability

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

• managers / macOS — cask rows, non-zero tap counts and the Intel prefix are exercised by synthetic in-code layouts only, never a real capture
• packages / macOS — cask rows and the Intel prefix are exercised by synthetic in-code layouts only, never a real capture
• packages / Linux — installed_apps.list_inventory owns the Linux package roster
• store_packages / macOS — installed_apps owns the macOS application list

The capability-matrix rows for this plugin in docs/os-capability-matrix.md are rendered from the plugin’s own kActionDescriptors (pkg_inventory_plugin.cpp); the Windows legs are declared planned, not supported, and a leg that is unsupported by design (Linux packages, macOS store_packages) is declared rung 0 with no mechanism.

Privileges and prerequisites

Binaries/subprocesses: none — every read is an in-process filesystem read. Network: none.

Data contract

Inputs

No action takes parameters.

Outputs

Pipe-delimited rows written via write_output(), two shapes per stream discriminated by field 0: exactly one status|<action>|<supported\|constrained\|unsupported>|<failure tokens or -> row first, then zero or more data rows — manager|<name>|<present\|unavailable>|<version or ->|<root_path or ->|<facts k=v;... or ->|<reason or -> for managers, package|homebrew|<id>|<version>|<formula\|cask> for packages, and the nine-column package|<snap\|flatpak>|<id>|<version or ->|<kind>|<revision or ->|<arch or ->|<branch or ->|<active\|inactive\|unknown> for store_packages. A genuinely absent manager, prefix or store is supported with zero data rows; an unreadable location is constrained with a token, never an empty success. root_path is the logical path (/opt/homebrew, /usr/local, /etc/apt, /var/lib/snapd, /var/lib/flatpak), never an injected test root; a manager row’s version is always - in this release (no brew --version or dpkg --version is run), while a Homebrew package row’s version is the real version directory name. A snap row carries the snap.yaml version (or -), the type as a closed kind token (app, gadget, kernel, base, snapd, os; other for anything else, unknown when snap.yaml could not be read) and the revision; a flatpak row carries the ref id, kind app or runtime, the commit as its revision, the architecture and the branch, and always a - version (the branch is a ref, not a version, and metadata is not read). Linux never reports a manager as unavailable: presence is the binary, and a fact whose source could not be read is omitted with its token. A formula or cask present under both Homebrew prefixes yields one package| row per prefix; the package row carries no prefix column — the manager rows say which prefixes exist. Every OS-supplied field goes through the shared escaper yuzu::util::safe_output_field; directory names that are dot-prefixed, over 255 bytes, or contain a pipe, backslash, control or non-ASCII character are skipped without a token (Homebrew and flatpak never create them), so they never reach a row. This plugin is not in the server’s kKeyValuePlugins set, so the server does not decode its rows as two-cell key|rest; the columns below are the definition’s own.

crossplatform.software.package_manager_packages — row_kind|manager|id|version|kind

crossplatform.software.package_managers — row_kind|name|state|version|root_path|facts|reason

crossplatform.software.store_packages — row_kind|manager|id|version|kind|revision|arch|branch|state

Result status

Where the data goes

• Instruction result AND daily-sync inventory. Rows travel over the agent’s mTLS gRPC channel as the command response and land in the ResponseStore, queryable at /api/responses/{id}. The three actions are gathered definitions (crossplatform.software.package_managers, crossplatform.software.package_manager_packages and crossplatform.software.store_packages, 300s TTL).
• Also consumed by the installed_software daily-sync source (agents/core/src/sync_source_installed_software.cpp), which calls all three actions in-process on the agent’s 24 h schedule: packages rows become pkg (formula) / app (cask) rows with ecosystem brew; managers becomes one homebrew presence row (every other manager name, including the Linux ones, is read but not mapped); store_packages maps ACTIVE rows only, to ecosystem snap (kind app when the snap type is app, else pkg; version from snap.yaml; release = the revision) and ecosystem flatpak (kind app for apps, pkg for runtimes; version EMPTY because the branch is a ref and not a version; release = the commit; arch). An inactive or unknown revision is on the wire but is not installed software and never reaches the catalogue. A constrained managers answer keeps the cycle iff at least one PRESENT manager row was seen, mapped or not; a constrained packages or store_packages answer skips the cycle. Not consumed by Echo, DEX, or metrics.
• Sensitivity. Rows name installed software (Homebrew formula and cask names and versions, snap and flatpak ids, versions, revisions and commits) and the package managers and Homebrew prefixes present on the host with their counts — a software inventory by another route. No row carries a username, account name or user-profile path.
• Siblings: installed_apps (owns the Linux distro-package roster and the macOS application list, and its list_per_user also lists Homebrew formulae per user — see caveat 4 for both overlaps) and software_actions (installs and removes software; this plugin only reads).

Sample output

macOS — captured: macos macOS 26.6.2 arm64 · bare-metal · 2026-10-14 · euid 501 · leg-hash 5e3ad4e08431

== action=managers
status|managers|supported|-
manager|homebrew|present|-|/opt/homebrew|taps=0;formulae=69;casks=0|-
[result_status] OK / FULL

== action=packages
status|packages|supported|-
package|homebrew|actionlint|1.7.12|formula
package|homebrew|ada-url|4.0.0|formula
package|homebrew|autoconf|2.73|formula
package|homebrew|automake|1.18.1_1|formula
package|homebrew|bash|5.3.15|formula
package|homebrew|blake3|1.8.7|formula
package|homebrew|brotli|1.2.0|formula
package|homebrew|c-ares|1.34.8|formula
package|homebrew|ca-certificates|2026-08-13|formula
package|homebrew|ccache|4.13.6_1|formula
package|homebrew|cmake|4.4.2|formula
… 12 of 71 rows shown
[result_status] OK / FULL

== action=store_packages
status|store_packages|unsupported|macos:owned_by_installed_apps
[result_status] UNAVAILABLE / PARTIAL / macos:owned_by_installed_apps

Linux — captured: linux Debian GNU/Linux 13 (trixie) aarch64 · container · 2026-10-14 · euid 0 · leg-hash 5e3ad4e08431

== action=managers
status|managers|supported|-
manager|dpkg|present|-|-|-|-
manager|apt|present|-|/etc/apt|sources_d_files=1|-
[result_status] OK / FULL

== action=packages
status|packages|unsupported|linux:owned_by_installed_apps
[result_status] UNAVAILABLE / PARTIAL / linux:owned_by_installed_apps

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

Caveats and known gaps

1. Machine scope, default prefixes, point in time. Per-user package stores (per-user Homebrew, pip user installs, npm and cargo) are out of scope and deferred to the user-session helper (ADR-3003). Only the two default Homebrew prefixes are probed, so a Homebrew in a custom or symlinked prefix reads as absent or refused rather than installed, and an entry removed during a walk is skipped rather than reported.
2. A stalled mount can pin a worker, and the sync waits behind it. The walk deadline is cooperative: it cannot interrupt a filesystem call blocked on a dead mount, so that dispatch holds one agent worker and later dispatches of the action report busy; on Linux it also holds the sequential daily-sync source loop, so every later sync source waits. A persistent SELinux or AppArmor denial on /var/lib/snapd/snaps or /var/lib/flatpak/{app,runtime} makes store_packages constrained and skips the daily installed-software cycle until the agent’s domain is granted read access.
3. Linux reports presence and counts, and a per-item failure stays supported. Manager versions and the dpkg, rpm, dnf, pacman and apk facts are not read. A snap with an unmounted, unreadable or hostile snap.yaml is still a row with version - and kind unknown, a snap disabled snap is inactive, and .Locale and .Debug flatpak runtimes appear although flatpak list hides them; only the system flatpak installation and the default snap roots are read, and the Linux sample comes from a container with neither store, so real rows are proven by a WSL2 capture tree only.
4. Homebrew rows overlap installed_apps on macOS, and cask and tap rows are unexercised against real data. Casks install .app bundles that installed_apps also reports, and its list_per_user also lists Homebrew formulae per user, so this is a machine-scope, no-subprocess view of the same store and not a disjoint one. The real-capture host had a populated Cellar only, so tap, cask and Intel-prefix paths are covered by synthetic layouts built from Homebrew’s own scripts, not by a real capture.
5. Windows legs planned. All three Windows actions report status|<action>|unsupported|windows:planned and no data rows. The Chocolatey lib\ walk with .nuspec metadata, winget presence and the Appx store roster are not built.

Source and tests

• Plugin: agents/plugins/pkg_inventory/src/pkg_inventory_legs.hpp · agents/plugins/pkg_inventory/src/pkg_inventory_linux.cpp · agents/plugins/pkg_inventory/src/pkg_inventory_linux_parsers.hpp · agents/plugins/pkg_inventory/src/pkg_inventory_macos.cpp · agents/plugins/pkg_inventory/src/pkg_inventory_macos_parsers.hpp · agents/plugins/pkg_inventory/src/pkg_inventory_parsers.hpp · agents/plugins/pkg_inventory/src/pkg_inventory_plugin.cpp · agents/plugins/pkg_inventory/src/pkg_inventory_win.cpp
• Definitions: content/definitions/pkg_inventory.yaml
• Capability rows: server/core/src/capability_decls/plugin_action_catalogue_pkg_inventory.hpp
• Tests: tests/unit/test_pkg_inventory_linux_parsers.cpp · tests/unit/test_pkg_inventory_local_dispatcher.cpp · tests/unit/test_pkg_inventory_macos_parsers.cpp · tests/unit/test_pkg_inventory_parsers.cpp
• Privilege row: docs/agent-privilege-model.md