SSH/AWS SSM

The Formal Connector supports connecting to upstream resources via both SSH and AWS SSM. The Formal Endpoint can also intercept SSH on the user’s machine with Transparent Mode.

Requirements for SSH

When creating an SSH resource, set the resource hostname to the hostname of the target instance. Create a Native User with one of these credential types:

Password uses an SSH username and password.
SSH Key uses an SSH username and private key. You can also provide a CA-signed SSH certificate.

In Terraform, to configure an SSH key Native User:

resource "formal_native_user_v3" "ssh_key" {
  resource_id = formal_resource.ssh.id
  label       = "ssh-key"

  ssh_key {
    username = "ubuntu"
    key {
      environment_variable = "SSH_PRIVATE_KEY"
    }
    certificate {
      environment_variable = "SSH_CERTIFICATE"
    }
  }
}

Secrets can be stored in Formal or read from Connector environment variables. See Native Users for credential setup and Select a default Native User for selection examples.

Resources using a JSON document for SSH certificates use the legacy format.

Requirements for AWS SSM

Formal streamlines user access to instances using the AWS SSM protocol (AWS EC2 and ECS Fargate instances) through the Connector.

For AWS EC2 instances: To utilize AWS SSM with EC2 instances, ensure the following:
- SSM Agent Installation: The AWS Systems Manager Agent (SSM Agent) must be installed and running on the instance. While the SSM Agent comes pre-installed on certain Amazon Machine Images (AMIs), it may need to be manually installed or updated on others. For detailed guidance on verifying installation and performing manual installations, refer to the SSM Agent documentation.
- IAM Role Configuration: The EC2 instance must be associated with an IAM Role that includes the AmazonSSMManagedInstanceCore policy. This policy grants the necessary permissions to enable AWS Systems Manager service core functionality.
For a list of AMIs with the SSM Agent pre-installed and additional setup information, visit the official documentation.
For ECS Fargate instances: For applications running on ECS Fargate, AWS SSM access requires enabling the ECS Exec feature. This feature allows you to interact with your containers in real-time for tasks such as executing commands within a container or obtaining container logs.
- ECS Exec Enablement: To use AWS SSM with ECS Fargate, the ECS Exec feature must be enabled for your services and standalone tasks. This setup allows secure and interactive access to your Fargate containers.
For comprehensive steps on activating and using ECS Exec, consult the ECS Exec documentation..

Permissions

In order to discover and connect to the EC2 and ECS instances, the Formal Connector requires some permissions. You can give those permissions in two ways:

Ambient IAM role

Configure an IAM role for the Connector with the necessary permissions. Create an AWS IAM Native User so the Connector uses this ambient identity.

IAM Role as a Native User

You can configure an IAM role to be assumed by the Formal Connector when connecting to the EC2 or ECS instances. This is useful if you want to use a specific IAM role for the Formal Connector rather than the default role, e.g. for connecting to resources in a different account. Create an AWS IAM Role Native User and provide the role ARN. The username can be any descriptive value. See Native Users for setup.

Required IAM permissions

The IAM role requires the following permissions:

- ssm:StartSession
- ssm:DescribeInstanceInformation
- ecs:ExecuteCommand
- ecs:DescribeClusters
- ecs:ListTasks
- ecs:DescribeTasks
- ecs:ListResourceTags
- ec2:DescribeRegions
- ec2:DescribeInstances
- sts:GetCallerIdentity

Connect to the Connector

The Formal Endpoint helps configure your ~/.ssh/config file automatically for SSH resources.

Once you have created an SSH resource, you can connect to it by making an SSH connection to the connector using a remote command to tell the connector which resource to connect to.

ssh -t -p [CONNECTOR_LISTENER_PORT] \
  'idp:formal:human:john@joinformal.com'@[CONNECTOR_HOSTNAME] \
  formal connect ssh --instance-name [RESOURCE_NAME]

ssh -t -p [CONNECTOR_LISTENER_PORT] \
  'idp:formal:human:john@joinformal.com'@[CONNECTOR_HOSTNAME] \
  formal connect ec2 --instance-arn arn:aws:ec2:us-east-1:123456789012:instance/i-01234567890abcdef0

Note for EC2, either an instance ARN or an instance ID and region must be provided (i.e., --instance-id <INSTANCE_ID> --region <REGION>).The connector can optionally assume a role from the command line argument --assume-role <IAM_ROLE_ARN> before making the connection.

