vpcjump 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 91bc9c02d6d0df3b88ee4e7660859087db1666ef
+  data.tar.gz: 058a24349db38b81fb048eb9a464493c47701559
+SHA512:
+  metadata.gz: 269e9d7410ab40a60c21bd3625b948e3cd96ca0e4712109dab73c7debf413a4ed94fcbb0ebeb48332f43567e908d9780bffe87169d5cd5cd6a6b7d8472d16699
+  data.tar.gz: 2cf93eb463b09b39e2da84b575e38c7fd016de82089d7b7815d1bc265b670b65023aba0f5f28c54ea234bdc64c407a49801ab1e89e581c55df1bb739c644e4ed

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in vpcjump.gemspec
+gemspec

data/README.md

@@ -0,0 +1,87 @@
+# `vpcjump`
+
+`vpcjump` is a helper tool to make it as easy as possible to connect to a jumpbox in an AWS [VPC](https://aws.amazon.com/vpc/). 
+
+What makes `vpcjump` unique is that your jumpbox doesn't need a public IP nor needs to open any ports in a security group. What it _does_ need is outbound Internet connectivity on port 443 - whether via a [NAT instance](http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_NAT_Instance.html), Amazon-managed [NAT gateway](http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/vpc-nat-gateway.html) or some custom solution. 
+
+## Setup
+
+* Install the tool: `gem install vpcjump`
+* Sign up for [ngrok](https://ngrok.com/) and note down your authentication token
+* Start an instance in EC2 - this only needs to be done once.
+
+You can launch the EC2 instance from the AWS web console. Amazon Linux on a t2.nano is sufficient. The t2.nano is less than $5/month (as little as $2.16/month if paid upfront!) so leaving it always up is quite affordable.
+
+When on step 3 (**Configure Instance Details**), expand **Advanced Details** and paste the following into **User data**:
+
+```
+#!/bin/bash
+cd /tmp
+curl https://amazon-ssm-ap-southeast-2.s3.amazonaws.com/latest/linux_amd64/amazon-ssm-agent.rpm -o amazon-ssm-agent.rpm
+yum install -y amazon-ssm-agent.rpm
+curl https://bin.equinox.io/c/4VmDzA7iaHb/ngrok-stable-linux-amd64.zip -o ngrok.zip
+unzip ngrok.zip
+mv ngrok /usr/bin/
+```
+
+You will also need to create and select an **IAM Role** for this instance to grant it permission to use [SSM](http://docs.aws.amazon.com/ssm/latest/APIReference/Welcome.html). To do this, you:
+
+* Click **Create new IAM role**
+* Click **Create New Role**
+* Specify a role name of your choice, e.g.`SSMForVpcjump`, then hit next.
+* Under **AWS Service Roles**, select **Amazon EC2 Role for Simple Systems Manager**, then hit next.
+* Tick the checkbox for **AmazonEC2RoleforSSM**, then next.
+* Click **Create Role**.
+* Return to the instance creation screen, hit refresh next to **IAM Role**, then select the role you just created.
+
+You can now proceed through the instance creation process - all the default values are fine. You can delete the security group rule opening up access to port 22 if you wish, this is unneeded. Once the instance has launched, note down the instance ID (looks like `i-abcdef`) as you will use it later.
+
+## Usage
+
+Invocation can be as simple as `vpcjump --ngrok-token <auth token> --instance-id i-abc123 ssh`. This takes about 30 seconds and will SSH you into the jumpbox instance. The complete list of options is:
+
+```
+$ vpcjump --help
+Usage:
+    vpcjump [OPTIONS] SUBCOMMAND [ARG] ...
+
+Parameters:
+    SUBCOMMAND                    subcommand
+    [ARG] ...                     subcommand arguments
+
+Subcommands:
+    kill                          Terminate ngrok tunnel
+    ssh                           SSH into the jumpbox
+
+Options:
+    --instance-id INSTANCE ID     EC2 instance id of jump box (e.g. i-abc123)
+    --name INSTANCE NAME          EC2 instance name of jump box
+    --ngrok-token NGROK TOKEN     ngrok auth token
+    --ngrok-region NGROK REGION   ngrok region (default: "us")
+    -v, --verbose                 Output AWS API calls
+    -h, --help                    print help
+    
+$ vpcjump ssh --help
+Usage:
+    vpcjump ssh [OPTIONS] [SSHPARAMS] ...
+
+Parameters:
+    [SSHPARAMS] ...               Arguments to pass to SSH
+
+Options:
+    --ssh-user SSH USER           SSH user (default: "ec2-user")
+```
+
+Often you will want to use the jumpbox as an intermediary in order to connect to a second instance. This can be done using SSH port forwarding, e.g. `vpcjump --ngrok-token <auth token> --instance-id i-abc123 ssh -- -L 3389:172.16.0.1:3389` - This will let you to connect to Microsoft Remote Desktop on 127.0.0.1 and it will connect to the remote instance!
+
+Finally, you may wish to terminate the jumpbox tunnel early. This can be done as such: `vpcjump --instance-id i-abc123 kill`. 
+
+## How it works
+
+`vpcjump` uses AWS SSM to remotely execute shell commands on your jumpbox. You can see the precise SSM and SSH commands it executes on your behalf by passing the `--verbose` flag during execution. It does the following:
+
+* Use SSM to execute `ngrok tcp 22` with your provided auth token. This creates a tunnel over HTTPS between the instance and ngrok's tunnelling service.
+* Use SSM to query ngrok's local API: `curl -s http://localhost:4040/api/tunnels`. This returns the ngrok hostname and port that are forwarded to port 22 on your jump box.
+* Execute `ssh -p <ngrok port> <ssh user>@<ngrok host>` to log into your jumpbox through the ngrok tunnel. 
+* Use SSM to execute `killall ngrok` on the remote instance when you explicitly terminate the tunnel. If you don't do this, the SSM agent process on the remote instance will terminate the ngrok tunnel after a predefined period.
+

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler/gem_tasks'
+task :default => :spec

data/exe/vpcjump

@@ -0,0 +1,95 @@
+#!/usr/bin/env ruby
+require 'uri'
+require 'json'
+require 'clamp'
+require 'aws-sdk'
+require 'logger'
+
+module VpcJump
+  class CLI < Clamp::Command
+    option '--instance-id', 'INSTANCE ID', 'EC2 instance id of jump box (e.g. i-abc123)'
+    option '--name', 'INSTANCE NAME', 'EC2 instance name of jump box'
+    option '--ngrok-token', 'NGROK TOKEN', 'ngrok auth token'
+    option '--ngrok-region', 'NGROK REGION', 'ngrok region', default: 'us'
+    option ['-v', '--verbose'], :flag, 'Output AWS API calls'
+
+    subcommand 'kill', 'Terminate ngrok tunnel' do
+      def execute
+        Aws.config[:logger] = Logger.new($stdout) if verbose?
+
+        id = instance_id
+        ssm_exec id, 'killall ngrok'
+      end
+    end
+
+    subcommand 'ssh', 'SSH into the jumpbox' do
+      option '--ssh-user', 'SSH USER', 'SSH user', default: 'ec2-user'
+      parameter '[SSHPARAMS] ...', 'Arguments to pass to SSH'
+
+      def default_sshparams_list
+        []
+      end
+
+      def execute
+        Aws.config[:logger] = Logger.new($stdout) if verbose?
+
+        id = instance_id
+
+        ssm_exec id, "ngrok tcp --log stdout --region #{ngrok_region} --authtoken #{ngrok_token} 22"
+        sleep 20
+
+        tunnels = []
+
+        loop do
+          resp = ssm_exec id, 'curl -s http://localhost:4040/api/tunnels'
+          output = ssm_output resp.command_id
+          json = JSON.parse output
+          tunnels = json['tunnels']
+          break if tunnels.length > 0
+        end
+
+        url = tunnels[0]['public_url']
+        uri = URI.parse url
+        port = uri.port
+        host = uri.hostname
+
+        cmd = "ssh -p #{port} #{sshparams_list.join(' ')} #{ssh_user}@#{host}"
+        puts cmd if verbose?
+        exec cmd
+      end
+    end
+
+    def ssm_exec(instance_id, command)
+      ssm = Aws::SSM::Client.new
+
+      resp = ssm.send_command(
+          instance_ids: [instance_id],
+          document_name: 'AWS-RunShellScript',
+          parameters: {
+              commands: [command]
+          }
+      )
+
+      resp.command
+    end
+
+    def ssm_output(command_id)
+      ssm = Aws::SSM::Client.new
+
+      loop do
+        sleep 1
+        response = ssm.list_command_invocations command_id: command_id, details: true
+        invocation = response.command_invocations.first
+
+        if ['Pending', 'InProgress'].include?(invocation.status)
+          next
+        end
+
+        escaped = invocation.command_plugins[0].output
+        return escaped.gsub('&quot;', '"')
+      end
+    end
+  end
+end
+
+VpcJump::CLI.run

data/lib/vpcjump/version.rb

@@ -0,0 +1,3 @@
+module Vpcjump
+  VERSION = '0.1.0'
+end

data/lib/vpcjump.rb

@@ -0,0 +1,5 @@
+require 'vpcjump/version'
+
+module Vpcjump
+  # Your code goes here...
+end

data/vpcjump.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'vpcjump/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'vpcjump'
+  spec.version       = Vpcjump::VERSION
+  spec.authors       = ['Aidan Steele']
+  spec.email         = ['aidan.steele@glassechidna.com.au']
+  spec.homepage      = 'https://github.com/aidansteele/vpcjump'
+
+  spec.summary       = %q{Helper tool for connecting to jumpboxes in AWS.}
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.13'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'pry-rescue'
+  spec.add_development_dependency 'pry-stack_explorer'
+
+  spec.add_dependency 'clamp'
+  spec.add_dependency 'aws-sdk', '~> 2'
+end

metadata

@@ -0,0 +1,136 @@
+--- !ruby/object:Gem::Specification
+name: vpcjump
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Aidan Steele
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-11-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: pry-rescue
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-stack_explorer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: clamp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: aws-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+description: 
+email:
+- aidan.steele@glassechidna.com.au
+executables:
+- vpcjump
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- README.md
+- Rakefile
+- exe/vpcjump
+- lib/vpcjump.rb
+- lib/vpcjump/version.rb
+- vpcjump.gemspec
+homepage: https://github.com/aidansteele/vpcjump
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5.1
+signing_key: 
+specification_version: 4
+summary: Helper tool for connecting to jumpboxes in AWS.
+test_files: []