Skip to content

Commit 9a7b985

Browse files
ppostmappostma
committed
Initial commit.
0 parents  commit 9a7b985

24 files changed

Lines changed: 1103 additions & 0 deletions

‎.github/workflows/test.yml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
name: CI
2+
3+
on:
4+
- push
5+
- pull_request
6+
7+
jobs:
8+
test:
9+
runs-on: ubuntu-latest
10+
strategy:
11+
matrix:
12+
ruby-version: ['3.3', '3.4', '4.0']
13+
14+
steps:
15+
- uses: actions/checkout@v5
16+
- uses: ruby/setup-ruby@v1
17+
with:
18+
ruby-version: ${{ matrix.ruby-version }}
19+
bundler-cache: true
20+
- name: Install dependencies
21+
run: bundle install
22+
- name: Run tests
23+
run: bundle exec rspec
24+
- name: Run rubocop
25+
run: bundle exec rubocop

‎.gitignore‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
/.bundle/
2+
/.yardoc
3+
/_yardoc/
4+
/coverage/
5+
/doc/
6+
/pkg/
7+
/spec/reports/
8+
/tmp/
9+
10+
# rspec failure tracking
11+
.rspec_status
12+
13+
.ruby-version
14+
.ruby-gemset

‎.rspec‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
--format documentation
2+
--color
3+
--require spec_helper

‎.rubocop.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# sshkit-ec2instanceconnect RuboCop configuration
2+
# https://docs.rubocop.org/rubocop/cops.html
3+
#
4+
# Run with: `bin/rubocop`.
5+
6+
plugins:
7+
- rubocop-performance
8+
- rubocop-rspec
9+
10+
AllCops:
11+
NewCops: enable
12+
TargetRubyVersion: 3.3
13+
14+
Gemspec/DevelopmentDependencies:
15+
EnforcedStyle: gemspec
16+
17+
Layout/LineLength:
18+
Enabled: false
19+
20+
Metrics/AbcSize:
21+
Enabled: false
22+
23+
Metrics/MethodLength:
24+
Enabled: false
25+
26+
RSpec/ExampleLength:
27+
Enabled: false
28+
29+
RSpec/MultipleExpectations:
30+
Enabled: false
31+
32+
RSpec/NestedGroups:
33+
Max: 4
34+
35+
RSpec/SpecFilePathFormat:
36+
Enabled: false
37+
38+
Style/GuardClause:
39+
Enabled: false

‎Gemfile‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# frozen_string_literal: true
2+
3+
source 'https://rubygems.org'
4+
5+
# Specify your gem's dependencies in sshkit-ec2instanceconnect.gemspec
6+
gemspec

