Struct PowerShellSession 

pub struct PowerShellSession { /* private fields */ }

Represents a PowerShell parsing and evaluation session.

This is the main entry point for parsing and evaluating PowerShell scripts. It maintains the session state including variables, tokens, and error information.

Examples

use ps_parser::PowerShellSession;

// Create a new session
let mut session = PowerShellSession::new();

// Evaluate a simple expression
let result = session.safe_eval("$a = 1 + 2; Write-Output $a").unwrap();
assert_eq!(result, "3");

// Parse and get detailed results
let script_result = session.parse_command("$b = 'Hello World'; $b").unwrap();
println!("Result: {:?}", script_result.result());

Implementations

impl<'a> PowerShellSession

pub fn new() -> Self

Creates a new PowerShell parsing session with default settings.

The session is initialized with built-in variables like $true, $false, $null, and special variables like $? for error status tracking.

Returns

A new PowerShellSession instance ready for script evaluation.

Examples

use ps_parser::PowerShellSession;

let mut session = PowerShellSession::new();
let result = session.safe_eval("$true").unwrap();
assert_eq!(result, "True");

Examples found in repository

examples/enc_oneliner.rs (line 11)

fn main() {
    let Some(path) = std::env::args().nth(1) else {
        eprintln!("usage: cargo run --example enc_oneliner -- <script.ps1>");
        std::process::exit(1);
    };
    let script = std::fs::read_to_string(path).unwrap();

    println!("=== parse_command ===");
    match PowerShellSession::new().parse_command(script.trim()) {
        Ok(res) => println!("deob:\n{}\nout:\n{}", res.deobfuscated(), res.output()),
        Err(e) => println!("error: {e:?}"),
    }

    println!("=== parse_script ===");
    match PowerShellSession::new().parse_script(script.trim()) {
        Ok(res) => println!("deob:\n{}\nout:\n{}", res.deobfuscated(), res.output()),
        Err(e) => println!("error: {e:?}"),
    }
}

examples/panic_hunt.rs (line 201)

fn depth_matrix() {
    let patterns: &[(&str, &str, &str)] = &[
        ("paren", "(", ")"),
        ("block", "& {", "}"),
        ("sub", "$(", ")"),
        ("dq", "\"$(", ")\""),
        ("idx", "$a[", "]"),
        ("if", "if(1){", "}"),
        ("ifelse", "if(0){1}else{", "}"),
        ("arr", "@(", ")"),
        ("hash", "@{a=", "}"),
        ("neg", "-(", ")"),
        ("method", "'a'.Replace((", "),'b')"),
        ("plus", "+(", ")"),
        ("not", "!(", ")"),
        ("cast", "[int](", ")"),
        ("sb", "{", "}"),
        ("cmd", "echo (", ")"),
    ];
    let only = std::env::args().nth(2);
    let depths: Vec<usize> = match std::env::args().nth(3) {
        Some(d) => d.split(',').map(|d| d.parse().unwrap()).collect(),
        None => vec![5, 10, 20, 40, 60, 80, 100, 300, 1500, 5000],
    };
    for n in depths {
        println!("--- depth {n}");
        let mut cases: Vec<(String, String)> = patterns
            .iter()
            .filter(|(name, _, _)| only.as_deref().is_none_or(|o| o == "all" || o == *name))
            .map(|(name, o, c)| (name.to_string(), format!("$a=1;{}1{}", o.repeat(n), c.repeat(n))))
            .collect();
        cases.push((
            "func".into(),
            format!("function f($n) {{ if ($n -gt 0) {{ f ($n - 1) }} else {{ 'done' }} }}; f {n}"),
        ));
        for (name, script) in cases {
            let (tx, rx) = std::sync::mpsc::channel();
            std::thread::Builder::new()
                .stack_size(1 << 20)
                .spawn(move || {
                    let t = std::time::Instant::now();
                    let r = PowerShellSession::new().parse_script(&script).map(|r| r.result());
                    let _ = tx.send(format!("{:?} [{} ms]", r, t.elapsed().as_millis()));
                })
                .unwrap();
            let res = rx
                .recv_timeout(std::time::Duration::from_secs(20))
                .unwrap_or_else(|_| "TIMEOUT".into());
            let short: String = res.chars().take(70).collect();
            println!("{name:>7}: {short}");
        }
    }
    std::process::exit(0);
}

fn run(script: &str) -> Option<String> {
    LAST.with(|l| l.borrow_mut().clear());
    let res = panic::catch_unwind(|| {
        let mut ps = PowerShellSession::new();
        let _ = ps.parse_script(script);
        let _ = PowerShellSession::new().parse_command(script);
    });
    // the hook fires even when the parser catches the panic internally
    let last = LAST.with(|l| l.borrow().clone());
    (res.is_err() || !last.is_empty()).then_some(last)
}

