users

How it works

All seven actions are reads: nothing in this plugin creates, changes or deletes an account, session or group. logged_on and sessions answer “who is on this host right now” from the OS session table (Windows Terminal Services sessions, Linux utmp, macOS who and w). local_users, local_admins and group_members list accounts and group membership from the OS’s own directory (the Windows NetAPI, /etc/passwd and getgrnam on Linux, dscl on macOS); group_members takes a group name, local_admins is a fixed lookup of the admin group. primary_user and session_history mine recent login history: the Security event log on Windows, last on Linux and macOS. primary_user reduces that window to the one account with the most login records; session_history returns the records themselves, newest first, up to count. On Linux and macOS every external tool (w, last, lastlog, who, dscl) runs through a bounded argv runner with no shell and a 10 second deadline, and a tool that cannot be started, times out or is killed is reported through the result status instead of reading as an empty list. Windows runs no subprocess. The plugin is deliberately not an authorisation view: it reports what the OS records, not who is entitled to what.

flowchart LR
  OP[Operator / workflow] --> SRV[Server<br/>authz: UserManagement.Read]
  SRV -- gRPC mTLS --> HOST[Agent plugin host] --> EX[users.execute]
  EX --> WIN[Windows leg<br/>WTS sessions, NetUserEnum<br/>NetLocalGroupGetMembers, Security event log]
  EX --> MAC[macOS leg<br/>who, w, last, dscl via the argv runner]
  EX --> LIN[Linux leg<br/>utmp, getgrnam, /etc/passwd<br/>w, last, lastlog via the argv runner]
  WIN & MAC & LIN --> ROWS[pipe rows + typed result status] --> RS[(ResponseStore)] --> API[REST /api/responses]

What you can decide with it

What a clean result does and does not prove. An empty logged_on or sessions is a legitimate answer (nobody is signed in) and carries no status; only the typed result status tells a degraded read from a clean empty one. A local_admins or group_members list is the direct, local view only: it does not follow nested groups, directory-service groups or sudoers rules, so it is not the set of people who can become administrator. primary_user and session_history see only the latest window of the login records, so they say nothing about a long-quiet account, and a host with the Security log cleared, or without logon auditing, returns nothing useful on Windows. Nothing here proves an account is in use: enabled reflects the account-disabled flag on Windows and the login shell on Linux and macOS, not a password lock or expiry.

Diagrams

Which action answers which question

flowchart TD
  Q{"What do you need to know?"}
  Q -- "who is on the host now" --> L["logged_on: user, host, logon type<br/>sessions: state, client, idle"]
  Q -- "which accounts exist" --> LU["local_users"]
  Q -- "who has admin rights" --> LA["local_admins"]
  Q -- "who is in group X" --> GM["group_members, parameter group"]
  Q -- "who normally uses it" --> PU["primary_user"]
  Q -- "who logged in or out lately" --> SH["session_history, parameter count"]

The first two read the live session table, the next three read the account directory, and the last two read recorded history. Only group_members and session_history take a parameter.

How a Security-log read can fail on Windows

flowchart TD
  S["Query the Security channel, newest first"] --> R{"Outcome"}
  R -- "read to the end" --> OK["Rows from the events, status stays undeclared"]
  R -- "access denied" --> D["PERMISSION_DENIED, users_win_events:access_denied"]
  R -- "channel not found" --> U1["UNAVAILABLE, users_win_events:channel_not_found"]
  R -- "no answer in 10 seconds" --> T["CONSTRAINED, users_win_events:evt_next_timeout"]
  R -- "any other error" --> U2["UNAVAILABLE, users_win_events:evt_query_failed"]
  D & U1 & T & U2 --> A{"Which action"}
  A -- "session_history" --> E["One error row naming the cause"]
  A -- "primary_user" --> F["Fall back to the ProfileList registry"]
  F -- "readable" --> G["Row with source profile_list and login_count 0, status not set"]
  F -- "unreadable" --> H["Row saying it cannot query, status from the failure above"]

session_history fails loudly: the status and the error row both name the cause. primary_user prefers an answer, so when the Security log cannot be read it names a profile from the registry instead, and that answer carries no status; tell it apart by source profile_list and a login count of 0. The fallback picks the last profile under \Users\ in registry order, which says nothing about who actually uses the host.

