Pkg.VBABeautifier — API for beautifying and deobfuscating VBA/VBS scripts

Overview

The Pkg.VBABeautifier module contains the API for beautifying and deobfuscating VBA (Visual Basic for Applications) and VBS (VBScript) code. It handles formatting (indentation, keyword casing, whitespace normalization) and multi-pass deobfuscation (constant folding, variable propagation, dead code removal, and automatic variable renaming).

Beautifying a VBA Script

The following code example demonstrates how to beautify and deobfuscate a VBA script:

from Pkg.VBABeautifier import *

def beautifyVBA(script):
    vba = VBABeautifier()
    vba.known_variables = vba.defaultKnownVariables()
    result = vba.beautify(script)
    if result is not None:
        print(result)

Beautifying with Custom Options

The following code example demonstrates how to configure the beautifier for specific use cases:

from Pkg.VBABeautifier import *

def beautifyMalware(script):
    vba = VBABeautifier()
    vba.known_variables = vba.defaultKnownVariables()
    vba.remove_unused_variables = True
    vba.indent_spaces = 4
    result = vba.beautify(script)
    if result is not None:
        print(result)

def formatOnly(script):
    vba = VBABeautifier()
    vba.deobfuscate_code = False
    result = vba.beautify(script)
    if result is not None:
        print(result)

Module API

Pkg.VBABeautifier module API.

Classes:

VBABeautifier()

Beautifier for VBA/VBS scripts.

class VBABeautifier

Beautifier for VBA/VBS scripts.

Methods:

beautify(script[, fmt])	Beautifies the input script.
defaultKnownVariables()	Returns a dictionary that can be used to initialize known_variables.

Attributes:

deobfuscate_code	If True, deobfuscates the code.
indent_spaces	The amount of indentation spaces.
keep_comments	If True, keeps the comments in the code.
known_variables	A dictionary used to resolve known variables.
name_variables	If True, automatically names variables.
remove_unused_variables	If True, removes unused variables in the code.
replace_variables	If True, replaces the variables in the code.

beautify(script: str, fmt: str = 'text') → Optional[str]

Beautifies the input script.

Parameters

• script (str) – The script to beautify.

• fmt (str) – The output format. Only "text" is supported.

Returns

Returns the beautified code as a string if successful; otherwise returns None.

Return type

Optional[str]

defaultKnownVariables() → Dict[str, Union[str, int]]

Returns

Returns a dictionary that can be used to initialize known_variables.

Return type

Dict[str, Union[str, int]]

See also known_variables.

deobfuscate_code

If True, deobfuscates the code.

indent_spaces

The amount of indentation spaces.

keep_comments

If True, keeps the comments in the code.

known_variables

A dictionary used to resolve known variables.

Note

The variable names are case-insensitive.

See also defaultKnownVariables().

name_variables

If True, automatically names variables.

remove_unused_variables

If True, removes unused variables in the code.

replace_variables

If True, replaces the variables in the code.