fn main() {
    panic::set_hook(Box::new(|info| {
        let loc = info
            .location()
            .map(|l| format!("{}:{}", l.file(), l.line()))
            .unwrap_or_default();
        let msg = info
            .payload()
            .downcast_ref::<&str>()
            .map(|s| s.to_string())
            .or_else(|| info.payload().downcast_ref::<String>().cloned())
            .unwrap_or_default();
        LAST.with(|l| *l.borrow_mut() = format!("{loc} | {msg}"));
    }));

    if std::env::args().nth(1).as_deref() == Some("--depth") {
        depth_matrix();
        return;
    }

    if let Some(script) = std::env::args().nth(1) {
        let (tx, rx) = std::sync::mpsc::channel();
        std::thread::spawn(move || {
            let t = std::time::Instant::now();
            let r = PowerShellSession::new().parse_script(&script).map(|r| r.result());
            let _ = tx.send(format!("[{} ms] {:?}", t.elapsed().as_millis(), r));
        });
        let res = rx
            .recv_timeout(std::time::Duration::from_secs(15))
            .unwrap_or_else(|_| "TIMEOUT".into());
        println!("{}", res.chars().take(200).collect::<String>());
        std::process::exit(0);
    }

    // location -> (count, shortest input)
    let mut found: BTreeMap<String, (usize, String)> = BTreeMap::new();
    let mut record = |input: &str, panic: String| {
        let key = panic.split(" | ").next().unwrap_or_default().to_string();
        let e = found.entry(key).or_insert((0, input.to_string()));
        e.0 += 1;
        if input.len() < e.1.len() {
            e.1 = input.to_string();
        }
        let _ = panic;
    };

    let mut runs = 0;
    for s in TARGETED {
        runs += 1;
        if let Some(p) = run(s) {
            println!("TARGETED PANIC: {s:?}\n    {p}");
            record(s, p);
        }
    }

    let corpus = [
        "test_scripts/comprehensive/input.ps1",
        "test_scripts/parser_focused/input.ps1",
        "test_scripts/stress/input.ps1",
        "test_scripts/enc_oneliner.ps1",
    ];
    for path in corpus {
        // local samples (e.g. enc_oneliner.ps1) are not in the repo
        let Ok(text) = std::fs::read_to_string(path) else {
            continue;
        };
        let lines: Vec<&str> = text.lines().collect();

        // every single line on its own, and every line truncated at each char boundary
        for line in &lines {
            let idxs: Vec<usize> = line.char_indices().map(|(i, _)| i).chain([line.len()]).collect();
            for &i in &idxs {
                runs += 1;
                let s = &line[..i];
                if let Some(p) = run(s) {
                    record(s, p);
                }
            }
        }

        // whole file truncated at every line boundary
        for n in 0..=lines.len() {
            runs += 1;
            let s = lines[..n].join("\n");
            if let Some(p) = run(&s) {
                record(&s, p);
            }
        }
    }

    println!("\n=== {runs} runs, {} distinct panic locations ===", found.len());
    for (loc, (count, input)) in &found {
        let short: String = input.chars().take(160).collect();
        println!("{loc}  (x{count})\n    shortest: {short:?}");
    }
}

pub fn with_variables(self, variables: Variables) -> Self

Creates a new PowerShell session with the provided variables.

This constructor allows you to initialize the session with a custom set of variables, such as environment variables or variables loaded from configuration files.

Arguments

• variables - A Variables instance containing the initial variable set.

Returns

A new PowerShellSession instance with the provided variables.

Examples

use ps_parser::{PowerShellSession, Variables};

let env_vars = Variables::env();
let mut session = PowerShellSession::new().with_variables(env_vars);
let username = session.safe_eval("$env:USERNAME").unwrap();

pub fn safe_eval(&mut self, script: &str) -> Result<String, ParserError>

Safely evaluates a PowerShell script and returns the output as a string.

This method parses and evaluates the provided PowerShell script, handling errors gracefully and returning the result as a formatted string. It’s the recommended method for simple script evaluation.

Arguments

• script - A string slice containing the PowerShell script to evaluate.

Returns

• Result<String, ParserError> - The output of the script evaluation, or an error if parsing/evaluation fails.

Examples

use ps_parser::PowerShellSession;

let mut session = PowerShellSession::new();

// Simple arithmetic
let result = session.safe_eval("1 + 2 * 3").unwrap();
assert_eq!(result, "7");

// Variable assignment and retrieval
let result = session.safe_eval("$name = 'World'; \"Hello $name\"").unwrap();
assert_eq!(result, "Hello World");

pub fn deobfuscate_script( &mut self, script: &str, ) -> Result<String, ParserError>

pub fn env_variables(&self) -> HashMap<String, PsValue>

