VBASH Tutorial

Demo Document:

VBASH_demo.7z

Installation

1. VBASH works on Windows only.
2. Shortly after placing your order, you will receive an "Order Confirmation" email.
3. Download VBASH installer using the link in the "Order Confirmation" email.
4. Unzip with 7zip (download for free) to get the executable, then run it and follow the instruction.
5. Activate VBASH online, you are good to go.

Activation

Important note: VBASH License Serial Key is permanently node-locked to the computer on which it is activated. Please use the computer on which you intend to use VBASH to activate. Once activated, you can use VBASH without internet and you can reinstall or upgrade VBASH on the same computer as many times as you want.

Important note: VBASH needs to save license file to your local drive during activation, so please run VBASH as administrator (right click and select "Run As Administrator") and temporary turn off any protection software that may block VBASH from saving file.

1. Within 5 minutes after completing your order, you will receive an "Order Confirmation" email which contains all necessary information to activate VBASH. Please check your spam folder or contact us if you do not see the email.

VBASH Basic

This is how VBASH works:

1. Load target VBA document using "Browse Document" button. VBASH supports .xlsm, .docm and .pptm file types. Macro in document will be listed in the "document panel".
2. Use "Auto Tag" or manually setup Tags. You may skip this step if you don't want obfuscation.
3. Select an action from the menu and click "Go!"
4. Review the processed VBA document under the same directory of the original document.

More detail:

VBASH works on an internal copy of the target document. It will never alter the original document.

Selecting a Macro name in the "Document Panel", its Macro code will appear in the "Original Code Panel". You can make change to the code, such as customizing Tags. However, VBASH does not compile the code and it will not save your changes unless you take an action that incurs progress saving (see explanation of "actions" below for more detail).

"Tagging" is required before obfuscation. You can use the three Tagging buttons or you can customize Tags by right click at the code panel and select "Insert Tag". Please note that these operations only apply to the selected Macro. You need to tag each Macro separately if there are multiple Macros in your VBA document.

Actions

There are 5 actions you can take with VBASH:

1. Save progress: Save a copy of the original document in which all Macro are updated to the Macro in "Original Code Panel". This is to save progress so you may continue your work at a later time. This document is NOT fused nor obfuscated and it should not be distributed to end user. If you are satisfied with the obfuscation result, we recommend you continue the project development using the progress file where all the tags are preserved as VBA comment.
2. Obfuscate for preview: Run obfuscation but doesn't save anything. The obfuscated code will appear in the "Obfuscated Code Panel". You can run this to test out the obfuscation without generating too many documents.
3. Obfuscate & save: Run obfuscation and save a copy of the original document in which all Macro are updated to the Macro in "Obfuscated Code Panel". It will save a progress and a obfuscation log by default.
4. Fuse & save: Save a progress and a copy of the progress with the VBA project fused. Although you can not see the Macro in the fused VBA document, it is exactly the same as in the progress document.
5. Obfuscate, fuse & save: Save a progress, an obfuscated document and a obfuscation log, and an obfuscated document with VBA project fused. Although you can not see the Macro in the fused VBA document, it is exactly the same as in the obfuscated document.

There are 2 additional obfuscation styles you can choose:

1. Regular (Obseleted): This is the default style. With this style each macro is assigned a unique indentification charactor and all sub/function/type/variable originally defined in such macro will start with the indentification charactor.
2. Blended: With this style all sub/function/type/variable in the project will start with letter "l", concealing the origination of any obfuscated name.
3. Debug: Debugging a ofbuscated project is very challanging, debug style is aim to help that. With this style, instead of replacing the original name, the obfuscated name is appended to the original name. This allows developer to see what has been obfuscated for debug purpose. This is not for production because the original name is still in the macro code.

VBASH saves files using this naming convention:

Tagging

Tags are required for VBASH's obfuscation to work correctly. The easiest way is to setup Tags is using the built-in Tagging functions:

1. AutoTag: Screen Macro code and setup Tags for Global Variables ("'#DimGlobalVariable#"), Functions and Subroutine ("'#DimFunctionSub#"), and Local Variables ("'#DimLocalVariable#"). VBA event subroutine will be automatically skipped ("'#DimSkipFunctionSub#"). It does not affect other kind of Tags.
2. CleanTag: Consolidate repeating Tags and reorganize the Tags format. This helps you organize Tags after customization to make them easier to read.
3. ClearTag: Remove all Tags.

