antivirus

How it works

products enumerates installed/running AV products. Windows queries root\SecurityCenter2 for AntiVirusProduct rows in-process via WMI and decodes each productState into enabled/snoozed/disabled plus a current/stale definitions field. Linux checks for clamd, falcon-sensor, and sophos via pgrep, falling back to an install-directory check for the latter two. macOS probes the XProtect definition bundle for identity, then enumerates endpoint-security system extensions for third-party EDR/AV, falling back to pgrep only for vendors the extension registry didn’t already report.

status reports engine/definitions freshness. Windows queries MSFT_MpComputerStatus for real-time protection, signature version, and scan times. macOS reads the XProtect bundle’s version and modification time plus the Remediator/MRT engine versions — no real-time-protection field, since macOS exposes no queryable equivalent. Linux checks ClamAV liveness plus its signature database’s mtime, and reports CrowdStrike/Sophos presence only (no freshness data is reachable at this leg’s rung).

av_exclusions is Windows-only: it reads Defender’s Paths/Processes/Extensions exclusion keys from both the operator-editable local hive and the GPO/MDM policy hive, merges the two with per-entry provenance, and reports the worst of six subkey-read outcomes as the action’s status. Linux and macOS have no equivalent exclusion store to read, so the action reports unsupported there rather than guessing.

The plugin deliberately stops at raw posture: a snoozed or disabled product is reported honestly, never normalized into a compliance verdict — that judgment belongs to a downstream policy engine.

flowchart LR
  OP[Operator / workflow] --> SRV[Server<br/>authz: Security.Read]
  SRV -- gRPC mTLS --> HOST[Agent plugin host] --> EX[antivirus.execute]
  EX --> WIN[Windows leg<br/>in-process WMI SecurityCenter2/Defender<br/>+ registry exclusion keys]
  EX --> MAC[macOS leg<br/>PlistBuddy + systemextensionsctl + pgrep<br/>bounded subprocess]
  EX --> LIN[Linux leg<br/>pgrep + stat<br/>bounded subprocess]
  WIN & MAC & LIN --> ROWS[rows + typed result status<br/>Windows only]
  ROWS --> RS[(ResponseStore)]
  RS --> API[REST /api/responses]

OS capability

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

• av_exclusions / Windows — permission_denied sentinel on ACL’d key, never a silent empty list
• av_exclusions / macOS — Windows-only concept
• av_exclusions / Linux — Windows-only concept
• status / Linux — ClamAV liveness+definitions mtime; CrowdStrike/Sophos presence-only

Privileges and prerequisites

Binaries/subprocesses: macOS — /usr/libexec/PlistBuddy, /usr/bin/systemextensionsctl, /usr/bin/pgrep (bounded subprocess, 5s deadline). Linux — /usr/bin/pgrep or /bin/pgrep (bounded subprocess, 5s deadline). Windows — none; WMI and registry access are in-process. No network access on any OS.

Data contract

Inputs

No action takes parameters.

Outputs

Pipe-delimited rows, one per record, with the first field a literal row-type discriminator. products also emits ancillary single-purpose rows outside the av| shape: av_count|0 when nothing was found, xprotect_version|<n> alongside av|XProtect|active on macOS, edr|<bundle_id>|<version> per detected macOS endpoint-security extension, and not_available|<detail> on Windows when the SecurityCenter2 query itself failed. av_exclusions likewise emits exclusion_count|0 (clean empty read), or a typed permission_denied|… / not_available|… / partial|… row when a subkey read failed, or unsupported|av_exclusions is Windows-only on Linux/macOS. A missing WMI property is simply omitted from status’s Windows output, never fabricated.

security.antivirus.av_exclusions — kind|source|value

security.antivirus.defender_status — realtime_protection|definition_version|last_update|last_quick_scan

security.antivirus.products — name|state|definitions

security.antivirus.xprotect_status — definition_version|last_update|remediator_version|mrt_version

Result status

Where the data goes

