remote_access_audit

How it works

list reports who can log in to this host over SSH, as configured, and changes nothing. It reads, in this order: /etc/ssh/sshd_config (with Include files followed at the directive’s position), the state of the sshd service units, and the authorized_keys files of each account home it walks. It answers with a status row first saying whether the read was complete, then three source rows (sshd_config, homes, service, each read, absent, refused or failed, so zero key rows is never an ambiguous empty success), a config row for every allowlisted setting, the service rows, and one file row per authorized_keys file followed by a key row for every key line this plugin’s bounded decoder accepts (a line it refuses is counted and never listed: see caveat 2). A leg that throws after its rows have started adds a second unsupported status row, which wins.

sshd_config is read as sshd reads it: the first value of a setting wins, and a Match block is counted but never evaluated. A key row carries the type, the fingerprint (byte-identical to ssh-keygen -lf; a certificate reports the key it carries) and the option names it uses; every key blob is decoded completely and within bounds. A key comment, an option value and any key-file path are never emitted (see Sensitivity). The plugin is deliberately a configured-access inventory, not sshd -T, not a login history and not a validity check.

What it does not read. sshd can accept a login from sources this plugin never opens: a certificate authority (TrustedUserCAKeys), keys or principals supplied by a command (AuthorizedKeysCommand, AuthorizedPrincipalsCommand), a principals file (AuthorizedPrincipalsFile), host-based authentication (HostbasedAuthentication yes) and a method requirement that changes what a key alone is worth (AuthenticationMethods). When sshd_config sets one of those sources at global scope to a value other than its inert one (none; no for HostbasedAuthentication; any for AuthenticationMethods; see the CONSTRAINED row below) the listing is CONSTRAINED with <os>:remote_access_audit:sshd_config:other_credential_sources: the token is presence only (no value, no path), and it means the key rows are not the whole answer to who can log in. The same holds for the Remote Login access list on macOS (caveat 1) and for any account whose home is outside the walked roots (caveat 3). A login that needs no key is governed by the config rows: the no-key methods reported are password, keyboard-interactive and GSSAPI (passwordauthentication, kbdinteractiveauthentication, gssapiauthentication), as written and never flagged; other no-key methods (KerberosAuthentication, a PAM-supplied method) are not read.

Symlinks follow a two-tier rule. Under /etc/ssh (writable by root only: sshd_config, the Include directory, each Include file) a link is followed as sshd follows it, so stock macOS and NixOS links do not make the listing CONSTRAINED; a target outside /etc/ssh is read with no owner or mode check (sshd applies none), and a non-regular target is still refused. A home parent (/home, /Users) is root-owned too, so one link hop is allowed (Fedora Atomic ships /home -> var/home). Where the audited account can write (a home, .ssh, authorized_keys*, an absolute AuthorizedKeysFile path) a link is never followed, because a root agent would read what the account cannot: that file reports failed with a symlink_refused or enotdir token. Absolute paths and homes are opened from / one component at a time without following a link, so a link anywhere in the chain is refused; the macOS root home is therefore configured as /private/var/root, the canonical spelling of /var/root.

flowchart LR
  OP[Operator / workflow] --> SRV[Server<br/>authz: Forensics.Read + AdminOrApproval, single target, kill switch]
  SRV -- gRPC mTLS --> HOST[Agent plugin host] --> EX[remote_access_audit.execute]
  EX --> WIN[Windows leg<br/>status row only: windows:planned]
  EX --> MAC[macOS leg<br/>sshd_config, authorized_keys, launchctl print-disabled]
  EX --> LIN[Linux leg<br/>sshd_config, authorized_keys, systemctl is-enabled]
  WIN & MAC & LIN --> ROWS[rows + typed result status] --> RS[(ResponseStore)] --> API[REST /api/responses]

What you can decide with it

A clean OK with zero key rows means every walked home was readable and held no accepted key, which is not the same as “nobody can log in”: passwords, certificates, key commands and accounts outside the walked homes are separate questions answered by the config rows, the CONSTRAINED token above, or not at all. A CONSTRAINED or PERMISSION_DENIED result means the missing part is unknown, not empty. The action is read-only and needs the server-side kill switch enabled first (see Where the data goes).

Diagrams

Who can log in: what is covered

