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.
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.
- Make sure you have the AWS CLI installed and that AWS credentials are properly configured before starting. You can do this by running
aws configureon the command line. - Clone this repository, change directory to it, and run
npm install - 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.
- Edit the
secrets.jsonfile and replaceAUTH0_CLIENT_IDwith the Client ID found in the previous step. - Go back to Auth0 Application settings and click on Show Advanced Settings -> Certificates. Copy and paste the Signing Certificate into the
public_keyfile. - Edit
frontend/app.js. ReplaceAUTH0_CLIENT_IDwith the Client ID andAUTH0_DOMAINwith the Domain found in Step 3. ReplaceleaseTimewith the desired time for temporary SSH permissions in seconds - Edit the
serverless.ymlfile where you will need to change the environment variables under provider -> environment section.
- Change
VPC_IDto your vpc id. You can find it in the AWS Console in the VPC section under Your VPCs. - Change
USER_AWS_REGIONto the region you want to deploy resources in - Change
S3_BUCKET_NAMEto something unique. An error will be thrown if the S3 bucket name is already taken.
- Run
sls deployat the command line. - A URL will be generated under endpoints if deployment runs sucessfully. In
app.js, replacePRIVATE_ENDPOINTwith this URL. Runsls client deployand type Y when prompted. This updates and deploys the front-end. - 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.
- 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.
- 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.
A development environment can be set up by following the steps outlined in Getting Started
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.
Check out the contributing guide.
- 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 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.
This project is MIT licensed.