farssh 0.4__py3-none-any.whl

farssh/__main__.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+
+import subprocess
+
+from farssh.const import *
+from farssh.args import FarsshArguments
+from farssh.ssh import FarsshSshKeyHandler
+from farssh.commands import build_commands
+import farssh.aws as aws
+
+def main():
+	args = FarsshArguments()
+	ssh_keys = FarsshSshKeyHandler(args)
+	database = aws.select_database(args) if args.cmd_args.get('command') in ["psql", "mysql"] else None
+	target_ip_address = aws.run_ecs_task(args, ssh_keys, FARSSH_ID)
+
+	ssh_keys.write_known_hosts(target_ip_address)
+	(ssh_command, main_command) = build_commands(args, ssh_keys, target_ip_address, database)
+
+	if not main_command:
+		try:
+			subprocess.run(ssh_command)
+		except KeyboardInterrupt:
+			pass
+
+		exit(0)
+
+	ssh_command.insert(1, "-n") # StdinNull
+	ssh_command += [ "echo connected; sleep infinity" ]
+
+	with subprocess.Popen(ssh_command, stdout = subprocess.PIPE, stdin = subprocess.DEVNULL, text = True) as ssh:
+		try:
+			ssh_out = ssh.stdout.readline().strip() # wait for "connected"
+			ssh.stdout.close()
+
+			print(f"Tunnel connection established.")
+			print(f"Running {' '.join(main_command)}")
+			print("------------------------------------------------------------------------")
+
+			subprocess.run(main_command)
+
+		finally:
+			ssh.terminate()
+
+if __name__ == "__main__":
+	main()
+

farssh/args.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+
+import argparse
+import sys
+
+from farssh.const import *
+from farssh.aws import get_farssh_ssm_parameters
+
+class FarsshArguments:
+	def __init__(self):
+		self.cmd_args = self._parse_args()
+		self.cmd_args['remote_port'] = self.cmd_args.get('remote_port') or self.cmd_args.get('local_port')
+
+		self.enable_execute_command = False
+
+		# defaults, if not found in Parameter Store
+		self.force_public_ipv4 = False
+
+		for (key, value) in get_farssh_ssm_parameters(FARSSH_ID).items():
+			setattr(self, key, value)
+
+		try:
+			self.public_subnets = self.public_subnets.split(',')
+			self.force_public_ipv4 = (self.force_public_ipv4 == "true")
+		except AttributeError:
+			x  = f"ERROR:  FarSSH parameters not found for this AWS account and region. "
+			x += f"Please follow setup instructions at {FARSSH_URL} first."
+			raise SystemExit(x)
+
+		# assign_public_ipv4 is not set from Parameter Store, but set here dynamically. It has to be sent from
+		# the client (network configuration in ecs:RunTask), but the AWS side can set force_public_ipv4 to
+		# signal the client that the server side needs public IPv4, e.g. for pulling the FarSSH image without NAT.
+		# Otherwise, and if we're going to use IPv6 anyway, we don't need public IPv4.
+		self.assign_public_ipv4 = "ENABLED" if self.force_public_ipv4 or not self.cmd_args.get('ipv6') else "DISABLED"
+
+	def _parse_args(self):
+		# TODO: the old syntax from v0.1, where it's possible to omit the "tunnel" command word,
+		# seems to be impossible with python's argparse. figure out a way to support this again.
+
+		if len(sys.argv) == 1:
+			sys.argv += [ "--help" ]
+
+		parser = argparse.ArgumentParser(
+			description = "Secure on-demand connections into AWS VPCs",
+		)
+
+		parser.add_argument('-6', '--ipv6', action='store_true', help = 'use IPv6 (disables public IPv4 when possible)')
+		parser.add_argument('-V', '--version', action='version', version = f'FarSSH {FARSSH_VERSION}')
+
+		subparsers = parser.add_subparsers(dest = 'command', required = True)
+
+		parser_ssh = subparsers.add_parser('ssh', help = 'start interactive SSH session')
+		parser_ssh.add_argument('extra_arguments', nargs = '*', help = 'extra arguments passed to ssh')
+
+		parser_proxy = subparsers.add_parser('proxy', help = 'start SOCKS proxy')
+
+		parser_tunnel = subparsers.add_parser('tunnel', help = 'establish a port-forwarding tunnel')
+		parser_tunnel.add_argument('local_port', help='local port number')
+		parser_tunnel.add_argument('remote_host', help='remote host address')
+		parser_tunnel.add_argument('remote_port', help='remote port (optional)', nargs = '?', default = argparse.SUPPRESS)
+
+		parser_psql = subparsers.add_parser('psql', help = 'establish tunnel to a postgres endpoint and launch the psql client')
+		parser_psql.add_argument('-i', '--identifier', help='database identifier (RDS)')
+		parser_psql.add_argument('-u', '--user', dest='username', help='database username')
+		parser_psql.add_argument('-U', '--username', help=argparse.SUPPRESS)
+		parser_psql.add_argument('database', nargs = '?', help='database name (in the DB engine)')
+		parser_psql.add_argument('extra_arguments', nargs = '*', help = 'extra arguments passed to psql')
+
+		parser_mysql = subparsers.add_parser('mysql', help = 'establish tunnel to a mysql/mariadb endpoint and launch the mysql client')
+		parser_mysql.add_argument('-i', '--identifier', help='database identifier (RDS)')
+		parser_mysql.add_argument('-p', '--password', dest='password', action='store_true', help='ask for mysql password (pass -p to the mysql client)')
+		parser_mysql.add_argument('-u', '--user', dest='username', help=argparse.SUPPRESS)
+		parser_mysql.add_argument('-U', '--username', help='database username')
+		parser_mysql.add_argument('database', nargs = '?', help='database name (in the DB engine)')
+		parser_mysql.add_argument('extra_arguments', nargs = '*', help = 'extra arguments passed to mysql')
+
+		return vars(parser.parse_args())
+