pub fn session_variables(&self) -> HashMap<String, PsValue>

pub fn parse_script(&mut self, input: &str) -> Result<ScriptResult, ParserError>

Parses and evaluates a PowerShell script, returning detailed results.

This method provides comprehensive information about the parsing and evaluation process, including the final result, generated output, any errors encountered, and the tokenized representation of the script. It’s particularly useful for debugging and deobfuscation.

Arguments

• input - A string slice containing the PowerShell script to parse and evaluate.

Returns

• Result<ScriptResult, ParserError> - A detailed result containing the evaluation outcome, output, errors, and tokens, or a parsing error if the script is malformed.

Examples

use ps_parser::PowerShellSession;

let mut session = PowerShellSession::new();
let script_result = session.parse_command("$a = 42; Write-Output $a").unwrap();

println!("Final result: {:?}", script_result.result());
println!("Generated output: {:?}", script_result.output());
println!("Parsing errors: {:?}", script_result.errors());
println!("Deobfuscated code: {:?}", script_result.deobfuscated());

Examples found in repository

examples/enc_oneliner.rs (line 17)

fn main() {
    let Some(path) = std::env::args().nth(1) else {
        eprintln!("usage: cargo run --example enc_oneliner -- <script.ps1>");
        std::process::exit(1);
    };
    let script = std::fs::read_to_string(path).unwrap();

    println!("=== parse_command ===");
    match PowerShellSession::new().parse_command(script.trim()) {
        Ok(res) => println!("deob:\n{}\nout:\n{}", res.deobfuscated(), res.output()),
        Err(e) => println!("error: {e:?}"),
    }

    println!("=== parse_script ===");
    match PowerShellSession::new().parse_script(script.trim()) {
        Ok(res) => println!("deob:\n{}\nout:\n{}", res.deobfuscated(), res.output()),
        Err(e) => println!("error: {e:?}"),
    }
}

examples/panic_hunt.rs (line 201)

fn depth_matrix() {
    let patterns: &[(&str, &str, &str)] = &[
        ("paren", "(", ")"),
        ("block", "& {", "}"),
        ("sub", "$(", ")"),
        ("dq", "\"$(", ")\""),
        ("idx", "$a[", "]"),
        ("if", "if(1){", "}"),
        ("ifelse", "if(0){1}else{", "}"),
        ("arr", "@(", ")"),
        ("hash", "@{a=", "}"),
        ("neg", "-(", ")"),
        ("method", "'a'.Replace((", "),'b')"),
        ("plus", "+(", ")"),
        ("not", "!(", ")"),
        ("cast", "[int](", ")"),
        ("sb", "{", "}"),
        ("cmd", "echo (", ")"),
    ];
    let only = std::env::args().nth(2);
    let depths: Vec<usize> = match std::env::args().nth(3) {
        Some(d) => d.split(',').map(|d| d.parse().unwrap()).collect(),
        None => vec![5, 10, 20, 40, 60, 80, 100, 300, 1500, 5000],
    };
    for n in depths {
        println!("--- depth {n}");
        let mut cases: Vec<(String, String)> = patterns
            .iter()
            .filter(|(name, _, _)| only.as_deref().is_none_or(|o| o == "all" || o == *name))
            .map(|(name, o, c)| (name.to_string(), format!("$a=1;{}1{}", o.repeat(n), c.repeat(n))))
            .collect();
        cases.push((
            "func".into(),
            format!("function f($n) {{ if ($n -gt 0) {{ f ($n - 1) }} else {{ 'done' }} }}; f {n}"),
        ));
        for (name, script) in cases {
            let (tx, rx) = std::sync::mpsc::channel();
            std::thread::Builder::new()
                .stack_size(1 << 20)
                .spawn(move || {
                    let t = std::time::Instant::now();
                    let r = PowerShellSession::new().parse_script(&script).map(|r| r.result());
                    let _ = tx.send(format!("{:?} [{} ms]", r, t.elapsed().as_millis()));
                })
                .unwrap();
            let res = rx
                .recv_timeout(std::time::Duration::from_secs(20))
                .unwrap_or_else(|_| "TIMEOUT".into());
            let short: String = res.chars().take(70).collect();
            println!("{name:>7}: {short}");
        }
    }
    std::process::exit(0);
}

fn run(script: &str) -> Option<String> {
    LAST.with(|l| l.borrow_mut().clear());
    let res = panic::catch_unwind(|| {
        let mut ps = PowerShellSession::new();
        let _ = ps.parse_script(script);
        let _ = PowerShellSession::new().parse_command(script);
    });
    // the hook fires even when the parser catches the panic internally
    let last = LAST.with(|l| l.borrow().clone());
    (res.is_err() || !last.is_empty()).then_some(last)
}