ssh -t -p [CONNECTOR_LISTENER_PORT] \
  'idp:formal:human:john@joinformal.com'@[CONNECTOR_HOSTNAME] \
  formal connect ecs \
    --cluster-arn arn:aws:ecs:us-east-1:123456789012:cluster/my-cluster \
    --task-id 0761dca1661d4776b3fba04fe985cbcf \
    --container my-container

Note that for ECS, you can pass a service ARN rather than a task ID and container name, in which case the connector will automatically find the first task in the service’s first container.The connector can optionally assume a role from the command line argument --assume-role <IAM_ROLE_ARN> before making the connection.

As with other resources, the Formal user password to the connector is the Formal access token available from the Control Plane. Additionally, with the Formal Endpoint installed, a local private key identity automatically populated at ~/.formal/id_rsa can be used as well.

Policy Evaluation

Formal supports the following policy evaluation stages for SSH:

Session: Evaluate and enforce policies at connection time

Session policies can read what the client asked for, such as the remote command. See the SSH object for the available fields.

Policies

You can apply access restrictions to SSH Resources, similar to any other Resource. For EC2 resources, you can apply restrictions based on the instance ARN and tags. For ECS resources, you can apply restrictions based on the cluster ARN, service ARN, task ID, task tags, and container name.

Recordings

The Formal Connector records every session and makes recordings available in the Sessions application.

Applications

VSCode Remote SSH

The Formal Connector supports the VSCode Remote SSH extension for SSH and SSM remotes. To do so, we recommend adding configuration in the ~/.ssh/config file, which VSCode will read to render a menu of hosts to connect to. For hosts that you would like to use VSCode Remote SSH with, we recommend configuring your SSH client to:

Refrain from requesting a TTY (RequestTTY no)
Use the formal command to request a remote host to connect to from the connector (see Connect to the Connector above)
For ECS Fargate remotes, use --shell /bin/bash to avoid breaking VSCode Remote SSH’s setup script.

Additionally,

For SSH remotes, ensure the AllowTcpForwarding directive is set to yes in your SSH server configuration.
For EC2 remotes, set the SSM agent to exec /bin/bash at startup in the AWS Session Manager console’s Preferences section.

In the VSCode Remote SSH extension, you should also configure

Remote.SSH: Enable Dynamic Forwarding (enabled)
Remote.SSH: Use Local Server (enabled)
Remote.SSH: Enable Remote Command (enabled)
Remote.SSH: Permit Pty Allocation (disabled)
Remote.SSH: Use Curl And Wget Configuration Files (enabled)
Remote.SSH: Use Exec Server (enabled for ECS Fargate remotes, disabled for EC2 remotes)

Note that you’ll need to configure additional IAM permissions for the Formal Connector to work with VSCode Remote SSH with SSM remotes. You’ll need to allow the following permissions:

ssm:StartSession on AWS-StartPortForwardingSession
ssm:TerminateSession

For ECS Fargate remotes, AWS requires a “runtime ID” of the specific container to start a port forwarding session with. The Connector does not look up this value. When ECS Autodiscovery is enabled for your AWS Cloud Account, the Formal Endpoint adds --runtime-id to the SSH configuration it writes for discovered containers. Otherwise, pass it yourself, e.g. with

ssh ... formal connect ecs ... --runtime-id $(aws ecs describe-tasks --cluster [CLUSTER_NAME] --tasks [TASK_ID] | jq .tasks[].containers[].runtimeId)

Cursor Remote SSH

As a VS Code fork, Cursor’s Remote SSH extension works similarly to that of VS Code. However, the way it sets up the remote server binary is a bit different and requires additional configuration against ECS Fargate remotes. First, create an .ssh_inputrc file in the home directory of the remote native user with the following content:

set enable-bracketed-paste off
set completion-query-items 0
set page-completions off

Then, in your Formal connection string, use --shell "/bin/bash -c 'exec env INPUTRC=/path/to/.ssh_inputrc /bin/bash'" to ensure that the ~/.ssh_inputrc file is used when connecting to the remote host.

SCP/SFTP

The Formal Connector supports SCP using the SFTP protocol for SSH resources only. For SSH remotes, note that the scp command will not work with the RemoteCommand SSH directive, which is used by the Formal Connector to determine which remote host to connect to. Instead, you can include the resource name in the user identity string, such as idp:formal:human:example@example.com+resource-name (i.e., the resource name is the last part of the identity string after the + character). To transfer a file, you can format the SCP command as

