Skip to content

OBFUSCATION_INSTRUCTION_ENG.md

Latest commit

 

History

History
629 lines (466 loc) · 16.8 KB

OBFUSCATION_INSTRUCTION_ENG.md

File metadata and controls

629 lines (466 loc) · 16.8 KB

English | Русский

VBA Code Obfuscation Instruction

Tool: MACROTools v2.0 Class: clsObfuscator Launch Module: modToolsObfuscation Version: 2.0.38

📋 Table of Contents

  1. What is Obfuscation
  2. Why Obfuscation is Needed
  3. Preparation for Obfuscation
  4. Running Obfuscation
  5. Obfuscation Stages
  6. Obfuscation Results
  7. OBFUSCATION_VARIABLE Settings Sheet
  8. What Gets Obfuscated
  9. What Does NOT Get Obfuscated
  10. Recovery and Debugging
  11. ⚠️🚨Limitations and Warnings ← CRITICALLY IMPORTANT SECTION!
  12. Frequently Asked Questions

What is Obfuscation

Obfuscation is the process of transforming source code into a form that preserves its functionality but makes understanding, analysis, and modification difficult.

When obfuscating a VBA project:

  • ✅ Identifiers (variable, procedure, module names) are replaced with generated names
  • ✅ String literals are extracted to a separate constants module
  • ✅ Ribbon XML callbacks are replaced with generated names
  • ✅ A report of all performed replacements is created
  • ✅ Code functionality is fully preserved

Why Obfuscation is Needed

🔐 Intellectual Property Protection

  • Hides algorithm logic
  • Makes reverse engineering difficult
  • Protects commercial solutions

📦 Code Readability Reduction

  • Variables get names like O01l1l01l1l0
  • Procedures are renamed to O01l1l01l1l0
  • Modules get names O01l1l01l1l0

Preparation for Obfuscation

✅ Requirements

  1. Access to VBA Project

    • Project must not be password protected
    • VBA object model access is enabled:
      • Excel → File → Options → Trust Center → Macro Settings → ✅ Trust access to the VBA project object model

  2. Backup Copy

    • ⚠️ Obfuscation is irreversible!
    • Always create a file copy before running
    • The add-in automatically creates a backup, but additional protection doesn't hurt

  3. Testing

    • Test obfuscation on a file copy
    • Ensure code works after obfuscation
    • Check all macros bound to buttons and shapes

⚙️ Configuring OBFUSCATION_VARIABLE Sheet

Before running obfuscation, you need to collect data about the VBA project:

  1. Open the target Excel workbook

  2. In MACROTools select: Tools → Collect Data for Obfuscation

  3. The add-in will create an OBFUSCATION_VARIABLE sheet with data:

    • Modules and their code
    • Procedures and functions
    • Variables and constants
    • UserForm controls
    • Declarations

  4. Verify data on the sheet:

    • Ensure all elements are collected correctly
    • Edit the list if necessary
    • Check element types (TypeElement)
    • Exclude variables you don't want to obfuscate by removing them from the list

Running Obfuscation

Method 1: Via Ribbon UI

  1. Open Excel with MACROTools add-in loaded
  2. Go to the MACROTools tab in the Ribbon
  3. Click the Obfuscate VBA Project button (btnObfuscator)
  4. Select the target workbook (if multiple are open)
  5. Wait for the process to complete

Method 2: Via VBE

  1. Open Visual Basic Editor (Alt+F11)
  2. In the context menu select Tools → Obfuscate VBA Project
  3. Confirm the action

Method 3: Programmatically

Sub RunObfuscation()
    Call ObfuscationVBAProject
End Sub

Execution Process

During obfuscation:

  • 🔄 Screen updating is disabled (ScreenUpdating = False)
  • 🔄 Alerts are disabled (DisplayAlerts = False)
  • 🔄 A backup copy of the file is created
  • 🔄 Obfuscation stages are executed sequentially
  • 🔄 A report is generated on the OBFUSCATION_REPORT sheet

Obfuscation Stages

Obfuscation is performed in 9 stages:

Stage 1: String Literals (Literals)

