Security

Stylus SFTP Server provides multiple layers of security: cryptographic algorithm configuration, host key management, IP-based access control, geographic blocking, connection rate limiting, account lockout, multi-factor authentication (MFA), the AI & MCP token surface, path traversal prevention, and license enforcement. This chapter covers each mechanism and its configuration.

SSH Algorithm Configuration

Ciphers, MACs, and key-exchange algorithms are configurable via allow-lists in the <security> block of sftp-server.xml. The default configuration ships with a modern-only set — no CBC ciphers and no SHA-1 MACs. The server also supports post-quantum key exchange via mlkem768x25519-sha256.

If an allow-list is left empty, built-in defaults apply. These include legacy algorithms and are not recommended for production.

Unknown or unsupported algorithm names are logged at WARN level and silently skipped — the server continues to start with the remaining valid algorithms.

Default Ciphers

Default MACs

Default Key Exchange Algorithms

Legacy Algorithms (Disabled by Default)

The following algorithms are disabled by default due to known weaknesses. They can be re-enabled by adding them to the appropriate allow-list in sftp-server.xml if required for backward compatibility with older clients.

Host Keys

On first startup, Stylus SFTP Server automatically generates SSH host key pairs for all three supported key types:

• RSA (3072-bit or higher)
• ECDSA (P-256)
• Ed25519

Host key files are stored in the conf/ directory by default. The paths are configurable in sftp-server.xml.

IP Block List

Static IP addresses and CIDR ranges can be blocked via the <block-list> element in sftp-server.xml. Both IPv4 and IPv6 are supported. Blocked clients are disconnected immediately before the SSH handshake begins, minimizing resource consumption.

<block-list>
    <entry>10.0.0.0/8</entry>
    <entry>192.168.1.100</entry>
    <entry>2001:db8::/32</entry>
</block-list>

Connection Rate Limiting

The connection rate limiter tracks connections per source IP using a sliding window. When a client exceeds the allowed threshold, its IP is automatically blacklisted for a configurable duration.

Auto-blacklisted IPs are treated identically to entries in the static block list — connections are refused before the SSH handshake.

GeoIP Country Blocking

Stylus SFTP Server can restrict connections by country of origin using a MaxMind GeoIP database. The server supports both .mmdb (binary) and .csv formats.

Setup

1. Obtain a GeoIP database file from MaxMind (GeoLite2 Country or GeoIP2 Country).
2. Place the .mmdb or .csv file in the geodb/ folder under the data directory.
3. Configure the blocking mode and country list in sftp-server.xml.

Configuration

<geo-blocking>
    <mode>allow</mode>
    <countries>US, CA, GB</countries>
</geo-blocking>

CSV Format

If you do not have a MaxMind .mmdb file, you can provide a plain CSV file with three columns: ip_from, ip_to, and country_code.

ip_from,ip_to,country_code
"16777216","16777471","AU"
"16777472","16778239","CN"
"16778240","16779263","AU"

Format rules:

• First row is treated as a header and skipped if it contains the word "country".
• Lines starting with # are treated as comments and ignored.
• Empty lines are ignored.
• Values may be optionally quoted with double quotes.
• Rows with fewer than 3 columns or invalid IP values are silently skipped.

How It Works

• On startup, the GeoIP database file is imported into the sftp_geo_ip database table.
• IP lookups use an in-memory binary search for O(log n) performance.
• A WatchService monitors the geodb/ folder — dropping a new database file triggers automatic re-import with no restart required.

Account Lockout

To protect against brute-force password attacks, Stylus SFTP Server tracks consecutive authentication failures per account. After the configured threshold is exceeded, the account is locked for a specified duration.

<password-policy>
    <lockout-threshold>5</lockout-threshold>
    <lockout-duration-minutes>30</lockout-duration-minutes>
</password-policy>

Lockout state is tracked in the sftp_lockout database table, so it survives server restarts. A successful authentication resets the failure counter.

Administrator Unlock

An administrator can unlock a locked account immediately using the CLI tool:

admin unlock-user <username>

Multi-Factor Authentication (MFA)

TOTP-based multi-factor authentication adds a second verification step to password authentication. Configure MFA in the <mfa> block of sftp-server.xml:

MFA per protocol

The MFA policy is enforced on every protocol that supports interactive login, but the challenge-response shape differs by protocol:

<mfa>
    <policy>optional</policy>
    <issuer>Stylus SFTP Server</issuer>
    <window-size>1</window-size>
    <recovery-codes>8</recovery-codes>
    <admin-required>false</admin-required>
</mfa>

Enrollment and authenticator labels

SFTP users self-enroll from the File Transfer Portal header. Admin-console users enroll from the Admin Users tab of the Web Admin console: select the account and choose the enroll (shield) action to display the QR code and one-time recovery codes, then confirm with a code from the authenticator app to activate. The same operations are available from the CLI — mfa-admin-enroll, mfa-admin-disable, and mfa-admin-status for admin accounts, and mfa-enroll / mfa-reset / mfa-disable / mfa-status for SFTP users.

Database Tables

MFA state is stored in four auto-created database tables:

Audit Events

All MFA operations generate audit events that are recorded by every enabled audit sink. See the Audit Trail chapter for the full event list.

AI & MCP Token Surface