**These Tagging functions can be applied to all modules in the project or to just the selected module.

Besides the built-in Tagging functions, you can customize Tags by right click at the desire position on the "Original Code Panel" and select "InertTag". You may even manually type in a Tag. Here are Tags VBASH recognizes:

**In Tags where parameters are accepted, you can put multiple paramters as long as they are separated by comma ",".

'#DimGlobalVar# Name1, Name2

Define Global Variables. The parameters, for example Name1 and Name2, are considered global variables and they will be replaced by a unique coded name to conceal the naming intention.

'#DimSkipGlobalVar# Name1, Name2

Define Global Variables that VBASH should ignore. The parameters, for example Name1 and Name2, are considered global variables but obfuscation for them will be skipped, regardless if they are defined in a "'#DimGlobalVar#" Tag or not. This Tag is designed to avoiding obfuscating some particular global variables for whatever reason without needing to alter the "'#DimGlobalVar#" Tag.

'#DimSubFunction# Name1, Name2

Define Functions and Subroutines. The parameters, for example Name1 and Name2, are considered functions or subroutines and they will be replaced by a unique coded name to conceal the naming intention.

'#DimSkipSubFunction# Name1, Name2

Define Functions and Subroutines that VBASH should ignore. The parameters, for example Name1 and Name2, are considered functions or subroutines but obfuscation for them will be skipped, regardless if they are defined in a "'#DimSubFunction#" Tag or not. This Tag is designed to avoiding obfuscating some particular functions or subroutines for whatever reason without needing to alter the "'#DimSubFunction#" Tag.

'#DimType# Name1, Name2

Define Types. The parameters, for example Name1 and Name2, are considered as Type and they will be replaced by a unique coded name to conceal the naming intention. This only affects the name of the Type, and the obfuscations of type variables are defined by "'#DimLocalVar#" tag before the Type definition.

'#DimSkipType# Name1, Name2

Define Types that VBASH should ignore. The parameters, for example Name1 and Name2, are considered Type but obfuscation for them will be skipped, regardless if they are defined in a "'#DimType#" Tag or not. This Tag is designed to avoid obfuscating some particular types for whatever reason without needing to alter the "'#DimType#" Tag.

'#DimLocalVar# Name1, Name2

Define Local Variables for next Function or Subrotine. The parameters, for example Name1 and Name2, are considered local variables and they will be replaced by a unique coded name to conceal the naming intention. The local variable definition is locked by the declaration of Function or Subroutine and is cleared by the "End Function" or "End Sub", therefore in general you want to put "'#DimLocalVar#" Tag before each function or subroutine where you want local variable obfuscated.

'#DimSkipLocalVar# Name1, Name2

Define Local Variables that VBASH should ignore. The parameters, for example Name1 and Name2, are considered local variables used in function or subroutine but obfuscation for them will be skipped, regardless if they are still defined in a "'#DimLocalVar#" Tag. This Tag is designed to avoiding obfuscating some particular local variables for whatever reason without needing to alter the "'#DimLocalVar#" Tag.

'#StartObfuscation#

Set VBASH to start obfuscating string, comment and format. It is equivalent to setting "'#StartObfuscateString#", "'#StartObfuscateComment#", "'#StartObfuscateFormat#". This Tag is deemed as set at the beginning of each Macro.

'#StopObfuscation#

Set VBASH to stop obfuscating string, comment and format. It is equivalent to setting "'#StopObfuscateString#", "'#StopObfuscateComment#", "'#StopObfuscateFormat#".

'#StartObfuscateString#

Set VBASH to start obfuscating string (text between double-quotes). This is mainly for restarting string obfuscation after "'#StopObfuscateString#" or '#StopObfuscation#" Tags.

'#SkipObfuscateString#

Set VBASH to skip obfuscating string in the code line right after this Tag. This affects only one line after the Tag.

'#StopObfuscateString#

Set VBASH to stop obfuscating string (between double-quotes).

'#StartObfuscateComment#

Set VBASH to remove comment. This is mainly for restarting comment removal after "'#StopObfuscateComment#" or '#StopObfuscation#" Tags.

