sftp

Upload or download files over SSH. This command shares the same connection settings and session cache as the ssh command — all SSH options apply, and sessions created by either command can be reused by the other.

Note

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

Background mode with a session is not supported for this commands.

vars:
  $SERVER_ADDRESS: 192.42.0.254
  $SSH_SERVER: 10.10.10.19

commands:
  # Upload a file and create a named session:
  - 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

  # Download a file using cached connection settings, creates new connection:
  - type: sftp
    cmd: get
    remote_path: /etc/passwd
    local_path: /tmp/remote_passwd

  # Reuse the "attacker" session from the first command in an ssh command:
  - type: ssh
    session: attacker
    cmd: id

File Transfer

cmd

The SFTP operation to perform.

put - upload a file from the local machine to the remote host
get - download a file from the remote host to the local machine

Type:: str
Required:: True

local_path

Path to the file on the local machine.

Type:: str
Required:: True

remote_path

Path to the file on the remote machine.

Type:: str
Required:: True

mode

File permissions to set on the remote file after upload (e.g. 755).

Type:: str
Required:: False

Connection

hostname

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

Username to authenticate as on the remote host.

Type:: str

password

Password for authentication. An alternative is to use key_filename.

Type:: str

key_filename

Path to a private key file for authentication.

Type:: str

passphrase

Passphrase to decrypt key_filename, if the key is passphrase-protected.

Type:: str

timeout

Timeout in seconds for connection attempts.

Type:: float

clear_cache

Clear all cached connection settings before this command runs, allowing a fresh connection to be configured. (Normally all settings for ssh-connections are cached. This allows to define all settings in one command and reuse them in the following commands without having to redefine them)

Type:: bool
Default:: False
Required:: False

Sessions

creates_session

Name to assign to the session opened by this command. Can be reused in subsequent sftp or ssh commands via session.

Type:: str

session

Name of an existing session to reuse. The session must have been created previously via creates_session in an sftp or ssh command.

Type:: str
Required:: False

Jump Host

jmp_hostname

Hostname or IP address of an SSH jump host to tunnel through.

Type:: str

jmp_port

Port to connect to on the jump host.

Type:: int
Default:: 22

jmp_username

Username to authenticate as on the jump host.

Type:: str
Default:: same as username