‎Gemfile.lock‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
PATH
2+
remote: .
3+
specs:
4+
sshkit-ec2instanceconnect (0.1.0)
5+
aws-sdk-ec2instanceconnect (~> 1.63)
6+
concurrent-ruby (~> 1.2)
7+
logger
8+
rake (~> 13.0)
9+
sshkit (~> 1.24)
10+
11+
GEM
12+
remote: https://rubygems.org/
13+
specs:
14+
addressable (2.8.8)
15+
public_suffix (>= 2.0.2, < 8.0)
16+
ast (2.4.3)
17+
aws-eventstream (1.4.0)
18+
aws-partitions (1.1200.0)
19+
aws-sdk-core (3.240.0)
20+
aws-eventstream (~> 1, >= 1.3.0)
21+
aws-partitions (~> 1, >= 1.992.0)
22+
aws-sigv4 (~> 1.9)
23+
base64
24+
bigdecimal
25+
jmespath (~> 1, >= 1.6.1)
26+
logger
27+
aws-sdk-ec2instanceconnect (1.66.0)
28+
aws-sdk-core (~> 3, >= 3.239.1)
29+
aws-sigv4 (~> 1.5)
30+
aws-sigv4 (1.12.1)
31+
aws-eventstream (~> 1, >= 1.0.2)
32+
base64 (0.3.0)
33+
bigdecimal (4.0.1)
34+
concurrent-ruby (1.3.6)
35+
crack (1.0.1)
36+
bigdecimal
37+
rexml
38+
diff-lcs (1.6.2)
39+
docile (1.4.1)
40+
hashdiff (1.2.1)
41+
jmespath (1.6.2)
42+
json (2.18.0)
43+
language_server-protocol (3.17.0.5)
44+
lint_roller (1.1.0)
45+
logger (1.7.0)
46+
net-scp (4.1.0)
47+
net-ssh (>= 2.6.5, < 8.0.0)
48+
net-sftp (4.0.0)
49+
net-ssh (>= 5.0.0, < 8.0.0)
50+
net-ssh (7.3.0)
51+
ostruct (0.6.3)
52+
parallel (1.27.0)
53+
parser (3.3.10.0)
54+
ast (~> 2.4.1)
55+
racc
56+
prism (1.7.0)
57+
public_suffix (7.0.2)
58+
racc (1.8.1)
59+
rainbow (3.1.1)
60+
rake (13.3.1)
61+
regexp_parser (2.11.3)
62+
rexml (3.4.4)
63+
rspec (3.13.2)
64+
rspec-core (~> 3.13.0)
65+
rspec-expectations (~> 3.13.0)
66+
rspec-mocks (~> 3.13.0)
67+
rspec-core (3.13.6)
68+
rspec-support (~> 3.13.0)
69+
rspec-expectations (3.13.5)
70+
diff-lcs (>= 1.2.0, < 2.0)
71+
rspec-support (~> 3.13.0)
72+
rspec-mocks (3.13.7)
73+
diff-lcs (>= 1.2.0, < 2.0)
74+
rspec-support (~> 3.13.0)
75+
rspec-support (3.13.6)
76+
rubocop (1.82.1)
77+
json (~> 2.3)
78+
language_server-protocol (~> 3.17.0.2)
79+
lint_roller (~> 1.1.0)
80+
parallel (~> 1.10)
81+
parser (>= 3.3.0.2)
82+
rainbow (>= 2.2.2, < 4.0)
83+
regexp_parser (>= 2.9.3, < 3.0)
84+
rubocop-ast (>= 1.48.0, < 2.0)
85+
ruby-progressbar (~> 1.7)
86+
unicode-display_width (>= 2.4.0, < 4.0)
87+
rubocop-ast (1.49.0)
88+
parser (>= 3.3.7.2)
89+
prism (~> 1.7)
90+
rubocop-performance (1.26.1)
91+
lint_roller (~> 1.1)
92+
rubocop (>= 1.75.0, < 2.0)
93+
rubocop-ast (>= 1.47.1, < 2.0)
94+
rubocop-rspec (3.8.0)
95+
lint_roller (~> 1.1)
96+
rubocop (~> 1.81)
97+
ruby-progressbar (1.13.0)
98+
simplecov (0.22.0)
99+
docile (~> 1.1)
100+
simplecov-html (~> 0.11)
101+
simplecov_json_formatter (~> 0.1)
102+
simplecov-html (0.13.2)
103+
simplecov_json_formatter (0.1.4)
104+
sshkit (1.25.0)
105+
base64
106+
logger
107+
net-scp (>= 1.1.2)
108+
net-sftp (>= 2.1.2)
109+
net-ssh (>= 2.8.0)
110+
ostruct
111+
unicode-display_width (3.2.0)
112+
unicode-emoji (~> 4.1)
113+
unicode-emoji (4.2.0)
114+
webmock (3.26.1)
115+
addressable (>= 2.8.0)
116+
crack (>= 0.3.2)
117+
hashdiff (>= 0.4.0, < 2.0.0)
118+
119+
PLATFORMS
120+
arm64-darwin-24
121+
ruby
122+
123+
DEPENDENCIES
124+
rspec (~> 3.13)
125+
rubocop (~> 1.78)
126+
rubocop-performance (~> 1.25)
127+
rubocop-rspec (~> 3.6)
128+
simplecov (~> 0.22)
129+
sshkit-ec2instanceconnect!
130+
webmock (~> 3.26)
131+
132+
BUNDLED WITH
133+
2.7.2

‎LICENSE.txt‎

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

