cfn-vpn 0.5.1 → 1.3.1

data/cfn-vpn.gemspec

@@ -17,8 +17,6 @@ Gem::Specification.new do |spec|
   # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
   # to allow pushing to a single host or delete this section to allow pushing to any host.
   if spec.respond_to?(:metadata)
-    spec.metadata["allowed_push_host"] = 'https://rubygems.org'
-
     spec.metadata["homepage_uri"] = spec.homepage
     spec.metadata["source_code_uri"] = "https://github.com/base2services/aws-client-vpn"
   else
@@ -37,13 +35,15 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "thor", "~> 0.20"
   spec.add_dependency "terminal-table", '~> 1', '<2'
-  spec.add_dependency 'cfhighlander', '~> 0.9', '<1'
+  spec.add_dependency 'cfndsl', '~> 1', '<2'
   spec.add_dependency 'netaddr', '2.0.4'
+  spec.add_dependency 'rubyzip', '~> 2.3'
   spec.add_runtime_dependency 'aws-sdk-ec2', '~> 1.95', '<2'
   spec.add_runtime_dependency 'aws-sdk-acm', '~> 1', '<2'
   spec.add_runtime_dependency 'aws-sdk-s3', '~> 1', '<2'
   spec.add_runtime_dependency 'aws-sdk-cloudformation', '~> 1', '<2'
+  spec.add_runtime_dependency 'aws-sdk-ssm', '~> 1', '<2'
 
   spec.add_development_dependency "bundler", "~> 2.0"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rake", "~> 13.0"
 end

data/docs/README.md

