Conditional Statements
Previously, original DuckyScript payloads executed sequentially — line by line from start to finish.
With DuckyScript 3.0, it isn't necessary for payload execution to be linear. Conditional statements, loops and functions allow for dynamic execution.
The flow control statement
IF
will determine whether or not to execute its block of code based on the evaluation of an expression. One way to interpret an IF
statement is to read it as "IF
this condition is true, THEN
do this".The IF statement consists of these parts
- The
IF
keyword - The condition, or expression that evaluates to
TRUE
orFALSE
- In nearly all cases, the expression should be surrounded by parenthesis
( )
- The
THEN
keyword - One or more newlines containing the block of code to execute
- The
END_IF
keyword
REM Example IF THEN
$FOO = 42
$BAR = 1337
IF ( $FOO < $BAR ) THEN
STRING 42 is less than 1337
END_IF
- The expression "Is 42 less than 1337" is evaluated and determined to be
TRUE
. - Because the
IF
condition isTRUE
, the code between the keywordsTHEN
andEND_IF
are executed. - The string "
42 is less than 1337
" is typed.
The ELSE statement is an optional component of the IF statement which will only execute when the IF statement condition is FALSE. One way to interpret an
ELSE
statement is to read it as "IF
this condition is true, THEN
do this thing, or ELSE
do another thing".REM Example IF THEN ELSE
IF ( $_CAPSLOCK_ON == TRUE ) THEN
STRING Capslock is on!
ELSE IF ( $_CAPSLOCK_ON == FALSE ) THEN
STRING Capslock is off!
END_IF
- The condition of the capslock key, as determined by the target operating system, is checked.
- If the capslock key state has been reported by the target as ON, the string "
Capslock is on
" will be typed. - Otherwise, if the capslock key state has not been reported by the target (or it has been reported as not being on), the string "
Capslock is off
" will be typed.
A nested IF statement is quite simply an IF statement placed inside another IF statement. Nested IF statements may be used when evaluating a combination of conditions.
REM Example nested IF statements
IF ( $_CAPSLOCK_ON == TRUE ) THEN
IF ( $_NUMLOCK_ON == TRUE ) THEN
STRING Both Capslock and Numlock are on!
END_IF
END_IF
- The condition of the first
IF
statement is evaluated — whether or not the target has reported that the Capslock key is on. If it isTRUE
, then the nestedIF
statement will run. - The second
IF
statement is evaluated much like the first, only this time checking the status of the Numlock key. - If both the capslock and numlock keys have been reported by the target as being on, then the string "
Both Capslock and Numlock are on!
" will be typed.
In some cases it may be more efficient to use logical operators within a single IF statement, rather than using a nested IF structure.
REM Example IF statement with logical operators
IF (( $_CAPSLOCK_ON == TRUE ) && ( $_NUMLOCK_ON == TRUE )) THEN
STRING Both Capslock and Numlock are on!
END_IF
- Because the AND logical operator is in use, the whole condition will only evaluate as TRUE if both sub conditions are TRUE.
- Similar to the Nested IF example, the string "
Both Capslock and Numlock are on!
" will only be typed if both capslock and numlock are reported by the target as being on.
The syntax of
IF
states that in nearly all cases the expression should be surrounded by parenthesis ( )
— however there is an exception to this rule. If the condition of only one variable is true or false, the parenthesis may be omitted. This results in a slightly smaller encoded
inject.bin
file as well as slightly faster payload execution. This is because it removes the step of first reducing the order precedence.REM Example of optimized and unoptimized IF statements
REM Consider
VAR $FLAG = TRUE
IF $FLAG THEN
STRING FLAG is TRUE
END_IF
REM versus
IF ( $FLAG == TRUE ) THEN
STRING FLAG is TRUE
END_IF
- In the first example, the
IF
statement without the parenthesis results in a 6 bytes added to the compiledinject.bin
file. - In the second example, the
IF
statement surrounded by parenthesis results in 16 bytes added to the compiledinject.bin
file.
REM Example of optimized IF statement with internal variable
IF $_CAPSLOCK_ON THEN
STRINGLN The caps lock key is on
END_IF
- The internal variable
$_CAPSLOCK_ON
is checked. - If it evaluates as
TRUE
, the message "The caps lock key is on
" is typed.