When AI Integration is enabled, the Knowledge Base exposes a Model Context Protocol (MCP) endpoint that AI assistants authenticate to with bearer tokens, entirely separate from the SFTP/FTPS/Portal login providers. This section summarizes the security properties of that surface; the operational walkthrough lives in Knowledge Base → Connecting AI Assistants.

• Disabled by default. The endpoint returns 503 Service Unavailable until an administrator turns AI Integration on. No token, however valid, reaches the Knowledge Base while the master switch is off.
• Two token kinds. A personal access token (PAT), prefixed ssskb_, is minted by a signed-in user and shown once; or an OAuth 2.1 browser sign-in issues short-lived access tokens with rotating refresh tokens. OAuth 2.1 with mandatory PKCE is the default for the downloadable client configurations.
• Hashed at rest. Tokens are stored as SHA-256 hashes, never in clear text. A leaked database row cannot be replayed as a token.
• Scoped. A token carries either read or read,write scope; a read-only token can never author or publish content.
• Bound to the account and revocable. A token acts as the user who created it and inherits that user's Knowledge Base role. Disabling the account, or revoking the token from the AI Integration tab, cuts off access immediately. Refresh-token reuse revokes the entire token family.
• Attributed. Every page an assistant creates or edits is committed with a “generated by AI agent” note in its version history.

Path Traversal Prevention

All filesystem operations enforce strict path confinement. After resolving a requested path (including symbolic links), the server verifies that the resolved path starts with the user's home directory:

resolved.startsWith(home)

Any attempt to escape the home directory — whether via ../ sequences, symbolic links, or absolute paths — is denied.

Additionally, the UsernameValidator rejects usernames containing .. sequences, preventing directory traversal attacks during home directory creation.

The Web File Transfer Portal applies the same path confinement checks, ensuring consistent security across both SFTP and browser-based access.

Activation Key

Stylus SFTP Server requires a valid activation key to operate. The key is cryptographically signed and verified at startup and periodically at runtime.

Place the activation.key file in the root of the data directory (${STYLUS_SFTPSERVER_DATA}/activation.key).

Database Encryption at Rest

The internal H2 database is encrypted with AES (Advanced Encryption Standard) from the moment it is created. The database file on disk contains no readable data — table names, usernames, password hashes, audit records, and all other content are stored as AES-encrypted ciphertext.

How It Works

H2 supports transparent file-level encryption via the CIPHER=AES parameter in the JDBC connection URL. When enabled, H2 encrypts every page written to the .mv.db file using a file encryption password that is separate from the SQL authentication password.

Both passwords are randomly generated during installation (24 and 32 alphanumeric characters respectively) and stored in the PKCS12 credential store. They are never displayed, logged, or written to configuration files.

What This Protects Against

• Stolen database files — if an attacker copies the .mv.db file from the server, they cannot read its contents without the file encryption password. The file header shows H2encrypt but no data is readable.
• Disk forensics — deleted data within the database file is also encrypted. No cleartext fragments remain on disk.
• Backup exposure — database backups are encrypted at rest. An intercepted backup is useless without access to credentials.p12.

JDBC URL

The installer automatically adds ;CIPHER=AES to the JDBC URL in sftp-server.xml and admin-console.xml:

jdbc:h2:${STYLUS_SFTPSERVER_DATA}/db/sftpdb;AUTO_SERVER=TRUE;CIPHER=AES

At connection time, the server reads both passwords from the credential store and composes them in the format H2 expects: filePassword userPassword (space-separated). This is handled automatically — no manual configuration is needed.

Credential Store

Stylus SFTP Server stores sensitive credentials (database passwords, LDAP bind passwords, SMTP passwords) in a PKCS12 keystore file rather than in plain text inside XML configuration files.

Files

Both files are created automatically during installation. The installer generates random passwords and sets the database password via ALTER USER. On upgrade, existing plain-text passwords are migrated from the XML files into the keystore.

Well-Known Credential Keys

Windows Group ACL

On Windows, the installer can protect master.key and credentials.p12 with NTFS access control lists (ACLs) tied to a Windows security group. This allows multiple accounts (the service account, the administrator, etc.) to access the credentials without requiring individual per-file ACL entries.

Installer Options

ACL Applied

When a group is selected or created, the installer runs:

icacls master.key /inheritance:r
icacls master.key /grant "GroupName:(R)"
icacls master.key /grant "BUILTIN\Administrators:(F)"

This removes inherited permissions, grants read access to the group, and grants full control to local administrators. The same ACL is applied to credentials.p12.

Cloud Vault Integration

Instead of storing the master key password on disk, it can be stored in a cloud secret management service. When vault integration is enabled, the master.key file contains a vault URI instead of the actual password. At startup, the server resolves the URI to retrieve the password.

How It Works

Supported Providers

Setup

1. During installation, the installer generates a random master key password and displays it on the Cloud Vault wizard page.
2. Copy the password and create a secret in your vault provider with this value.
3. Enter the vault URI in the installer and click Verify to confirm the round-trip.
4. The installer writes the vault URI into master.key instead of the plain password.

Manual Configuration

To enable vault integration on an existing installation, replace the contents of conf/master.key with the vault URI:

vault:azure:https://myvault.vault.azure.net/secrets/sss-master-key

The server detects the vault: prefix at startup and resolves the secret automatically.

GCP Version Pinning

For Google Cloud, append a version number to access a specific secret version instead of latest:

vault:gcp:my-project-123/sss-master-key/3