farssh/aws.py

@@ -0,0 +1,181 @@
+import base64
+import boto3
+import time
+
+# ----------------------------------------------------------------------
+
+def get_farssh_ssm_parameters(farssh_id):
+	r = {}
+
+	ssm = boto3.client('ssm')
+	for param in ssm.get_parameters_by_path(Path = f"/farssh/{farssh_id}", Recursive = True)['Parameters']:
+		param_name = param['Name'].split('/')[-1]
+		r[param_name] = param['Value']
+
+	return r
+
+def select_ip_address(args, task):
+	ipv4_address = None
+	ipv6_address = task['containers'][0]['networkInterfaces'][0].get('ipv6Address')
+
+	if args.cmd_args.get('ipv6'):
+		if not ipv6_address:
+			raise SystemExit("ERROR:  IPv6 requested, but no IPv6 address on the FarSSH ECS task. Check selected VPC subnets.")
+
+		return ipv6_address
+
+	# The IPv6 is available in `task`, but the public IPv4 address is not, so we need to query this separately.
+	ec2 = boto3.client('ec2')
+	eni_id = [detail['value'] for detail in task['attachments'][0]['details'] if detail['name'] == "networkInterfaceId"][0]
+	dni = ec2.describe_network_interfaces(NetworkInterfaceIds = [ eni_id ])
+	ipv4_address = dni['NetworkInterfaces'][0].get('Association', {}).get('PublicIp')
+
+	if ipv4_address:
+		return ipv4_address
+
+	if ipv6_address:
+		print("WARNING:  FarSSH ECS task has no public IPv4 address; attempting with IPv6.")
+		return ipv6_address
+
+	raise SystemExit("ERROR:  FarSSH ECS task has neither IPv6 nor public IPv4 address. Check selected VPC subnets.")
+
+def run_ecs_task(args, ssh_keys, farssh_id):
+	override_env = [
+		{
+			"name": "FARSSH_SSH_AUTHORIZED_KEYS",
+			"value": ssh_keys.login_key_pub,
+		},
+		{
+			"name": "FARSSH_SSH_HOST_RSA_KEY_BASE64",
+			"value": base64.b64encode(bytes(ssh_keys.host_key, "utf-8")).decode("utf-8")
+		}
+	]
+
+	override_entry = {
+		"name": "farssh", # container name from task definition
+		"environment": override_env,
+	}
+
+	overrides = {}
+	overrides['containerOverrides'] = [ override_entry ]
+
+	network_configuration = {
+		"awsvpcConfiguration": {
+			"subnets": args.public_subnets,
+			"securityGroups": [ args.security_group ],
+			"assignPublicIp": args.assign_public_ipv4,
+		}
+	}
+
+	ecs = boto3.client('ecs')
+	tasks = ecs.run_task(
+		cluster = "farssh",
+		capacityProviderStrategy = [
+			{ "capacityProvider": "FARGATE", "weight": 1, "base": 1 },
+			# { "capacityProvider": "FARGATE_SPOT", "weight": 0, "base": 0 }, # not supported for Arm images
+		],
+		taskDefinition = f"farssh-{farssh_id}",
+		enableExecuteCommand = args.enable_execute_command,
+		overrides = overrides,
+		networkConfiguration = network_configuration,
+	)
+
+	task = tasks['tasks'][0]
+	task_arn = task['taskArn']
+	task_id = task_arn.split('/')[-1]
+
+	print(f"Launched FarSSH ECS task: {task_id}")
+	print(f"Status: {task['lastStatus']}")
+
+	while True:
+		time.sleep(1)
+
+		task_old = task
+		task = ecs.describe_tasks(cluster = "farssh", tasks = [ task_arn ])['tasks'][0]
+
+		if task['lastStatus'] == "STOPPED":
+			raise SystemExit("ERROR:  ECS task is in status STOPPED; see ECS Console for details.")
+
+		if task['lastStatus'] != task_old['lastStatus']:
+			print(f"Status: {task['lastStatus']}")
+
+		if task['lastStatus'] == "RUNNING":
+			break
+
+	ip_address = select_ip_address(args, task)
+
+	print(f"FarSSH task IP address: {ip_address}")
+	print()
+
+	return ip_address
+
+def select_database(args):
+	rds = boto3.client('rds')
+
+	db_instances = rds.describe_db_instances()['DBInstances']
+	db_clusters = rds.describe_db_clusters()['DBClusters']
+	db_clusters_with_instances = [dbi.get('DBClusterIdentifier') for dbi in db_instances if dbi.get('DBClusterIdentifier')]
+
+	available = []
+
+	for candidate_instance in db_instances:
+		available += [{
+			'identifier': candidate_instance.get('DBInstanceIdentifier'),
+			'cluster':    candidate_instance.get('DBClusterIdentifier'),
+			'engine':     candidate_instance.get('Engine'),
+			'status':     candidate_instance.get('DBInstanceStatus'),
+			'hostname':   candidate_instance['Endpoint'].get('Address'),
+			'port':       candidate_instance['Endpoint'].get('Port'),
+			'database':   candidate_instance.get('DBName'),
+			'username':   candidate_instance.get('MasterUsername'),
+		}]
+
+	for candidate_cluster in db_clusters:
+		cluster_id = candidate_cluster.get('DBClusterIdentifier')
+
+		# exclude clusters that also have associated instances
+		if cluster_id in db_clusters_with_instances:
+			continue
+
+		available += [{
+			'identifier': cluster_id,
+			'cluster':    cluster_id,
+			'engine':     candidate_instance.get('Engine'),
+			'status':     candidate_cluster.get('Status'),
+			'hostname':   candidate_cluster['Endpoint'],
+			'port':       candidate_cluster.get('Port'),
+			'database':   candidate_cluster.get('DatabaseName'),
+			'username':   candidate_cluster.get('MasterUsername'),
+		}]
+
+	candidates = []
+	for db in available:
+		if db['status'] != "available":
+			continue
+
+		if args.cmd_args.get('command') == "psql" and "postgres" not in db['engine']:
+			continue
+
+		if args.cmd_args.get('command') == "mysql" and "mysql" not in db['engine'] and "maria" not in db['engine']:
+			continue
+
+		if args.cmd_args.get('identifier') and db['identifier'].lower() != args.cmd_args.get('identifier').lower():
+			continue
+
+		candidates += [db]
+
+	if len(candidates) == 0:
+		raise SystemExit("ERROR:  No matching database found")
+
+	if len(candidates) == 1:
+		db = candidates[0]
+		if not args.cmd_args.get('identifier'):
+			print(f"Selected database: {db['identifier']} ({db['hostname']})")
+		return db
+
+	print("Multiple databases available; use --identifier/-i to select one:")
+	for db in candidates:
+		print(f"- {db['identifier']}")
+
+	exit(0)
+

