privesc 1.1.2

Small utility library for multi-platform privilege escalation
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104

# privesc
[![Crates.io](https://img.shields.io/crates/v/privesc.svg)](https://crates.io/crates/privesc)
[![Documentation](https://docs.rs/privesc/badge.svg)](https://docs.rs/privesc/)
[![Build status](https://github.com/quincy-rs/privesc/workflows/CI/badge.svg)](https://github.com/quincy-rs/privesc/actions?query=workflow%3ACI)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENCE)
[![Matrix](https://img.shields.io/badge/chat-%23quincy:matrix.org-%2346BC99?logo=matrix)](https://matrix.to/#/#quincy:matrix.org)

Cross-platform privilege escalation for Rust. 

Run commands with elevated privileges on macOS, Linux, and Windows.

## Usage

```rust
use privesc::PrivilegedCommand;

fn main() -> privesc::Result<()> {
    let output = PrivilegedCommand::new("/usr/bin/cat")
        .arg("/etc/shadow")
        .run()?;

    if output.success() {
        if let Some(content) = output.stdout_str() {
            println!("{content}");
        }
    }

    Ok(())
}
```

With all options:

```rust
use privesc::PrivilegedCommand;

let output = PrivilegedCommand::new("/usr/bin/cat")
    .args(["/etc/shadow", "/etc/passwd"])
    .gui(true)
    .prompt("Reading protected files")
    .run()?;
```

### Spawning without blocking

Use `spawn()` to start a privileged process and continue working while it runs:

```rust
use privesc::PrivilegedCommand;

fn main() -> privesc::Result<()> {
    let mut child = PrivilegedCommand::new("/usr/bin/long-task")
        .spawn()?;

    if let Some(id) = child.id() {
        println!("Process started with ID: {id}");
    }

    // Do other work while the process runs...

    // Check if done without blocking
    if let Some(status) = child.try_wait()? {
        println!("Already finished: {status}");
    }

    // Block until completion
    let output = child.wait()?;
    println!("Exit status: {}", output.status);

    Ok(())
}
```

## Platform Behavior

| Platform | GUI mode | CLI mode | Output capture |
|----------|----------|----------|----------------|
| macOS | AppleScript dialog | `sudo` | Yes |
| Linux | `pkexec` | `sudo` | Yes |
| Windows | UAC prompt | UAC prompt | No |

### macOS

GUI mode spawns an AppleScript authentication dialog via `osascript`. CLI mode uses `sudo` with optional custom prompt.

### Linux

GUI mode requires `pkexec` (PolicyKit). Falls back to error if unavailable. CLI mode uses `sudo`. Custom prompts only work in CLI mode due to pkexec limitations.

### Windows

Always shows UAC dialog regardless of `gui` parameter. Custom prompts are ignored (UAC controls the dialog). **stdout/stderr are not captured** — `PrivilegedOutput.stdout` and `.stderr` will be `None`.

## Security Considerations

This library executes commands with root/administrator privileges. Misuse can compromise system security.

**Input validation is your responsibility.** This library does not sanitize inputs. Before calling `Command::run()`:

- Validate `program` is an expected absolute path
- Validate all `args` against an allowlist if derived from user input
- Never pass unsanitized user input to `prompt`

**sudo prompt format strings**: The `prompt` parameter on Unix is passed to `sudo -p`, which interprets `%u`, `%h`, etc. Avoid user-controlled prompt strings or escape `%` characters.