Module refinery.units.scripting.ps1

Classes

class ps1 (timeout=500, keep_output=False)

AST-based PowerShell deobfuscator.

Parses the script into an abstract syntax tree, applies simplifying transformations (constant folding, format string evaluation, bracket removal, type cast simplification, string operations, case normalization, invoke simplification, uncurly variables), and synthesizes clean output. Iterates until stable; running this twice does not change the output.

What the output preserves. Every side effect the script performs, and every value that anything other than the console could read. In PowerShell a statement that merely yields a value has written to the success output stream, so a bare 'literal' or 42 is output like any other. Such a statement is deleted only where three things are provable at once: that evaluating it cannot raise, that its value reaches the process output and nothing else — traced through every call site, so a bare value inside a function is kept unless every caller merely prints it — and that no redirection moves that output elsewhere. Anything that fails one of them is kept, as is every statement that does something, whatever it writes.

That leaves a real class of junk standing. [Math]::Sqrt(36) and Get-Random are removed by neither model, because nothing here can prove a call does not throw.

The assumption behind the default. Stripping console output treats the input as a standalone script. A file cannot say whether it is a module: a .psm1 exports its functions to callers no walk over this tree can see, and a bare value inside such a function is part of what those callers receive. Use the switch for a module, for a fragment that runs as part of something larger, or whenever the printed output is itself the artifact.

Expand source code Browse git

class ps1(IterativeDeobfuscator):
    """
    AST-based PowerShell deobfuscator.

    Parses the script into an abstract syntax tree, applies simplifying transformations (constant
    folding, format string evaluation, bracket removal, type cast simplification, string
    operations, case normalization, invoke simplification, uncurly variables), and synthesizes
    clean output. Iterates until stable; running this twice does not change the output.

    **What the output preserves.** Every side effect the script performs, and every value that
    anything other than the console could read. In PowerShell a statement that merely yields a value
    has written to the success output stream, so a bare `'literal'` or `42` is output like any
    other. Such a statement is deleted only where three things are provable at once: that evaluating
    it cannot raise, that its value reaches the process output and nothing else — traced through
    every call site, so a bare value inside a function is kept unless every caller merely prints it
    — and that no redirection moves that output elsewhere. Anything that fails one of them is kept,
    as is every statement that does something, whatever it writes.

    That leaves a real class of junk standing. `[Math]::Sqrt(36)` and `Get-Random` are removed by
    neither model, because nothing here can prove a call does not throw.

    **The assumption behind the default.** Stripping console output treats the input as a standalone
    script. A file cannot say whether it is a module: a `.psm1` exports its functions to callers no
    walk over this tree can see, and a bare value inside such a function is part of what those
    callers receive. Use the switch for a module, for a fragment that runs as part of something
    larger, or whenever the printed output is itself the artifact.
    """

    def __init__(
        self,
        timeout=500,
        keep_output: Param[bool, Arg.Switch('-k', help=(
            'Keep every statement that writes a value to the success output stream, including bare '
            'literals an obfuscator injected as noise. Use this when the input is a module or a '
            'fragment of a larger script, where such a value can reach a caller rather than only '
            'the console.'))] = False,
    ):
        super().__init__(timeout=timeout, keep_output=keep_output)

    def parse(self, data: str) -> Ps1Script:
        return Ps1Parser(data).parse()

    def transform(self, ast: Ps1Script) -> int:
        return deobfuscate(ast, preserve_bare_output=self.args.keep_output)

    def synthesize(self, ast: Ps1Script) -> str:
        return Ps1Synthesizer().convert(ast)

Ancestors

• IterativeDeobfuscator
• Unit
• UnitBase
• Entry

Subclasses

• ps1

Class variables

var reverse

The type of the None singleton.

Methods

def parse(self, data)

Expand source code Browse git

def parse(self, data: str) -> Ps1Script:
    return Ps1Parser(data).parse()

def transform(self, ast)

Expand source code Browse git

def transform(self, ast: Ps1Script) -> int:
    return deobfuscate(ast, preserve_bare_output=self.args.keep_output)

def synthesize(self, ast)

Expand source code Browse git

def synthesize(self, ast: Ps1Script) -> str:
    return Ps1Synthesizer().convert(ast)

Inherited members

• IterativeDeobfuscator:
  • FilterEverything
  • Requires
  • act
  • assemble
  • carved
  • codec
  • console
  • filter
  • finish
  • handles
  • is_quiet
  • is_reversible
  • isatty
  • labelled
  • leniency
  • log_always
  • log_debug
  • log_detach
  • log_fail
  • log_info
  • log_level
  • log_warn
  • logger
  • name
  • nozzle
  • optional_dependencies
  • read
  • read1
  • required_dependencies
  • reset
  • run
  • source
  • superinit
• UnitBase:
  • process