Configuration¶

pwncat can load a configuration script from a few different locations. First, if a file named pwncatrc exists in $XDG_CONFIG_HOME/pwncat/ then it will be executed prior to any other configuration. Next, if no --config/-c argument is provided, and a file in the current directory named pwncatrc exists, it will be executed. Lastly, if the --config/-c argument is specified, pwncat will load and run the specified configuration script prior to establishing a connection.

The value of XDG_CONFIG_HOME depends on your environment but commonly defaults to ~/.config. The purpose of this configuration script is for global settings that you would like to persist across all instances of pwncat.

The purpose of the explicit script (or implicit script in the current directory) is for you to specify settings which are specific to this connection or context. For example, you may have a different pwncatrc that specifies a specific database location in your analysis directory while a configuration exists in $XDG_CONFIG_HOME which loads custom modules. The database is specific to a single machine or network while the global configuration may apply to multiple machines, networks or engagements.

The syntax of the pwncatrc script is the same as the local prompt within pwncat. This means you can generally use most commands that are available there with the exception of any command which requires a connection be established. For example, you cannot run enumeration or escalation modules (with the exception of on_load scripts). You can, however, set key bindings, load module classes, and set default configuration parameters.

Configuration Parameters¶

Configuration parameters are modified with the set command. By default, parameters are modified in the local context. This is meaningless if you are not in a module context. Therefore, if you are setting global runtime parameters, you should use the --global/-g flag.

To run commands and interact with the remote host upon successful connection, you can specify a script to run via the set command:

set -g on_load {
    # Automatically install an authorized key implant
    run implant.authorized_key
}

The script between the braces will be run as soon as a victim is connected and stable. Any command you can normally run from within pwncat is available.

Besides the on-load script, the following global configuration values can be set:

lhost - your attacking ip from the perspective of the victim
prefix - the key used as a prefix for keyboard shortcuts
privkey - the private key used for RSA-based persistence
backdoor_user - the username to insert for backdoor persistence
backdoor_pass - the password for the backdoor user
db - a SQLAlchemy connection string for the database to use
on_load - a script to run upon successful connection
windows_c2_dir - a directory where the Windows C2 DLLs are placed. This defaults to ~/.local/share/pwncat

The set command is also used to set module arguments when with a module context. In this case, the --global/-g flag is not used, and the values are lost upon exiting the module context.

User Credentials¶

The set command can also be used to specify user credentials. When used in this form, it can only be used after client connection. To specify a user password, you can use the “–password/-p” parameter:

set -p bob "b0b5_P@ssw0rd"

Key Bindings¶

Key bindings are keys which trigger specific commands or scripts to run after being pressed. To access key bindings, you must first press your defined prefix. By default, one binding is enabled, which is s. This will synchronize the terminal state with your local terminal, which is helpful if you change the width and height of your terminal window. A key binding can either be a single command specified in quotes, or a script block specified in braces as with the on_load callback. Examples of key bindings:

bind t {
    # Just an example of a block
    run report
}

Aliases¶

Basic command aliases can be defined using the alias command. Aliases can only be to base commands, and cannot contain scripts or command parameters. Examples of basic aliases:

alias up upload
alias down download

Shortcuts¶

Shortcuts provide single-character prefixes to act as commands. The entire command string after the prefix is sent as the parameters to the specified command. The following two shortcuts are provided to enable running local and remote shell commands from the pwncat prompt:

shortcut ! local
shortcut @ run