What happens:

  • All string values are extracted from code
  • A new modLiterals module is created with constants
  • Strings in the source code are replaced with references to constants

Example:

' Before:
MsgBox "Hello, World!"

' After:
MsgBox O01l1l01l1l0  ' where O01l1l01l1l0 = "Hello, World!"

Stage 2: Local Variables (Local Variables)

What happens:

  • Local variables inside procedures are renamed
  • Procedure parameters are renamed
  • Local constants are renamed

Example:

' Before:
Dim userName As String
userName = "John"

' After:
Dim O01l1l01l1l0 As String
O01l1l01l1l0 = "John"

Stage 3: UserForms Controls

What happens:

  • All controls on UserForm are renamed
  • References in form code are updated
  • References in all project modules are updated

Example:

' Before:
TextBox1.Value = "Test"

' After:
O01l1l01l1l0.Value = "Test"

Stage 4: Procedures and Functions (Procedures)

What happens:

  • All procedures and functions are renamed
  • Calls in all modules are updated
  • Macros bound to shapes are processed
  • Ribbon UI callbacks are processed

Example:

' Before:
Sub CalculateTotal()
    ' ...
End Sub

' After:
Sub O01l1l01l1l0()
    ' ...
End Sub

Stage 5: Declarations

What happens:

  • Module-level variables are renamed
  • WithEvents declarations are processed
  • References to classes with events are updated

Stage 6: Module Renaming

What happens:

  • All modules get new names
  • Standard modules → OXXXXXXXXXXXX
  • Classes → OXXXXXXXXXXXX
  • UserForms → OXXXXXXXXXXXX

Example:

' Before:
modTools.bas
clsHelper.cls
UserForm1.frm

' After:
O01l1l01l1l0.bas
O01l1l01l1l1.cls
O01l1l01l1ll.frm

Stage 7: UI Elements Writing

What happens:

  • UserForm interface changes are saved
  • Control properties are updated

Stage 8: Writing Changes to Project

What happens:

  • Modified code is written to VBComponents
  • Modules are renamed in VBA project
  • Project is saved

Stage 9: Report Generation

What happens:

  • OBFUSCATION_REPORT sheet is created
  • All correspondences are recorded: New name → Original value
  • Complete obfuscation map is formed

Obfuscation Results

📊 OBFUSCATION_REPORT Sheet

After obfuscation is completed, a report sheet is created:

Column Description
A Element type (Literals, Module, Procedure, etc.)
B Element subtype
C Additional information
D Module name
E New obfuscated name

🔍 Report Structure

OBFUSCATION_REPORT
├── Literals.<ModuleName>.<StringValue> → OXXXXXXXXXXXX
├── Module.<ModuleName> → OXXXXXXXXXXXX
├── Procedure.<ModuleName>.<ProcName> → OXXXXXXXXXXXX
├── Declaration.<ModuleName>.<VarName> → OXXXXXXXXXXXX
├── Local Variable.<Module>.<Proc>.<VarLines> → OXXXXXXXXXXXX
└── UserForm.<Module>.<ControlName> → OXXXXXXXXXXXX

💾 File Saving

  • File is automatically saved after obfuscation
  • Backup copy is created before starting
  • ⚠️ It is recommended to immediately verify functionality

OBFUSCATION_VARIABLE Settings Sheet

Data Structure

The OBFUSCATION_VARIABLE sheet contains information about the VBA project:

Column Data Description
A TypeElement Element type (Module, Procedure, Declaration, etc.)
B ModuleName Module name
C ModuleType Module type (Standard, Class, UserForm)
D ProcName Procedure/variable name
E ProcType Type (Function, Sub, WithEvents, etc.)
F ProcLines Line numbers or identifier
G ProcDeclaration Procedure declaration
H-J Additional data Internal parameters

Element Types (TypeElement)

Type Description
Module Standard module, class, or UserForm
Procedure Procedure or function
Declaration Module-level variable declaration
UserForms Control on UserForm
Parametr Procedure parameter
Local Variable Local variable
Local Const Local constant

How to Update Data

If you changed the code after collecting data:

  1. Delete the OBFUSCATION_VARIABLE sheet
  2. Run: Tools → Collect Data for Obfuscation
  3. Data will be collected again

