Cased Shell on AWS: Provision and deploy on your pre-existing architecture in minutes

Overview

Amazon Web Services (AWS) is the largest cloud provider in the world — and it's easy to run Cased on AWS by using AWS's built-in container services. Using Amazon ECS (a fully managed container orchestration service) we will walk through how simple it is to get Cased Shell up and running on your AWS production systems in minutes.

Cased Infrastructure

Let's first take a glance at what Cased Shell is like under the hood. Cased Shell is deployed as a standalone Python application on your own infrastructure. It runs with a single Docker container, hosted on GitHub. It features automatic SSL setup, allowing for encryption all the way to the application. It can be deployed using standard container orchestraction software (k8s, EKS, ECS, etc) or just run on a host. Users interact with Cased Shell through a web browser, with websockets used for real-time browser communication. Cased Shell is designed to be extremely lightweight, and does not require any data storage beyond setting a few environmental variables when you run the service. The app requires minimal configuration itself, and some light operations work (outlined here) to get the app running on your infrastructure.

Cased Infrastructure on AWS example

This diagram roughly outlines what running Cased Shell on AWS looks like.

Straight-forward enough! It's easy to configure and fits right with typical AWS topologies. Some things to note - prompts are Cased's abstraction for endpoints. They can be a regular host, a container, or an application prompt. They are still an abstraction: Cased Shell is always just making SSH connections via SSH to a host that is running sshd. Additionally, non-transient data (configuration, session recordings, metadata) is currently stored with JSON and flatfiles in either S3 or minio. This was done for initial deployment simplicity. It’s a configurable data layer, with support for S3, minio, and soon additional databases and storage engines.

Provisioning via Terraform Module

This is the easiest option to deploy Cased. Using our Terraform module, organizations can easily deploy Cased Shell on ECS, featuring end-to-end encryption, and using a network load balancer. Here's a link to the Terraform registry, as well as the usage documentation.

Provisioning via Docker

Besides the Terraform module, what follows is the recommended and tested approach to getting a single Cased Shell instance running on AWS. There are of course other ways to deploy Cased Shell (it's just a single Docker image that you need to get running and accessible) — but this process is quick and straight-forward, and should work well with existing infrastructure setups.

• Cased Shell runs as a single Docker image at ghcr.io/cased/shell. You can use the latest tag as we are rapidly adding features, but also releasing versioned images.
• Set up a subdomain (e.g., shell.mydomain.net). Cased Shell takes care of SSL entirely for you, and the application runs on 443. The container does need both port 80 and port 443 open. The application itself runs on 443.
• Setup a Network Load Balancer that forwards raw TCP traffic on both 443 and 80 to a single container. For fast and effective startup and updating:
  • Set a high health check grace time number (figure 800-1000 seconds to be safe), since you're just using a single container
  • Set your NLB health check interval to 10 seconds.
  • Set your healthy/unhealthy threshold to 2.
  • Set your ECS deregistration_delay to 60 seconds.
  • Set the target group's preserve_client_ip value to true, so you get accurate logging of client IP addresses.
• Remember that when using a NLB, you set access control at the container level, not the load balancer. So if you want your app on 443 to be accessible to only some IPs, you need to set the correct security groups at the container/ECS level. Port 80 can be safely let open to the world, and is necessary to do so for automatic https setup.
• The application exposes a /_ping route that you should use for your load balancer health checks. It returns a 200, the current epoch time, and version.
• Deploy the pre-built Docker container with an ECS service. We use terraform to do this at Cased, but obviously CloudFormation or other config management software works. You will only need a single task, running the shell image.
• There are a few environmental variables/secrets you'll need to set into your container. You can find the first two values on your Shell settings page.
  • CASED_SHELL_HOSTNAME
    • The hostname of your installation (e.g. myshell.mydomain.net). Don't include the protocol.
  • CASED_SHELL_SECRET
    • A secret used for verifying API requests for Shell.
• Additional optional env vars. You can include any of these, or none. For example, you can include the private key, but not the passphrase. The application will prompt you during use for whatever data is not yet stored.
  • CASED_SHELL_KEPPALIVE_INTERVAL
    • How often (in seconds) to send keep-alives. Defaults to 30.
  • CASED_SHELL_SSH_PRIVATE_KEY
    • The text of an SSH private key to store in the container. If SSH certificates are not enabled, this key will be used for all SSH access.
  • CASED_SHELL_SSH_USERNAME
    • The username associated with the key.
  • CASED_SHELL_SSH_PASSPHRASE
    • A passphrase for the SSH key.
  • You can read more about the application's required and optional environmental variables.
• Make sure the SSH ports on your hosts will accept connections from the Cased Shell service. If you use a NAT, make sure your NAT IPs, are in the relevant security group.
• Cased Shell logs to stdout in it's container, so log messages should automatically get picked up by most Docker loggers (e.g., Datadog's logger).

After these best practices, Cased Shell will now be deployed onto your AWS infrastrucure and ready to expedite production work.

If you're interested and want to learn more schedule a demo or visit our documentation.