Bastion Host and Stacio Integration Specification

1. Document Purpose

This specification defines two ways to integrate a bastion host with Stacio:

1. The bastion host exports remote connection files that users import into Stacio.
2. A bastion host web page launches Stacio directly through the stacio:// URL Scheme.

A vendor may implement file import only or support web launch as well. Supporting both is recommended: file import suits migration and bulk setup, while URL launch lets a user connect from the bastion host web console with one click.

2. Security Boundaries

3. File Import

3.1 Recommended File Types

Stacio adapters identify files by format and do not rely on filename extension alone:

• OpenSSH config
• Xshell .xsh
• Xftp session files
• SecureCRT session/INI
• Vendor-defined INI, JSON, XML, or TXT
• Multi-session ZIP packages

3.2 Standard Field Mapping

If a bastion host requires a special account syntax such as SSH@account@asset, the adapter must retain the final login username exactly as required for the real connection. It must not split it and lose its meaning.

3.3 Import Flow

1. The user selects or drags in a file.
2. Stacio identifies the format using the extension, MIME type, file header, and content characteristics.
3. The file is parsed into the standard fields.
4. A preview shows host, port, username, asset, and authentication method.
5. For duplicate session names, the user is offered overwrite, skip, or rename.
6. Sensitive fields are redacted and plaintext passwords are ignored.
7. After user confirmation, the session is written to the session database.
8. The user chooses to connect now or later.

3.4 Vendor Adaptation Submission Materials

Each vendor/version must provide at least:

• One redacted single-session export file.
• One redacted multi-session export file.
• File-format and field documentation.
• Bastion host address, port, and username composition rules.
• Whether asset ID/account ID is required.
• Whether SFTP reuses SSH fields.
• Whether a local plug-in, CLI, or certificate is required.
• Lifecycle and expiry rules for authentication fields.
• Examples of successful connection, expiry, and permission denial.

4. Direct Launch from a Web Page

4.1 URL Scheme

Stacio registers this custom Scheme:

stacio://

Open an existing session:

stacio://open-session/{sessionID}

sessionID must be URL encoded.

Create an ephemeral connection request:

stacio://connect?v=1&vendor=example&request_id=req-123&expires_at=2026-07-21T12%3A00%3A00Z&nonce=abc123&payload=...&signature=...

4.2 Connection Request Fields

The following payload fields are recommended:

{
  "version": 1,
  "vendor": "example",
  "protocol": "ssh",
  "gatewayHost": "bastion.example.com",
  "gatewayPort": 60022,
  "gatewayUsername": "SSH@account@asset",
  "targetHost": "10.0.0.8",
  "targetPort": 22,
  "targetUsername": "root",
  "assetId": "asset-123",
  "accountId": "account-456",
  "requestId": "req-123",
  "nonce": "abc123",
  "expiresAt": "2026-07-21T12:00:00Z"
}

Use Base64URL-encoded JSON as payload and sign the normalized payload. The signature algorithm and public-key distribution method are agreed separately by the vendor and Stacio.

4.3 Stacio Behavior

• Stacio is installed: launch the application and process the request.
• Stacio is not installed: send the user to the website installation page.
• Missing or expired parameters, an invalid signature, or an unsupported protocol: reject the connection and show the reason.
• Unknown vendor: handle as generic SSH, but show user confirmation.
• When a request carries a save marker, create an ephemeral session first and let the user decide whether to save it.
• A URL launch must not silently save a password or long-lived credential.

4.4 Browser Page Example

<a href="stacio://connect?v=1&amp;vendor=example&amp;request_id=req-123&amp;expires_at=2026-07-21T12%3A00%3A00Z&amp;nonce=abc123&amp;payload=PAYLOAD&amp;signature=SIGNATURE">
  Connect with Stacio
</a>

Vendors should provide both a "Download connection file" entry and a "Connect with Stacio" entry so users can continue when Stacio is not installed.

5. Proxy and CLI Bastion Hosts

Some products are not ordinary SSH entry points and rely on a local CLI or proxy, such as Teleport, AWS SSM, Azure Bastion, GCP IAP, and Boundary. These vendors must provide:

• CLI name and minimum version.
• Local executable-path discovery rules.
• Target resource ID.
• Restricted ProxyCommand template.
• CLI login-state check method.
• Exit-code and error-code mappings.

Stacio allows only command templates generated by built-in adapters. It does not directly execute unvalidated URL text.

6. Vendor Adaptation Priority

Phase 1: OpenSSH, Xshell, SecureCRT, JumpServer, 天融信 (Topsec), 深信服 (Sangfor), 奇安信 (QAX), 安恒 (DBAPPSecurity), Alibaba Cloud, Tencent Cloud, and Huawei Cloud.

Phase 2: 360, Teleport, AWS SSM, Azure Bastion, GCP IAP, CyberArk, BeyondTrust, and other products that depend on a CLI or proxy.

Public-cloud, private-deployment, and major-version variants of the same vendor must register format versions separately and must not be assumed to be mutually compatible.

7. Acceptance Checklist

• Single-session and multi-session files can be identified and imported.
• The previewed gateway, port, account, and asset match the vendor client.
• The imported session can complete an SSH connection through the bastion host.
• SFTP/Xftp cases are not mistaken for ordinary SSH.
• Passwords, tokens, and private keys do not appear in logs, URLs, exported JSON, or diagnostic packages.
• Expired URLs, repeated nonces, and invalid signatures are rejected.
• A web-page fallback exists when Stacio is not installed.
• When a vendor version changes, the adapter reports an unsupported format version instead of silently producing a connection error.
• Every adapter has redacted samples and automated parsing tests.

8. Contact and Version Registration

When joining the integration, a vendor must provide its vendor name, product name, deployment form, version number, file-format version, URL-launch protocol version, signing public key, test environment, and contact. The Stacio website Wiki should maintain independent adaptation status, supported versions, and known limitations for each vendor.