privesc 1.2.0

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
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

use crate::PrivilegedOutput;
use crate::error::{PrivescError, Result};
use std::path::Path;
use std::process::{Child, Command, ExitStatus, Stdio};

/// Platform-specific handle to a spawned privileged process.
///
/// This struct wraps the underlying process and provides methods to wait for
/// completion and retrieve the output.
pub struct PrivilegedChildInner {
    child: Child,
}

impl PrivilegedChildInner {
    /// Waits for the process to exit and returns the output.
    ///
    /// This method consumes the handle and blocks until the process
    /// has finished executing.
    pub fn wait(self) -> Result<PrivilegedOutput> {
        let output = self.child.wait_with_output()?;
        Ok(PrivilegedOutput {
            status: output.status,
            stdout: Some(output.stdout),
            stderr: Some(output.stderr),
        })
    }

    /// Attempts to collect the exit status of the child if it has already exited.
    ///
    /// This method will not block. Returns `Ok(None)` if the process has not
    /// yet exited.
    pub fn try_wait(&mut self) -> Result<Option<ExitStatus>> {
        Ok(self.child.try_wait()?)
    }

    /// Returns the OS-assigned process identifier of the child process, if available.
    pub fn id(&self) -> Option<u32> {
        Some(self.child.id())
    }
}

/// Spawn a program with elevated privileges using `pkexec`.
///
/// # Args:
/// - `program` - The path to the program to execute.
/// - `args` - The arguments to pass to the program.
///
/// # Returns:
/// - `Result<PrivilegedChildInner>` - A handle to the spawned process.
fn spawn_gui(program: &Path, args: &[&str]) -> Result<PrivilegedChildInner> {
    let pkexec_path = which::which("pkexec")
        .map_err(|_| PrivescError::PrivilegeEscalationToolNotFound("pkexec".to_string()))?;

    let process = Command::new(pkexec_path)
        .arg(program)
        .args(args)
        .stdin(Stdio::piped())
        .stdout(Stdio::piped())
        .stderr(Stdio::piped())
        .spawn()?;

    Ok(PrivilegedChildInner { child: process })
}

/// Spawn a program with elevated privileges using `sudo`.
///
/// # Args:
/// - `program` - The path to the program to execute.
/// - `args` - The arguments to pass to the program.
/// - `prompt` - The prompt to display to the user.
///
/// # Returns:
/// - `Result<PrivilegedChildInner>` - A handle to the spawned process.
fn spawn_cli(program: &Path, args: &[&str], prompt: Option<&str>) -> Result<PrivilegedChildInner> {
    let mut command = Command::new("sudo");

    if let Some(prompt) = prompt {
        command.arg("-p").arg(prompt);
    }

    let process = command
        .arg("--")
        .arg(program)
        .args(args)
        .stdin(Stdio::piped())
        .stdout(Stdio::piped())
        .stderr(Stdio::piped())
        .spawn()?;

    Ok(PrivilegedChildInner { child: process })
}

/// Spawn a program with elevated privileges using either `pkexec` or `sudo`.
///
/// # Args:
/// - `program` - The path to the program to execute.
/// - `args` - The arguments to pass to the program.
/// - `gui` - Whether to prompt the user for a password using GUI or sudo.
/// - `prompt` - The prompt to display to the user. Only used if `gui` is false due to `pkexec` limitations.
///
/// # Returns:
/// - `Result<PrivilegedChildInner>` - A handle to the spawned process.
pub fn spawn(
    program: &Path,
    args: &[&str],
    gui: bool,
    prompt: Option<&str>,
) -> Result<PrivilegedChildInner> {
    if gui {
        spawn_gui(program, args)
    } else {
        spawn_cli(program, args, prompt)
    }
}

/// Execute a program with elevated privileges using either `pkexec` or `sudo`.
///
/// # Args:
/// - `program` - The path to the program to execute.
/// - `args` - The arguments to pass to the program.
/// - `gui` - Whether to prompt the user for a password using GUI or sudo.
/// - `prompt` - The prompt to display to the user. Only used if `gui` is false due to `pkexec` limitations.
///
/// # Returns:
/// - `Result<PrivilegedOutput>` - The output of the program.
pub fn run(
    program: &Path,
    args: &[&str],
    gui: bool,
    prompt: Option<&str>,
) -> Result<PrivilegedOutput> {
    spawn(program, args, gui, prompt)?.wait()
}