cfn-vpn 0.5.1 → 1.1.0

data/cfn-vpn.gemspec

@@ -37,13 +37,14 @@ 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_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 and federated type authentication for AWS Client-VPN. It currently doesn't support Active Directory type authentication.
+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,87 @@
+## 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"
+```
+
+## Initialising CfnVpn
+
+to launch a new CfnVpn stack run the `init` command along with the options.
+
+### Certificate Authenticated VPN
+
+The following command and required option 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
+
+**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]
+```
+
+## Additional Initialising 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
+      [--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,82 @@
+# 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.
+
+## Routes Command
+
+```
+Options:
+  r, [--region=REGION]              # AWS Region
+                                    # Default: ap-southeast-2
+      [--verbose], [--no-verbose]   # set log level to debug
+      [--cidr=CIDR]                 # cidr range
+      [--subnet=SUBNET]             # the target vpc subnet to route through, if none is supplied the default subnet is used
+      [--desc=DESC]                 # description of the route
+      [--groups=one two three]      # override all authorised groups on thr route
+      [--add-groups=one two three]  # add authorised groups to an existing route
+      [--del-groups=one two three]  # remove authorised groups from an existing route
+      [--delete], [--no-delete]     # delete the route from the client vpn
+
+List, add or delete client vpn 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 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.
+
+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 --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 --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 --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
+```
+
+run the `modify` command and supply the yaml file to apply the changes
+
+```sh
+cfn-vpn routes [name] --params-yaml cfnvpn.[name].yaml
+```

data/docs/scheduling.md

@@ -0,0 +1,32 @@
+# Stop and Start Client-VPN
+
+Stopping and starting the VPN can help save AWS costs when you're not using the VPN. AWS pricing model for Client-VPN is per associated subnet per hour so we can achieve this by disassociating the subnets when the VPN is not required and the associated them again when required.
+
+This can be achieved through `cfn-vpn` in 2 ways, by a cli command or via a cloudwatch event schedule.
+
+## CLI Command
+
+Use the following commands to stop and start your Client-VPN
+
+### Disassociate
+
+```sh
+cfn-vpn subnets [name] --disassociate
+```
+
+### Associate
+
+```sh
+cfn-vpn subnets [name] --associate
+```
+
+## Schedule
+
+A CloudWatch cron schedule with a lambda function can be setup to stop and start your Client-VPN. This can be achieved by modifying the `cfn-vpn` stack with the required cron schedules.
+To see the CloudWatch cron syntax please visit the [AWS docs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/ScheduledEvents.html#CronExpressions) for further info
+
+```sh
+cfn-vpn modify [name] --stop "10 6 * * ? *" --start "00 20 ? * MON-FRI *"
+```
+
+One or both of `--start` and `--stop` can be supplied, for example if you wanted an on demand start with a scheduled stop.

data/docs/sessions.md

@@ -0,0 +1,27 @@
+# Managing Client-VPN Sessions
+
+## Show Sessions
+
+This is show a table of current connections on the vpn. You can then kill sessions by using the connection id.
+
+```sh
+cfn-vpn sessions [name]
+```
+
+The sessions are displayed in a table format
+
+```bash
++-------------+---------------------+--------+-------------+-----------------------------------+---------------+--------------+
+| Common Name | Connected (UTC)     | Status | IP Address  | Connection ID                     | Ingress Bytes | Egress Bytes |
++-------------+---------------------+--------+-------------+-----------------------------------+---------------+--------------+
+| user1       | 2019-06-28 04:58:19 | active | 10.250.0.98 | cvpn-connection-05bcc579cb3fdf9a3 | 3000          | 2679         |
++-------------+---------------------+--------+-------------+-----------------------------------+---------------+--------------+
+```
+
+## Terminate a Session
+
+To terminate a Client-VPN session specify the `--kill` flag with the connection id to kill the session.
+
+```sh
+cfn-vpn sessions myvpn --kill cvpn-connection-05bcc579cb3fdf9a3
+```