scp -i ~/.formal/id_rsa \
  -o User='idp:formal:human:john@joinformal.com+ssh-demo-resource' \
  /path/to/src \
  demo-connector.formal.connectors.joinformal.com:/path/to/dest

or, you can format ~/.ssh/config as

Host scp-demo-connector
	Port 22
	User idp:formal:human:john@joinformal.com+ssh-demo-resource
	HostName demo-connector.formal.connectors.joinformal.com
	RequestTTY yes
	IdentityFile ~/.formal/id_rsa

The Formal Endpoint configures ~/.ssh/config this way automatically.

Rsync

The Formal Connector supports rsync over SSH for SSH and SSM remotes. For SSH remotes, rsync encounters a similar RemoteCommand limitation as scp. You will need to configure ~/.ssh/config similar to the example above, but also set RequestTTY to no for rsync compatibility. For SSM remotes, the Formal Connector does not support rsync using the normal SSH channel due to AWS limitations. Instead, you can run rsync as a daemon on the remote host and then use rsync:// to connect to it. Note that the rsync daemon needs to run on a port greater than 1000 (e.g., 8873) for permissions reasons. For EC2 remotes, ensure that the receiving directory is writable by the ssm-user user and for ECS Fargate remotes, ensure that the receiving directory is writable by the container user. For example, you can configure /etc/rsyncd.conf on the remote host as follows:

port = 8873

# EC2
[ec2-upload]
path = /home/ssm-user/upload
uid = ssm-user

# ECS Fargate
[ecs-upload]
path = /root/upload
uid = root

Then, port-forward the rsync daemon to your local machine:

ssh -L 8873:localhost:8873 -i ~/.formal/id_rsa -p [CONNECTOR_LISTENER_PORT] \
  'idp:formal:human:john@joinformal.com'@[CONNECTOR_HOSTNAME] \
  formal connect ec2 --instance-id i-01234567890abcdef0 --region us-east-1

Then, you can use the following command to copy files to the remote host:

rsync -r target-dir rsync://localhost:8873/ec2-upload/

Transparent Mode

The Formal Endpoint intercepts SSH in Transparent Mode on macOS and Linux. Users run ssh, scp, or sftp against the real host, with their own keys. The Endpoint connects to that host directly, without a Formal resource or Connector. Write a network rule that matches SSH for the hosts to watch. This rule matches SSH on port 22:

{
  "condition": {
    "pre_tcp": true,
    "pre_tls": port == 22,
    "post_tls": technology == "ssh"
  }
}

Session policies apply as they do on the Connector. Logs use the Endpoint source in Logs. Native Users, SSM, and the formal connect commands apply only to the Connector. Once a rule matches SSH, the Endpoint refuses any connection it cannot proxy. It never passes the connection through unwatched. The client prints the reason for the refusal.

Troubleshooting

The key is protected by a passphrase

Error: Formal cannot use SHA256:...: it is protected by a passphrase.Solution: Load the key into the agent with ssh-add, then retry.

The remote host identification has changed

Error: WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!Solution: The server key no longer matches known_hosts. Confirm the new key with the host owner. Then run the ssh-keygen -R command from the message.

Getting Started

Example Use Cases

AI Governance

Configuring Formal

Integrations

Configuration

Requirements for SSH

Requirements for AWS SSM

Permissions

Ambient IAM role

IAM Role as a Native User

Required IAM permissions

Connect to the Connector

Policy Evaluation

Policies

Recordings

Applications

VSCode Remote SSH

Cursor Remote SSH

SCP/SFTP

Rsync

Transparent Mode

Troubleshooting

​Requirements for SSH

​Requirements for AWS SSM

​Permissions

​Ambient IAM role

​IAM Role as a Native User

​Required IAM permissions

​Connect to the Connector

​Policy Evaluation

​Policies

​Recordings

​Applications

​VSCode Remote SSH

​Cursor Remote SSH

​SCP/SFTP

​Rsync

​Transparent Mode

​Troubleshooting

Requirements for SSH

Requirements for AWS SSM

Permissions

Ambient IAM role

IAM Role as a Native User

Required IAM permissions

Connect to the Connector

Policy Evaluation

Policies

Recordings

Applications

VSCode Remote SSH

Cursor Remote SSH

SCP/SFTP

Rsync

Transparent Mode

Troubleshooting