OS capability

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

• primary_user / Windows — falls back to a native ProfileList registry enumeration (no login count) when the Security channel is inaccessible
• session_history / Windows — requires an elevated token to read the Security channel; reports an error otherwise

Privileges and prerequisites

Subprocesses: Linux runs w, lastlog and last, located with probe_tool_path and started by direct argv with no shell. macOS runs who, w, last, dscl and /usr/bin/env (used only to pin LC_ALL=C ahead of last -y, still a plain exec). Windows runs none. A tool’s exit code is not inspected: only a failure to start, a timeout, a cancellation or a signal is a failure, so an unreadable wtmp surfaces as an empty last result (caveat 5). No network use on any OS.

Data contract

Inputs

Outputs

Rows are pipe-delimited, one per record, and start with a literal discriminator (user, session, local_user, admin, group_member, primary_user or session_history). logged_on, sessions and group_members write zero rows, not a placeholder, when there is nothing to report; only the typed result status separates a degraded read from a clean empty one. A query-level problem (missing or invalid parameter, group not found, tool not found) writes a single <discriminator>|error|<message> row (for example group_member|error|Group not found: x or admin|error|query failed; on Linux an unreadable /etc/passwd writes local_user|error|false|Never|<message>). local_users varies its field count by OS: Windows and Linux rows carry four data fields, macOS rows carry five (console_state is appended). On Linux, last_logon is the account’s lastlog line verbatim, not the formatted timestamp the table below describes (caveat 4). On Linux and macOS session_history writes last’s columns into the declared fields in a different order (caveat 1), and sessions always reports state Active on those two systems.

device.users.group_members — member_name|group_name|member_type

device.users.local_admins — member_name|member_type|domain_or_group

device.users.local_users — username|enabled|last_logon|description|console_state

device.users.logged_on — username|domain|logon_type|session_id

device.users.primary_user — username|login_count|source

device.users.session_history — username|event_type|logon_type|source|timestamp|detail

device.users.sessions — session_id|username|state|client|idle

Result status

Windows sets the status explicitly when the Security-channel query fails. On Linux and macOS every external tool call is checked, and the first non-normal termination of a call latches the status for the whole action, so a later per-account call cannot overwrite an earlier UNAVAILABLE. A tool that exits normally, with any exit code, sets nothing.

Where the data goes

• Instruction result only. Rows travel the agent’s mTLS gRPC channel as the command response and land in the ResponseStore (default 90-day retention), readable at /api/responses/{id}.
• Not consumed by daily-sync inventory, the Echo warehouse, DEX or metrics. Nothing in this plugin runs on a schedule; each definition’s gather.ttlSeconds (60 to 300 seconds) is a repeat-query cache lifetime, not a cron trigger.
• Sensitivity. Every action’s rows name specific accounts: username and member_name (local and logged-on accounts, including administrators), domain or domain_or_group (a Windows domain or host name), and Windows session_history carries the source IP address of each logon. On Linux and macOS session_history and sessions can carry the remote host or client name a user connected from, and local_users carries the account’s display name or comment. No column carries installed-software data.
• Siblings. The core.crossplatform.users instruction set (content/definitions/users_set.yaml, “User Account Management”) bundles the logged_on, sessions, local_users and local_admins definitions of this same plugin; this plugin has no action that creates, disables or reassigns an account.
• MCP / REST. Discover with discover_plugins (summary) then yuzu://plugin-docs (this page as data) and get_definition("device.users.session_history"); run with execute_instruction {definition_id, parameters}; read results at /api/responses/{id}.

Sample output

Windows — captured: windows Microsoft Windows NT 10.0.26200.0 x64 · bare-metal · 2026-09-07 · SYSTEM (account name redacted to jsmith; account SID replaced with a placeholder) · leg-hash 5734018da5be

== action=logged_on
[result_status] UNDECLARED / UNKNOWN

== action=sessions
[result_status] UNDECLARED / UNKNOWN

