feat: add elevated execution support to exec messages

[Richard Markiewicz (thenextman)]

Summary

Updates NOW-PROTO to v1.7, adding the ability for a client to request that an exec session run with elevated privileges.

RDM has had a "Run as administrator" checkbox in Execute script via Devolutions Agent since the legacy RDM Jump days, where it worked — the receiving RDM ran ShellExecute with the runas verb. The jump transport was removed in RDMW-21914 and the NOW exec path has no way to carry the intent, so the checkbox has silently done nothing since. This PR adds the protocol half.

What this adds

• NOW_EXEC_FLAG_*_ELEVATED on the run, process, shell, batch, winps and pwsh exec messages.
• NOW_CAP_EXEC_ELEVATE_SHELL (0x0080) - advertised by servers that elevate through the platform shell: may prompt the interactive user for consent, and cannot redirect stdio.
• NOW_EXEC_FLAG_BATCH_NO_EXIT (0x0010) - cmd /K rather than /C. Under shell elevation there is no stdio, so a console left open is the only way the user sees output. winps/pwsh already had NO_EXIT; batch did not. Must be ignored when the session redirects stdio, where the hidden interpreter would never exit.
• A new normative "Elevated Execution" spec section.
• Client-side refusal in NowClient: an elevated request is rejected unless the negotiated capset advertises elevation.

Design: intent, not mechanism

The part worth reviewing. Three rules, all aimed at letting a better elevation mechanism land later without a breaking change:

1. The message expresses intent only. The flag is ELEVATED, never RUNAS. A client cannot select a mechanism, so a server is free to change how it elevates without any client change.
2. The mechanism is advertised by the server in execCapset, the same way UNICODE_CONSOLE and IO_REDIRECTION already are. A client learns what elevation will cost it before sending.
3. The observable semantics are written down per mechanism — stdio, result reporting, abort — so tightening any of them later is a documented capability change rather than a silent behaviour change.

Only one elevation capability is defined. A mechanism with different observable properties (no prompt, stdio preserved) is expected to arrive as an additional capability rather than by redefining this one. An earlier revision of this branch also defined a reserved NOW_CAP_EXEC_ELEVATE_TOKEN; it was dropped, because a defined-but-meaningless constant invites clients to branch on it as a property proxy — ours already had one doing exactly that, untestably — and reserving a bit protects nothing when eight are free.

Two scoping statements in the spec exist to keep future work unblocked:

• ELEVATED raises the privileges of the identity that would otherwise run the command. It selects no identity and carries no credentials, so "run as another user" has clean ground for a separate field.
• An elevation capability means the server implements elevation, not that every advertised exec style can be elevated. A client must handle per-style. This is true from day one: the agent-side work lands run first.

Why the client refuses locally

The spec requires a server to fail rather than execute unelevated — but that only binds servers at 1.7 or later. A pre-1.7 server does not know the flag: it ignores the unknown bit and runs the command with normal privileges, with nothing on the wire to distinguish that from success. The server-side MUST cannot protect that case, so NowClient refuses the request when no elevation capability was advertised. Silent downgrade is the exact defect this PR exists to remove; it would be perverse to reintroduce it in the client.

Bit allocation

Each exec message has its own flag namespace; values avoid every bit already in use.

Message	Flag	Value
NOW_EXEC_RUN_MSG	NOW_EXEC_FLAG_RUN_ELEVATED	0x0002
NOW_EXEC_PROCESS_MSG	NOW_EXEC_FLAG_PROCESS_ELEVATED	0x0008
NOW_EXEC_SHELL_MSG	NOW_EXEC_FLAG_SHELL_ELEVATED	0x0008
NOW_EXEC_BATCH_MSG	NOW_EXEC_FLAG_BATCH_ELEVATED	0x0008
NOW_EXEC_BATCH_MSG	NOW_EXEC_FLAG_BATCH_NO_EXIT	0x0010
NOW_EXEC_WINPS_MSG / NOW_EXEC_PWSH_MSG	NOW_EXEC_FLAG_PS_ELEVATED	0x0800

Included bug fix (c9c788f, separate commit)

