Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

fix(cua-driver): explain elevated-token refusal of Windows isolated browsers (#4178)

Francesco Bonacciec96f96b48ed
diff --git a/docs/content/docs/how-to-guides/driver/jev-use.mdx b/docs/content/docs/how-to-guides/driver/jev-use.mdx
index 4097763a62..b6b279cd82 100644
--- a/docs/content/docs/how-to-guides/driver/jev-use.mdx
+++ b/docs/content/docs/how-to-guides/driver/jev-use.mdx
@@ -65,6 +65,14 @@ session. Install Google Chrome or Microsoft Edge as a system application.
Run Driver without elevation too: automatic browser discovery requires an
installation the running account's token cannot modify.
+An elevated or administrator token can modify `Program Files`, so Driver
+refuses its signed Chrome and Edge. `browser_prepare` then fails with
+`browser_route_unavailable` and a message that says the installed browser is
+writable by the current elevated or administrator token. Some cloud Windows
+images make the first user the built-in Administrator account (SID ending in
+`-500`). That account always runs elevated, even with UAC enabled. Sign in as
+a standard user instead, or run Driver from a non-elevated session.
+
```powershell
cua-driver --version
cua-driver status
diff --git a/libs/cua-driver/examples/jev-use/README.md b/libs/cua-driver/examples/jev-use/README.md
index abac7a1f96..7f0b12b566 100644
--- a/libs/cua-driver/examples/jev-use/README.md
+++ b/libs/cua-driver/examples/jev-use/README.md
@@ -87,7 +87,9 @@ npm ci
```
On Windows, use a non-administrator desktop session and `npm.cmd ci` in
-PowerShell. The managed verifier starts TypeScript through `node --import tsx`,
+PowerShell. An elevated session, including the built-in Administrator account
+that some cloud images create as the first user, makes Driver refuse the
+installed browser as writable by the current token. The managed verifier starts TypeScript through `node --import tsx`,
not an npm shell shim. On Linux, use a supported system browser and a desktop
session accessible to the same user as Driver; native Wayland has separate
compositor-specific requirements.
diff --git a/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md b/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md
index bde42c153c..f71f7a39b3 100644
--- a/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md
+++ b/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md
@@ -135,6 +135,11 @@ order: Google Chrome, then Microsoft Edge. On Linux it accepts exact
root-owned, non-group/world-writable package payloads in this order: Google
Chrome, Chromium, then Microsoft Edge. User application directories, `PATH`
entries, redirected paths, and unsigned or mismatched products fail closed.
+On Windows, the installation must also be unmodifiable by the Driver's token.
+An elevated or built-in Administrator token can write `Program Files`, so the
+refusal then says the installed Chrome/Edge is writable by the current
+elevated or administrator token. Run Driver from a non-administrator session
+in that case; the browser is not missing or unsigned.
Supply a Chromium-family browser pid when the isolated launch must use that
process's exact executable, including Chromium on macOS or Windows. The pid
remains required for existing-profile attachment.
diff --git a/libs/cua-driver/rust/crates/platform-windows/src/browser_isolated_selection.rs b/libs/cua-driver/rust/crates/platform-windows/src/browser_isolated_selection.rs
new file mode 100644
index 0000000000..80400e1e84
--- /dev/null
+++ b/libs/cua-driver/rust/crates/platform-windows/src/browser_isolated_selection.rs
@@ -0,0 +1,247 @@
+//! Pure decision logic for choosing the Windows isolated-launch browser.
+//!
+//! The Windows adapter gathers facts about each trusted Chrome and Edge
+//! installation (present, write access for the current token, vendor
+//! signature) and this module turns them into either a launch choice or a
+//! refusal message. It has no Win32 dependencies so its unit tests run on any
+//! host.
+//!
+//! The security rule is unchanged by the diagnostic: a candidate launches only
+//! when it is installed, protected from the current token, and vendor-signed.
+//! The distinct message exists because an elevated or built-in Administrator
+//! token can write `Program Files`, so correctly signed browsers are refused
+//! for that token. Reporting that case as "no vendor-signed executable"
+//! wrongly implies the browser is missing or unsigned.
+
+/// Whether the current token can modify a candidate's installation tree.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum InstallationWriteAccess {
+ /// The executable and every ancestor up to the trusted root deny write
+ /// access to the current token.
+ Protected,
+ /// The current token was granted a write-class right on the executable or
+ /// an ancestor (typical for elevated and built-in Administrator tokens).
+ WritableByCurrentToken,
+ /// The path is outside the trusted root or a write probe failed closed.
+ Untrusted,
+}
+
+/// Facts about one isolated-launch candidate, in product-preference order.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct IsolatedCandidateFacts {
+ /// Human-readable product name used in the refusal message.
+ pub product: &'static str,
+ /// The executable exists at its trusted path without redirection.
+ pub installed: bool,
+ pub write_access: InstallationWriteAccess,
+ /// The executable carries the expected vendor Authenticode identity. The
+ /// adapter evaluates this only for installed candidates whose write access
+ /// is `Protected` or `WritableByCurrentToken`; otherwise it is `false`.
+ pub vendor_signed: bool,
+}
+
+impl IsolatedCandidateFacts {
+ pub(crate) fn missing(product: &'static str) -> Self {
+ Self {
+ product,
+ installed: false,
+ write_access: InstallationWriteAccess::Untrusted,
+ vendor_signed: false,
+ }
+ }
+
+ /// Whether this candidate satisfies every isolated-launch requirement.
+ pub(crate) fn launchable(&self) -> bool {
+ self.installed
+ && self.write_access == InstallationWriteAccess::Protected
+ && self.vendor_signed
+ }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) enum IsolatedBrowserDecision {
+ /// Launch the candidate at this index.
+ Launch(usize),
+ /// Refuse with `browser_route_unavailable` and this message.
+ Refuse(String),
+}
+
+pub(crate) const NO_PROTECTED_BROWSER_MESSAGE: &str =
+ "no vendor-signed protected Chromium executable is available for isolated launch";
+
+/// Choose the first launchable candidate, or explain why none qualifies.
+pub(crate) fn decide_isolated_browser(
+ candidates: &[IsolatedCandidateFacts],
+) -> IsolatedBrowserDecision {
+ if let Some(index) = candidates
+ .iter()
+ .position(IsolatedCandidateFacts::launchable)
+ {
+ return IsolatedBrowserDecision::Launch(index);
+ }
+ let mut writable_products: Vec<&str> = Vec::new();
+ for candidate in candidates {
+ if candidate.installed
+ && candidate.vendor_signed
+ && candidate.write_access == InstallationWriteAccess::WritableByCurrentToken
+ && !writable_products.contains(&candidate.product)
+ {
+ writable_products.push(candidate.product);
+ }
+ }
+ if writable_products.is_empty() {
+ return IsolatedBrowserDecision::Refuse(NO_PROTECTED_BROWSER_MESSAGE.to_owned());
+ }
+ IsolatedBrowserDecision::Refuse(format!(
+ "installed vendor-signed {} is writable by the current elevated or administrator token, \
+ so Cua Driver refuses to launch it for an isolated browser; run Cua Driver from a \
+ non-administrator, non-elevated session (the built-in Administrator account is always \
+ elevated)",
+ writable_products.join("/"),
+ ))
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn candidate(
+ product: &'static str,
+ write_access: InstallationWriteAccess,
+ vendor_signed: bool,
+ ) -> IsolatedCandidateFacts {
+ IsolatedCandidateFacts {
+ product,
+ installed: true,
+ write_access,
+ vendor_signed,
+ }
+ }
+
+ fn refusal_message(decision: IsolatedBrowserDecision) -> String {
+ match decision {
+ IsolatedBrowserDecision::Refuse(message) => message,
+ other => panic!("expected refusal, got {other:?}"),
+ }
+ }
+
+ #[test]
+ fn no_installed_candidate_keeps_generic_message() {
+ let facts = [
+ IsolatedCandidateFacts::missing("Chrome"),
+ IsolatedCandidateFacts::missing("Edge"),
+ ];
+ assert_eq!(
+ refusal_message(decide_isolated_browser(&facts)),
+ NO_PROTECTED_BROWSER_MESSAGE
+ );
+ assert_eq!(
+ refusal_message(decide_isolated_browser(&[])),
+ NO_PROTECTED_BROWSER_MESSAGE
+ );
+ }
+
+ #[test]
+ fn installed_but_unsigned_candidate_keeps_generic_message() {
+ let facts = [
+ candidate("Chrome", InstallationWriteAccess::Protected, false),
+ candidate(
+ "Edge",
+ InstallationWriteAccess::WritableByCurrentToken,
+ false,
+ ),
+ ];
+ assert_eq!(
+ refusal_message(decide_isolated_browser(&facts)),
+ NO_PROTECTED_BROWSER_MESSAGE
+ );
+ }
+
+ #[test]
+ fn untrusted_location_keeps_generic_message() {
+ let facts = [candidate(
+ "Chrome",
+ InstallationWriteAccess::Untrusted,
+ false,
+ )];
+ assert_eq!(
+ refusal_message(decide_isolated_browser(&facts)),
+ NO_PROTECTED_BROWSER_MESSAGE
+ );
+ }
+
+ #[test]
+ fn signed_but_writable_candidates_get_elevated_token_message() {
+ let facts = [
+ candidate(
+ "Chrome",
+ InstallationWriteAccess::WritableByCurrentToken,
+ true,
+ ),
+ IsolatedCandidateFacts::missing("Chrome"),
+ candidate(
+ "Edge",
+ InstallationWriteAccess::WritableByCurrentToken,
+ true,
+ ),
+ candidate(
+ "Edge",
+ InstallationWriteAccess::WritableByCurrentToken,
+ true,
+ ),
+ ];
+ let message = refusal_message(decide_isolated_browser(&facts));
+ assert_ne!(message, NO_PROTECTED_BROWSER_MESSAGE);
+ assert!(message.starts_with("installed vendor-signed Chrome/Edge is writable"));
+ assert!(message.contains("elevated or administrator token"));
+ assert!(message.contains("non-administrator"));
+ }
+
+ #[test]
+ fn writable_message_names_only_signed_writable_products() {
+ let facts = [
+ candidate("Chrome", InstallationWriteAccess::Protected, false),
+ candidate(
+ "Edge",
+ InstallationWriteAccess::WritableByCurrentToken,
+ true,
+ ),
+ ];
+ let message = refusal_message(decide_isolated_browser(&facts));
+ assert!(message.starts_with("installed vendor-signed Edge is writable"));
+ }
+
+ #[test]
+ fn one_protected_signed_candidate_wins_over_writable_ones() {
+ let facts = [
+ candidate(
+ "Chrome",
+ InstallationWriteAccess::WritableByCurrentToken,
+ true,
+ ),
+ IsolatedCandidateFacts::missing("Chrome"),
+ candidate("Edge", InstallationWriteAccess::Protected, true),
+ candidate("Edge", InstallationWriteAccess::Protected, true),
+ ];
+ assert_eq!(
+ decide_isolated_browser(&facts),
+ IsolatedBrowserDecision::Launch(2)
+ );
+ }
+
+ #[test]
+ fn launchable_requires_every_condition() {
+ assert!(candidate("Chrome", InstallationWriteAccess::Protected, true).launchable());
+ assert!(!candidate("Chrome", InstallationWriteAccess::Protected, false).launchable());
+ assert!(!candidate(
+ "Chrome",
+ InstallationWriteAccess::WritableByCurrentToken,
+ true
+ )
+ .launchable());
+ assert!(!candidate("Chrome", InstallationWriteAccess::Untrusted, true).launchable());
+ let mut missing = candidate("Chrome", InstallationWriteAccess::Protected, true);
+ missing.installed = false;
+ assert!(!missing.launchable());
+ }
+}
diff --git a/libs/cua-driver/rust/crates/platform-windows/src/browser_platform.rs b/libs/cua-driver/rust/crates/platform-windows/src/browser_platform.rs
index 7dc73c6058..18449713e0 100644
--- a/libs/cua-driver/rust/crates/platform-windows/src/browser_platform.rs
+++ b/libs/cua-driver/rust/crates/platform-windows/src/browser_platform.rs
@@ -23,6 +23,11 @@ use cua_driver_core::browser::{
existing_profile_setup_descriptor, is_firefox, parse_devtools_active_port, BrowserCursorTracker,
};
use tokio::io::{AsyncReadExt, AsyncWriteExt};
+
+use crate::browser_isolated_selection::{
+ decide_isolated_browser, InstallationWriteAccess, IsolatedBrowserDecision,
+ IsolatedCandidateFacts, NO_PROTECTED_BROWSER_MESSAGE,
+};
use windows::core::PCWSTR;
use windows::Win32::Foundation::{CloseHandle, E_ACCESSDENIED, FILETIME, HWND, RECT};
use windows::Win32::Storage::FileSystem::{
@@ -215,7 +220,22 @@ fn authenticode_output(executable: &std::path::Path) -> std::io::Result<std::pro
.output()
}
+/// Result of probing one path for write-class rights held by the current token.
+enum WriteProbe {
+ Denied,
+ Granted(&'static str),
+ Failed(String),
+}
+
fn current_token_write_denial_reason(path: &std::path::Path, directory: bool) -> Option<String> {
+ match current_token_write_probe(path, directory) {
+ WriteProbe::Denied => None,
+ WriteProbe::Granted(name) => Some(format!("current token was granted {name}")),
+ WriteProbe::Failed(reason) => Some(reason),
+ }
+}
+
+fn current_token_write_probe(path: &std::path::Path, directory: bool) -> WriteProbe {
use std::os::windows::ffi::OsStrExt;
// This launch boundary protects the current agent token from executing a
@@ -267,45 +287,90 @@ fn current_token_write_denial_reason(path: &std::path::Path, directory: bool) ->
} {
Ok(handle) => {
let _ = unsafe { CloseHandle(handle) };
- return Some(format!("current token was granted {name}"));
+ return WriteProbe::Granted(name);
}
Err(error) if error.code() == E_ACCESSDENIED => {}
- Err(error) => return Some(format!("{name} probe failed closed: {error}")),
+ Err(error) => {
+ return WriteProbe::Failed(format!("{name} probe failed closed: {error}"))
+ }
}
}
- None
+ WriteProbe::Denied
}
-fn current_token_cannot_write(path: &std::path::Path, directory: bool) -> bool {
- current_token_write_denial_reason(path, directory).is_none()
+fn windows_installation_write_access(
+ executable: &std::path::Path,
+ trusted_root: &std::path::Path,
+) -> InstallationWriteAccess {
+ windows_installation_write_access_with_probe(
+ executable,
+ trusted_root,
+ current_token_write_probe,
+ )
}
+#[cfg(test)]
fn trusted_windows_installation(
executable: &std::path::Path,
trusted_root: &std::path::Path,
) -> bool {
- trusted_windows_installation_with_probe(executable, trusted_root, current_token_cannot_write)
+ windows_installation_write_access(executable, trusted_root)
+ == InstallationWriteAccess::Protected
}
+#[cfg(test)]
fn trusted_windows_installation_with_probe(
executable: &std::path::Path,
trusted_root: &std::path::Path,
mut cannot_write: impl FnMut(&std::path::Path, bool) -> bool,
) -> bool {
- if !executable.starts_with(trusted_root) || !cannot_write(executable, false) {
- return false;
+ windows_installation_write_access_with_probe(executable, trusted_root, |path, directory| {
+ if cannot_write(path, directory) {
+ WriteProbe::Denied
+ } else {
+ WriteProbe::Granted("test_write")
+ }
+ }) == InstallationWriteAccess::Protected
+}
+
+/// Walk the executable and every ancestor up to `trusted_root`, requiring
+/// each probe to deny write access. The first non-denied probe decides the
+/// rejection kind: a granted right is `WritableByCurrentToken`, a failed probe
+/// is `Untrusted` (fail closed).
+fn windows_installation_write_access_with_probe(
+ executable: &std::path::Path,
+ trusted_root: &std::path::Path,
+ mut probe: impl FnMut(&std::path::Path, bool) -> WriteProbe,
+) -> InstallationWriteAccess {
+ let rejection = |result: WriteProbe| match result {
+ WriteProbe::Denied => None,
+ WriteProbe::Granted(_) => Some(InstallationWriteAccess::WritableByCurrentToken),
+ WriteProbe::Failed(_) => Some(InstallationWriteAccess::Untrusted),
+ };
+ if !executable.starts_with(trusted_root) {
+ return InstallationWriteAccess::Untrusted;
+ }
+ if let Some(rejected) = rejection(probe(executable, false)) {
+ return rejected;
}
let mut current = executable.parent();
while let Some(directory) = current {
- if !cannot_write(directory, true) {
- return false;
+ if let Some(rejected) = rejection(probe(directory, true)) {
+ return rejected;
}
if directory == trusted_root {
- return true;
+ return InstallationWriteAccess::Protected;
}
current = directory.parent();
}
- false
+ InstallationWriteAccess::Untrusted
+}
+
+fn isolated_browser_product_name(executable: &std::path::Path) -> &'static str {
+ match browser_product(&executable.to_string_lossy()) {
+ BrowserProduct::MicrosoftEdge => "Edge",
+ _ => "Chrome",
+ }
}
fn default_user_data_dir(product: BrowserProduct) -> Option<PathBuf> {
@@ -1236,24 +1301,49 @@ where
#[async_trait]
impl BrowserPlatform for WindowsBrowserPlatform {
fn isolated_browser_executable(&self) -> Result<String, BrowserRefusal> {
+ let mut facts = Vec::new();
+ let mut executables = Vec::new();
for (candidate, trusted_root, expected_cn, expected_org) in isolated_browser_candidates()? {
+ let product = isolated_browser_product_name(&candidate);
let Ok(executable) = select_isolated_browser_executable([candidate.clone()]) else {
+ facts.push(IsolatedCandidateFacts::missing(product));
+ executables.push(None);
continue;
};
- if trusted_windows_installation(&candidate, &trusted_root)
+ let write_access = windows_installation_write_access(&candidate, &trusted_root);
+ // The signature of a writable candidate is read only to explain
+ // the refusal; such a candidate is never launched.
+ let vendor_signed = write_access != InstallationWriteAccess::Untrusted
&& has_trusted_authenticode_identity(
std::path::Path::new(&executable),
expected_cn,
expected_org,
- )
- {
- return Ok(executable);
+ );
+ let fact = IsolatedCandidateFacts {
+ product,
+ installed: true,
+ write_access,
+ vendor_signed,
+ };
+ let launchable = fact.launchable();
+ facts.push(fact);
+ executables.push(Some(executable));
+ if launchable {
+ break;
}
}
- Err(refusal(
- BrowserRefusalCode::BrowserRouteUnavailable,
- "no vendor-signed protected Chromium executable is available for isolated launch",
- ))
+ match decide_isolated_browser(&facts) {
+ IsolatedBrowserDecision::Launch(index) => executables[index].take().ok_or_else(|| {
+ refusal(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ NO_PROTECTED_BROWSER_MESSAGE,
+ )
+ }),
+ IsolatedBrowserDecision::Refuse(message) => Err(refusal(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ message,
+ )),
+ }
}
async fn visualize_browser_action(&self, action: BrowserVisualAction) {
@@ -2008,6 +2098,52 @@ mod tests {
));
}
+ #[test]
+ fn installation_write_access_distinguishes_granted_from_failed_probes() {
+ let root = std::path::Path::new(r"C:\Program Files");
+ let executable = root.join(r"Google\Chrome\Application\chrome.exe");
+
+ assert_eq!(
+ windows_installation_write_access_with_probe(&executable, root, |_, _| {
+ WriteProbe::Denied
+ }),
+ InstallationWriteAccess::Protected
+ );
+ assert_eq!(
+ windows_installation_write_access_with_probe(&executable, root, |path, directory| {
+ if directory && path == root {
+ WriteProbe::Granted("add_file")
+ } else {
+ WriteProbe::Denied
+ }
+ }),
+ InstallationWriteAccess::WritableByCurrentToken
+ );
+ assert_eq!(
+ windows_installation_write_access_with_probe(&executable, root, |_, directory| {
+ if directory {
+ WriteProbe::Denied
+ } else {
+ WriteProbe::Failed("write_data probe failed closed".to_owned())
+ }
+ }),
+ InstallationWriteAccess::Untrusted
+ );
+ assert_eq!(
+ windows_installation_write_access_with_probe(
+ std::path::Path::new(r"D:\UserControlled\chrome.exe"),
+ root,
+ |_, _| WriteProbe::Denied,
+ ),
+ InstallationWriteAccess::Untrusted
+ );
+ assert_eq!(isolated_browser_product_name(&executable), "Chrome");
+ assert_eq!(
+ isolated_browser_product_name(&root.join(r"Microsoft\Edge\Application\msedge.exe")),
+ "Edge"
+ );
+ }
+
#[test]
fn installed_vendor_browser_tree_is_accepted_only_for_a_nonwritable_token() {
let candidates = isolated_browser_candidates().expect("trusted Known Folder roots");
diff --git a/libs/cua-driver/rust/crates/platform-windows/src/lib.rs b/libs/cua-driver/rust/crates/platform-windows/src/lib.rs
index e74100605a..0563c366f9 100644
--- a/libs/cua-driver/rust/crates/platform-windows/src/lib.rs
+++ b/libs/cua-driver/rust/crates/platform-windows/src/lib.rs
@@ -52,6 +52,11 @@ pub mod history;
#[cfg(target_os = "windows")]
pub mod browser_platform;
+// Pure isolated-browser selection decision; cfg-independent so its unit
+// tests run on any host.
+#[cfg(any(target_os = "windows", test))]
+mod browser_isolated_selection;
+
#[cfg(target_os = "windows")]
mod browser_consent_ui;
#[cfg(target_os = "windows")]