Re-order and re-priorise after review

Author: aug24

README.md

@@ -1,26 +1,73 @@
 Deprecation Announcement
 ========================
 
-SSM-Scala is now considered deprecated.  All its functionality is available within the AWS CLI.  eg:
+tl;dr
 
-Finding oldest running instance by Guardian tags:
+You should stop using SSM Scala.  It is no longer maintained, and the AWS CLI has all the same functionality, and more.
+SSM Scala is no longer worth the maintenance cost.  It won't be deleted, but you should consider moving away from it.
+
+In an ideal world, you don't need ssh access to an instance at all.  Consider _why_ you want to do this.
+
+The simplest way to get ssh access to an instance is to
+ * obtain the `.ssh` permission in Janus for your account
+ * access the EC2 instance page console
+ * find the instance you want to access
+ * click the Connect button:
+
+![deprecation/connect.png](deprecation/connect.png)
+
+This has the advantage that you don't need to put any credentials on your laptop, just click through from Janus to the
+AWS console to the ssh session.  This is preferable, because credentials for ssh access are sufficient to access all the
+secrets that the instance has access to, and also to obtain the instance's role credentials, which can be used to access
+other AWS resources.
+
+If that's not sufficient, see the [./deprecation/scripts](./deprecation/scripts) directory for worked example command line scripts,
+and below for instructions on how to use aws ssm to access instances from a container to avoid putting credentials on
+your laptop.
+
+# Quick scripts
+
+These commands should be run inside a dev container with the AWS CLI installed and configured with credentials.
+
+Replace values in capitals.
+
+## Starting a session on an instance
+
+```
+aws --profile $PROFILE --region $REGION ssm start-session --target $INSTANCEID
 ```
-aws ec2 describe-instances \
+
+## Starting a tunnel to a remote host via an instance
+
+```
+aws ssm start-session \
+    --document-name AWS-StartPortForwardingSessionToRemoteHost \
+    --parameters '{
+      "host":["$HOST"],
+      "portNumber":["$REMOTE_PORT"],
+      "localPortNumber":[
+        "$SSM_PORT"
+      ]
+    }' \
+    --target $INSTANCEID
+```
+
+## Finding oldest running instance by Guardian tags
+```
+aws --profile $PROFILE --region $REGION ec2 describe-instances \
     --filters \
-        "Name=tag:App,Values=$app" \
-        "Name=tag:Stack,Values=$stack" \
-        "Name=tag:Stage,Values=$stage" \
+        "Name=tag:App,Values=$APP" \
+        "Name=tag:Stack,Values=$STACK" \
+        "Name=tag:Stage,Values=$STAGE" \
         "Name=instance-state-name,Values=running" \
     --query "Reservations[].Instances[] | sort_by(@, &LaunchTime)[0] | InstanceId"
 ```
-and starting a session on an instance:
-```
-aws ssm start-session --target $instanceid
-```
 
-For more information and worked examples, visit [the deprecation documentation](deprecation/README.md).
+For more information and worked examples, visit the [deprecation documentation](deprecation/README.md).
+
+
 
-Original Documentation follows
+**Original Documentation follows:**
 
 SSM-Scala
 =========

deprecation/README.md

@@ -1,79 +1,31 @@
-# Purpose
+# Using AWS SSM commands from a docker container to restrict credentials scope
 
-AWS SSM has been sufficient to achieve virtually all ssh type needs for some time.  However, it has two
-issues we should address.
+NB This is a worked example, not a production-ready solution.  It is intended to demonstrate how to use AWS SSM commands
 
-## AWS CLI is more powerful
-
-When it was first written, in 2018, by the then security team, fifty percent of whom are now back on the security team,
-SSM Scala closed a gap in the AWS CLI.  It required instances to be permitted access via the ssh port (22) and managed 
-discovery, then it created an ssh key, and put it on the instance, allowing the user to ssh in.  It also allowed for
-port forwarding, and other useful ssh features.
-
-The AWS CLI has since been updated to include almost the same functionality, but better.  Instances no longer need to
-be permitted access via the ssh port, and the AWS CLI can now do port forwarding by host name.
-
-SSM Scala is no longer worth the maintenance cost.  It won't be deleted, but you should consider moving away from it.
-
-![ssm-scala-tombstone.png](ssm-scala-tombstone.png)
-
-## More paranoia around credentials
-
-The AWS credentials used to get a session on a remote instance inherently provide a lot of power.  Once you have a
-session on an instance, you can use the instance's profile to access quite a lot of information, and any secrets
-the instance can read.
-
-For example: 
-```
-# Fetch the user data script
-TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
-curl -s -H "X-aws-ec2-metadata-token: $TOKEN" \
-  http://169.254.169.254/latest/user-data
-```
-or even
-```
-# Fetch the private cert
-aws --region eu-west-1 s3 cp s3://my-bucket-of-secrets/my-stack/PROD/my-secure-app/secret-cert.json
-```
-or EVEN
-```
-curl -H "X-aws-ec2-metadata-token: $TOKEN" \
-  http://169.254.169.254/latest/meta-data/iam/security-credentials/[role-name]
-```
-
-Incidentally, there is now a dedicated `.ssh` permission in Janus, which gives just enough permissions to discover
-and access an instance within the account, without providing the excessive power of `.dev`
-
-Even with those reduced credentials, we should aim use the same approach as devcontainers, and not put "bare" 
-credentials on our laptops (where they can potentially be exfiltrated by attackers) at all.
-
-This is a simple setup to deliver containerised ssh to instances, with discover built in.  You can use this, or take
-the principles and build your own, but the important thing is to avoid putting credentials on your laptop.
-
-# Setup
+## Setup
 
 Build a small docker image which includes some scripts, the AWS cli tool and, crucially, the SSM session manager plugin for AWS.
 
 ```
 docker build -t aws-shell .
 ```
 
-# Run
+## Run
 
 ```
 docker run -it aws-shell bash
 ```
 
 These can be done in one clean step using the `scripts/container` script.
 
-# Configuring
+## Configuring
 
 Grab your AWS credentials as `aws configure` commands.  Make sure the profile name is `default` or set `AWS_PROFILE`.
 Paste them into the docker shell.  The region is already set to eu-west-1, but can be overridden on the command line.
 
-# Examples
+## Examples
 
-## Starting a remote SSM session
+### Starting a remote SSM session
 
 ```
 docker run -it aws-shell bash
@@ -87,9 +39,9 @@ Connecting to i-0c7f9cb1234567890
 Starting session with SessionId: justin.rowles-rycskjdsfjkgflkbgdflksdfakl
 ```
 
-## Starting a tunnel to a remote host
+### Starting a tunnel to a remote host
 
-### Ports
+#### Ports
 
 There will be three ports in play.
 
@@ -109,7 +61,7 @@ host-tunnel myApp myStack myStage theirHostName
 ```
 to open a tunnel on the oldest instance with those tags from SSM_PORT to <theirHostName>:REMOTE_PORT
 
-A similar approach can be used to get to remote RDS hosts, looking them up with tags, using `rds-tunnel.
+A similar approach can be used to get to remote RDS hosts, looking them up with tags, using `rds-tunnel`.
 
 At this point, you can run a client to the remote host communicating on localhost:CONTAINER_PORT.  This
 client can be anything - psql, curl, ftp...