NowExecRunMsg::decode_from_body discarded the header flags and rebuilt them from payload content, making it the only exec message that did not preserve flags on decode. Any flag added to NOW_EXEC_RUN_MSG — including ELEVATED — was silently dropped, so a server would never have observed the request. DIRECTORY_SET is still derived from the payload, because peers older than v1.1 omit the directory field entirely.

Split out so it gets its own Bug Fixes changelog entry: it is a latent bug in released 0.4.4, independent of this feature. It compiles and passes on its own; the round-trip tests in 454f214 are its first coverage, since ELEVATED is the first RUN flag that would have been dropped.

Verified behaviour behind the spec

The section says a shell-elevated session SHOULD still report its real exit code despite having no stdio. That was an assumption, so I measured it rather than shipping it on faith. From a Medium IL (S-1-16-8192) unelevated caller, a ShellExecuteEx/runas child at High IL (S-1-16-12288):

WaitForExit : ok [SYNCHRONIZE granted]
Id : ok [PROCESS_QUERY_LIMITED_INFORMATION granted]
ExitCode : 42 [true value, not a default 0]

MIC's no-read-up rule is enforced when opening a handle; here the handle is created for us by the AppInfo service, so it does not apply at use. PROCESS_QUERY_LIMITED_INFORMATION exists for exactly this. The legacy jump path also depended on the wait half in production for years.

PROCESS_TERMINATE is untested, which is why abort stays MAY-fail in the spec.

Testing

• 14 new round-trip tests across both languages. ELEVATED is asserted for every exec style, and ELEVATED / NO_EXIT are asserted independently as well as together — the combined 0x0018 mask alone would stay green if the two constants were swapped.
• The .NET byte arrays are the exact encodings the Rust suite asserts, pinning both implementations to one wire format.
• Version-byte snapshots updated for 1.7 in both suites.
• Full gate run: rust fmt, dotnet fmt, check typos, rust tests (62), rust lints, dotnet tests (61), dotnet build, check locks — all green.

Open questions

1. Should 1.7 define elevation error codes? NOW_STATUS carries the failure fine, but there is no NOW-level code for "elevation was requested and could not be granted", so a client must sniff Win32 numbers — brittle, and meaningless on POSIX. Candidates, 0x0009+ being free: NOW_CODE_ELEVATION_DENIED (consent not granted) and NOW_CODE_ELEVATION_UNAVAILABLE (no elevated token for this account — UAC disabled, or a standard user).

My recommendation is to add them now. The protocol change is additive at any time, but the cost of deferring lands in clients: anything shipped in the interim hardcodes ERROR_CANCELLED (1223) and that code outlives the fix. For what it's worth, denial and consent timeout are indistinguishable at the API level — both surface as 1223 — and I think "consent not granted" is the right granularity, but it should be a stated decision.

2. Should NO_EXIT get a capability bit? It currently has none and is implied by version 1.7, while ELEVATED in the same bump is capability-discovered. Two flags, two discovery rules, no stated principle. Leaving it version-implied matches DETACHED exactly (added in 1.4, no bit, gated client-side), which is why I left it — but if you want the rule written down, the honest version is: flags whose support varies by host capability get bits, flags that are pure protocol behaviour are version-implied.

3. Should this reconcile with the policies/ elevation model? This repo already has an Elevation enum (Standard/Elevated), RequestedElevation and ElevationRequired under policies/. I did not reconcile the two, so there are now two elevation vocabularies in one repo. "Elevate this exec session, subject to PEDM policy" will eventually want them to compose.

Known gaps, accepted deliberately