flowchart TD
  L["Login attempt over SSH"] --> K{"Which credential source?"}
  K -- "Key in an account's authorized_keys" --> R1["Read: key rows with fingerprint and option names"]
  K -- "Password, keyboard-interactive, GSSAPI" --> R2["Read as written: config rows"]
  K -- "Certificate authority, key or principals command, principals file" --> N1["Not read: flagged CONSTRAINED, other_credential_sources"]
  K -- "Host-based auth, AuthenticationMethods" --> N1
  K -- "Match block, Remote Login access list on macOS, account home outside the walked roots" --> N2["Not evaluated or not read: Match only counted, the rest leaves no row"]
  R1 --> D["Treat the key rows as a lower bound on who can log in"]
  R2 --> D
  N1 --> D
  N2 --> D

Key rows and config rows are the part the plugin can vouch for. The credential sources in the third group are announced by a constrained status when sshd_config sets them at global scope; the last group is at most hinted (a match_blocks count; the homes skipped count covers only home-root entries not treated as accounts, such as a macOS uid under 500, and says nothing about accounts whose home is outside the walked roots), so a clean result never proves that nobody else can log in.

Symlink rule

flowchart TD
  P["Path to read"] --> W{"Who can write it?"}
  W -- "Only root: sshd_config, Include files, /home or /Users parent" --> F["Follow the link as sshd does, one hop for a home parent"]
  F --> T{"Config or Include file: is the target a regular file?"}
  T -- "no" --> X["Refused, constrained"]
  T -- "yes" --> OK["Read, size capped"]
  W -- "The audited account: home, .ssh, authorized_keys, absolute key path" --> NF["Open from slash one component at a time, never follow"]
  NF --> L{"Link met?"}
  L -- "yes" --> FA["file row failed, symlink_refused or enotdir, listing CONSTRAINED"]
  L -- "no" --> OK

Paths only root can change are read the way sshd reads them, so ordinary distribution links do not distort the result. Anything the audited account controls is never followed, since a root agent would otherwise read files the account itself could not.

OS capability

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

• list / Windows — not read yet: one unsupported status row, windows:planned
• list / macOS — configured access as written, not sshd’s effective policy; the launchd override is not ‘running’; CA trust, key and principals commands, a principals file, hostbased auth and AuthenticationMethods are not read; the Remote Login access list (pam_sacl) is not read; key comments, option values and key-file paths are never emitted; only homes under /Users owned by uid 500 or above, and /var/root, are walked; a symlinked key file or .ssh is refused; network mounts are skipped
• list / Linux — constrained: the agent runs unprivileged, so other users’ homes (usually 0700) are refused, not empty, and the listing is constrained; configured access as written, not sshd’s effective policy (Match is not evaluated); CA trust, key and principals commands, a principals file, hostbased auth and AuthenticationMethods are not read; key comments, option values and key-file paths are never emitted; only homes under /home and /root are walked; a symlinked key file or .ssh is refused; network mounts are skipped

Privileges and prerequisites

Subprocesses: Linux runs systemctl is-enabled <unit> once for each of ssh.service, sshd.service, ssh.socket and sshd.socket (argv resolved from /usr/bin/systemctl or /bin/systemctl, no shell, 5 s deadline each, no sudo). sshd.socket is listed for distributions that ship it (Fedora and Arch). Whether RHEL 9’s openssh-server package ships sshd.socket is not verified. On a socket-activated host ssh.service can read disabled while ssh.socket is enabled; read both. macOS runs /bin/launchctl print-disabled system once (5 s deadline). Both go through the bounded runner and have sink-manifest rows (docs/agent-spawn-sink-manifest.md). Files are read in process. Symlink handling: see How it works. No network use. A containerised agent (Dockerfile.agent) audits the image’s /etc/ssh and /home, not the host’s.

Data contract

Inputs

The action takes no parameters.

Outputs

Every row is pipe-delimited; field 0 is the row kind and - is an absent value; the order and the field meanings are in the table below. port is comma-joined across occurrences, and the deprecated ChallengeResponseAuthentication shares the kbdinteractiveauthentication slot. unknown in a service row means two things: on Linux it always comes with a service:* or subprocess_runner:* token and a CONSTRAINED listing (the unit could not be queried); on macOS the read succeeded and launchd has no override entry for the label, so the status stays supported (enabled there is a launchd override, not “running”). Every free field is scrubbed of NUL and invalid UTF-8, pipe-escaped and cut at 4096 bytes.

