Add guarded WPR captureDenials fallback

[Richie Gomez (richiemsft)]

📖 Description

Adds a secure processContainer.captureDenials fallback for Windows hosts where the complete native PSEC plus V2 Learning Mode capability set cannot honor the requested policy.

Native capture remains preferred when PSEC, V2 Learning Mode, and request-specific capabilities are available. Otherwise MXC selects the highest compatible legacy containment tier—SBOX, AppContainer+BFS, or AppContainer+DACL—and pairs it with the guarded WPR capture session. Proxy and least-privilege policies that PSEC cannot represent route to the compatible legacy path rather than weakening policy.

MXC uses a privilege-separated, brokered elevation model. The main executor and public plm.exe process remain unelevated, and a session-scoped UAC-elevated helper is launched only when privileged guarded WPR capture is required. The helper performs a fixed set of WPR control and analysis operations and returns bounded results over an authenticated named pipe.

The guarded fallback builds on the PLM architecture refactored in #760 rather than introducing a separate capture or decoding stack. It reuses PLM's asInvoker front end, retained elevated guardian, embedded WPR profile, protected scratch and recovery state, authenticated bounded control channel, and learning_mode_windows::EtlDenialAnalyzer canonical decoder. This PR extends that foundation with sandbox job/process-handle attachment, exact descendant lifetime tracking, and a bounded analysis response that feeds the same canonical DenialsDocument output as native capture.

The guarded path:

• Uses the same canonical denial analyzer and DenialsDocument output as native captureDenials.
• Supports block collection through learningModeLogging and allow/audit collection through permissiveLearningMode.
• Starts WPR before the suspended sandbox root resumes.
• Authenticates the unelevated owner and duplicates its sandbox job and root-process handles.
• Opens, job-validates, and retains a handle for every descendant reported by the job completion port.
• Filters host-wide WPR denial events using exact process creation/exit times from those retained handles, preventing PID reuse from expanding capture scope.
• Checks ordered job notifications and TotalProcesses accounting, with a 4096-generation bound.
• Gives the tracker worker independent owned job and completion-port handles. Shutdown posts a sentinel and joins the worker; if bounded waits expire, the guardian fail-stops rather than detaching or releasing handles still in use.
• Keeps raw ETL in protected elevated scratch and returns only bounded canonical denial data.
• Preserves a protected recovery marker on uncertain guardian or pipe failure without issuing blind host-wide WPR cancellation.
• Stops and discards owned traces on definite launch, tracking, or analysis failures.

Runtime resolution locates plm.exe relative to wxc-exec.exe or the loaded mxc_ffi module rather than the caller's working directory. Before elevation, MXC opens the helper with sharing that denies replacement, resolves the pinned object to a stable local DOS path, verifies Authenticode against the pinned handle, requires the embedded signer organization to be Microsoft Corporation, and validates the owner and DACL of the containing directory and its ancestors. The pinned handle remains open across ShellExecuteExW, and the resolved path is launched, preventing file replacement and path-alias check/launch races. The elevated child restricts runtime DLL resolution to System32 and fails closed if that hardening cannot be applied.

Windows artifact packaging, ESRP signing/verification, and SDK package assertions are defined in #834. Unsigned local helpers and helpers in user-writable locations are intentionally rejected, so guarded-WPR end-to-end execution requires a signed packaged plm.exe in a protected directory. This also applies to Rust SDK source consumers whose module-relative lookup resolves beside a locally compiled executable; native PSEC capture remains available when supported.

🔗 References

• Refactor PLM to use the canonical Learning Mode analyzer #760
• Package and sign PLM with Windows binaries #834

🔍 Validation