• Instruction result only. Rows travel over the agent’s mTLS gRPC channel as the command response and land in the ResponseStore, queryable at /api/responses/{id}. defender_status’s real-time-protection field also drives a fleet-wide pie-chart visualization defined directly in the YAML.
• Not consumed by daily-sync inventory, the Echo warehouse, DEX, or metrics — no source under those subsystems references antivirus or any security.antivirus.* id. The plugin executes only when an operator or workflow dispatches one of its definitions.
• Sensitivity. products’ name field is an installed-software inventory by another route — OS-supplied AV/EDR product or extension display names (e.g. Windows Defender, CrowdStrike Falcon). av_exclusions’ value field is a free-text, operator/vendor-controlled path, process, or extension name that can embed a Windows username or other host-specific detail (the sample row itself is a filesystem path). status rows carry only version strings and timestamps — nothing that identifies a device or a person.
• Siblings: none — no other shipped plugin covers AV product/status/exclusion detection.
• MCP / REST. Discover: discover_plugins (summary) → yuzu://plugin-docs (this page as data) → discover_instructions / get_definition("security.antivirus.products"). Run: execute_instruction {definition_id, parameters}. Read: /api/responses/{id}.

Sample output

Windows — captured: windows Microsoft Windows NT 10.0.26200.0 x64 · bare-metal · 2026-09-07 · SYSTEM · leg-hash a4abf06e398d

== action=products
av|Windows Defender|snoozed|current
[result_status] UNDECLARED / UNKNOWN

== action=status
realtime_protection|enabled
definition_version|1.459.88.0
last_update|20260906211522.000000+000
last_quick_scan|20260906150800.885000+000
[result_status] UNDECLARED / UNKNOWN

== action=av_exclusions
exclusion|path|local|D:\yuzu-dev
[result_status] UNDECLARED / UNKNOWN

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

== action=products
av|XProtect|active
xprotect_version|5358
[result_status] UNDECLARED / UNKNOWN

== action=status
definition_version|5358
last_update|2026-08-28T08:11:38
remediator_version|157
mrt_version|1.93
[result_status] UNDECLARED / UNKNOWN

== action=av_exclusions
unsupported|av_exclusions is Windows-only
[result_status] UNDECLARED / UNKNOWN

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

== action=products
av_count|0
[result_status] UNDECLARED / UNKNOWN

== action=status
av|ClamAV|not_running
av|CrowdStrike Falcon|not_detected
av|Sophos|not_detected
[result_status] UNDECLARED / UNKNOWN

== action=av_exclusions
unsupported|av_exclusions is Windows-only
[result_status] UNDECLARED / UNKNOWN

Caveats and known gaps

1. The Windows productState decode is a reverse-engineered convention, not a documented API. decode_wsc_product_state (antivirus_parsers.hpp:217) formats a widely-corroborated community convention going back to Vista — Microsoft has never published this layout, so the decode is MEDIUM confidence, not the HIGH confidence a header-published struct would carry.
2. No content definition targets the Linux status leg. list_status_linux is real, and the descriptor declares status supported on Linux at rung 2 (antivirus_plugin.cpp:490-492), but security.antivirus.defender_status is platforms: [windows] and security.antivirus.xprotect_status is platforms: [darwin] (content/definitions/antivirus.yaml:104, :178) — no definition in this file targets Linux for the status action.
3. A single ACL’d exclusion subkey degrades the whole av_exclusions run. The worst-of-six aggregation (antivirus_plugin.cpp:211-247) means one policy-hive key denied to the reading account reports PERMISSION_DENIED for the entire action, even if the other five subkey reads succeeded and returned real exclusions.
4. docs/agent-privilege-model.md’s Windows cell now matches the code. It describes in-process WMI/COM queries against root\SecurityCenter2 and root\Microsoft\Windows\Defender, no PowerShell subprocess (docs/agent-privilege-model.md:97) — matching the plugin’s actual mechanism since PR #3369 (2026-08-23). Earlier revisions of that row described a PowerShell Get-MpComputerStatus CIM query; treat any remaining reference to it elsewhere as stale.
5. CrowdStrike and Sophos are presence-only outside Windows. Linux and macOS report detected/not_detected or installed/running for these vendors with no definitions-freshness data — this plugin has no rung-1 or rung-2 mechanism to read their own signature state on those platforms (antivirus_plugin.cpp:327-329).

Source and tests

• Plugin: agents/plugins/antivirus/src/antivirus_parsers.hpp · agents/plugins/antivirus/src/antivirus_plugin.cpp
• Definitions: content/definitions/antivirus.yaml
• Capability rows: server/core/src/capability_decls/plugin_action_catalogue_d.hpp
• Tests: tests/unit/test_antivirus_local_dispatcher.cpp · tests/unit/test_antivirus_parsers.cpp
• Privilege row: docs/agent-privilege-model.md