Conditional Compilation

For use with DEFINE for more configurable and efficient payloads

As covered in the Constants section, DEFINE can be used to declare constants used throughout your payloads. Using DEFINE and some additional commands described below we can gain even more control over the source code that get included into your inject.binduring compilation.

What problem does this solve?

Imagine you have a payload that you would like to add some optional features to. With the help of a DEFINE you could provide a set of boolean constants to toggle those features on or off; consider the example below:

DEFINE #EnableExtraFeature1 TRUE
DEFINE #EnableExtraFeature2 FALSE
DEFINE #EnableExtraFeature3 FALSE

... payload ...

IF #EnableExtraFeature1 THEN
 ... code will always run ...
END_IF

IF #EnableExtraFeature2 THEN
 ... code will always get skipped at runtime ...
END_IF

IF #EnableExtraFeature3 THEN
 ... code that will always get skipped at runtime ...
END_IF

Here we have #EnableExtraFeature1 set to TRUE. At the time of compile IF #EnableExtraFeature1 THEN will become IF TRUE THEN which will allow for the code within that IF statement to be executed.

While the payload user is deciding to enable that feature before compiling their inject.bin by setting #EnableExtraFeature1 to TRUE, the USB Rubber Ducky is still evaluating the IF statement during runtime of the payload even though we know IF TRUE will always evaluate to TRUE.

In the opposite case, the features that are disabled are still compiled into the inject.bin . The USB Rubber Ducky still has to evaluate the IF #EnabledExtraFeature3 THEN which we know will become IF FALSE THEN to decide to skip the code within the IF statement. This becomes not only a waste of space but a waste of computation that could be better used.

Solution

Using IF_DEFINED_TRUE IF_NOT_DEFINED_TRUE and ELSE_DEFINED,we can conditionally include portions of our payload in the resulting inject.bin.

These act similarly to IF / ELSE except they are evaluated before compile time and control inclusion or exclusion of blocks of code.

IF_DEFINED_TRUE

With IF_DEFINED_TRUE, the code within it's body/block will be compiled into the inject.bin ONLY if the given LABEL exists and evaluates to TRUE

Syntax

IF_DEFINED_TRUE #LABEL
    ... code ...
END_IF_DEFINED

Example

DEFINE #EnableExtraFeature1 TRUE
DEFINE #EnableExtraFeature2 FALSE

... payload ...

IF_DEFINED_TRUE #EnableExtraFeature1
 ... code that will be included because #EnableExtraFeature1 is TRUE ...
END_IF_DEFINED

IF_DEFINED_TRUE #EnableExtraFeature2
 ... code that wont be included because #EnableExtraFeature2 is FALSE ...
END_IF_DEFINED

IF_DEFINED_TRUE #EnableExtraFeature3
 ... code that wont be included because #EnableExtraFeature3 does not exist ...
END_IF_DEFINED

IF_NOT_DEFINED_TRUE

As the opposite of IF_DEFINED_TRUE, with IF_NOT_DEFINED_TRUE, the code within it's body/block will be compiled into the inject.bin if the given LABEL does not exist or evaluates to FALSE

Syntax

IF_NOT_DEFINED_TRUE #LABEL
    ... code ...
END_IF_DEFINED

Example

DEFINE #EnableExtraFeature1 TRUE
DEFINE #EnableExtraFeature2 FALSE

... payload ...

IF_NOT_DEFINED_TRUE #EnableExtraFeature1
 ... code that wont be included because #EnableExtraFeature1 is TRUE ...
END_IF_DEFINED

IF_NOT_DEFINED_TRUE  #EnableExtraFeature2
 ... code that will be included because #EnableExtraFeature2 is FALSE ...
END_IF_DEFINED

IF_NOT_DEFINED_TRUE #EnableExtraFeature3
 ... code that will be included because #EnableExtraFeature3 does not exist ...
END_IF_DEFINED

ELSE_DEFINED

Used in combination with IF_DEFINED_TRUE and IF_NOT_DEFINED_TRUE to provide the alternative to the provided condition; the negated case. Code within the ELSE_DEFINED body/block will only be included if the paired IF_DEFINED_TRUE or IF_NOT_DEFINED_TRUE case is not met.

Syntax

IF_DEFINED_TRUE #LABEL
    ... code ...
ELSE_DEFINED
    ... other code ...
END_IF_DEFINED

IF_NOT_DEFINED_TRUE #LABEL
    ... code ...
ELSE_DEFINED
    ... other code ...
END_IF_DEFINED

Example

DEFINE #EnableExtraFeature1 TRUE
DEFINE #EnableExtraFeature2 FALSE

... payload ...

IF_NOT_DEFINED_TRUE #EnableExtraFeature1
 ...  code that wont be included because #EnableExtraFeature1 is TRUE ...
ELSE_DEFINED
 ... alternative to feature 1 that wont be included because #EnableExtraFeature1 is TRUE ...
END_IF_DEFINED

IF_NOT_DEFINED_TRUE  #EnableExtraFeature2
 ... code that will be included because #EnableExtraFeature2 is FALSE ...
END_IF_DEFINED

IF_NOT_DEFINED_TRUE #EnableExtraFeature3
 ... code that will be included because #EnableExtraFeature3 does not exist ...
END_IF_DEFINED