crossplatform.security.remote_access_audit — row_kind|field_1|field_2|field_3|field_4|field_5|field_6|field_7

Result status

The leading status row carries the same tokens as the result status; a leg that throws is UNAVAILABLE and the last status row wins.

Where the data goes

• Instruction result. Rows travel over the agent’s mTLS gRPC channel as the command response and land in the standard ResponseStore, kept 90 days (--response-retention-days, default 90) and served over GET /api/responses (legacy), GET /api/v1/responses/{id} and the equivalent MCP result-poll tools. list is also a gathered definition (crossplatform.security.remote_access_audit, 3600s TTL).
• Not consumed by daily-sync, Echo, DEX, or metrics.
• Default off, and how to turn it on. The plugin is Forensics-class and ships off: the server seeds a default-off kill switch at boot, so nothing dispatches until an operator runs PUT /api/v1/plugin-config/remote_access_audit/kill-switch {"enabled":true} (PluginConfig:Write, audited as plugin_config.kill_switch.set; the MCP twin is set_plugin_kill_switch). After that, dispatch is gated at Forensics:Read with AdminOrApproval (Administrator by default; a non-admin needs a delegated Forensics:Read grant plus an approval) and is single-target: exactly one device per request. While the switch is off, REST /api/command answers “permission denied: Forensics:Read” even to an Administrator, the dashboard console says “No agents connected”, MCP returns an “emergency stop” message, and instruction execute answers 503 “no agents reached … concurrency claim” (misleading; check the switch first). The switch is checked when a command is dispatched: disabling stops new dispatches, a run already in flight completes, and a delayed or staggered command already sent still runs (up to 10 minutes).
• Sensitivity. Per-account key fingerprints on one named machine are identity material: they say which keys can log in as which account, and the account is the home directory’s name. Key comments, option values, principals lists and key-file paths are never emitted. A key fingerprint is the same on every host that trusts the key, so results from two machines can be joined on it to show where one person’s or one service’s key is trusted: that cross-host linkability is inherent in the fact reported, and listing every walked home as an account, keyless ones included, is deliberate. Which accounts hold keys that can log in to a named machine is works-council co-determination-relevant. In the macOS sample the account name is replaced with jsmith. Dispatch is gated Forensics:Read + AdminOrApproval, and stored rows 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. Reads are audited as response.read on REST v1 /responses/{id}, /aggregate and /export and on the legacy /api/responses/... twins (all fail-closed), execution.detail.fetch (/executions/{id}/responses) and mcp.query_responses, and a read that serves these rows additionally writes response.forensics.read (on the dashboard results fragment it is the only row written; 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. There is no per-user erasure path. The Instructions UAT runner cannot exercise Forensics-tier dispatch (known gap #5261), which is not fixed here.
• Siblings: privacy_permissions, browser_inventory and execution_artifacts (the other Forensics-class plugins) and mgmt_posture (which plane controls the device).

Sample output

macOS — captured: macos macOS 26.6.2 arm64 · bare-metal · 2026-10-18 · euid 501 (account redacted to jsmith) · leg-hash 58c6c41593ed

== action=list
status|list|constrained|macos:remote_access_audit:homes:permission_denied
source|sshd_config|read|3
source|homes|read|2|1
source|service|read|1
config|permitrootlogin|-|-
config|passwordauthentication|-|-
config|pubkeyauthentication|-|-
config|kbdinteractiveauthentication|-|-
config|gssapiauthentication|-|-
config|permitemptypasswords|-|-
config|usepam|yes|include:100-macos.conf
config|port|-|-
… 12 of 22 rows shown
[result_status] CONSTRAINED / PARTIAL / macos:remote_access_audit:homes:permission_denied

Linux — captured: linux Ubuntu 26.04.1 LTS x86_64 · container · 2026-10-18 · euid 0 · leg-hash 58c6c41593ed

== action=list
status|list|constrained|linux:remote_access_audit:keys:malformed,linux:remote_access_audit:keys:oversized_line,linux:remote_access_audit:keys:symlink_refused
source|sshd_config|read|3
source|homes|read|5|-
source|service|read|4
config|permitrootlogin|prohibit-password|include:10-test.conf
config|passwordauthentication|no|include:10-test.conf
config|pubkeyauthentication|-|-
config|kbdinteractiveauthentication|no|sshd_config
config|gssapiauthentication|-|-
config|permitemptypasswords|-|-
config|usepam|yes|sshd_config
config|port|-|-
… 12 of 53 rows shown
[result_status] CONSTRAINED / PARTIAL / linux:remote_access_audit:keys:malformed,linux:remote_access_audit:keys:oversized_line,linux:remote_access_audit:keys:symlink_refused

Caveats and known gaps

1. Configured, not effective. Rows report what the files say, not what sshd enforces: a Match block (including Match all) is counted and not evaluated, defaults are not applied (an unset setting is -), an Include wildcard is expanded in byte order where sshd uses locale order, and directives sshd would refuse are listed as written with only an unbalanced quote flagged. On macOS, Remote Login is also gated by an access list outside both files (pam_sacl, group com.apple.access_ssh), which a user can fail even with a key present and which this plugin does not read; sshd -t and sshd -T are the validity and effective-policy checks.
2. A syntactic inventory, not sshd’s validity check. A key row means the line parses by sshd’s grammar and its blob decodes completely. The lines counted malformed (the file row’s field_5) are the lines this plugin refuses, which is not the set sshd rejects. Option values are not validated, an ECDSA point is not checked against the curve, and a certificate’s signature is not verified; a certificate signed with a WebAuthn webauthn-sk- algorithm carries signature fields this plugin does not decode, so it is counted malformed (tracked in issue #6263). A line of a key type this plugin does not know (ssh-dss, a newer algorithm) is counted malformed and never reported as a key, so a key sshd accepts can be missing here and a tampered certificate sshd rejects can appear; a certificate row reports the embedded key’s fingerprint, not the certificate’s.
3. Identity is the home directory’s name, and only these homes are walked. account is the basename of the walked home, not the login name; Linux walks every directory directly under /home plus /root, macOS every /Users entry owned by uid 500 or above plus /var/root, so a service account with its home elsewhere is never seen and the plugin cannot tell it from an absent account. Over 512 homes the first 512 in directory order are kept (homes:too_many), any directory under a walked root such as lost+found is listed as an account, and an AuthorizedKeysFile entry using %u, %U or another token is reported unsupported rather than guessed.
4. Blocking I/O on mounts is guarded by name, with residuals. The config path, Include files, home roots, homes and key paths on a network filesystem named by the run-start mount table (yuzu::shared::is_network_fstype, plus webdav/afpfs/macfuse/osxfuse on macOS) are never opened, because an open on a dead hard mount pins a worker with no deadline. A stacked filesystem, a bare fuse mount over a dead server, a mount made after the snapshot, a link chain and an entry of a listed Include directory that is itself a link into a mount are not caught (#4875), and the reads carry no deadline of their own, so the worst case is 1,024 key-file reads of up to 1 MiB on one shared command worker.
5. Windows is not read. The Windows leg reports one unsupported row, windows:planned, and reads no key file, sshd_config or service state; the intended mechanism is a per-profile .ssh\authorized_keys, %ProgramData%\ssh\administrators_authorized_keys and sshd_config read through the profile walk. No leg runs sshd -T, so configured access is all this plugin reports on any OS.

Source and tests

• Plugin: agents/plugins/remote_access_audit/src/remote_access_audit_config_parsers.hpp · agents/plugins/remote_access_audit/src/remote_access_audit_keys_parsers.hpp · agents/plugins/remote_access_audit/src/remote_access_audit_legs.hpp · agents/plugins/remote_access_audit/src/remote_access_audit_linux.cpp · agents/plugins/remote_access_audit/src/remote_access_audit_macos.cpp · agents/plugins/remote_access_audit/src/remote_access_audit_plugin.cpp · agents/plugins/remote_access_audit/src/remote_access_audit_posix_fs.hpp · agents/plugins/remote_access_audit/src/remote_access_audit_win.cpp
• Definitions: content/definitions/remote_access_audit.yaml
• Capability rows: server/core/src/capability_decls/plugin_action_catalogue_remote_access_audit.hpp
• Tests: tests/test_remote_access_audit_definition.py · tests/unit/test_remote_access_audit_config_parsers.cpp · tests/unit/test_remote_access_audit_keys_parsers.cpp · tests/unit/test_remote_access_audit_legs.cpp · tests/unit/test_remote_access_audit_local_dispatcher.cpp · tests/unit/test_remote_access_audit_posix_fs.cpp
• Privilege row: docs/agent-privilege-model.md