iron-proxy/internal/sshproxy
…
History
..
config.go
config_test.go
lifecycle_test.go
policy.go
policy_test.go
README.md
server.go
server_test.go
transport.go
websocket.go
wstunnel_integration_test.go

Iron SSH listener

SSH runs as an optional listener inside the main iron-proxy process. Build and test it with the normal repository commands; no separate executable or module is needed.

Configure a top-level ssh: block in the regular YAML file, or set IRON_SSH_CONFIG_JSON to the equivalent JSON object for managed deployments. SSH is disabled when configuration is absent. Pass --ssh to require a configured listener at startup. Listener settings apply at startup.

The SSH configuration contains listen, host_key (an existing Iron secret source), client_public_key (registered by the trusted control plane), authorize_url, and token_env. The environment variable named by token_env is a proxy-only bearer token. Configuration and host keys must never be mounted in the sandbox. Upstream dials honor the proxy-wide proxy.upstream_deny_cidrs. Connections, authorization decisions, and session requests emit the standard audit entries (JSON and OTEL) with mode: ssh.

The authorizer receives {route, public_key} and an optional destination for per-call targets. A client names these using SSH username ee:<base64url-encoded-WSS-URL>; the proxy decodes this to route ee and passes the URL to the authorizer. This is only a request: the authorizer must enforce deployment-owned host/path policy and must never infer a user from this input. It must derive the principal from the proxy token and return a grant containing id, principal, generation, destination (tcp://host:port or a full wss://host/path), username, host_key (authorized-key format), private_key (Iron secret source), and expires_at (RFC3339, at most 15 minutes away). It must deny ambiguous or unauthorized routes with HTTP 401 or 403; other non-200 statuses are audited as authorizer errors. Responses are limited to 1 MiB; errors never expose their bodies or credential values. Redirects are not followed.

The client must prove possession of the paired key before authorization or any upstream dial. Exec and SFTP channels are supported; forwarding is blocked. Global requests are refused locally, and environment/end-of-write requests are discarded. Other channel types and requests are refused. Grants normally require a pinned SSH host key and verified WSS TLS. An authorizer may explicitly return tls_identity: true with an empty host_key for deployment-allowed WSS gateways. This authenticates the exact destination using the TLS certificate and hostname, allowing the SSH key inside that authenticated tunnel to rotate. It is rejected for plain TCP or combined with a host pin. TLS verification, redirect rejection, IP guards, disposable client keys, and per-request authorization remain mandatory. WSS implements the wstunnel v11 default unmasked framing and routing handshake with a fixed remote target 127.0.0.1:22. The JWT is protocol metadata, not an authentication credential.

The lease is renewed every five seconds. Expiry, authorization failure, or a change to any grant field except expiry closes the active connection. Authorizer failures fail closed. Both peers are probed with keepalives every 15 seconds, and a peer that misses three intervals closes the connection. Reconnection never retries a remote command automatically. A terminated channel does not guarantee detached remote descendants have exited.

Run go test -race ./internal/sshproxy. No SSH functionality is enabled merely by installing this binary; the embedding platform must supply the paired key, authenticated authorizer, destination grants, and lifecycle wiring.