@@ -0,0 +1,44 @@
+# CfnVpn for AWS Client-VPN
+
+`cfn-vpn` is a wrapper around [AWS Client-VPN](https://docs.aws.amazon.com/vpn/latest/clientvpn-admin/what-is.html) to improve the management experience of the VPN. The tool utilises Cloudformation to manage the AWS resources required by the Client-VPN and automates the certificate management process with the [openvpn/easy-rsa](https://github.com/OpenVPN/easy-rsa) library.
+
+## VPN Scenarios 
+
+For further AWS documentation please visit https://docs.aws.amazon.com/vpn/latest/clientvpn-admin/scenario.html
+
+### Split Tunnel
+
+Split tunnel when enabled will only push the routes defined on the client vpn. This is useful if you only want to push routes from your vpc through the vpn.
+
+### Public Subnet with Internet Access
+
+This can be setup with default options selected. This will push all routes from through the vpn including all internet traffic. The ENI attached to the vpn client attaches a public IP which is used for natting between the vpn and the internet. This must be placed inside a public subnet with a internet gateway attached to the vpc.
+Please read the AWS [documentation](https://docs.aws.amazon.com/vpn/latest/clientvpn-admin/scenario-internet.html) for troubleshooting any networking issues
+
+### Private Subnet with Internet Access
+
+This is the same as above but the vpn attached to a subnet in a private subnet with the public route being routed through a nat gateway. **NOTE** the dns on the vpn must be set to the dns server of the vpc you've attached the vpn to, the reserved IP address at the base of the VPC IPv4 network range plus two. For example if you VPC cidr is 10.0.0.0/16 then the dns server for that vpc is 10.0.0.2.
+
+```bash
+cfn-vpn init myvpn --bucket mybucket --server-cn myvpn.domain.tld --subnet-id subnet-123456ab --dns-servers 10.0.0.2
+```
+
+If you are experiencing issue connecting to the internet check to see if your local dns configurations are overriding the ones set by the vpn. You can test this by using `dig` to query a domain from the vpc dns server. For example:
+
+```bash
+dig @10.0.0.2 google.com
+```
+
+## Authentication Types
+
+`cfn-vpn` supports certificate, federated and active directory type authentication for AWS Client-VPN.
+For further information on the authentication types please visit https://docs.aws.amazon.com/vpn/latest/clientvpn-admin/client-authentication.html
+
+## CfnVpn Documentation
+
+1. [Getting Started](getting-started.md)
+2. [Modifying The Client-VPN](modifying.md)
+3. [Managing Certificate Users](certificate-users.md)
+4. [Managing Routes](routes.md)
+5. [Stop and Start Client-VPN](scheduling.md)
+6. [Managing Sessions](sessions.md)

data/docs/certificate-users.md

@@ -0,0 +1,89 @@
+# Managing Certificate Authenticated Users
+
+This section explains how to generate, revoke VPN clients and share config the config with the users
+
+## Create a new user
+
+This will generate a new client certificate and key against the CA generated in the `init`.
+It will be bundled into a tar and stored encrypted in your provided s3 bucket.
+
+```
+cfn-vpn client myvpn --client-cn user1 --bucket mybucket
+```
+
+
+## Revoke a user
+
+This will revoke the client certificate and apply to the client VPN endpoint.
+Note this wont terminate the session but will stop the client from reconnecting using the certificate.
+
+```sh
+cfn-vpn revoke myvpn --client-cn user1 --bucket mybucket
+```
+
+## Modify the Client VPN config
+
+This will modify some attributes of the client vpn endpoint.
+
+```sh
+cfn-vpn config myvpn --dns-servers 8.8.8.8 8.8.4.4
+```
+
+*Options:*
+
+```bash
+[--cidr=CIDR]                              # cidr from which to assign client IP addresses
+                                           # Default: 10.250.0.0/16
+[--dns-servers=DNS_SERVERS]                # DNS Servers to push to clients.
+[--split-tunnel], [--no-split-tunnel]      # only push routes to the client on the vpn endpoint
+[--internet-route], [--no-internet-route]  # create a default route to the internet
+                                           # Default: true
+[--protocol=PROTOCOL]                      # set the protocol for the vpn connections
+                                           # Default: udp
+                                           # Possible values: udp, tcp
+```
+
+
+## Share client certificates with a user
+
+The users vpn config and certificates can be passed to the user securely using S3 signed URLs to allow the user to directly download them.
+There are 2 ways to generate the vpn config file, by having the certificates and config file separate or by embedding the certificates into the config file.
+
+
+### Certificate embedded into config
+
+This will pull the clients certificate and key archives from S3 and embed them into the config file, upload it back to S3 and generate a presigned URL for the user.
+This allows the you to download or share a single, ready to import config file into a OpenVPN client.
+
+```sh
+cfn-vpn embedded myvpn --client-cn user1 --bucket mybucket
+```
+
+### Separate certificate and config
+
+This will generate a presigned url for the client's certificate and config file to allow them to download them to their local computer.
+
+```sh
+cfn-vpn share myvpn --client-cn user1 --bucket mybucket
+```
+
+You can then share the output with your user
+
+```
+Download the certificates and config from the bellow presigned URLs which will expire in 1 hour.
+
+Certificate:
+<presigned url>
+
+Config:
+<presigned url>
+
+Extract the certificates from the tar and place into a safe location.
+	tar xzfv user1.tar.gz -C <path>
+
+Modify base2-ciinabox.config.ovpn to include the full location of your extracted certificates
+	echo "key /<path>/user1.key" >> myvpn.config.ovpn
+	echo "cert /<path>/user1.crt" >> myvpn.config.ovpn
+
+Open myvpn.config.ovpn with your favourite openvpn client.
+```

data/docs/getting-started.md

@@ -0,0 +1,128 @@
+## Getting Started with CfnVpn
+
+## Installation
+
+Install `cfn-vpn` gem
+
+```bash
+gem install cfn-vpn --source "https://rubygems.pkg.github.com/base2services"
+```
+
+## Setup Easy-RSA
+
+**Option 1 - Docker**
+
+Install [docker](https://docs.docker.com/install/)
+
+Docker is required to generate the certificates required for the client vpn.
+The gem uses [openvpn/easy-rsa](https://github.com/OpenVPN/easy-rsa) project in [base2/aws-client-vpn](https://hub.docker.com/r/base2/aws-client-vpn) docker image. [repo](https://github.com/base2Services/ciinabox-containers/tree/master/easy-rsa)
+
+**Option 2 - local**
+
+If you would rather setup easy-rsa than install docker, you can use the `--easyrsa-local` flag when running the commands to use a local copy of easy-rsa, the binary just needs to be available in the `$PATH`. Install from [openvpn/easy-rsa](https://github.com/OpenVPN/easy-rsa)
+
+
+## Setup Your AWS Credentials
+
+Setup your [AWS credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) by either setting a profile or exporting them as environment variables.
+
+```bash
+export AWS_ACCESS_KEY_ID="XXXXXXXXXXXXXXXXXXXXX"
+export AWS_SECRET_ACCESS_KEY="XXXXXXXXXXXXXXXXXXXXX"
+export AWS_SESSION_TOKEN="XXXXXXXXXXXXXXXXXXXXX"
+```
+
+Optionally export the AWS region if not providing `--region` flag
+
+```bash
+export AWS_REGION="us-east-1"
+```
+
+
+## Initializing CfnVpn
+
+to launch a new CfnVpn stack run the `init` command along with the options.
+
+### Certificate Authenticated VPN
+
+This is the default option when launching a ClientVPN using certificated based authentication. https://docs.aws.amazon.com/vpn/latest/clientvpn-admin/client-authentication.html#mutual
+
+The following command and required options will launch a new certificate based Client-VPN
+
+```sh
+cfn-vpn init [name] --bucket [s3-bucket] --server-cn [server certificate name] --subnet-ids [list of subets to associate with the vpn]
+```
+
+
+### Federated SAML Authenticated VPN
+
+This option is for when you want to manage users through an external directory provider like AWS SSO, OKTA or AzureAD. https://docs.aws.amazon.com/vpn/latest/clientvpn-admin/client-authentication.html#federated-authentication
+
+**Prerequisites:** Client-VPN requires a IAM SAML identity provider ARN, see the [AWS docs](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml.html) to create one.
+
+The following command and required option will launch a new federated based Client-VPN
+
+```sh
+cfn-vpn init [name] --server-cn [server certificate name] --subnet-ids [list of subets to associate with the vpn] --saml-arn [identity providor arn]
+```
+
+The default authorization rule for the associated subnets allows all. You can optionally change this by using the `--default-groups` flag to set groups on the default authorization rule. 
+
+```sh
+cfn-vpn init [name] --server-cn [server certificate name] --subnet-ids [list of subets to associate with the vpn] --saml-arn [identity providor arn] --default-groups [list of group ids]
+```
+
+**AWS SSO**
+
+If using AWS SSO as your SAML provider check this guide on how to set up SAML using AWS SSO https://codeburst.io/the-aws-client-vpn-federated-authentication-missing-example-655e0a1ff7f4
+
+
+### AWS Directory Services Authenticated VPN
+
+This option integrates Microsoft Active Directory or Simple AD through AWS Directory Service with AWS Client VPN.
+
+The following command and required option will launch a new directory service based Client-VPN
+
+```sh
+cfn-vpn init simple-ad --server-cn [server certificate name] --subnet-ids [list of subets to associate with the vpn] --directory-id [aws directirory serivce id]
+```
+
+The default authorization rule for the associated subnets allows all. You can optionally change this by using the `--default-groups` flag to set groups on the default authorization rule. The group Id is the Active Directory Group ID or SID.
+
+```sh
+cfn-vpn init simple-ad --server-cn [server certificate name] --subnet-ids [list of subets to associate with the vpn] --directory-id [aws directirory serivce id] --default-groups [list of group ids]
+```
+
+See this guide for further help on setting up https://shogokobayashi.com/2019/05/18/aws-client-vpn-with-simplead/
+
+## Subnet Associations and Authorization
+
+AWS ClientVPN requires one or more subnets to be associated with the vpn. These subnets setup the default routes and by default cfn-vpn creates a allow all auth for the default routes.
+When using a federated ClientVPN you can modify the default auth to only allow specific groups by setting the groups in the `--default-groups` flag. This can also be modified later using the `modify` command.
+
+## Additional Initializing Options
+
+```
+Options:
+  r, [--region=REGION]                         # AWS Region
+                                               # Default: ap-southeast-2
+      [--verbose], [--no-verbose]              # set log level to debug
+      --server-cn=SERVER_CN                    # server certificate common name
+      [--client-cn=CLIENT_CN]                  # client certificate common name
+      [--easyrsa-local], [--no-easyrsa-local]  # run the easyrsa executable from your local rather than from docker
+      [--bucket=BUCKET]                        # s3 bucket
+      --subnet-ids=one two three               # subnet id to associate your vpn with
+      [--default-groups=one two three]         # groups to allow through the subnet associations when using federated auth
+      [--cidr=CIDR]                            # cidr from which to assign client IP addresses
+                                               # Default: 10.250.0.0/16
+      [--dns-servers=one two three]            # DNS Servers to push to clients.
+      [--split-tunnel], [--no-split-tunnel]    # only push routes to the client on the vpn endpoint
+                                               # Default: true
+      [--internet-route=INTERNET_ROUTE]        # [subnet-id] create a default route to the internet through a subnet
+      [--protocol=PROTOCOL]                    # set the protocol for the vpn connections
+                                               # Default: udp
+                                               # Possible values: udp, tcp
+      [--start=START]                          # cloudwatch event cron schedule in UTC to associate subnets to the client vpn
+      [--stop=STOP]                            # cloudwatch event cron schedule in UTC to disassociate subnets to the client vpn
+      [--saml-arn=SAML_ARN]                    # IAM SAML idenditiy providor arn if using SAML federated authentication
+```

data/docs/modifying.md

@@ -0,0 +1,67 @@
+# Modifying The Client-VPN
+
+The Client-VPN properties such as the DNS servers and the associated subnets can be modified using the `modify` command
+
+
+## CfnVpn Configuration
+
+By default `cfn-vpn` configuration is managed in a SSM parameter name `/cfnvpn/config/[name]`. This config can be dumped to a YAML file if you wish to manage through source control and use for updating `cfn-vpn` configuration.
+
+to dump the config to a yaml file use the `params` command. this will create a file call `cfnvpn.[name].yaml` in your current directory
+
+```sh
+cfn-vpn params [name] --dump
+```
+
+the `params` command can also be used to view the current deployed config and diff the deployed config against your local yaml file
+
+### View
+
+```sh
+cfn-vpn params [name]
+```
+
+### Diff
+
+```sh
+cfn-vpn params [name] --diff-yaml cfnvpn.[name].yaml
+```
+
+## Modifying
+
+### With CLI Options
+
+to modify the VPN properties run the modify command with the desired options
+
+```
+cfn-vpn modify [name] --dns-servers 10.15.0.2
+```
+
+a cloudformation changeset is created with the desired changes and approval is asked
+
+```
+INFO: - Creating cloudformation changeset for stack [name]-cfnvpn in [region]
+
++-----------------------------------+---------------------------------------------+-------------+---------------------+
+|                                                       Modify                                                        |
++-----------------------------------+---------------------------------------------+-------------+---------------------+
+| Logical Resource Id               | Resource Type                               | Replacement | Changes             |
++-----------------------------------+---------------------------------------------+-------------+---------------------+
+| CfnVpnConfig                      | AWS::SSM::Parameter                         | Conditional | Value               |
+| ClientVpnEndpoint                 | AWS::EC2::ClientVpnEndpoint                 | Conditional | DnsServers          |
+| ClientVpnTargetNetworkAssociation | AWS::EC2::ClientVpnTargetNetworkAssociation | Conditional | ClientVpnEndpointId |
+| TargetNetworkAuthorizationRule    | AWS::EC2::ClientVpnAuthorizationRule        | Conditional | ClientVpnEndpointId |
++-----------------------------------+---------------------------------------------+-------------+---------------------+
+INFO: - Cloudformation changeset changes:
+
+Continue? y
+INFO: - Waiting for changeset to UPDATE
+INFO: - Changeset UPDATE complete
+INFO: - Client VPN [endpoint-id] modified
+```
+
+### With YAML File
+
+```
+cfn-vpn modify [name] --params-yaml cfnvpn.[name].yaml
+```

data/docs/routes.md

@@ -0,0 +1,98 @@
+# Managing Client-VPN Routes
+
+Management of the VPN routes can be altered using the `routes` command or by using the `modify` command along with the yaml config file.
+
+**Note:** The default route via subnet association cannot be modified through this command. Use the `modify` command to alter the subnet associations.
+
+CfnVpn can create static routes for CIDRs as well as dynamically lookup IPs for dns endpoints and continue to monitor and update the routes if the IPs change.
+
+```sh
+cfn-vpn help routes
+```
+
+## Dynamic DNS Routes
+
+Dynamic DNS routes takes a dns endpoint and will query the record every 5 minutes to see if the IPs have changed and update the routes.
+
+### Add New
+
+to add a new route run the routes command along with the `--dns` option
+
+```sh
+cfn-vpn routes [name] --dns example.com
+```
+
+### Delete
+
+to delete a route run the routes command along with the `--dns` option of the route to delete and the delete option
+
+```sh
+cfn-vpn routes [name] --dns example.com --delete
+```
+
+## Static CIDR Routes
+
+### Add New
+
+to add a new route run the routes command along with the `--cidr` option
+
+```sh
+cfn-vpn routes [name] --cidr 10.151.0.0/16
+```
+
+### Delete
+
+to delete a route run the routes command along with the `--cidr` option of the route to delete and the delete option
+
+```sh
+cfn-vpn routes [name] --cidr 10.151.0.0/16 --delete
+```
+
+## Manage Authorization Groups
+
+When using federated or active directory authentication groups can be used to control access to certain routes. These can be managed on the routes by providing the `--groups [list of groups]` along with a space delimited list of groups to the `routes` command. This is available for both DNS and CIDR routes
+
+To add groups to a new route or to override all groups on an exiting route use the `--groups` options
+
+```sh
+cfn-vpn routes [name] [--cidr 10.151.0.0/16] [--dns example.com] --groups devs ops
+```
+
+To add groups to an existing route use the `--add-groups` options
+
+```sh
+cfn-vpn routes [name] [--cidr 10.151.0.0/16] [--dns example.com] --add-groups admin
+```
+
+To delete groups from an existing route use the `--del-groups` options
+
+```sh
+cfn-vpn routes [name] [--cidr 10.151.0.0/16] [--dns example.com] --del-groups dev
+```
+
+## Modify Command
+
+add or modify the `routes:` key in your config yaml file
+
+```yaml
+routes:
+- cidr: 10.151.0.0/16
+  desc: route to dev peered vpc
+  groups:
+  - devs
+  - ops
+- cidr: 10.152.0.0/16
+  desc: route to prod peered vpc
+  groups:
+  - ops
+- dns: example.com
+  desc: my dev alb
+  groups:
+  - dev
+```
+
+run the `modify` command and supply the yaml file to apply the changes
+
+```sh
+cfn-vpn routes [name] --params-yaml cfnvpn.[name].yaml
+```