farssh/commands.py

@@ -0,0 +1,83 @@
+import os
+import shutil
+
+from farssh.const import *
+
+def build_commands(args, ssh_keys, ip_address, database):
+	ssh_command  = [ shutil.which("ssh") ]
+	ssh_command += [ "-p", args.ssh_port ]
+	ssh_command += [ "-o", f"IdentityFile {ssh_keys.login_key_file}" ]
+	ssh_command += [ "-o", f"IdentitiesOnly yes" ]
+	ssh_command += [ "-o", f"UserKnownHostsFile {ssh_keys.known_hosts_file}" ]
+	ssh_command += [ "-o", f"StrictHostKeyChecking yes" ]
+	ssh_command += [ "-o", f"ExitOnForwardFailure yes" ]
+	ssh_command += [ "-l", f"root" ]
+
+	main_command = None
+
+	if args.cmd_args.get('command') == "ssh":
+		ssh_command += [ ip_address ]
+		ssh_command += args.cmd_args.get('extra_arguments')
+
+		print("------------------------------------------------------------------------")
+		print()
+
+	elif args.cmd_args.get('command') == "proxy":
+		ssh_command += [ "-D", "1080" ]
+		ssh_command += [ ip_address ]
+		ssh_command += [ "echo SOCKS proxy available on port 1080. Hit Ctrl-C to terminate.; sleep infinity" ]
+
+	elif args.cmd_args.get('command') in [ "psql", "mysql" ]:
+		port = str(database['port'])
+
+		l_args = [ port, database['hostname'], port ]
+		ssh_command += [ "-L", ":".join(l_args) ]
+		ssh_command += [ ip_address ]
+
+		if args.cmd_args.get('command') == "psql":
+			username = args.cmd_args.get('username') or os.environ.get('PGUSER') or database.get('username')
+			database = args.cmd_args.get('database') or os.environ.get('PGDATABASE') or database.get('database') or 'template1'
+			main_command  = [ "psql" ]
+			main_command += [ "--host", "localhost" ]
+			main_command += [ "--port", port ]
+			main_command += args.cmd_args.get('extra_arguments')
+			main_command += [ database ]
+			main_command += [ username ]
+		elif args.cmd_args.get('command') == "mysql":
+			username = args.cmd_args.get('username') or database.get('username')
+			database = args.cmd_args.get('database') or database.get('database') or 'mysql'
+			main_command  = [ "mysql" ]
+			main_command += [ "--protocol", "tcp" ] # defaults to local socket otherwise
+			main_command += [ "--host", "localhost" ]
+			main_command += [ "--port", port ]
+			main_command += [ "--user", username ]
+
+			if args.cmd_args.get('password'):
+				# we intentionally only support -p without an argument; it would
+				# create ambiguity for argparse otherwise.
+				main_command += [ "-p" ]
+
+			main_command += args.cmd_args.get('extra_arguments')
+			main_command += [ database ]
+
+	elif args.cmd_args.get('command') == "tunnel":
+		l_args = [
+			args.cmd_args.get('local_port'),
+			args.cmd_args.get('remote_host'),
+			args.cmd_args.get('remote_port'),
+		]
+
+		ssh_command += [ "-L", ":".join(l_args) ]
+		ssh_command += [ ip_address ]
+		ssh_command += [ "echo Port forwarding tunnel established. Hit Ctrl-C to terminate.; sleep infinity" ]
+
+	if main_command:
+		mc_path = shutil.which(main_command[0])
+
+		if not mc_path:
+			raise SystemExit(f"ERROR:  Command {main_command[0]} not found")
+
+		main_command[0] = mc_path
+
+	return (ssh_command, main_command)
+