• cargo fmt --all -- --check
• cargo test -p plm --lib -p mxc_engine — 218 passed, 1 ignored.
• cargo clippy -p plm -p mxc_engine --all-targets -- -D warnings
• Release builds of wxc-exec.exe and plm.exe.
• Windows VM: native PSEC/V2 block capture produced canonical denial output.
• Windows VM guarded fallback:
  • Guarded SBOX block and allow capture passed.
  • Forty short-lived descendants completed without an attestation race.
  • Nonzero sandbox exit code 23 was preserved.
  • A 4100-process workload failed closed at the 4096-generation bound.
  • Successful and bounded-failure paths left no WPR recording, recovery marker, PLM process, or incomplete denial output.
• The runtime signature gate requires an official signed artifact from Package and sign PLM with Windows binaries #834 for signing-dependent VM validation; unofficial PR artifacts are intentionally unsigned and rejected.

✅ Checklist

• Signed the Contributor License Agreement
• Linked to an issue
• Updated documentation (if applicable)
• Updated Copilot instructions (if build, architecture, or conventions changed)
• If this PR changes Cargo.lock, the dependency-feed-check check passes (see docs/pull-requests.md)

📋 Issue Type

• Bug fix
• Feature
• Task

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

Copilot resolve the merge conflicts in this pull request

Resolved the conflicts with current main in merge commit 1d0831d.

[Copilot]

Pull request overview

Copilot reviewed 30 out of 32 changed files in this pull request and generated 2 comments.

Suppressed comments (1)

docs/learning-mode/capabilities.md:139

• The unchanged validation paragraph immediately below still says build 26657.1002 “is rejected,” contradicting this new fallback behavior and the updated OS-support document, which says that build uses legacy containment. Update this block so it distinguishes rejection of native capture from fallback of the overall request.

> **Host selection.** MXC prefers native capture on a feature-enabled Windows
> build exposing the complete official V2 API set:
> `StartLearningModeTrace`, `StopLearningModeTrace`,
> `CloseLearningModeTrace`, `CreateProcessSecurityEnvironment`,
> `QueryProcessSecurityEnvironmentSupport`, and
> `CloseProcessSecurityEnvironment`. When that set is unavailable or cannot
> fully honor the requested policy, MXC retains the highest compatible legacy
> containment tier (SBOX, AppContainer+BFS, or AppContainer+DACL) and pairs it
> with the guarded WPR capture provider. Unsupported hosts return
> `backend_unavailable` only when neither path can preserve the full policy.

[Copilot]

Pull request overview

Copilot reviewed 30 out of 32 changed files in this pull request and generated no new comments.

Suppressed comments (1)

src/backends/appcontainer/common/src/appcontainer_runner.rs:1825

• Returning here permanently skips run_teardown(). Prepared does not clean these policies on drop (NetworkManager::drop only balances Winsock, and FileSystemBfsManager has no Drop), so any job-query error or five-second drain timeout leaves the run's firewall/BFS configuration installed. Preserve the enforcement ordering, but after resolving guarded-capture ownership ensure the last job handle is closed/reaped and then execute policy cleanup rather than abandoning it.

        if let Err(error) = self.kill() {
            capture_output::write_stderr_line_best_effort(format_args!(
                "failed to terminate sandbox job during drop: {error}"
            ));
            self.release_guarded_capture_after_termination_failure();
            return;

[Richie Gomez (richiemsft)]

/azp run

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).

[Gudge (MGudgin)]

Summary

I re-resolved this review against base b960cf5 and head 2463a29; the merge-base exactly matches the PR base, and the local/GitHub diffs are line-for-line equivalent apart from abbreviated index hashes.

I am requesting changes primarily because:

• the new asynchronous process attestation can fail the whole sandbox when a descendant exits before the tracker opens it;
• the security-sensitive attach/resume/discard/release failure orchestration has no runtime regression coverage;
• a wedged guardian can block an embedding process for roughly 40 minutes before aborting it; and
• strict job-drain failures now affect non-capture ProcessContainer runs too.

Verified clean, with receipts

• The exact process-lifetime model records creation/exit times, enforces the 4096-generation bound, and has consumer-side PID-reuse tests.
• Manifest changes add only in-tree workspace dependencies and existing Windows API feature gates; there are no new third-party dependencies or unrelated lockfile drift.
• New security-sensitive modules and dependencies are Windows-gated; shared protocol/lifetime types remain portable and non-Windows paths remain fail-closed.

