Skip to main content

How SSH connections work

Permaura brokers SSH the same way it brokers everything else: the agent gets permission, not the key.

A raw SSH key is all-or-nothing (a key is a shell is, usually, root). An SSH connection in Permaura turns that into something you can reason about: this agent may run these commands on this host, and the risky ones need your approval.

The pieces​

  • Connection — a configured SSH target. The host, port, user and expected host-key fingerprint are pinned here, server-side. An agent can never change them.
  • Capabilities — the exact operations the connection exposes: allow-listed exec commands (for example uptime, systemctl restart {service}) and path-scoped SFTP file operations (sftp.get, sftp.put, sftp.list).
  • Policy and grant — which capabilities are allowed, denied, or require approval, and which agents may use them.

The private key (or password) is sealed in the gateway's vault and referenced by the connection. It is decrypted only inside the gateway, only for the moment a call needs it.

What happens on a call​

When an agent invokes, say, db1.uptime:

  1. The gateway identifies the agent and looks up the capability.
  2. The policy engine decides: allow, deny, or requires approval (risky commands escalate to you).
  3. On allow, the gateway decrypts the key in memory, opens the SSH connection, and verifies the host-key fingerprint before authenticating (this is the defence against a man-in-the-middle).
  4. It runs the one pinned command, redacts the output, appends a signed audit entry, and returns the result. The key is wiped from memory straight after the handshake.

The agent only ever sees the redacted result. It never holds the key, never opens a shell, and can only run what you allow-listed.

What keeps it safe​

  • No free-form commands. An exec capability is a fixed command template. An agent can fill only the placeholders you named, and a filled value can never be a flag (a leading - is rejected) or carry shell metacharacters or whitespace. There is no path to "run any command".
  • Host-key pinning. The connection stores the server's expected SHA256 fingerprint and refuses to connect if it does not match.
  • Scoped, capped file transfer. SFTP paths resolve under a pinned root (no .. and no absolute escapes) and every transfer and listing is size-capped.
  • Graduated risk. Read-only commands can run automatically; writes, restarts and deletes carry a higher risk tier and escalate to your approval, on your device.

Real by default​

The gateway you install runs the real SSH transport: connections actually reach hosts. There is a mock mode for exploration (permaura-gateway --mock / the public demo), which returns canned results instead of connecting, but a normal install is live out of the box.

Next: add an SSH connection.