farssh/const.py

@@ -0,0 +1,4 @@
+FARSSH_VERSION = "0.4"
+FARSSH_ID = 'default'
+FARSSH_URL = 'https://github.com/apparentorder/farssh'
+

farssh/ssh.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+
+import subprocess
+import tempfile
+
+# ----------------------------------------------------------------------
+
+class FarsshSshKeyHandler:
+	def __init__(self, farssh_args):
+		self._tempdir = tempfile.TemporaryDirectory()
+
+		self.farssh_args = farssh_args
+		self.known_hosts_file = f"{self._tempdir.name}/known-hosts"
+
+		subprocess.run(["ssh-keygen", "-q", "-N", "", "-t", "rsa", "-f", f"{self._tempdir.name}/ssh_host_rsa_key"], check = True)
+		subprocess.run(["ssh-keygen", "-q", "-N", "", "-t", "rsa", "-f", f"{self._tempdir.name}/ssh_login_key"], check = True)
+
+		self.host_key_file =      f"{self._tempdir.name}/ssh_host_rsa_key"
+		self.host_key_pub_file =  f"{self._tempdir.name}/ssh_host_rsa_key.pub"
+		self.login_key_file =     f"{self._tempdir.name}/ssh_login_key"
+		self.login_key_pub_file = f"{self._tempdir.name}/ssh_login_key.pub"
+
+		self.host_key = open(self.host_key_file, "r").read()
+		self.host_key_pub = open(self.host_key_pub_file, "r").read()
+		# self.login_key = open(self.login_key_file, "r").read() # not used
+		self.login_key_pub = open(self.login_key_pub_file, "r").read()
+
+	def write_known_hosts(self, ip_address):
+		# Create temporary known-hosts file so the SSH client can verify the remote host's public key that we configured it with.
+		# The `host` *must* be without port number when the port is 22; this seems to be a quirk of OpenSSH's known-hosts file format.
+
+		with open(self.known_hosts_file, "w") as f:
+			host = ip_address
+
+			if self.farssh_args.ssh_port != "22":
+				host = f"[{host}]:{self.farssh_args.ssh_port}"
+
+			f.write(f"{host} {self.host_key_pub}\n")
+