Body-only findings

Medium (documentation) - PLM's new production role is undocumented. README.md and src/host/plm/readme.md are byte-identical between base and head and still describe PLM strictly as an --audit developer workflow. This PR newly makes PLM the automatic production fallback for processContainer.captureDenials, so those existing statements become false because of this change. Please update both overviews.

Medium (testability) - the new job tracker has no deterministic event seam. JobProcessTracker and ProcessTrackerState are new, but directly consume live completion-port and process APIs. Extracting an injectable job-event/handle-resolver seam would allow deterministic testing of delayed notifications, rapid exits, and process-open failures. This is not independently a merge blocker, but it compounds the missing runtime coverage noted inline.

Low (maintainability) - legacy dispatcher wrappers have no production callers. The old dispatch_with_fallback and spawn_with_fallback wrappers now only delegate to the capture-aware entrypoints, and their remaining workspace callers are tests. Consider keeping one run and one spawn entrypoint that accept an optional guarded-capture factory.

Verified pre-existing or withdrawn - not attributed to this PR

• Global\Mxc_Plm_Audit test isolation is byte-identical at base and head.
• run_guarded_stop replacing an original error when writing the pipe response fails is byte-identical at base and head.
• SDK packaging, ESRP signing, and package assertions are explicitly deferred to #834.
• The original performance claims about retained process handles, 64 MB allocation, and polling were withdrawn: handle retention is a deliberate PID-reuse control, 64 MB is a validated cap rather than an eager allocation, and the cited polling was largely pre-existing.

[Copilot]

Pull request overview

Copilot reviewed 31 out of 33 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 34 out of 36 changed files in this pull request and generated no new comments.

Suppressed comments (2)

src/core/mxc_engine/src/guarded_capture.rs:238

• The new fallback is wired into execution, but the public backend probe still derives CaptureDenials solely from BaseContainerRunner::is_capture_denials_usable() (src/core/mxc_engine/src/probe.rs:73-75), which only tests native PSEC/V2. On exactly the legacy hosts enabled by this change, available_backends() therefore reports that capture is unsupported even when the trusted guarded-WPR path is usable. Update the probe to include guarded fallback availability (compatible legacy tier plus a co-located binary passing the trust gate), so SDK consumers do not incorrectly disable the feature.

