sshkit-ec2instanceconnect 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4457259f1ad225bf3974f58d58c4b77e5141b94c66506423101dc874438e13d0
+  data.tar.gz: 2b98209f24ec5f55837b4e8e1f790e0fc1f47dc909083dd52c3d80396d059c23
+SHA512:
+  metadata.gz: 2a754e8d2ffb490deb94b01fe7378d8fcd10d02722d406882d2cb95266e6af8335325a01ef3af690cfe3dea2dd73343b94d4639423f1abf47837d7e5c8aede91
+  data.tar.gz: c9c8696b44a6c310031b5981c3406309d6e68ca296ba3ae1e7a8cd61ad65ed257e6ae1da4095154d46d4cd00006e741484dda1e33dcd0ac50191d640d4d992a2

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Kentaa BV
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,105 @@
+# sshkit-ec2instanceconnect
+
+[![Gem Version](https://badge.fury.io/rb/sshkit-ec2instanceconnect.svg)](https://badge.fury.io/rb/sshkit-ec2instanceconnect)
+[![Build Status](https://github.com/KentaaNL/sshkit-ec2instanceconnect/actions/workflows/test.yml/badge.svg)](https://github.com/KentaaNL/sshkit-ec2instanceconnect/actions)
+[![CodeQL](https://github.com/KentaaNL/sshkit-ec2instanceconnect/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/KentaaNL/sshkit-ec2instanceconnect/actions/workflows/github-code-scanning/codeql)
+
+A [SSHKit](https://github.com/capistrano/sshkit) backend that integrates with
+[AWS EC2 Instance Connect](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connect-linux-inst-eic.html) .
+
+This backend automatically generates ephemeral SSH keys, delivers the public key to the target instance using EC2 Instance Connect, and refreshes the key before it expires. It is designed for use with [Capistrano](https://github.com/capistrano/capistrano) deployments on AWS.
+
+Additionally, the backend can optionally connect through an [EC2 Instance Connect Endpoint](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connect-with-ec2-instance-connect-endpoint.html) by establishing a tunnel and routing SSH traffic through it.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'sshkit-ec2instanceconnect'
+```
+
+## Configuration
+
+Global configuration can be set during application boot (e.g., in a Capistrano initializer).
+Default configuration:
+
+```ruby
+SSHKit::EC2InstanceConnect.configure do |config|
+  config.ssh_key_refresh_enabled = true   # Enable ephemeral SSH keys and refresh them periodically
+  config.ssh_key_size = 3072              # Ephemeral SSH key size (RSA)
+  config.tunnel_enabled = false           # Enable EC2 Instance Connect Endpoint tunneling
+  config.tunnel_ports = 8000...8100       # Local port range used when allocating a tunnel
+end
+```
+
+To use this backend with Capistrano, add to your `config/deploy.rb`:
+
+```ruby
+set :sshkit_backend, SSHKit::EC2InstanceConnect::Backend
+```
+
+Ensure your server definitions include the `instance_id` property:
+
+```ruby
+server 'ec2-hostname', user: 'ec2-user', roles: %w[app web], instance_id: 'i-0abcdef1234567890'
+```
+
+When using [capistrano-asg-rolling](https://github.com/KentaaNL/capistrano-asg-rolling), no additional configuration is needed; it automatically passes the correct `instance_id` to the backend.
+
+## EC2 Instance Connect Endpoint (Tunneling)
+
+This gem supports connecting to EC2 instances through an [EC2 Instance Connect Endpoint](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connect-with-ec2-instance-connect-endpoint.html) by invoking the AWS CLI command `aws ec2-instance-connect open-tunnel`.
+
+When tunneling is enabled:
+1. A local port is selected from the configured `tunnel_ports` range.
+2. A tunnel is opened to the target instance through the EC2 Instance Connect Endpoint.
+3. SSHKit connects through the tunnel transparently.
+4. The tunnel is automatically closed when the session ends.
+
+This is particularly useful in VPC environments where instances do not have public IPs and can only be accessed through an EC2 Instance Connect Endpoint.
+
+To enable tunneling, set:
+
+```ruby
+config.tunnel_enabled = true
+```
+
+**Note**: Tunneling requires the AWS CLI (`aws ec2-instance-connect`) to be installed and configured.
+
+## IAM Policy
+
+Sending ephemeral SSH keys and opening tunnels require the correct IAM permissions.
+For example:
+
+### EC2 Instance Connect
+
+```json
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Action": ["ec2-instance-connect:SendSSHPublicKey"],
+            "Resource": "*"
+        }
+    ]
+}
+```
+
+### EC2 Instance Connect Endpoint (Tunneling)
+
+```json
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Action": ["ec2-instance-connect:OpenTunnel"],
+            "Resource": "*"
+        }
+    ]
+}
+```
+
+Please refer to the AWS documentation for further details.

data/lib/sshkit/ec2instanceconnect/backend.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'aws-sdk-ec2instanceconnect'
+require 'concurrent/hash'
+require 'forwardable'
+require 'sshkit'
+
+module SSHKit
+  module EC2InstanceConnect
+    # SSHKit backend that integrates with EC2 Instance Connect.
+    #
+    # It ensures that SSH keys are automatically created and send to
+    # the server before executing any command.  It also ensures
+    # a timely refresh of the SSH key before it expires.
+    class Backend < SSHKit::Backend::Abstract
+      # SSH keys using EC2 Instance Connect are valid for 60 seconds,
+      # so refresh them a bit earlier.
+      EXPIRES_IN = 50
+
+      # Store SSH keys per instance with expiration.
+      @ssh_keys = SSHKit::EC2InstanceConnect::TimedHash.new(expires_in: EXPIRES_IN)
+
+      @tunnels = Concurrent::Hash.new
+
+      # Make sure to stop any tunnels before the Ruby process exits.
+      at_exit { @tunnels.each_value(&:stop) }
+
+      class << self
+        attr_accessor :ssh_keys, :tunnels
+      end
+
+      extend Forwardable
+
+      # Define delegators to the config object.
+      def_delegators :config, :ssh_key_size, :random_tunnel_port, :logger
+      private :ssh_key_size, :random_tunnel_port, :logger
+
+      def initialize(host, &)
+        super
+        @backend = SSHKit::Backend::Netssh.new(host)
+      end
+
+      def self.configure(&)
+        SSHKit::Backend::Netssh.configure(&)
+      end
+
+      def upload!(local, remote, options = {})
+        ensure_connection
+        @backend.send(:upload!, local, remote, options)
+      end
+
+      def download!(remote, local = nil, options = {})
+        ensure_connection
+        @backend.send(:download!, remote, local, options)
+      end
+
+      def execute_command(cmd)
+        ensure_connection
+        @backend.send(:execute_command, cmd)
+      end
+
+      private
+
+      def ensure_connection
+        if SSHKit::EC2InstanceConnect.config.tunnel_enabled
+          tunnel = self.class.tunnels[instance_id] ||= setup_tunnel
+          update_host_and_port(tunnel: tunnel)
+        end
+
+        if SSHKit::EC2InstanceConnect.config.ssh_key_refresh_enabled
+          ssh_key = self.class.ssh_keys[instance_id] ||= refresh_ssh_key
+          update_host_ssh_options(private_key: ssh_key.private_key)
+        end
+      end
+
+      def setup_tunnel
+        logger.debug { "Setting up tunnel for instance #{instance_id}" }
+
+        Tunnel.new(instance_id: instance_id, port: random_tunnel_port).tap do |tunnel|
+          tunnel.start
+
+          logger.debug { "Tunnel (#{tunnel}) started for instance #{instance_id}" }
+        end
+      end
+
+      def update_host_and_port(tunnel:)
+        host.hostname = tunnel.host
+        host.port = tunnel.port
+      end
+
+      def refresh_ssh_key
+        logger.debug { "Refreshing SSH key for instance #{instance_id}" }
+
+        SSHKey.new(size: ssh_key_size).tap do |ssh_key|
+          logger.debug { "SSH key generated, sending to instance #{instance_id}" }
+
+          send_ssh_public_key(public_key: ssh_key.public_key)
+        end
+      end
+
+      def send_ssh_public_key(public_key:)
+        client = Aws::EC2InstanceConnect::Client.new
+        client.send_ssh_public_key(
+          instance_id: instance_id,
+          instance_os_user: instance_user,
+          ssh_public_key: public_key
+        )
+      end
+
+      def update_host_ssh_options(private_key:)
+        host.ssh_options ||= {}
+        host.ssh_options.merge!(
+          keys: [],
+          key_data: [private_key],
+          keys_only: true
+        )
+      end
+
+      def instance_user
+        host.user
+      end
+
+      def instance_id
+        host.properties.fetch(:instance_id)
+      end
+
+      def config
+        SSHKit::EC2InstanceConnect.config
+      end
+    end
+  end
+end

data/lib/sshkit/ec2instanceconnect/ssh_key.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'net/ssh'
+require 'openssl'
+
+module SSHKit
+  module EC2InstanceConnect
+    # Generate a private/public SSH keypair.
+    class SSHKey
+      def initialize(size:)
+        @key = OpenSSL::PKey::RSA.generate(size)
+      end
+
+      def private_key
+        @key.to_pem
+      end
+
+      def public_key
+        blob = @key.public_key.to_blob
+        encoded = [blob].pack('m0')
+
+        "ssh-rsa #{encoded}"
+      end
+    end
+  end
+end

data/lib/sshkit/ec2instanceconnect/timed_hash.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'concurrent/map'
+
+module SSHKit
+  module EC2InstanceConnect
+    # A thread-safe Hash that expires keys after a given time.
+    class TimedHash
+      def initialize(expires_in:)
+        @expires_in = expires_in
+        @store = Concurrent::Map.new
+      end
+
+      def []=(key, value)
+        @store[key] = { value: value, expires_at: Time.now + @expires_in }
+      end
+
+      def [](key)
+        now = Time.now
+
+        data = @store.compute_if_present(key) do |value|
+          # Expired → delete by returning nil.
+          if now > value[:expires_at]
+            nil
+          else
+            value # keep
+          end
+        end
+
+        data&.fetch(:value)
+      end
+
+      def size
+        @store.values.count { |value| Time.now <= value[:expires_at] }
+      end
+
+      def clear
+        @store.clear
+      end
+    end
+  end
+end

data/lib/sshkit/ec2instanceconnect/tunnel.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'pty'
+
+module SSHKit
+  module EC2InstanceConnect
+    # Manages a tunnel using the EC2 Instance Connect Endpoint Service, for secure SSH access to EC2 instances.
+    class Tunnel
+      attr_reader :host, :port
+
+      def initialize(instance_id:, host: 'localhost', port: '8000')
+        @instance_id = instance_id
+        @host = host
+        @port = port
+      end
+
+      # Start the tunnel subprocess and wait until it is listening for connections.
+      def start
+        mutex = Mutex.new
+        condition = ConditionVariable.new
+        ready = false
+        error = nil
+
+        @thread = Thread.new do
+          PTY.spawn(command) do |stdout, _stdin, pid|
+            @pid = pid
+
+            stdout.each_line do |line|
+              next unless line.start_with?('Listening for connections')
+
+              mutex.synchronize do
+                ready = true
+                condition.signal
+              end
+            end
+          rescue Errno::EIO
+            # PTY closed — safe to ignore
+          end
+        rescue Errno::ENOENT => e
+          mutex.synchronize do
+            error = e
+            condition.signal
+          end
+        end
+
+        mutex.synchronize { condition.wait(mutex) until ready || error }
+
+        raise error if error
+      end
+
+      # Stop the tunnel process.
+      def stop
+        return if @pid.nil?
+
+        begin
+          Process.kill('TERM', @pid)
+        rescue Errno::ESRCH
+          # Process already exited — safe to ignore
+        end
+        @pid = nil
+
+        @thread&.join
+      end
+
+      def to_s
+        "#{@host}:#{@port}"
+      end
+
+      private
+
+      # Generate the AWS CLI command to open the tunnel.
+      def command
+        "aws ec2-instance-connect open-tunnel --instance-id #{@instance_id} --local-port #{@port}"
+      end
+    end
+  end
+end

data/lib/sshkit/ec2instanceconnect/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module SSHKit
+  module EC2InstanceConnect
+    VERSION = '0.1.0'
+  end
+end

data/lib/sshkit/ec2instanceconnect.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'securerandom'
+
+require_relative 'ec2instanceconnect/timed_hash'
+require_relative 'ec2instanceconnect/ssh_key'
+require_relative 'ec2instanceconnect/tunnel'
+require_relative 'ec2instanceconnect/backend'
+require_relative 'ec2instanceconnect/version'
+
+module SSHKit
+  # SSHKit backend that integrates with EC2 Instance Connect.
+  module EC2InstanceConnect
+    # :nodoc:
+    class Configuration
+      attr_accessor :logger, :ssh_key_refresh_enabled, :ssh_key_size, :tunnel_enabled, :tunnel_ports
+
+      def initialize
+        @logger = ::Logger.new(IO::NULL)
+        @ssh_key_refresh_enabled = true
+        @ssh_key_size = 3072
+        @tunnel_enabled = false
+        @tunnel_ports = 8000...8100
+      end
+
+      # Returns a secure random tunnel port.
+      def random_tunnel_port
+        random_number = SecureRandom.random_number(tunnel_ports.size)
+
+        case tunnel_ports
+        when Array
+          tunnel_ports[random_number]
+        when Range
+          tunnel_ports.begin + random_number
+        else
+          raise ArgumentError, 'tunnel_ports must be an Array or Range'
+        end
+      end
+    end
+
+    class << self
+      def config
+        @config ||= Configuration.new
+      end
+
+      def configure
+        yield(config)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,207 @@
+--- !ruby/object:Gem::Specification
+name: sshkit-ec2instanceconnect
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kentaa
+- iRaiser
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-01-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-ec2instanceconnect
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.63'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.63'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: logger
+  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: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: sshkit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.24'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.24'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.78'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.78'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.25'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.26'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.26'
+description:
+email:
+- tech-arnhem@iraiser.eu
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/sshkit/ec2instanceconnect.rb
+- lib/sshkit/ec2instanceconnect/backend.rb
+- lib/sshkit/ec2instanceconnect/ssh_key.rb
+- lib/sshkit/ec2instanceconnect/timed_hash.rb
+- lib/sshkit/ec2instanceconnect/tunnel.rb
+- lib/sshkit/ec2instanceconnect/version.rb
+homepage: https://github.com/KentaaNL/sshkit-ec2instanceconnect
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: SSHKit backend that integrates with EC2 Instance Connect
+test_files: []