rdp_control

How it works

set_state runs three sequential steps under a per-process mutex (registry fDenyTSConnections, the built-in Remote Desktop firewall rule group via INetFwPolicy2, then TermService) and reports each step’s outcome independently; overall|ok only when every attempted step succeeded, and there is no rollback on partial failure. Disable deliberately leaves TermService running — only the registry and firewall gates are closed. status independently re-reads all three gates and derives a rdp verdict that is unknown (never a false off) whenever any gate could not be read. On macOS and Linux neither action touches the OS: both return the honest rdp_control|unsupported|... sentinel; set_state still reports rc=1 there (a state-changing action that touched nothing must not read as success), while status keeps rc=0 (an unsupported read is not itself a failure). The plugin is deliberately not a rollback/undo mechanism, and it never stops a running TermService — that is the Guardian service-guard’s job.

flowchart LR
  OP["Operator / ITSM change window"] --> SRV["Server - authz: Security.Write set_state, Security.Read status"]
  SRV -->|"gRPC mTLS"| HOST["Agent plugin host"] --> EX["rdp_control.execute"]
  EX --> WIN["Windows leg - registry + INetFwPolicy2 COM + SCM"]
  EX --> MAC["macOS leg - honest UNSUPPORTED sentinel, no mechanism"]
  EX --> LIN["Linux leg - honest UNSUPPORTED sentinel, no mechanism"]
  WIN & MAC & LIN --> ROWS["key|value rows + result status"] --> RS[("ResponseStore")] --> API["REST /api/responses"]

OS capability

Privileges and prerequisites

None. The Windows leg calls Win32 registry, COM, and Service Control Manager APIs in-process (RegSetValueExW/RegGetValueW, INetFwPolicy2 COM, StartServiceW/QueryServiceStatusEx) — no subprocess, no network.

Data contract

Inputs

Outputs

Each action’s result is a set of independent key|value lines — one per gate or step, in emission order — not a single delimited row; the bold lines below list the field order. There is no - placeholder convention here: a step or gate that could not be read reports its own error:<code> (or error:com_init / error:group_not_found for the firewall step) instead.

windows.rdp.set_state — reg_status|firewall_status|service_status|overall

windows.rdp.status — deny_ts_connections|firewall_group|term_service|rdp

Result status

This plugin does not set a typed result status; the agent records UNDECLARED and the sample shows UNDECLARED / UNKNOWN /.

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 (default 90-day retention), queryable at /api/responses/{id}.
• Not consumed by daily-sync inventory, the Echo warehouse, DEX, or metrics. The plugin is registered only in the agent’s instruction catalogue and the capability catalogue — nothing else in server/ references rdp_control or the windows.rdp.* ids.
• Sensitivity. Rows carry only boolean/enum posture state (reg_status/firewall_status/service_status/overall, deny_ts_connections/firewall_group/term_service/rdp) — nothing that identifies a specific device, person, or installed software beyond the device id.
• Siblings: none report combined RDP posture. registry.get_value/registry.set_value can reach the same fDenyTSConnections value in isolation, and firewall.state/firewall.rules read Windows Firewall generally, but neither combines the registry + firewall-group + service triad this plugin reports together.
• MCP / REST. Discover: discover_plugins (summary) → yuzu://plugin-docs (this page as data) → discover_instructions / get_definition("windows.rdp.status"). 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 e17062cd8474

== action=set_state
error|invalid state (use enable or disable)
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=status
deny_ts_connections|0
firewall_group|enabled
term_service|running
rdp|on
[result_status] UNDECLARED / UNKNOWN

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

== action=set_state
rdp_control|unsupported|Windows Remote Desktop has no macOS equivalent; use Screen Sharing / com.apple.screensharing
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=status
rdp_control|unsupported|Windows Remote Desktop has no macOS equivalent; use Screen Sharing / com.apple.screensharing
[result_status] UNDECLARED / UNKNOWN

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

== action=set_state
rdp_control|unsupported|Windows Remote Desktop is not available on this platform
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=status
rdp_control|unsupported|Windows Remote Desktop is not available on this platform
[result_status] UNDECLARED / UNKNOWN

Caveats and known gaps

1. No rollback on partial failure. set_state’s three steps each report their own status; overall|ok only when all succeeded, and a partial failure leaves whichever gates were flipped in place with no automatic revert.
2. Disable does not stop TermService. Only the registry and firewall gates close on disable; the service is deliberately left running, which is why the capability catalogue classifies set_state as Irreversible rather than claiming a complete undo.
3. S_FALSE from the firewall API is not success. INetFwPolicy2::EnableRuleGroup/IsRuleGroupEnabled return S_FALSE (which passes SUCCEEDED()) when the built-in Remote Desktop rule group is absent (e.g. a hardened image); the plugin explicitly classifies that as group_not_found/an unreadable gate, never a confirmed enable, disable, or “off”.
4. status never reports “off” from an unreadable gate. If any of the three gates cannot be read, the derived verdict is unknown, distinguishing “confirmed closed” from “couldn’t tell” — the fail-safe direction for a remote-access posture check.
5. No typed result status. The plugin never calls a result-status setter; every sample on every OS shows UNDECLARED / UNKNOWN, so a caller must key off overall/rdp and the process exit code, not a typed status field.

Source and tests

• Plugin: agents/plugins/rdp_control/src/rdp_control_plugin.cpp
• Definitions: content/definitions/rdp_control.yaml
• Capability rows: server/core/src/capability_decls/plugin_action_catalogue_c.hpp
• Tests: none found by name
• Privilege row: docs/agent-privilege-model.md