== action=local_users
local_user|Administrator|false|2021-10-14 11:15:58|Built-in account for administering the computer/domain
local_user|jsmith|true|2026-09-07 11:08:37|-
local_user|CodexSandboxOffline|true|Never|-
local_user|CodexSandboxOnline|true|Never|-
local_user|DefaultAccount|false|Never|A user account managed by the system.
local_user|Guest|false|Never|Built-in account for guest access to the computer/domain
local_user|WDAGUtilityAccount|false|Never|A user account managed and used by the system for Windows Defender Application Guard scenarios.
[result_status] UNDECLARED / UNKNOWN

== action=local_admins
admin|Administrator|user|DESKTOP-04DNSIG
admin|jsmith|user|DESKTOP-04DNSIG
[result_status] UNDECLARED / UNKNOWN

== action=group_members group=Administrators
group_member|Administrator|Administrators|user
group_member|jsmith|Administrators|user
[result_status] UNDECLARED / UNKNOWN

== action=primary_user
primary_user|jsmith|118|event_log_4624
[result_status] UNDECLARED / UNKNOWN

== action=session_history
session_history|jsmith|logoff|network|-|2026-09-07T10:08:37.8345208Z|4634
session_history|sshd_6888|logoff|service|-|2026-09-07T10:08:37.8345130Z|4634
session_history|jsmith|logon|network|-|2026-09-07T10:08:37.5888936Z|4624
session_history|jsmith|logoff|network|-|2026-09-07T10:08:37.5439466Z|4634
session_history|jsmith|logon|network|-|2026-09-07T10:08:37.5436517Z|4624
session_history|sshd_6888|logon|service|-|2026-09-07T10:08:37.4636668Z|4624
session_history|jsmith|logoff|network|-|2026-09-07T10:08:06.3059890Z|4634
session_history|sshd_4452|logoff|service|-|2026-09-07T10:08:06.3059802Z|4634
session_history|jsmith|logon|network|-|2026-09-07T10:08:06.0444630Z|4624
session_history|jsmith|logoff|network|-|2026-09-07T10:08:05.9047716Z|4634
session_history|jsmith|logon|network|-|2026-09-07T10:08:05.9044759Z|4624
session_history|sshd_4452|logon|service|-|2026-09-07T10:08:05.8249284Z|4624
… 12 of 50 rows shown
[result_status] UNDECLARED / UNKNOWN

macOS — captured: macos macOS 26.6.2 arm64 · bare-metal · 2026-09-07 · euid 501 (jsmith) · leg-hash 5734018da5be

== action=logged_on
user|jsmith|local|console|console
[result_status] UNDECLARED / UNKNOWN

== action=sessions
session|console|jsmith|Active|-|13:35
[result_status] UNDECLARED / UNKNOWN

== action=local_users
local_user|jsmith|true|2026-09-06 21:20:00|Jordan Smith|true
local_user|root|true|2026-09-06 21:15:00|System Administrator|false
[result_status] UNDECLARED / UNKNOWN

== action=local_admins
admin|root|user|admin
admin|jsmith|user|admin
admin|_mbsetupuser|user|admin
[result_status] UNDECLARED / UNKNOWN

== action=group_members group=admin
group_member|root|admin|user
group_member|jsmith|admin|user
group_member|_mbsetupuser|admin|user
[result_status] UNDECLARED / UNKNOWN

== action=primary_user
primary_user|jsmith|35|last
[result_status] UNDECLARED / UNKNOWN

== action=session_history
session_history|jsmith|console|Sun|console|active|Sep  6 21:20   still logged in
session_history|reboot|time|Sun|system|completed|Sep  6 21:19
session_history|shutdown|time|Sun|system|completed|Sep  6 21:15
session_history|root|console|Sun|console|completed|Sep  6 21:15 - shutdown  (00:00)
session_history|jsmith|ttys000|Sun|remote|completed|Sep  6 18:53 - 18:53  (00:00)
session_history|jsmith|ttys000|Sun|remote|completed|Sep  6 18:53 - 18:53  (00:00)
session_history|jsmith|ttys000|Mon|remote|completed|Aug 31 09:30 - 09:30  (00:00)
session_history|jsmith|console|Mon|console|completed|Aug 31 09:30 - 21:14 (6+11:44)
session_history|reboot|time|Mon|system|completed|Aug 31 09:29
session_history|jsmith|ttys000|Fri|remote|completed|Aug 28 09:51 - 09:51  (00:00)
session_history|jsmith|console|Fri|console|completed|Aug 28 09:51 - 22:26  (12:35)
session_history|reboot|time|Fri|system|completed|Aug 28 09:50
… 12 of 50 rows shown
[result_status] UNDECLARED / UNKNOWN

