Cased

Cased developer and API documentation

Add a comprehensive, high-signal, and tamper-proof audit trail to any application in minutes. Give your compliance, security, and customer support teams the information they need.

Host and container auto-detection

Learn how Cased Shell's auto-detection feature works.

To ensure that your teams can quickly access the command-line tools they need - whether they exist on a long-lived host, or on a container created 45 seconds ago - Cased Shell can be configured to provide quick and easy access to those command-line prompts using our host auto-detection feature.

Overview

Cased Shell’s prompt auto-detection feature is configured with a list of queries and associated metadata designed to describe the results and connection options necessary to connect to a prompt. The provided queries are run against your cloud provider’s APIs, and any returned results are presented to the user along with the included metadata. This powerful combination of queries and metadata allows you to provide one-click access to the tools your team needs, like a “Rails Console” link that automatically runs the bin/rails console command in a container named rails-prod-f567d6c running on i-456afc9 (after first establishing a connection to bastion-567cee7).

Supported cloud providers

Your infrastructure may include a frequently-changing collection of hosts. For this use case, Cased Shell includes a 'static' provider which allows statically configured hosts, or supports the dynamic listing of hosts using API calls against another provider. Currently, Cased Shell's prompt auto-detection feature discovers prompts by running queries against the EC2 and ECS APIs (AWS). Please contact us if you’d like to use Cased Shell to detect prompts on another provider!

Configuring prompt auto-detection

When using our supported Terraform-based ECS deployment, Cased Shell’s prompt auto-detection feature is enabled by providing a list of jump_queries to the Terraform module. Each query has three general parts: provider configuration, filters, and prompt metadata:

jump_queries = [
  {
    # Provider configuration
    provider  = "ec2"        # ec2, ec2, or static
    limit     = 1            # optional, defaults to no limit
    sortOrder = "desc"       # optional, defaults to "asc"
    sortBy    = "startedAt"  # optional, provider specific

    # Filters
    # See https://github.com/cased/jump#providers for a full list of filters for each provider.
    filters   = {
        "tag:aws:autoscaling:groupName" = "*test*"
    }

    # Prompt metadata can be used to customize how this prompt is displayed,
    # as well as influence how Cased Shell connects to this prompt.
    prompt   = {
      name        = "Newest test instance" 
      description = "The newest instance in the 'test' autoscaling group."

      # Prompts can be "featured" above the fold by setting this value to true.
      featured    = true

      # Labels can be used to filter and group related prompts together.
      labels      = {
        environment = "test"
      }

      # If necessary, the SSH connection established when clicking on this prompt
      # can be configured using the following fields:
      # hostname = "example.com"
      # ipAddress = "1.2.3.4"
      # port      = "2222"
      # username  = "root"

      # If this prompt requires a key or username different from the default,
      # you can set the following fields to prompt the user each time:
      # promptForUsername = true
      # promptForKey      = true

      # Additional commands can be run immedaitely after connecting to a
      # prompt by setting the following fields:
      # jumpCommand  = "docker exec -it app-container"
      # shellCommand = "./bin/rails console"

      # If the instance that this prompt points has restricted access to 
      # its SSH ports to instances in another security group, you can instruct
      # Cased Shell to automatically proxy the connection via _another_ prompt
      # it knows about by using the `proxyJumpSelector` field, which expects a
      # hash of labels that identify the prompt to proxy the connection through.

      # proxyJumpSelector = {
      #   app = "bastion"
      # }

    }
  }
]

Examples

jump_queries = [
    # The most recently launched bastion instance in the test cluster
    {
      provider = "ec2"
      filters = {
        "tag:aws:autoscaling:groupName" = "*bastion*"
        "tag:cluster"                   = "*test*"
      }
      limit     = 1
      sortBy    = "launchTime"
      sortOrder = "desc"
      prompt = {
        name        = "Bastion host"
        featured    = true
        description = "newest bastion instance"
        labels = {
          environment = "test"
          app         = "bastion"
          shell       = "bash"
        }
      }
    },
    # All EC2 nodes in the test ECS cluster, proxied through the bastion host
    # above.
    {
      provider = "ec2"
      filters = {
        "tag:aws:autoscaling:groupName" = "*test*"
      }
      prompt = {
        name = "ECS node"
        labels = {
          environment = "test"
          app         = "ecs"
          shell       = "bash"
        }
        proxyJumpSelector = {
          app = "bastion"
        }

      }
    },
    # A Rails console in the container called "rails" launched as a part of the
    # "test-service"  ECS service in the test ECS cluster, proxied through the
    # bastion host above. This prompt is featured to provide one click access
    # to the Rails console.
    {
      provider = "ecs"
      filters = {
        cluster        = "test"
        task-group     = "service:test-service"
        container-name = "rails"
      }
      limit     = 1
      sortBy    = "startedAt"
      sortOrder = "desc"
      prompt = {
        name         = "Rails Console"
        featured     = true
        description  = "Use to perform exploratory debugging on the test cluster"
        shellCommand = "./bin/rails console"
        labels = {
          environment = "test"
          app         = "rails"
          shell       = "rails"
        }
        proxyJumpSelector = {
          app = "bastion"
        }
      }
    },
    # Allow access to a bash prompt on all Rails containers on the test cluster.
    {
      provider = "ecs"
      filters = {
        cluster        = "test"
        task-group     = "service:test-service"
        container-name = "rails"
      }
      prompt = {
        name         = "Bash on rails container"
        shellCommand = "/bin/bash"
        labels = {
          environment = "test"
          app         = "rails"
          shell       = "bash"
        }
        proxyJumpSelector = {
          app = "bastion"
        }
      }
    }
  ]

The source of this complete integration may be useful if you'd like to configure host auto-detection in some other way.

Please contact us if you have questions along the way!
FAQ

Updated about a month ago


Host and container auto-detection


Learn how Cased Shell's auto-detection feature works.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.