What Gets Obfuscated

✅ Fully Obfuscated

Element Example Result
String literals "Hello" O7A3B9C2D1E5
Local variables Dim x As Long Dim O4F8A2C9D3E7 As Long
Procedure parameters Sub Test(name As String) Sub Test(O2D7E4A1B8C3 As String)
Procedures Sub CalculateTotal() Sub O9B3C6D2E5A1()
Functions Function GetValue() Function O5A9B2C7D3E1()
Module variables Private m_count As Long Private O3F7C2D8E5A1 As Long
UserForm controls TextBox1 O2D7E4A1B8C3
Modules modTools O5A9B2C7D3E1
Classes clsHelper O8D4E1A6B9C2
UserForms UserForm1 O3F7C2D8E5A1
WithEvents WithEvents App As Application WithEvents O1C5D9E3A7B2 As Application

🔗 References Are Updated

  • Procedure calls in all modules
  • Control event handlers
  • Macros bound to shapes
  • Ribbon UI callbacks
  • References to classes with events

What Does NOT Get Obfuscated

❌ System Procedures

Name Reason
Class_Initialize System class constructor
Class_Terminate System class destructor
Auto_Open Automatic workbook opening
Auto_Close Automatic workbook closing

❌ Worksheet and Workbook Events

Name Example
Workbook events Workbook_Open, Workbook_SheetChange
Worksheet events Worksheet_Change, Worksheet_Activate
UserForm events UserForm_Initialize, UserForm_Click

❌ WithEvents Events

' NOT obfuscated:
Private Sub App_WorkbookOpen(ByVal Wb As Workbook)
    ' Event name is preserved
End Sub

❌ External References and API

  • Windows API calls (Declare Function)
  • References to external libraries
  • Built-in VBA function names

❌ Strings in Excel Formulas

Only strings in VBA code are obfuscated, not in cell formulas.

Recovery and Debugging

🔙 Recovering Original Code

IMPORTANT: Obfuscation is IRREVERSIBLE automatically.

Recovery Options:

  1. From backup copy

    • Use the automatically created file copy
    • Or your manual backup copy

  2. Via report sheet

    • OBFUSCATION_REPORT sheet contains correspondence map
    • Column E → new name
    • Columns A-D → original description
    • Names can be restored manually

  3. Via OBFUSCATION_VARIABLE

    • Settings sheet contains original names
    • Use as a reference

🐛 Debugging Obfuscated Code

Problems:

  • ❌ Variable names are non-informative
  • ❌ Code tracing is difficult
  • ❌ Immediate window shows OXXXXXXXXXXXX

Recommendations:

  1. Debug the NON-obfuscated version

    • Always keep the original
    • Develop in the original
    • Obfuscate only for distribution

  2. Use the report sheet

    • Open OBFUSCATION_REPORT
    • Find the needed new name in column E
    • Determine original purpose

  3. Comment code BEFORE obfuscation

    • Add detailed comments
    • Comments are removed during obfuscation
    • This will help understand logic later

  4. Keep a change log

    • Record what and why you obfuscated
    • Save the version before obfuscation

Limitations and Warnings

⚠️ Important Limitations

  1. Variable Name Conflicts with Object Properties

    • ⚠️ If a variable name matches an object property name, obfuscation may mistakenly replace the property
    • Problem Example:
    ' Before obfuscation:
Public Sub example()
    Dim oList As MSForms.ListBox
    Dim Value As String
    Debug.Print oList.Value = "value"
End Sub

' ❌ After obfuscation (INCORRECT):
Public Sub example()
    Dim oList As MSForms.ListBox
    Dim o01010l01l01l0 As String
    Debug.Print oList.o01010l01l01l0 = "value"  ' ← Error: .Value property replaced
End Sub
    • Solution: Rename the variable so it doesn't match object properties:
    ' ✅ Correct version (variable sValue instead of Value):
Public Sub example()
    Dim oList As MSForms.ListBox
    Dim sValue As String
    Debug.Print oList.Value = "value"
End Sub

