SSH Protocols & TTY
Relevant source files
The following files were used as context for generating this wiki page:
The hoop gateway functions as a layer 7 gateway that natively parses the SSH protocol to manage access between users (engineers or AI agents) and infrastructure. Within the hoop ecosystem, SSH is utilized in two primary capacities: as a target protocol for infrastructure connections and as a proxy server that users connect to via standard SSH clients.
This system ensures that every terminal session is recorded, audited, and protected by guardrails such as command blocking (e.g., rm -rf) and human approval workflows for risky operations.
Sources: README.md:27-40, client/cmd/admin/sshserver.go:111-125
SSH Proxy Server Management
The hoop gateway can host an SSH proxy server that allows users to interact with infrastructure using their local terminal and standard SSH tools. Administrators manage this server through the hoop admin sshserver command group.
Configuration Parameters
The SSH server configuration is managed via the /api/serverconfig/misc endpoint. It supports both password-based authentication and certificate-based authentication via Trusted CAs.
| Parameter | Type | Description |
|---|---|---|
listen_address | String | The address the SSH proxy binds to (e.g., 0.0.0.0:2222). Empty disables the server. |
hosts_key | String | Base64-encoded PEM private key for the SSH host identity. |
trusted_cas | Array | List of public keys in authorized_keys format used to verify client certificates. |
cert_attr | String | Attribute in the SSH certificate to match (principal, key_id). |
user_attr | String | Hoop user attribute to match against the certificate (email, subject, user_id). |
Sources: client/cmd/admin/sshserver.go:16-35, client/cmd/admin/sshserver.go:161-177
Server Deployment Flow
When applying a new configuration, the system attempts to preserve existing host keys to prevent breaking established client fingerprints.
Infrastructure Connection Configuration
For target SSH resources, hoop supports two main authentication methods: Username/Password and Private Key Authentication. These credentials are treated as "write-only" secrets in the UI to maintain security.
Auth Method Derivation
The active authentication method is derived based on the presence of specific keys in the connection secrets:
- Password: Presence of
envvar:PASS. - Private Key: Presence of
envvar:AUTHORIZED_SERVER_KEYS.
Sources: webapp_v2/src/pages/Roles/Configure/sections/credentials/SshRenderer.jsx:35-40
Credential Handling Logic
When a user switches authentication methods in the configuration UI, the system stages a deletion for the unused key to ensure the backend reflects the single chosen method upon saving.
const handleAuthChange = (next) => {
setAuthMethod(next)
const secrets = connection?.secret || {}
const passKey = 'envvar:PASS'
const keyKey = 'envvar:AUTHORIZED_SERVER_KEYS'
if (next === 'password') {
cancelSecretChange(passKey)
if (keyKey in secrets) deleteSecret(keyKey)
} else {
cancelSecretChange(keyKey)
if (passKey in secrets) deleteSecret(passKey)
}
}
Sources: webapp_v2/src/pages/Roles/Configure/sections/credentials/SshRenderer.jsx:50-64
Terminal Access & TTY Features
Terminal access involves more than just protocol connectivity; it encompasses the environment in which commands are executed and monitored.
Feature Capabilities
- Access Availability: Users can enable/disable terminal access specifically for the Web Terminal or CLI
exec/connectflows. - Runbooks: Integration with git-sourced automation templates.
- Guardrails: Application of custom rules (e.g., blocking destructive shell commands) to terminal sessions.
- Session Recording: Full capture and replay of shell traffic for compliance (SOC 2, HIPAA, etc.).
Sources: webapp_v2/src/pages/Roles/Configure/TerminalAccessTab.jsx:25-50, README.md:120-125
Terminal Execution Pipeline
SSH Configuration Schemas
The following fields are utilized when defining an SSH connection within a resource role:
| Key | Label | Type | Required |
|---|---|---|---|
host | Host | Text | Yes |
port | Port | Number | No |
user | User | Text | Yes |
pass | Pass | Password | Conditional |
authorized_server_keys | Private Key | Textarea | Conditional |
Sources: webapp_v2/src/pages/Roles/Configure/sections/credentials/SshRenderer.jsx:11-25
Conclusion
SSH Protocols & TTY in hoop provide a secure, audited bridge between users and infrastructure. By parsing SSH at the gateway layer, hoop enables advanced security features like ML-powered data masking in terminal outputs and real-time command guardrails while allowing engineers to continue using their preferred local tools through the SSH proxy server.