AWS Acme Instant Tunnel

AWS Acme Instant Tunnel is a tool to temporarily grant SSH access via Port 22 for a preconfigured EC2 instance to an authorized & authenticated user.

The CIS security benchmark for AWS recommends that Port 22 should have no public incoming traffic (0.0.0.0/0), so a problem arises when trying to access instances via SSH. A possible solution to this would be manually adding permissions (access from a specified IP address for example) to a instance's security group, but this could be very error prone and inconsistent. Some enterprises deal with this issue by having people VPN into their corporate network and having people SSH from there. However, this doesn't make sense for many distributed organizations where there is no VPN or granting access to a VPN is not a good idea for those who need to SSH into AWS resources.

AWS Acme Instant Tunnel presents an alternative to the two aforementioned approaches by automating the authorization, management and storage of security group permissions for temporary SSH access.

• Getting Started
• How it Works
• Developing
  • Prerequisites
  • Testing
  • Contributing
• Modus Create
• Licensing

How it works

This project uses these tools and services:

• Serverless framework
• Auth0, providing SAML & SSO Authentication via Google G-Suite or Github
• Amazon API Gateway
• AWS Lambda with Node.js
• Amazon S3 Static Web Site Hosting
• DynamoDB
• AWS EC2 including VPC Security Groups

The front-end web site is hosted on a S3 bucket. A basic demo can be accessed here

Users are authenticated and authorized through Auth0. You are able to configure different Identity Providers but Google G-Suite is the default.

Once logged in, users can click Tunnel into EC2 to gain access to an EC2 instance via SSH.

The code in this project uses the Serverless Framework to configure the underlying resources - AWS Lambda functions, DynamoDB table, and Security Groups. When a user clicks Tunnel into EC2, it triggers a Lambda function that adds an entry to the preconfigured DynamoDB table and a temporary permission into the preconfigured Security Group that is connected to an EC2 instance.

An item with lease start and end time, user IP address, and email address are added to DynamoDB table. The timestamps are in seconds since Epoch format. A corresponding security group ingress permission is added. The user can now SSH into this instance.
Security Group is added based on the IP Address & email held in the DynamoDB table.

The DynamoDB table has TTL enabled on the leaseEnd attribute. When the leaseEnd attribute is expired, the item will automatically delete itself and will also revoke the corresponding security group ingress permission. The user now cannot SSH into this instance.

Getting Started

1. Make sure you have the AWS CLI installed and that AWS credentials are properly configured before starting. You can do this by running aws configure on the command line.
2. Clone this repository, change directory to it, and run npm install
3. Go to Auth0 and sign up for an account. Go to Applications and click on your Default App. Here you can find your Auth0 development credentials for the next steps. Save the Client ID and Domain.
4. Edit the secrets.json file and replace AUTH0_CLIENT_ID with the Client ID found in the previous step.
5. Go back to Auth0 Application settings and click on Show Advanced Settings -> Certificates. Copy and paste the Signing Certificate into the public_key file.
6. Edit frontend/app.js. Replace AUTH0_CLIENT_ID with the Client ID and AUTH0_DOMAIN with the Domain found in Step 3. Replace leaseTime with the desired time for temporary SSH permissions in seconds
7. Edit the serverless.yml file where you will need to change the environment variables under provider -> environment section.

• Change VPC_ID to your vpc id. You can find it in the AWS Console in the VPC section under Your VPCs.
• Change USER_AWS_REGION to the region you want to deploy resources in
• Change S3_BUCKET_NAME to something unique. An error will be thrown if the S3 bucket name is already taken.

8. Run sls deploy at the command line.
9. A URL will be generated under endpoints if deployment runs sucessfully. In app.js, replace PRIVATE_ENDPOINT with this URL. Run sls client deploy and type Y when prompted. This updates and deploys the front-end.
10. With a successful front-end deployment, you should get an S3 URL where the web app is hosted. Copy this URL and go to Auth0 settings. Find Allowed Callback URIs under Application URIs and paste the S3 URL into this box. Make sure to Save Changes at the bottom.
11. Open the AWS Console and go to the EC2 instances section. Launch an EC2 instance (any storage or instance type settings are fine). Configure an existing security group and select the acme-instant-tunnel group that was generated during deployment. Generate and key pair and make sure to keep track of the key pair for when you want to SSH into the instance.
12. Navigate to the S3 URL that was generated in Steps 9-10. You should be able to log in and click Tunnel into EC2 with a success message 'You can now SSH into the EC2 instance for 1 hour'. After this, you can try to connect to the EC2 instance via SSH and it should work.

Developing

A development environment can be set up by following the steps outlined in Getting Started

Prerequisites

• AWS Account
• Auth0 Account

Testing

This project currently has no formal test suite of manual or automated tests. Deploy the code and perform manual exploratory tests. Contributions of tests would be welcome.

Contributing

Check out the contributing guide.

References

• The classic Warner Brothers cartoon Fast and Furry-ous: watch it on YouTube and learn about its history on Wikipedia
• Serverless Auth0 tutorial

Modus Create

Modus Create is a digital product consultancy. We use a distributed team of the best talent in the world to offer a full suite of digital product design-build services; ranging from consumer facing apps, to digital migration, to agile development training, and business transformation.

This project is part of Modus Labs.

Licensing

This project is MIT licensed.