SFTP Secure File Transfer Automation — Xferity MFT

SFTP

SFTP (SSH File Transfer Protocol) is the most common protocol for partner directory-style file exchange. Xferity uses SFTP for upload flows (local-to-remote) and download flows (remote-to-local).

This page explains the SFTP trust model, configuration, operational behavior, and limits in Xferity.

What SFTP is in Xferity

In Xferity, SFTP is a transfer transport. It is used when a flow needs to upload files to or download files from a remote directory over SSH.

SFTP differs from AS2 in that it is directory-based rather than message-based. There is no acknowledgement mechanism built into SFTP itself — reliability comes from the flow’s retry, idempotency, and audit model.

Trust model

SFTP trust is based on SSH host verification.

Before exchanging data, Xferity verifies that the remote SSH server is the expected server, not an impersonator.

Connections require one of:

a known_hosts file containing the accepted host key
a host_key_fingerprint (SHA-256) for fingerprint-based pinning
an explicit allow_insecure_host_key=true to skip verification (not recommended)

If neither trust source is configured, the connection fails. Xferity does not silently accept unknown host keys.

Authentication

SFTP supports two authentication modes:

Password authentication

sftp:
  host: sftp.partner.example
  port: 22
  user: xferity-transfer
  password: env:PARTNER_SFTP_PASSWORD

Use secret references (env:, file:, vault:) instead of plaintext passwords. In hardened mode, plaintext passwords are rejected.

SSH key authentication

sftp:
  host: sftp.partner.example
  port: 22
  user: xferity-transfer
  key_path: file:/etc/xferity/keys/partner_id_rsa
  key_passphrase: env:PARTNER_KEY_PASS

SSH key authentication is preferred for automated flows. Store private keys outside the config directory and use secret references.

Host verification setup

Option 1: known_hosts file

sftp:
  known_hosts: file:/etc/xferity/known_hosts

Generate an initial known_hosts entry using ssh-keyscan:

ssh-keyscan -H sftp.partner.example >> known_hosts

Then verify the fingerprint independently with the partner.

Option 2: fingerprint pinning

sftp:
  host_key_fingerprint: "SHA256:abcdefABCDEF0123456789..."

The fingerprint must start with SHA256:. Obtain the fingerprint from the partner or from ssh-keyscan:

ssh-keyscan -H sftp.partner.example | ssh-keygen -lf - -E sha256

Both methods verify the server’s identity before file transfer begins.

Remote file stability

For download flows where remote files may still be growing when Xferity polls, use remote file stability checks:

sftp:
  require_stable_remote: true
  stability_check_seconds: 3
  stability_checks: 3

This causes Xferity to check the remote file size repeatedly at the configured interval and only proceed when the size is stable for the required number of consecutive checks.

Use this setting when partners write large files that may not be fully written when the poll cycle runs.

Retry behavior

sftp:
  retry:
    max_attempts: 3
    initial_delay_ms: 1000
    max_delay_ms: 30000

Retries use exponential backoff. They are intended for transient conditions (brief connectivity loss, server briefly unavailable) and do not retry permanent failures such as authentication errors.

Timeout settings

sftp:
  timeout: 30         # connection timeout in seconds
  op_timeout_seconds: 120  # per-operation timeout

Without timeout limits, a stalled connection can hold a flow lock indefinitely.

Partner definition example

id: supplier-sftp
protocol: sftp
sftp:
  host: sftp.supplier.example
  port: 22
  user: xferity-transfer
  remote_dir: /outgoing/invoices
  known_hosts: file:/etc/xferity/known_hosts
  host_key_fingerprint: "SHA256:abcdefABCDEF0123456789..."
  key_path: file:/etc/xferity/keys/supplier_id_rsa
  key_passphrase: env:SUPPLIER_KEY_PASS

Flow example: SFTP download

flows:
  supplier-invoice-pickup:
    direction: download
    enabled: true
    source:
      partner: supplier-sftp
      path: /outgoing/invoices
    local:
      path: ./storage/supplier/invoices
    files:
      - pattern: "*.xml"
    idempotency_mode: hash
    schedule_cron: "0 */15 * * * *"

Operational considerations

When setting up an SFTP partner:

obtain the host key fingerprint from the partner out-of-band (not just from ssh-keyscan alone)
confirm which authentication method the partner supports
determine whether remote files may still be growing when you poll
set appropriate timeouts for the partner’s connection characteristics
run xferity diag <flow> before enabling the schedule

Common failures

Symptom	Cause
Host key mismatch on connect	Partner rotated SSH host key; update known_hosts
Authentication failed	Wrong user, wrong key, or passphrase not resolving
Connection timeout	Firewall blocking port 22, or wrong hostname
No files found	Wrong remote path, pattern doesn’t match, or files not yet available
File size changes during download	Partner still writing; enable `require_stable_remote`

SSH cipher and KEX algorithm configuration

For environments with specific cryptographic requirements, Xferity supports constraining the accepted SSH ciphers and key exchange (KEX) algorithms:

security:
  ssh_ciphers:
    - aes256-ctr
    - aes128-ctr
  ssh_kex_algorithms:
    - diffie-hellman-group14-sha256
    - ecdh-sha2-nistp256

Leave these fields empty to accept the default set provided by the underlying SSH library, which includes all secure modern algorithms.

Security posture integration

Xferity evaluates SFTP security configuration as part of the security posture engine. The following findings can appear for SFTP partners:

Finding code	Severity	Cause
`sftp_insecure_host_key`	warning (error in hardened mode)	Partner has `allow_insecure_host_key: true`
`sftp_host_key_not_pinned`	warning	Partner has host verification enabled but no fingerprint or known_hosts configured
`sftp_insecure_host_key_global`	warning (error in hardened mode)	Global `security.allow_insecure_host_key: true` overrides all SFTP partners

To check SFTP posture for a specific partner:

curl -s -H "Authorization: Bearer $TOKEN" \
  https://xferity.internal/api/security/posture?partner=vendor-a | jq '.checks'

The sftp_host_key_not_pinned finding means host verification is enabled (good) but the pinned key is not configured. This is a warning because an attacker could potentially conduct a man-in-the-middle attack during the first connection if the known_hosts file has not yet been populated. Resolve it by setting host_key_fingerprint or providing a pre-populated known_hosts file.

Limits

SFTP supports password and SSH key authentication; other SSH authentication methods (GSSAPI, certificate-based) are not supported
SFTP expects directory-based exchange; it does not implement inline streaming to external consumers
Host key verification is strict by default; disabling it creates a posture finding visible in the security dashboard