fn main() {
    panic::set_hook(Box::new(|info| {
        let loc = info
            .location()
            .map(|l| format!("{}:{}", l.file(), l.line()))
            .unwrap_or_default();
        let msg = info
            .payload()
            .downcast_ref::<&str>()
            .map(|s| s.to_string())
            .or_else(|| info.payload().downcast_ref::<String>().cloned())
            .unwrap_or_default();
        LAST.with(|l| *l.borrow_mut() = format!("{loc} | {msg}"));
    }));

    if std::env::args().nth(1).as_deref() == Some("--depth") {
        depth_matrix();
        return;
    }

    if let Some(script) = std::env::args().nth(1) {
        let (tx, rx) = std::sync::mpsc::channel();
        std::thread::spawn(move || {
            let t = std::time::Instant::now();
            let r = PowerShellSession::new().parse_script(&script).map(|r| r.result());
            let _ = tx.send(format!("[{} ms] {:?}", t.elapsed().as_millis(), r));
        });
        let res = rx
            .recv_timeout(std::time::Duration::from_secs(15))
            .unwrap_or_else(|_| "TIMEOUT".into());
        println!("{}", res.chars().take(200).collect::<String>());
        std::process::exit(0);
    }

    // location -> (count, shortest input)
    let mut found: BTreeMap<String, (usize, String)> = BTreeMap::new();
    let mut record = |input: &str, panic: String| {
        let key = panic.split(" | ").next().unwrap_or_default().to_string();
        let e = found.entry(key).or_insert((0, input.to_string()));
        e.0 += 1;
        if input.len() < e.1.len() {
            e.1 = input.to_string();
        }
        let _ = panic;
    };

    let mut runs = 0;
    for s in TARGETED {
        runs += 1;
        if let Some(p) = run(s) {
            println!("TARGETED PANIC: {s:?}\n    {p}");
            record(s, p);
        }
    }

    let corpus = [
        "test_scripts/comprehensive/input.ps1",
        "test_scripts/parser_focused/input.ps1",
        "test_scripts/stress/input.ps1",
        "test_scripts/enc_oneliner.ps1",
    ];
    for path in corpus {
        // local samples (e.g. enc_oneliner.ps1) are not in the repo
        let Ok(text) = std::fs::read_to_string(path) else {
            continue;
        };
        let lines: Vec<&str> = text.lines().collect();

        // every single line on its own, and every line truncated at each char boundary
        for line in &lines {
            let idxs: Vec<usize> = line.char_indices().map(|(i, _)| i).chain([line.len()]).collect();
            for &i in &idxs {
                runs += 1;
                let s = &line[..i];
                if let Some(p) = run(s) {
                    record(s, p);
                }
            }
        }

        // whole file truncated at every line boundary
        for n in 0..=lines.len() {
            runs += 1;
            let s = lines[..n].join("\n");
            if let Some(p) = run(&s) {
                record(&s, p);
            }
        }
    }

    println!("\n=== {runs} runs, {} distinct panic locations ===", found.len());
    for (loc, (count, input)) in &found {
        let short: String = input.chars().take(160).collect();
        println!("{loc}  (x{count})\n    shortest: {short:?}");
    }
}

pub fn parse_command( &mut self, input: &str, ) -> Result<ScriptResult, ParserError>

Examples found in repository

examples/panic_hunt.rs (line 220)

fn run(script: &str) -> Option<String> {
    LAST.with(|l| l.borrow_mut().clear());
    let res = panic::catch_unwind(|| {
        let mut ps = PowerShellSession::new();
        let _ = ps.parse_script(script);
        let _ = PowerShellSession::new().parse_command(script);
    });
    // the hook fires even when the parser catches the panic internally
    let last = LAST.with(|l| l.borrow().clone());
    (res.is_err() || !last.is_empty()).then_some(last)
}

examples/enc_oneliner.rs (line 11)

fn main() {
    let Some(path) = std::env::args().nth(1) else {
        eprintln!("usage: cargo run --example enc_oneliner -- <script.ps1>");
        std::process::exit(1);
    };
    let script = std::fs::read_to_string(path).unwrap();

    println!("=== parse_command ===");
    match PowerShellSession::new().parse_command(script.trim()) {
        Ok(res) => println!("deob:\n{}\nout:\n{}", res.deobfuscated(), res.output()),
        Err(e) => println!("error: {e:?}"),
    }

    println!("=== parse_script ===");
    match PowerShellSession::new().parse_script(script.trim()) {
        Ok(res) => println!("deob:\n{}\nout:\n{}", res.deobfuscated(), res.output()),
        Err(e) => println!("error: {e:?}"),
    }
}

Trait Implementations

impl Clone for PowerShellSession

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for PowerShellSession

fn default() -> Self

Returns the “default value” for a type.