Linux — captured: linux Debian GNU/Linux 13 (trixie) aarch64 · container · 2026-09-06 · euid 0 · leg-hash 5734018da5be

== action=logged_on
[result_status] UNDECLARED / UNKNOWN

== action=sessions
[result_status] UNDECLARED / UNKNOWN

== action=local_users
local_user|root|true|unknown|root
local_user|nobody|false|unknown|nobody
[result_status] UNAVAILABLE / PARTIAL / subprocess_runner:spawn_error

== action=local_admins
admin|root|user|root
[result_status] UNDECLARED / UNKNOWN

== action=group_members group=sudo
[result_status] UNDECLARED / UNKNOWN

== action=primary_user
primary_user|unknown|0|last command failed
[result_status] UNAVAILABLE / PARTIAL / subprocess_runner:spawn_error

== action=session_history
session_history|error|last command failed
[result_status] UNAVAILABLE / PARTIAL / subprocess_runner:spawn_error

Caveats and known gaps

1. session_history columns on Linux and macOS do not match the declared schema. The Windows leg fills event_type|logon_type|source|timestamp|detail as named, but the Linux and macOS leg splits last’s first three tokens and writes the tty, the host token, a derived console/remote/system class, a completed/active/crash word and the rest of the line into those same slots. The real date and duration exist only as free text in detail, so do not consume those two OSes’ output as if it matched the Windows or YAML meaning. The window is the latest count records (1 to 500, default 50 on an out-of-range value) and includes reboot lines.
2. primary_user is a recent-activity heuristic, not a usage measurement. It counts account names in the latest 200 Windows 4624 events (every logon type, so network and service logons count, and machine accounts and SYSTEM are dropped) or the latest 200 lines of last (boilerplate lines dropped); a tie goes to the alphabetically first name. When the Windows Security log cannot be read it falls back to the last profile under \Users\ in registry order with login_count 0, and sets no status.
3. The admin and group answers are narrow. Windows local_admins looks up the group literally named Administrators and, if that lookup fails (for example on a localised Windows), writes no rows, no error row and no status, which reads like a host with no administrators. group_members accepts only the characters A-Z a-z 0-9 . _ - and no leading - or ., so a group with a space in its name, such as Remote Desktop Users, is rejected with an Invalid group name row on every OS. Linux group_members finds primary-group members by scanning /etc/passwd only.
4. local_users is a best-effort account list. Linux and macOS leave out system accounts (uid below 1000 and 500, and _ names on macOS), and on Linux last_logon is the raw lastlog line, unknown for a name outside the safe character set, and Never when lastlog says so. enabled on Linux and macOS means a usable login shell, not an unlocked password, and the Windows last_logon is this machine’s own record shown in the agent’s local time.
5. A minimal or locked-down host can look empty. An image without last or lastlog degrades local_users, primary_user and session_history to UNAVAILABLE, while logged_on (utmp), local_admins and group_members (getgrnam) are unaffected. Because a tool’s exit code is ignored, an unreadable wtmp gives the same last command failed row as a missing tool but with no status, and group_members returning zero rows with no error row means the group exists with no members.

Source and tests

• Plugin: agents/plugins/users/src/users_macos_last.hpp · agents/plugins/users/src/users_plugin.cpp · agents/plugins/users/src/users_win_events.hpp
• Definitions: content/definitions/users.yaml
• Capability rows: server/core/src/capability_decls/plugin_action_catalogue_b.hpp
• Tests: tests/unit/test_users_macos_last.cpp · tests/unit/test_users_posix_actions.cpp · tests/unit/test_users_win_events.cpp
• Privilege row: docs/agent-privilege-model.md (no row yet)