' ✅ After obfuscation (CORRECT):
Public Sub example()
    Dim oList As MSForms.ListBox
    Dim o01010l01l01l0 As String
    Debug.Print oList.Value = "value"  ' ← .Value property preserved
End Sub
    • Recommendation: Use prefixes for variable names:
      • sValue, sName, sPath (strings)
      • lCount, lIndex, lTotal (Long numbers)
      • bFlag, bEnabled, bVisible (booleans)
      • oObject, oList, oRange (objects)

  2. VBA Project Password

    • ❌ Obfuscation does not work with protected projects
    • Remove protection before running

  3. Irreversibility

    • ⚠️ No automatic rollback
    • Always create a backup copy

  4. Complex Projects

    • ⚠️ Large projects may take a long time to process
    • Recommended to test on a copy

  5. API Calls

    • ⚠️ Some functions use API hooks
    • Additional configuration may be required

  6. References to Other Projects

    • ⚠️ External references are not obfuscated
    • Check compatibility after obfuscation

🚫 Known Issues

Problem Solution
Late Binding objects May not obfuscate correctly
Dynamic control creation Check after obfuscation
CallByName calls String names are not updated automatically
Evaluate() with procedure names May require manual editing

🔒 Security

  • Obfuscated code is protected from reading, but not from execution
  • For full protection, additionally use Unviewable VBA Project
  • Obfuscation makes reverse engineering difficult, but not impossible

Frequently Asked Questions

❓ Will obfuscation slow down my code?

No. Obfuscation does not affect performance. Only names are changed, logic remains the same.

❓ Can I choose what to obfuscate?

Yes. Edit the OBFUSCATION_VARIABLE sheet before running — delete rows that you don't want to obfuscate.

❓ What if obfuscation completed with an error?

  1. Check the log: ...\AppData\Roaming\Microsoft\AddIns\MACROTools_logs.csv
  2. Ensure the VBA project is not password protected
  3. Check data correctness on the OBFUSCATION_VARIABLE sheet
  4. Try on a simple test workbook

❓ Can I obfuscate multiple workbooks at once?

No. Obfuscation is performed for one workbook at a time. Repeat the process for each.

❓ Will comments be preserved in the code?

No. Comments are removed.

❓ Will macros on buttons work?

Yes. References to macros in shapes and controls are updated automatically.

❓ How do I check that everything works?

  1. Run all main macros
  2. Check UserForms
  3. Test buttons and shapes
  4. Check Ribbon UI callbacks
  5. Ensure events are working

❓ Should I delete the OBFUSCATION_VARIABLE sheet after obfuscation?

Recommended:

  • ✅ Save a copy of the file with report sheets
  • ✅ Delete sheets from the final version for security
  • ✅ Or hide sheets: xlSheetVeryHidden

❓ Can I run obfuscation programmatically from another workbook?

Yes. Use:

Sub ObfuscateTargetWorkbook()
    Dim wb As Workbook
    Set wb = Workbooks("TargetBook.xlsm")

    If wb.VBProject.Protection = vbext_pp_locked Then
        MsgBox "Project is protected!", vbCritical
        Exit Sub
    End If

    Dim oObs As Object
    Set oObs = CreateObject("clsObfuscator")

    Application.ScreenUpdating = False
    Application.DisplayAlerts = False

    If oObs.Execute(wb) Then
        MsgBox "Success!", vbInformation
    Else
        MsgBox "Failed!", vbExclamation
    End If

    Set oObs = Nothing
End Sub

📚 Additional Materials

  • MODULES_REFERENCE_ENG.md — Reference of all MACROTools modules
  • clsObfuscator.cls — Obfuscator class source code
  • modToolsObfuscation.bas — Obfuscation launch module

📞 Support

If you experience problems:

  1. Check the log file: ...\AppData\Roaming\Microsoft\AddIns\MACROTools_logs.csv

  2. Ensure VBA access is allowed

  3. Restart Excel and check add-in activation

  4. Test only on file copies

⚖️ License

Apache License Author: VBATools Add-in Version: v2.0.38

⚠️ Remember: Obfuscation is a tool to protect against accidental code reading, not against targeted hacking. Use comprehensive protection measures for critically important projects.