pub fn factory_for_request(
    request: &wxc_common::models::ExecutionRequest,
) -> Option<std::sync::Arc<dyn GuardedCaptureFactory>> {
    if request.policy.capture_denials.is_some() {
        Some(std::sync::Arc::new(PlmGuardedCaptureFactory))

docs/learning-mode/capabilities.md:144

• This fallback description is contradicted immediately below by the retained statement that build 26657.1002 “is rejected.” The updated OS-support document says that build uses legacy containment instead of native capture, so this page now gives conflicting host behavior. Update the validation note to say the earlier native contract routes to guarded legacy capture (when that path is available).

> `CloseProcessSecurityEnvironment`. When that set is unavailable or cannot
> fully honor the requested policy, MXC retains the highest compatible legacy
> containment tier (SBOX, AppContainer+BFS, or AppContainer+DACL) and pairs it
> with the guarded WPR capture provider. Unsupported hosts return
> `backend_unavailable` only when neither path can preserve the full policy.

[Copilot]

Pull request overview

Copilot reviewed 34 out of 36 changed files in this pull request and generated no new comments.

Suppressed comments (3)

src/host/plm/src/elevated.rs:638

• Attestation races bypass the advertised 4096-generation bound: only successfully retained processes are counted at line 653, while every failed attestation increments this counter and can add another entry to unattested_active. A sandbox that rapidly creates short-lived children can therefore drive unbounded tracker state and continue well past 4096 generations. Count every observed NEW_PROCESS generation (including races and the root) toward the limit and trigger the existing terminal tracker-failure path once it is exceeded.
  src/backends/appcontainer/common/src/appcontainer_runner.rs:1168
• Permanent guarded-provider failures (missing/untrusted plm.exe, missing WPR) reach this branch as an ordinary WxcError::Process, and spawn() later converts that to a default-phase ScriptResponse, so SDK callers receive backend_error. The updated support contract says an unavailable helper/provider returns backend_unavailable. Preserve a typed failure classification from the factory so prerequisite failures map to FailurePhase::BackendUnavailable, while transient failures such as UAC cancellation can remain launch errors.

                    Err(e) => {
                        // No active trace exists yet -- terminate the
                        // still-suspended child now, before it is ever
                        // resumed, so nothing runs unobserved.
                        job.terminate_and_wait(u32::MAX)

src/backends/appcontainer/common/src/base_container_runner.rs:2184

• All guarded-session start failures are labeled LaunchFailed here, including deterministic host-prerequisite failures such as a missing/untrusted plm.exe or absent WPR. These consequently become backend_error, contradicting the documented backend_unavailable result when the guarded helper is unavailable. Carry a typed start error from the factory and map permanent provider/prerequisite failures to FailurePhase::BackendUnavailable, retaining LaunchFailed for transient cases such as UAC cancellation or singleton contention.

                    return Err(ScriptResponse {
                        failure_phase: FailurePhase::LaunchFailed,
                        ..ScriptResponse::error(&message)

[Copilot]

Pull request overview

Copilot reviewed 34 out of 36 changed files in this pull request and generated no new comments.

Suppressed comments (3)

src/backends/appcontainer/common/src/appcontainer_runner.rs:1168

• Guardian startup failures are flattened to WxcError::Process, and spawn() then wraps them with ScriptResponse::error (FailurePhase::None). Consequently a missing, unsigned, or untrusted plm.exe is exposed by mxc_engine::map_spawn_error as backend_error, even though the updated contract says an unavailable guarded helper is backend_unavailable. Preserve a typed BackendUnavailable result for helper discovery/trust failures while retaining launch errors for transient startup failures.

                    Err(e) => {
                        // No active trace exists yet -- terminate the
                        // still-suspended child now, before it is ever
                        // resumed, so nothing runs unobserved.
                        job.terminate_and_wait(u32::MAX)

src/backends/appcontainer/common/src/base_container_runner.rs:2185

• This classifies every guarded-WPR start failure as LaunchFailed, including deterministic prerequisite failures such as missing or rejected plm.exe. Those cases will never succeed on retry and the updated documentation specifies backend_unavailable; preserve that phase for helper discovery/signature/trust failures, while reserving LaunchFailed for transient failures such as UAC cancellation or singleton contention.

                    return Err(ScriptResponse {
                        failure_phase: FailurePhase::LaunchFailed,
                        ..ScriptResponse::error(&message)
                    });

docs/learning-mode/capabilities.md:144

• The immediately following paragraph still says build 26657.1002 “is rejected,” contradicting this newly documented fallback and the updated OS-version guide, which says that build uses legacy containment. Clarify that only its earlier native contract is rejected and guarded WPR is selected instead.

> `CloseProcessSecurityEnvironment`. When that set is unavailable or cannot
> fully honor the requested policy, MXC retains the highest compatible legacy
> containment tier (SBOX, AppContainer+BFS, or AppContainer+DACL) and pairs it
> with the guarded WPR capture provider. Unsupported hosts return
> `backend_unavailable` only when neither path can preserve the full policy.

[Richie Gomez (richiemsft)]

/azp run

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).

[Gudge (MGudgin)]

Verified the review updates through 4a27b4e.

• 14 original findings are addressed.
• The three partially addressed items and remaining Low legacy-wrapper item are accepted as non-blocking.
• The newly identified non-ASCII trust-path normalization issue is also accepted as non-blocking for this approval.
• cargo fmt --all -- --check passed.
• 675 affected crate tests passed with 0 failures and 1 ignored.