• NOW-spec.pdf not regenerated. `. The PDF is untracked.
• No supports_exec_elevation() version helper, deviating from the 1.6 precedent that added supports_exec_unicode_console(). Elevation must be gated on the capability, not the version: a 1.7 Linux agent cannot runas, and a 1.7 Windows agent that has not shipped the server-side change cannot either. Both would answer true. A version helper is the more discoverable API and would invite exactly the bug the capability prevents.
• No best-effort mode. Elevation is strict-or-fail. Deliberate: strict is recoverable toward leniency later, whereas shipping lenient and tightening would break callers who relied on the downgrade.
• No NowClient unit test for the refusal path — there is no Devolutions.NowClient test project, and constructing a client needs a transport.

Follow-up work

1. devolutions-gateway — honour ELEVATED in process_exec_run (verb selection; the smallest useful increment), advertise ELEVATE_SHELL, and map declined consent to a distinct status.
2. devolutions-gateway — shell-launch path for batch/winps/pwsh, reusing the existing but currently unused win_api_wrappers::process::shell_execute so elevated sessions still report a real exit code.
3. RDM — send the flag, gate the checkbox on the capability, and state in the UI that elevated runs have no output capture.

[Copilot]

🟡 Changes recommended

Batch NoExit is not gated against pre-1.7 servers, allowing silent fallback to cmd /C.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds NOW-PROTO 1.7 elevated execution support across Rust and .NET implementations.

Changes:

• Adds elevated-execution flags and shell-elevation capability negotiation.
• Adds batch NO_EXIT support and fixes Rust run-flag decoding.
• Updates wire-format tests, client APIs, and protocol documentation.

File summaries

File	Description
protocols/rust/now-proto-testsuite/tests/proto/exec.rs	Tests new exec flags.
protocols/rust/now-proto-testsuite/tests/proto/channel.rs	Updates version snapshots.
protocols/rust/now-proto-pdu/src/exec/win_ps.rs	Adds WinPS elevation.
protocols/rust/now-proto-pdu/src/exec/shell.rs	Adds shell elevation.
protocols/rust/now-proto-pdu/src/exec/run.rs	Adds elevation and preserves decoded flags.
protocols/rust/now-proto-pdu/src/exec/pwsh.rs	Adds pwsh elevation.
protocols/rust/now-proto-pdu/src/exec/process.rs	Adds process elevation.
protocols/rust/now-proto-pdu/src/exec/batch.rs	Adds elevation and no-exit flags.
protocols/rust/now-proto-pdu/src/channel/capset.rs	Adds capability and protocol version.
protocols/dotnet/Devolutions.NowProto/src/NowProtoVersion.cs	Updates protocol version.
protocols/dotnet/Devolutions.NowProto/src/Messages/NowMsgExecWinPs.cs	Adds WinPS elevation serialization.
protocols/dotnet/Devolutions.NowProto/src/Messages/NowMsgExecShell.cs	Adds shell elevation serialization.
protocols/dotnet/Devolutions.NowProto/src/Messages/NowMsgExecRun.cs	Adds run elevation serialization.
protocols/dotnet/Devolutions.NowProto/src/Messages/NowMsgExecPwsh.cs	Adds pwsh elevation serialization.
protocols/dotnet/Devolutions.NowProto/src/Messages/NowMsgExecProcess.cs	Adds process elevation serialization.
protocols/dotnet/Devolutions.NowProto/src/Messages/NowMsgExecBatch.cs	Adds batch elevation and no-exit serialization.
protocols/dotnet/Devolutions.NowProto/src/Capabilities/NowCapabilityExec.cs	Defines shell-elevation capability.
protocols/dotnet/Devolutions.NowProto.Tests/src/NowExecStyles.cs	Tests new .NET wire encodings.
protocols/dotnet/Devolutions.NowProto.Tests/src/MsgChannel.cs	Updates version snapshots.
protocols/dotnet/Devolutions.NowClient/src/NowClient.cs	Rejects unsupported elevation requests.
protocols/dotnet/Devolutions.NowClient/src/ExecWinPsParams.cs	Exposes WinPS elevation option.
protocols/dotnet/Devolutions.NowClient/src/ExecShellParams.cs	Exposes shell elevation option.
protocols/dotnet/Devolutions.NowClient/src/ExecRunParams.cs	Exposes run elevation option.
protocols/dotnet/Devolutions.NowClient/src/ExecPwshParams.cs	Exposes pwsh elevation option.
protocols/dotnet/Devolutions.NowClient/src/ExecProcessParams.cs	Exposes process elevation option.
protocols/dotnet/Devolutions.NowClient/src/ExecBatchParams.cs	Exposes elevation and no-exit options.
protocols/dotnet/Devolutions.NowClient/src/AExecParams.cs	Tracks elevation intent.
protocols/docs/NOW-spec.md	Documents NOW-PROTO 1.7 semantics.

Review details

• Files reviewed: 28/28 changed files
• Comments generated: 1
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.