Module Docs

duck.py: Core module behind duckpy’s functionality.

class duckpy.duck.DuckyCommand(dline, lineno=-1, default_delay=0, script=None)

Execute a line of duckyscript in Python. Will log to the logger entitled duckpy.

Parameters:

• dline (str) – Raw duckyscript line to execute/model.
• lineno (int) – Line number of the given duckyscript line if it is a part of a script (defaults to -1, which indicates the line is not in a script).
• default_delay (int) – Default delay to use while executing. Essentially determines how long to wait before executing a command (except in the case of REM, where this delay is skipped).
• script (dict) – Dictionary of DuckyScript methods used for setting default delays and repeating commands. Used internally by the DuckyScript class (see DuckyScript.load()).

Raises:

ValueError – If scripts kwarg does not contain all necessary keys for execution.

_to_python(dline)

Parses the given duckyscript line into a Python function. The command in the line (i.e. the substring that lies before the first space) will be parsed and then matched against known commands. If a match is found, the appropriate Python function is constructed and returned. If a match is not found, a function will still be constructed and returned, however the line will be interpreted as a series of keys to press instead of a command (for instance if GUI r was given, GUI will be seen as a key and not a command). A pre-check is done prior to the matching process, to ensure that the given command/key combo is valid.

Here’s a list of translations for commands and their Python functions:

• REM: duckpy.duck._cmd_rem()
• DELAY: duckpy.duck._cmd_delay()
• DEFAULT_DELAY: This is done internally, see the default_delay parameter in the source code for details.
• STRING: pyautogui.typewrite()
• REPEAT: This is again done internally, see source code for more details.
• (Other): pyautogui.hotkey().

Parameters:dline (str) – Duckyscript line to translate. Returns:Python function that when executed, will simulate the given duckyscript line. Raises:ValueError – If an invalid command is given.

default_delay

default_delay property. Value of this property will be determined by whether or not this command is a part of a script. If it is, then the script’s default delay value will be used, otherwise this instance’s value will be used.

Return type:int Returns:default delay being used by the command Raises:KeyError – If get_default_delay method of script cannot be found in _script.

execute()

Execute the line of duckyscript that was given during class construction. This will block until finished.

Returns:None

class duckpy.duck.DuckyScript(dpath)

Representation of a duckyscript file. Allows for reading, parsing and execution. The given Duckyscript file to represent will be parsed and loaded on creation.

Parameters:dpath (str) – Path to duckyscript (text) file Raises:OSError – If given path to a duckyscript file either does not exist or cannot be read.

_get_default_delay()

Method for retreiving the default_delay attribute. This is given to DuckyCommand instances so that they may get the default delay for the script.

Returns:_default_delay

_set_default_delay(new_delay)

Method for setting the default_delay attribute. This is given to DuckyCommand instances so that they may set the default delay for the script.

Parameters:new_delay (int) – New default delay to set.

default_delay

default_delay property, using _get_default_delay as the getter method. default_delay is made into a property so the getter and setter methods can be passed onto children DuckyCommand instances.

load()

Loads the duckyscript and parses it into python functions for execution. Note that every time this method is called the duckyscript will be read and parsed (i.e. this method supports reloading of scripts).

Raises:ValueError – If line in duckyscript file cannot be parsed. Returns:None

run()

Runs the duckyscript file (loading it if necessary) by executing all of the parsed commands sequentially. Will ‘pass through’ any errors that may possibly occur during execution.

Returns:None

duckpy.duck._cmd_delay(ms)

Simulates the DELAY command by sleeping for the given number of milliseconds.

Parameters:ms (int) – Number of milliseconds to sleep. Returns:None

duckpy.duck._cmd_rem(comment)

Function that just takes in a comment and does nothing with it to simulate the REM command.

Parameters:comment (str) – Comment string passed to the REM command. Returns:None

duckpy.duck._cmd_repeat(dcmd, num_times)

Simulates the REPEAT command by continually executing the given DuckyCommand for num_times number of times.

Parameters:

• dcmd (DuckyCommand) – Command to repeat
• num_times (int) – Number of times to repeat

Returns:

None

duckpy.duck._set_args(func, *args, **kwargs)

Decorator that returns a new function which will execute the given function with the given arguments. Allows for a function’s arguments to be set ahead of time. The returned function will not take in any arguments and will have the following attributes:

• args: arguments that were passed to the wrapped function
• kwargs: kwargs that were passed to the wrapped function

• __name__: Will be overwritten with the wrapped function’s

  name.

Parameters:

• func – Function to set the arguments for.
• args – Arguments to pass to func.
• kwargs – Keyword arguments to pass to func.

Returns:

Function that when executed, will call the given function with the given arguments.

duckpy.duck.get_alias(dcmd)

Returns the known alias for the given ducky command. If the given command does not have an alias, then None is returned.

Parameters:

dcmd (str) – Duckyscript command to get the known alias of (case sensitive).

Returns:

Command’s alias if it exists, or None.

Raises:

• ValueError – if given ducky command is invalid.
• TypeError – if the given ducky command is already an alias.

duckpy.duck.get_alias_target(dalias)

Returns the duckyscript command that the given duckyscript alias targets.

Parameters:dalias (str) – Duckyscript alias (case sensitive) Returns:Duckyscript command the alias targets. Raises:ValueError – If given duckyscript alias is not valid (this includes if the given duckyscript command is not an alias).

duckpy.duck.is_valid_alias(dcmd)

Checks to see if the given ducky command is an alias (i.e. in the global variable ALIAS), returning True if it is. If the given command is not an alias for another, then False is returned.

Note

False will still be returned if a command is given that has an alias. For instance, is_alias('ESC') is True, is_alias('ESCAPE') is False.

Parameters:dcmd (str) – Duckyscript command to check (case sensitive). Return type:bool

duckpy.duck.is_valid_cmd(dcmd)

Checks to see if the given ducky command is valid. Note that if a command is not valid in the eyes of this function, then the interpreter will not be able to executed it.

Parameters:dcmd (str) – Duckyscript command to check the validity of (case sensitive). Aliases and keys can also be given. Return type:bool Returns:True if valid, False otherwise

duckpy.duck.main(cli_args=None)

Takes in a duckyscript file, parses it and executes it. This function can be called by executing python -m duckpy however it can also be called manually by passing command line arguments through args)

Parameters:cli_args (str) – Pass command line arguments directly. Example: "my_payload.txt -v" Returns:None

duckpy.duck.translate_key(dkey)

Translates the given duckyscript key into a pyautogui key name. A three step process is used to to this:

1. Check if the key is an alias, and if it is, get its target.
2. Translate the key using either TRANSLATE_KEYS if the key has a special translation or by setting the key to all lowercase. If a key such as CTRL-ALT is given (two key modifier) then each key in the macro will be translated individually.
3. Check if the key is found in pyautogui.KEYBOARD_KEYS, returning None if it isn’t found.

A tuple of the translated key is returned, so that it may be passed right into pyautogui commands even if more than one key is translated in the case a modifier was given.

Parameters:dkey (str) – Duckyscript key to translate. Return type:tuple Returns:pyautogui name of the given key inside a tuple if it could be translated, otherwise (None, ). If a given key name translates to more than one key, then a tuple of each key is returned (i.e. CTRL-ALT -> ('ctrl', 'alt'))