farssh-0.4.dist-info/METADATA

@@ -0,0 +1,273 @@
+Metadata-Version: 2.3
+Name: farssh
+Version: 0.4
+Summary: Secure on-demand connections into AWS VPCs
+Project-URL: Homepage, https://github.com/apparentorder/farssh
+Author-email: "@apparentorder" <apparentorder@neveragain.de>
+License: BSD 2-clause
+Keywords: aws,mysql,postgresql,proxy,rds,ssh,tunnel,vpc
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Requires-Dist: boto3
+Description-Content-Type: text/markdown
+
+## FarSSH
+
+FarSSH provides secure on-demand connections into AWS VPCs.
+
+You can easily connect to in-VPC resources like RDS and OpenSearch endpoints, using tools installed on your local machine.
+
+FarSSH features a SOCKS proxy mode, enabling your browser to be "in" the target VPC; this works both for accessing VPC
+resources and as a quick way to tunnel all your browser traffic, so your browser's connections will
+appear to come from this AWS region's public IP addresses (like a VPN).
+
+FarSSH integrates with the `psql` and `mysql` command line clients for easy database access.
+
+Resources are deployed in *your* AWS account; there is no third party / no external service involved. AWS charges apply,
+at roughly $0.01 per hour (billed per second) per active client; no charges when no client is active.
+
+
+## Usage
+
+### SQL Client Mode
+
+To launch a `psql` or `mysql` client directly to one of your RDS databases (instance or cluster), simply:
+```
+farssh psql [-U username] [database_name]
+```
+
+For MySQL / MariaDB:
+```
+farssh mysql -p [-u username] [database_name]
+```
+
+When not specified, username and database_name will be taken from the RDS configuration (master username and the
+initial database).
+
+If only one matching RDS database is available, it will automatically be selected. If there are multiple databases,
+use `--identifier` to select one; otherwise, a list of available databases will be shown.
+
+### Tunnel mode
+
+Forward a local port to your VPC like this:
+```
+farssh tunnel 5432 pg-cluster.cluster-foo.eu-central-1.rds.amazonaws.com
+```
+
+Then connect to the local port 5432 on your machine, e.g. just using `psql -h localhost` in another shell, or your favorite GUI client.
+
+Remember to terminate the FarSSH session using `^C` when done.
+
+### Proxy mode
+
+Simply run
+```
+farssh proxy
+```
+
+Then configure your browser to use a SOCKS proxy on `localhost`, port 1080.
+
+Remember to terminate the FarSSH session using `^C` when done.
+
+### SSH mode
+
+If you just need a shell inside your VPC, run
+```
+farssh ssh
+```
+
+### Additional Arguments
+
+The `psql`, `mysql` and `ssh` commands can be used with additional arguments that will be passed to the client, so you
+could do something like `farssh ssh -- /sbin/ip address` or `farssh psql -- -c "select foo from bar"`.
+
+
+## Installation
+
+### Requirements
+
+ * The target VPC needs to have a public subnet
+   * note that the connection target (FarSSH tunnel mode) can be in a private subnet, or, via VPC peering, even
+     in a different VPC
+ * For the client machine:
+   * local AWS configuration (appropriate credentials / profiles configured etc.)
+   * Python 3
+   * [AWS SDK for Python](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html), aka `boto3`
+   * OpenSSH `ssh` client
+   * The `psql` / `mysql` command line utilities if you want to use the respective mode
+
+### Deploy configuration on AWS
+
+Use this [Cloudformation quick-create link](https://console.aws.amazon.com/cloudformation/home#/stacks/create/review?templateURL=https://farssh.s3.amazonaws.com/cloudformation/farssh.yaml&stackName=farssh-default) to deploy necessary
+resources in the target environment.
+
+For Subnets, be sure to select one or more *public* subnets, i.e. that are connected to an Internet Gateway.
+
+Make sure you have selected the correct region! For a list of created resources,
+see below.
+
+**NOTE: If you intend to use IPv6, please read below, before continuing**
+
+**NOTE: If Cloudformation fails to create the stack with this error ...**
+```
+Unable to assume the service linked role. Please verify that the ECS service linked role exists.
+```
+... then please delete the stack from Cloudformation and simply retry from the quick-create link above.
+That role is automatically created by AWS on first-ever ECS usage, but the cluster creation fails anyway. If
+you know how to properly fix this in Cloudformation, please let me know.
+
+
+### Allow connections from FarSSH
+
+Adjust your existing Security Groups to allow inbound connections from the FarSSH Security Group.
+
+For example, to allow tunnel connections to your RDS instance, modify a corresponding RDS instance Security Group:
+* Edit *inbound rules*
+* Type: PostgreSQL (or MySQL or ...)
+* Source: custom: security group `farssh-default`
+
+### Install the FarSSH client
+
+The FarSSH client is available in the Python Package Index, so you can simply use `pip` to install and update:
+
+```
+pip install farssh
+```
+
+FarSSH will use the target AWS account, region and credentials from the local AWS configuration, e.g. your configuration in `~/.aws`,
+your `AWS_PROFILE` and `AWS_REGION` environment variables etc.
+
+**Note:** Make sure that your local environment uses the same AWS account and region that you deployed the
+Cloudformation template to.
+
+That's it. For usage, see above.
+
+
+### Updating
+
+To update the FarSSH client, simply re-download the client (see above).
+
+To update the FarSSH Cloudformation template, select the FarSSH stack in the Cloudformation console, hit
+"Update" and replace the template using this S3 url: `https://farssh.s3.amazonaws.com/cloudformation/farssh.yaml`
+
+To update FarSSH settings, update the stack with the "Use current template" option.
+
+
+## IPv6 Support
+
+Given that AWS now charges for any use of public IPv4 addresses, it's important to use IPv6 when possible.
+
+FarSSH supports IPv6 both on the AWS side and on the client.
+
+### Client Side
+
+Run the client with the option `-6` (or `--ipv6`) to make it connect to the FarSSH ECS task via IPv6. The
+client will fail when the FarSSH ECS task does not have an IPv6 address.
+
+### Server Side (ECS)
+
+IPv6 for the FarSSH ECS task is a bit more complicated, as we need to work around several IPv6 potholes in AWS.
+
+To allow IPv6 connections from the client, you only need to make sure that the configured public subnets have IPv6 configured.
+Fargate tasks will automatically get an IPv6 address. If that doesn't work out of the box, double-check the ECS [`dualStackIPv6` setting](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-account-settings.html).
+
+But an ECS task also needs some IP connectivity to pull the image and to send logs to Cloudwatch. If you have neither VPC endpoints
+nor NAT in your VPC, this will cause the ECS task to fail when a FarSSH client uses IPv6.
+
+The Cloudformation template has some knobs for this:
+
+The easy fix is to set `ForcePublicIpv4` to `true` in the Cloudformation stack; FarSSH will then always
+request a public IPv4 address, even when a clients connects via IPv6. With the public IPv4 address, everything works.
+
+Alternatively, to fully avoid using public IPv4 addresses, change these options during the Cloudformation setup:
+
+- set `ImageUri` to the `docker.io` address (the AWS ECR does not support IPv6)
+- disable the `awslogs` driver (Cloudwatch Logs does not support IPv6)
+
+
+## How it works
+
+FarSSH is basically a wrapper around an OpenSSH server and your local OpenSSH client. The latter does the
+actual work of tunneling (local port forwarding, parameter `-L`) and proxying (SOCKS proxy, parameter `-D`).
+
+FarSSH consists of three rather simple components to glue it together. Here's a highly professional
+architecture diagram:
+
+![farssh architecture painting](https://pbs.twimg.com/media/Fz776zoWIAI6f89?format=png&name=900x900)
+
+### Container image
+
+FarSSH publishes a container image in AWS Public ECR at `public.ecr.aws/apparentorder/farssh`. This is
+a tiny Alpine-based image that only runs an SSH server. There is also a background process that will
+terminate the task if there are no active connections.
+
+The same image is also published to Dockerhub at `docker.io/apparentorder/farssh`, because Dockerhub
+supports IPv6 and AWS Public ECR does not. Using Dockerhub over IPv4 might result in pull errors due
+to rate limit though.
+
+### Resources in the target environment
+
+The Cloudformation template creates the following resources so FarSSH tasks can be run in the target
+environment:
+
+  * IAM roles for the ECS task (TaskRole and ExecutionRole)
+  * ECS resources: cluster `farssh`, task definition `farssh-default`
+  * SSM Parameters `/farssh/*`
+  * Security Group `farssh-default`
+
+### Client
+
+The "client" pulls a few parameters from SSM Parameter Store
+and then starts an ECS Task with the FarSSH image. The FarSSH task will be available after a few seconds.
+
+The client will then start an `ssh` session to the public IP address of the FarSSH task.
+
+Key pairs are generated locally for both the client connection and the FarSSH task's SSH host key, and
+the SSH client will "strictly" check the expected host key.
+
+### Caveats
+
+* Currently, FarSSH can be deployed to only one VPC per region per account (deploying multiple times to
+  different regions works fine)
+
+
+## Future ideas
+
+* Support for multiple VPCs per region
+* Optionally use some kind of "reverse SSH", so the FarSSH task does not need a public IP address
+* Enable using existing ECS clusters (possibly including EC2-based)
+* Only half-way through building this I realized that I could have built the same thing for an
+  ad-hoc VPN endpoint instead of an SSH server; I have yet to think through what kind of sense
+  that could make
+* Properly tag the public ECR image(s) so it can be coupled with released versions
+
+ 
+  
+## Motivation
+
+To my knowledge, all alternative options use [time-based billing](https://tty.neveragain.de/2021/06/29/timeless-services.html),
+meaning that you pay a base fee for having them around, even if you're not using them at all.
+For example, while AWS ClientVPN does charge per connection hour, it also charges you just for
+being associated to your VPC.
+
+AWS recently announced [EC2 Instance Connect Endpoints](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connect-using-eice.html)
+which absolutely solve this problem, even without additional charges. For a few days after release, this
+allowed to make arbitrary TCP connections (e.g. to your RDS instance's port 5432!).
+
+Unfortunately, AWS decided that while this works great and allows most customer to get rid of jump hosts
+once and for all, it's just too easy. As it stands today, it's artificially limited to target ports 22 (ssh)
+and 3389 (RDP). This move also influenced this project's name: While "FarSSH" is a play on "Fargate" and "SSH",
+it shall be pronounced "farce" – because this project shouldn't have to exist.
+
+
+
+## Contact
+
+For bug reports, pull requests and other issues please use Github.
+
+For everything else:
+
+I'm (still) trying to get used to X/Twitter as [@apparentorder](https://twitter.com/apparentorder). DMs are open.
+You can also try legacy message delivery to apparentorder@neveragain.de.
+

farssh-0.4.dist-info/RECORD

@@ -0,0 +1,11 @@
+farssh/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+farssh/__main__.py,sha256=ROQYTg4ZonNI_9Q2HHBzur3c3muk476XbUa4JpseIEQ,1290
+farssh/args.py,sha256=MymYlAwntfXibNftjTTn96i1CxzWxwoVjrp0TZhTFzI,3938
+farssh/aws.py,sha256=jMGxe6nXdull1QpdYNdLsgUw8IXOHTLAxLWIHSo5cXk,5531
+farssh/commands.py,sha256=hSFOJLRfXxcU3fH1wGmyCYqM8Od0BdkEKIMbEQbOGHE,2990
+farssh/const.py,sha256=5glhV7D_xx-9x-RyYk8TDLLMyj6bQNzkYLYVJjDT0t0,101
+farssh/ssh.py,sha256=Vg5ex4HL1R7aAwj2W8UDStDctX8Pkcz-V5VLYXrjWMo,1620
+farssh-0.4.dist-info/METADATA,sha256=cdNyXc-q4je7AjnMXmv9yuyo0iQQFqB1uDYKwJoXP54,11128
+farssh-0.4.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
+farssh-0.4.dist-info/entry_points.txt,sha256=z_HBSvz92D1GbXve__7qdAgOS1uUrG4bVGVnOxrfx5w,48
+farssh-0.4.dist-info/RECORD,,

farssh-0.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.26.3
+Root-Is-Purelib: true
+Tag: py3-none-any

farssh-0.4.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+farssh = farssh.__main__:main