assumer 0.4.1a

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0040c2a8af4e270a7ece881c71b5697aeab7ac8f
+  data.tar.gz: 84b37cdfc3ab9d03ea47f24bb1aca1cc44a73c19
+SHA512:
+  metadata.gz: 0de21876310eec88959970b68c998e7e6559e6aa143931241297b49cd5c8e359c778475d33e179d055c8a19de4bf4cb596ff7f0d3409bd04a13c64fbc1a3ba31
+  data.tar.gz: 6f138e89278f33f2a0f2c543df35715c2c00b1ddde1dd82b78483b484067861cc7a51d478553bdbdaf7687b97b33f1e2927b8a28fa750b7b3d272780bdee9f95

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,34 @@
+PATH
+  remote: .
+  specs:
+    assumer (0.2.2)
+      aws-sdk-core (~> 2.1, >= 2.1.1)
+      pry (~> 0)
+      trollop (= 2.1.2)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    aws-sdk-core (2.1.26)
+      jmespath (~> 1.0)
+    coderay (1.1.0)
+    jmespath (1.1.3)
+    method_source (0.8.2)
+    pry (0.10.2)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+    rake (10.4.2)
+    slop (3.6.0)
+    trollop (2.1.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  assumer!
+  bundler (~> 1.10)
+  rake (~> 10.0)
+
+BUNDLED WITH
+   1.10.6

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/assumer.gemspec

@@ -0,0 +1,31 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'assumer/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'assumer'
+  spec.version       = Assumer::VERSION
+  spec.authors       = ['Brandon Sherman']
+  spec.email         = ['mechcozmo@gmail.com']
+
+  spec.summary       = 'This gem provides the functionality to Assume Role in AWS'
+  spec.description   = 'Allows for single or double-jumps through AWS accounts in order to assume a role in a target account'
+  spec.homepage      = 'https://github.com/devsecops/assumer'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.executables.reject! { |f| f == '.rubocop.yml' }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.10'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  # Requires Ruby 2.1 or higher; 2.0 is buggy
+  spec.required_ruby_version = '>= 2.1'
+  # There is a race condition in the aws-sdk-core gem 2.1.0.
+  # This constraint says 2.1.1 and up, but don't go to 2.2
+  spec.add_dependency 'aws-sdk-core', '~> 2.1', '>= 2.1.1'
+  spec.add_dependency 'pry', '~>0'
+  spec.add_dependency 'trollop', '2.1.2'
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'assumer'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+require 'pry'
+Pry.start
+
+# require "irb"
+# IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/exe/.rubocop.yml

@@ -0,0 +1,4 @@
+AllCops:
+  TargetRubyVersion: 2.1
+LineLength:
+  Max: 100

data/exe/assumer

@@ -0,0 +1,175 @@
+#! /usr/bin/env ruby
+require 'pry' # External gem
+require 'trollop' # External gem
+
+require 'tempfile' # Ruby core
+require 'net/http' # Ruby core
+require 'rbconfig' # Ruby core
+
+require 'assumer' # This gem
+
+parsed_options = Trollop::options do
+  version "Assumer v#{Assumer::VERSION}"
+  banner 'Parameters:'
+  opt :target_account, 'Target AWS account to assume into', short: '-a', type: :string
+  opt :target_role, 'The role in the target account', short: '-r', type: :string
+  opt :control_account, 'Control Plane AWS account', short: '-A', type: :string
+  opt :control_role, 'The role in the control account', short: '-R', type: :string
+  banner 'These parameters are optional:'
+  opt :region, 'AWS region to operate in', default: 'us-east-1', type: :string
+  opt :username, 'Your IAM username', short: '-u', default: `whoami`.chomp, type: :string
+  opt :profile, 'Profile name from ~/.aws/credentials', short: '-o', type: :string
+  opt :gui, 'Open a web browser to the AWS console with these credentials'
+  opt :pry, 'Open a pry shell with these credentials', short: '-p'
+  opt :enable_aws_bundled_ca_cert, 'Option to enable the certificate store bundled with the AWS SDK'
+  opt :debug, 'Output debugging information'
+end
+
+DEBUG_FLAG = parsed_options[:debug]
+warn "Options understood to be the following:\n#{parsed_options}" if DEBUG_FLAG
+
+Trollop::die :target_account, 'Must be a 12-digit AWS account number' unless parsed_options[:target_account] =~ /\d{12}/
+Trollop::die :control_account, 'Must be a 12-digit AWS account number' unless parsed_options[:control_account] =~ /\d{12}/
+
+mfa_serial_number =   "arn:aws:iam::#{parsed_options[:control_account]}:mfa/#{parsed_options[:username]}"
+control_plane_role =  "arn:aws:iam::#{parsed_options[:control_account]}:role/#{parsed_options[:control_role]}"
+target_account_role = "arn:aws:iam::#{parsed_options[:target_account]}:role/#{parsed_options[:target_role]}"
+
+warn "MFA Serial Number:   #{mfa_serial_number}" if DEBUG_FLAG
+warn "Control Plane Role:  #{control_plane_role}" if DEBUG_FLAG
+warn "Target Account Role: #{target_account_role}" if DEBUG_FLAG
+
+puts <<EOF
+#{parsed_options[:username]} is assuming
+#{target_account_role}
+via
+#{control_plane_role}
+EOF
+
+# AWS SDK includes a certificate store that is disabled by default
+# This is to allow the system certificates to take precedent
+# If a system's CA store is botched, you can enable the bundled cert. store
+# https://github.com/aws/aws-sdk-core-ruby/issues/166#issuecomment-111603660
+if parsed_options[:enable_aws_bundled_ca_cert]
+  warn '>>> AWS bunled CA certificate enabled <<< ' if DEBUG_FLAG
+  Aws.use_bundled_cert!
+end
+
+def debug_credential_output(credentials:)
+"  Access Key Id: #{credentials.access_key_id[0..5]}...#{credentials.access_key_id[-4..-1]}
+  Secret Access Key: #{credentials.secret_access_key[0..5]}...#{credentials.secret_access_key[-4..-1]}
+  Session Token: #{credentials.session_token[0..5]}...#{credentials.session_token[-4..-1]}"
+end
+
+# First jump
+control_creds = Assumer::Assumer.new(
+  region: parsed_options[:region],
+  account: parsed_options[:control_account],
+  role: control_plane_role,
+  serial_number: mfa_serial_number,
+  profile: parsed_options[:profile]
+)
+if DEBUG_FLAG
+  warn 'First Jump Credentials:'
+  warn debug_credential_output(credentials: control_creds.assume_role_credentials.credentials)
+end
+
+# Second jump
+target_creds = Assumer::Assumer.new(
+  region: parsed_options[:region],
+  account: parsed_options[:target_account],
+  role: target_account_role,
+  credentials: control_creds
+)
+if DEBUG_FLAG
+  warn 'Second Jump Credentials:'
+  warn debug_credential_output(credentials: target_creds.assume_role_credentials.credentials)
+end
+
+region = parsed_options[:region]
+aws_access_key_id = target_creds.assume_role_credentials.credentials.access_key_id
+aws_secret_access_key = target_creds.assume_role_credentials.credentials.secret_access_key
+aws_session_token = target_creds.assume_role_credentials.credentials.session_token
+
+# Write to a file for the user to pull into their own shell if they'd like
+file = Tempfile.new('assumer')
+warn "Writing temp file #{file.path}" if DEBUG_FLAG
+# Prevents tempfile from being deleted when the Ruby object is garbage collected
+ObjectSpace.undefine_finalizer(file)
+
+# Write a different file depending on UNIX or Windows
+if RbConfig::CONFIG['host_os'] =~ /mswin|mingw|cygwin/
+  output = <<-EOF.gsub(/^ {2}/, '')
+  set AWS_REGION=#{region}
+  set AWS_ACCESS_KEY_ID=#{aws_access_key_id}
+  set AWS_SECRET_ACCESS_KEY=#{aws_secret_access_key}
+  set AWS_SESSION_TOKEN=#{aws_session_token}
+  EOF
+  puts "To import these values into the shell, execute .\\'#{file.path}'\n"
+elsif RbConfig::CONFIG['host_os'] =~ /linux|bsd|darwin/
+  output = <<-EOF.gsub(/^ {2}/, '')
+  export AWS_REGION=#{region}
+  export AWS_ACCESS_KEY_ID=#{aws_access_key_id}
+  export AWS_SECRET_ACCESS_KEY=#{aws_secret_access_key}
+  export AWS_SESSION_TOKEN=#{aws_session_token}
+  EOF
+  puts "To import these values into the shell, source '#{file.path}'\n"
+end
+
+file.write(output)
+file.close
+warn "File '#{file.path}' closed" if DEBUG_FLAG
+
+# If GUI option was set, open default browser with creds into the account
+if parsed_options[:gui]
+  print "Generating signin URL to #{parsed_options[:target_account]}..."
+  issuer_url = 'assumer'
+  console_url = 'https://console.aws.amazon.com/'
+  signin_url = 'https://signin.aws.amazon.com/federation'
+  # Compose credential block used to request login token
+  session_json = {
+    sessionId: aws_access_key_id,
+    sessionKey: aws_secret_access_key,
+    sessionToken: aws_session_token
+  }.to_json
+
+  # Request signin token from Federation endpoint (valid for 15 minutes)
+  signin_token_url = <<-EOF.gsub(/^ {2}/, '')
+  #{signin_url}?Action=getSigninToken&SessionType=json&Session=#{CGI.escape(session_json)}
+  EOF
+  returned_content = Net::HTTP.get(URI.parse(signin_token_url))
+
+  # Extract the signin token from the information returned by the federation endpoint.
+  signin_token = JSON.parse(returned_content).fetch('SigninToken', {})
+
+  signin_token_param = "&SigninToken=#{CGI.escape(signin_token)}"
+
+  # Create the URL to give to the user, which includes the
+  # signin token and the URL of the console to open.
+  # The 'issuer' parameter is optional but recommended.
+  issuer_param = "&Issuer=#{CGI.escape(issuer_url)}"
+  destination_param = "&Destination=#{CGI.escape(console_url)}"
+  # Generate the signin URL, clean up the string
+  login_url = <<-EOF.gsub(/^ {2}/, '').chomp
+  #{signin_url}?Action=login#{signin_token_param}#{issuer_param}#{destination_param}
+  EOF
+  puts "Login URL is:\n#{login_url}"
+
+  # Depending on the system we are running on, use the appropriate
+  # system command to launch the default browser
+  if RbConfig::CONFIG['host_os'] =~ /mswin|mingw|cygwin/
+    # On Windows, it matters what kind of quotes you use...
+    warn "System command is: 'start \"\" \"#{login_url}\"'" if DEBUG_FLAG
+    system "start \"\" \"#{login_url}\""
+  elsif RbConfig::CONFIG['host_os'] =~ /darwin/
+    warn 'System command is: ' + "open '#{login_url}'" if DEBUG_FLAG
+    system "open '#{login_url}'"
+  elsif RbConfig::CONFIG['host_os'] =~ /linux|bsd/
+    warn 'System command is: ' + "xdg-open '#{login_url}'" if DEBUG_FLAG
+    system "xdg-open '#{login_url}'"
+  end
+# If a pry shell was requested, deliver one with credentials available
+elsif parsed_options[:pry]
+  puts "Your Assumer object within pry is 'target_creds'"
+  binding.pry(quiet: true)
+end

data/lib/assumer.rb

@@ -0,0 +1,110 @@
+require 'assumer/version'
+require 'aws-sdk-core'
+require 'mfa'
+
+module Assumer
+  # The regex that AWS uses to verify if a role's ARN is valid
+  AWS_ROLE_REGEX = %r{arn:aws:iam::\d{12}:role/?[a-zA-Z_0-9+=,.@\-_/]+}
+  class AssumerError < StandardError; end
+  # This class provides the main functionallity to the Assumer gem
+
+  class Assumer
+    # This is the only thing clients are allowed to access
+    # It will be an STS::AssumeRoleCredentials object created by AWS
+    attr_accessor :assume_role_credentials
+
+    ##
+    # Creates the Assumer object
+    #
+    # @param [String] region The AWS region to establish a connection from (if left nil, Assumer will try and use it's current region)
+    # @param [String] account The AWS account number without dashes
+    # @param [String] role The ARN for the role to assume
+    # @param [String] serial_number The Serial Number of an MFA device
+    # @param [Assumer] credentials An assumer object (to support double-jumps)
+
+    def initialize(region: nil, account: nil, role: nil, serial_number: nil, credentials: nil, profile: nil)
+      @region = region ? region : my_region # if region is passed in, use it, otherwise find what region we're in and use that
+      @account = account
+      @role = verify_role(role: role)
+      # If we are being passed credentials, it's an Assumer instance, and we can
+      # get the creds from it.  Otherwise, establish an STS connection
+      @sts_client = establish_sts(
+        region: @region,
+        passed_credentials: credentials,
+        credentials_profile: profile
+      )
+      @serial_number = serial_number # ARN for the user's MFA serial number
+
+      opts = {
+        client: @sts_client,
+        role_arn: @role,
+        role_session_name: 'AssumedRole'
+      }
+      # Don't specify MFA serial number or token code if they aren't needed
+      unless @serial_number.nil?
+        opts[:serial_number] = @serial_number
+        opts[:token_code] = MFA.new.request_one_time_code
+      end
+      @assume_role_credentials = Aws::AssumeRoleCredentials.new(opts)
+
+    rescue Aws::STS::Errors::AccessDenied => e
+      raise AssumerError, "Access Denied: #{e.message}"
+    end
+
+    ##
+    # Verifies the requested role is valid
+    # Only checks syntax, does not guarantee the role exists or can be assumed into
+    # @param [String] role The ARN of the role to be verified
+    # @return [String] The ARN of a valid role
+    # @raise [AssumerError] If the ARN is invalid, an exception is raised
+    def verify_role(role:)
+      raise AssumerError, "Invalid ARN for role #{role}" unless role =~ AWS_ROLE_REGEX
+      role
+    end
+
+    private
+
+    ##
+    # Establish an AWS STS connection to retrieve tokens
+    # @param [String] region An AWS region to establish a connection in
+    # @param [Assumer] passed_credentials An Assumer object that has established a connection to an account.  Used for double-jumps.
+    # @param [String] credentials_profile The credentials profile to load from the user's .aws/credentials file
+    # @return [Aws::STS::Client] The Secure Token Service client
+    def establish_sts(region: nil, passed_credentials: nil, credentials_profile: nil)
+      throw AssumerError.new('No region provided') if region.nil?
+      opts = { region: region }
+
+      # If credentials were passed in, use those to build the STS client
+      opts.merge!(
+        access_key_id: passed_credentials.assume_role_credentials.credentials.access_key_id,
+        secret_access_key: passed_credentials.assume_role_credentials.credentials.secret_access_key,
+        session_token: passed_credentials.assume_role_credentials.credentials.session_token
+      ) unless passed_credentials.nil?
+
+      # If a profile is specified, read those from the ~/.aws/credentials file
+      # Or anywhere AWS STS Client knows where to load them from
+      opts[:profile] = credentials_profile unless credentials_profile.nil?
+      @sts_client = Aws::STS::Client.new(opts)
+    end
+
+    ##
+    # Determine the region this code is being called in by contacting the AWS
+    # metadata service
+    # @return [String] AWS Region Assumer is being called in OR 'us-east-1' if unable to be determined
+    # @raise [AssumerError] If the region cannot be determined, an exception is raised
+    def my_region
+      require 'net/http'
+      require 'json'
+      metadata_uri = URI('http://169.254.169.254/latest/dynamic/instance-identity/document/')
+      request = Net::HTTP::Get.new(metadata_uri.path)
+      response = Net::HTTP.start(metadata_uri.host, metadata_uri.port) do |http|
+        http.read_timeout = 10
+        http.open_timeout = 10
+        http.request(request)
+      end
+      JSON.parse(response).fetch('region', 'us-east-1')
+    rescue => e
+      raise AssumerError, "Could not determine region (are you running in AWS?): #{e.message}"
+    end
+  end
+end

data/lib/assumer/version.rb

@@ -0,0 +1,3 @@
+module Assumer
+  VERSION = '0.4.1a'.freeze
+end

data/lib/mfa.rb

@@ -0,0 +1,19 @@
+module Assumer
+  ##
+  # A class to manage methods of obtaining OTP codes for MFA
+  class MFA
+    attr_reader :otp
+    ##
+    # A method to prompt for the user's OTP MFA code on the CLI
+    # @return [String] The MFA code entered by the user
+    def request_one_time_code
+      until @otp =~ /\d{6}/
+        print 'Enter MFA: '
+        $stdout.flush
+        @otp = $stdin.gets(7).chomp
+        $stderr.puts 'MFA code should be 6 digits' if @otp !~ /\d{6}/
+      end
+      @otp
+    end
+  end
+end

metadata

@@ -0,0 +1,132 @@
+--- !ruby/object:Gem::Specification
+name: assumer
+version: !ruby/object:Gem::Version
+  version: 0.4.1a
+platform: ruby
+authors:
+- Brandon Sherman
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-06-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.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !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: aws-sdk-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.1.1
+- !ruby/object:Gem::Dependency
+  name: pry
+  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: trollop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.1.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.1.2
+description: Allows for single or double-jumps through AWS accounts in order to assume
+  a role in a target account
+email:
+- mechcozmo@gmail.com
+executables:
+- assumer
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- Gemfile.lock
+- Rakefile
+- assumer.gemspec
+- bin/console
+- bin/setup
+- exe/.rubocop.yml
+- exe/assumer
+- lib/assumer.rb
+- lib/assumer/version.rb
+- lib/mfa.rb
+homepage: https://github.com/devsecops/assumer
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5.1
+signing_key: 
+specification_version: 4
+summary: This gem provides the functionality to Assume Role in AWS
+test_files: []