‎README.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# sshkit-ec2instanceconnect
2+
3+
[![Gem Version](https://badge.fury.io/rb/sshkit-ec2instanceconnect.svg)](https://badge.fury.io/rb/sshkit-ec2instanceconnect)
4+
[![Build Status](https://github.com/KentaaNL/sshkit-ec2instanceconnect/actions/workflows/test.yml/badge.svg)](https://github.com/KentaaNL/sshkit-ec2instanceconnect/actions)
5+
[![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)
6+
7+
A [SSHKit](https://github.com/capistrano/sshkit) backend that integrates with
8+
[AWS EC2 Instance Connect](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connect-linux-inst-eic.html) .
9+
10+
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.
11+
12+
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.
13+
14+
## Installation
15+
16+
Add this line to your application's Gemfile:
17+
18+
```ruby
19+
gem 'sshkit-ec2instanceconnect'
20+
```
21+
22+
## Configuration
23+
24+
Global configuration can be set during application boot (e.g., in a Capistrano initializer).
25+
Default configuration:
26+
27+
```ruby
28+
SSHKit::EC2InstanceConnect.configure do |config|
29+
config.ssh_key_refresh_enabled = true # Enable ephemeral SSH keys and refresh them periodically
30+
config.ssh_key_size = 3072 # Ephemeral SSH key size (RSA)
31+
config.tunnel_enabled = false # Enable EC2 Instance Connect Endpoint tunneling
32+
config.tunnel_ports = 8000...8100 # Local port range used when allocating a tunnel
33+
end
34+
```
35+
36+
To use this backend with Capistrano, add to your `config/deploy.rb`:
37+
38+
```ruby
39+
set :sshkit_backend, SSHKit::EC2InstanceConnect::Backend
40+
```
41+
42+
Ensure your server definitions include the `instance_id` property:
43+
44+
```ruby
45+
server 'ec2-hostname', user: 'ec2-user', roles: %w[app web], instance_id: 'i-0abcdef1234567890'
46+
```
47+
48+
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.
49+
50+
## EC2 Instance Connect Endpoint (Tunneling)
51+
52+
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`.
53+
54+
When tunneling is enabled:
55+
1. A local port is selected from the configured `tunnel_ports` range.
56+
2. A tunnel is opened to the target instance through the EC2 Instance Connect Endpoint.
57+
3. SSHKit connects through the tunnel transparently.
58+
4. The tunnel is automatically closed when the session ends.
59+
60+
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.
61+
62+
To enable tunneling, set:
63+
64+
```ruby
65+
config.tunnel_enabled = true
66+
```
67+
68+
**Note**: Tunneling requires the AWS CLI (`aws ec2-instance-connect`) to be installed and configured.
69+
70+
## IAM Policy
71+
72+
Sending ephemeral SSH keys and opening tunnels require the correct IAM permissions.
73+
For example:
74+
75+
### EC2 Instance Connect
76+
77+
```json
78+
{
79+
"Version": "2012-10-17",
80+
"Statement": [
81+
{
82+
"Effect": "Allow",
83+
"Action": ["ec2-instance-connect:SendSSHPublicKey"],
84+
"Resource": "*"
85+
}
86+
]
87+
}
88+
```
89+
90+
### EC2 Instance Connect Endpoint (Tunneling)
91+
92+
```json
93+
{
94+
"Version": "2012-10-17",
95+
"Statement": [
96+
{
97+
"Effect": "Allow",
98+
"Action": ["ec2-instance-connect:OpenTunnel"],
99+
"Resource": "*"
100+
}
101+
]
102+
}
103+
```
104+
105+
Please refer to the AWS documentation for further details.

‎Rakefile‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# frozen_string_literal: true
2+
3+
require 'bundler/gem_tasks'
4+
require 'rspec/core/rake_task'
5+
require 'rubocop/rake_task'
6+
7+
RSpec::Core::RakeTask.new(:spec)
8+
RuboCop::RakeTask.new(:rubocop)
9+
10+
task default: %i[spec rubocop]

‎bin/console‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
#!/usr/bin/env ruby
2+
# frozen_string_literal: true
3+
4+
require 'bundler/setup'
5+
require 'sshkit/ec2instanceconnect'
6+
7+
# You can add fixtures and/or initialization code here to make experimenting
8+
# with your gem easier. You can also use a different console, if you like.
9+
10+
require 'irb'
11+
IRB.start(__FILE__)

0 commit comments

Comments
 (0)