'#SkipObfuscateComment#

Set VBASH to skip removing comment in the code line right after this Tag. This affects only one line after the Tag.

'#StopObfuscateComment#

Set VBASH to stop removing comment.

'#StartObfuscateFormat#

Set VBASH to remove coding format (indent and blank lines). This is mainly for restarting format removal after "'#StopObfuscateFormat#" or '#StopObfuscation#" Tags.

'#SkipObfuscateFormat#

Set VBASH to skip removing coding format (indent and blank lines). This affects only one line after the Tag.

'#StopObfuscateFormat#

Set VBASH to stop removing coding format (indent and blank lines).

'#StartObfuscateLocalVar#

Set VBASH to start obfuscating local variables. This will only affect next functions or subroutines. This is mainly for restarting local variable obfuscation after "'#StopObfuscateLocalVar#" Tag.

'#StopObfuscateLocalVar#

Set VBASH to stop obfuscating local variable. This is equivalent to removing all subsequent '#DimLocalVariable#'. This is mainly for stopping local variable obfuscation for debug purpose without needing to alter the "'#DimLocalVariable#" and "'#DimSkipLocalVariable#" Tags.

'#StringAsName# Name1, Name2 (updated in v1.1.9)

Set VBASH to consider string between quotes as function or subroutine name. If the entire string between quotes matches to one of the name specified, Name1, Name2 and etc, VBASH will obfuscate the string as if it is a sub/function/variable name. For example, with "'#StringAsName# MyFunc"in this statement "Application.OnKey "{ENTER}", "MyFunc"", "MyFunc" will be replaced by its obfuscated name instead of being obfucated as a string. This applies only the next line after the Tag.

Tagging example and the obfuscation result can be found in the demo document:

Console Mode

(v1.1.15 and newer)

In response to an overwhelmed request, VBASH console mode is added. Now you can run selected VBASH tasks by calling VBASH.exe in cmd. The following arguments are supported:

-i|--input <InputFilePath>  Required to incur console mode. <InputFilePath>=Input file path (use "" if path includes whitespace).

-a|--action <action>       Required to incur console mode. <action> must be one of these phrases: obfuscate, fuse, obfuscate+fuse. Case insensitive.

-t|--tag           Apply autoTag (elimiate this argument to skip autoTag).

*It is recommanded to run "Start /w VBASH.exe <arguments>" instead of "VBASH.exe <arguments>", so that the cmd will not return until VBASH task is completed.

Example command: "Start /w VBASH.exe -i "C:\my path\my.xlsm" -t -a obfuscate+fuse"

Frequently Asked Questions:

1. Why VBASH fails to open some document and shows a warning message saying "Programmatic access to Visual Basic Project is not trusted"?

Answer: VBASH requires access to VBA project to extract Macro. To resolve this, in Excel/Word/PowerPoint go to "File"->"options"->"Trust Center"->"Trust Center Settings"->"Macro Settings" and check the option "Trust access to the VBA project object model" under "Developer Macro Settings".



2. Some obfuscator uses random strings for variable names and etc. Why VBASH does not?

Answer: Random string made out of letters and numbers may seem unreadable to human, but each unique random string is unique and it is easy to be searched and replaced by simpler phrases, defeating the purpose of obfuscation. VBASH chooses to use a random pattern consist with "1" and "l" as the obfuscated name, for example "l1l1l11ll", because it is hard to read and it is not easy to be searched and replaced. However, we are considering enabling more patterns of obfuscated names, feel free to send us your idea through Contact Us and we are more than happy to take it into consideration.



3. In demo document, why adding a unused optional parameter to some Subroutines?

Answer: As you may already know, subroutine without parameter will appear in the Macros list (on Ribbon under "Developer" tab, "Macros" command). This is also the case for a fused document. To avoid your subroutine being listed, simply add a unused optional parameter for the subroutines.

Revision History:

v1.1.18 (2023/08/07): Activation improvement. Bug fixed. Local variable detection updated.

v1.1.19 (2023/03/09): Phasing out Regular Mode. Obfuscating in Blended mode only.

v1.1.19b (2023/08/24): Bug fixed.

v1.1.20 (2024/03/02): Minor optimization. Code updates.