From bff7c414b2ddf00316ac7f9ca9c7e46c2182a803 Mon Sep 17 00:00:00 2001 From: Dan Guido Date: Thu, 13 Oct 2016 15:27:06 +0200 Subject: [PATCH 1/7] Initial commit of reorg'd docs --- ADVANCED.md | 81 -------------------- CONTRIBUTING.md | 4 +- README.md | 131 ++++++++++---------------------- algo | 30 ++++---- config.cfg | 3 +- deploy.yml | 1 - docs/ADVANCED.md | 135 +++++++++++++++++++++++++++++++++ docs/ROLES.md | 32 ++++++++ requirements.txt | 1 + roles/cloud-ec2/tasks/main.yml | 4 +- 10 files changed, 229 insertions(+), 193 deletions(-) delete mode 100644 ADVANCED.md create mode 100644 docs/ADVANCED.md create mode 100644 docs/ROLES.md diff --git a/ADVANCED.md b/ADVANCED.md deleted file mode 100644 index 00de5fe..0000000 --- a/ADVANCED.md +++ /dev/null @@ -1,81 +0,0 @@ -### Cloud Providers - -**digitalocean** -*Requirement variables:* -- do_access_token -- do_ssh_name -- do_server_name -- do_region - -*Possible regions:* -- ams2 -- ams3 -- fra1 -- lon1 -- nyc1 -- nyc2 -- nyc3 -- sfo1 -- sfo2 -- sgp1 -- tor1 -- blr1 - -**gce** -*Requirement variables:* -- credentials_file -- server_name -- ssh_public_key -- zone - -*Possible zones:* -- us-central1-a -- us-central1-b -- us-central1-c -- us-central1-f -- us-east1-b -- us-east1-c -- us-east1-d -- europe-west1-b -- europe-west1-c -- europe-west1-d -- asia-east1-a -- asia-east1-b -- asia-east1-c - -**ec2** -*Requirement variables:* -- aws_access_key -- aws_secret_key -- aws_server_name -- ssh_public_key -- region - -*Possible regions:* -- us-east-1 -- us-west-1 -- us-west-2 -- ap-south-1 -- ap-northeast-2 -- ap-southeast-1 -- ap-southeast-2 -- ap-northeast-1 -- eu-central-1 -- eu-west-1 -- sa-east-1 - -**local installation** -*Requirement variables:* -- server_ip -- server_user -- IP_subject_alt_name - -### Deployment - -Start the deploy with extra variables and tags that you need. -Example for DigitalOcean: - -``` -ansible-playbook deploy.yml -t digitalocean,vpn -e 'do_access_token=secret_token_abc do_ssh_name=my_ssh_key do_server_name=algo.local do_region=ams2' -``` - diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9a1001f..c3a7ac5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,8 @@ ### Common Issues * Check that you're using at least Ansible 2.1 -* If installing to a local server, try using a fresh install -* Please review the [FAQ](https://github.com/trailofbits/algo#faq) in the readme +* If installing to a local server, use a fresh install of Ubuntu 16.04 +* Please review the [FAQ](https://github.com/trailofbits/algo#faq) ### Coding Guidelines diff --git a/README.md b/README.md index 5cb7148..c125213 100644 --- a/README.md +++ b/README.md @@ -6,11 +6,11 @@ Algo VPN (short for "Al Gore", the **V**ice **P**resident of **N**etworks everyw ## Features -* Supports only IKEv2 -* Supports only a single cipher suite w/ AES GCM, SHA2 HMAC, and P-256 DH -* Generates mobileconfig profiles to auto-configure Apple devices +* Supports only IKEv2 w/ a single cipher suite: AES GCM, SHA2 HMAC, and P-256 DH +* Generates Apple Profiles to auto-configure iOS and macOS devices * Provides helper scripts to add and remove users * Blocks ads with a local DNS resolver and HTTP proxy (optional) +* Sets up limited SSH tunnels for each user (optional) * Based on current versions of Ubuntu and StrongSwan * Installs to DigitalOcean, Amazon EC2, Google Cloud Engine, or your own server @@ -23,120 +23,71 @@ Algo VPN (short for "Al Gore", the **V**ice **P**resident of **N**etworks everyw * Does not claim to provide anonymity or censorship avoidance * Does not claim to protect you from the [FSB](https://en.wikipedia.org/wiki/Federal_Security_Service), [MSS](https://en.wikipedia.org/wiki/Ministry_of_State_Security_(China)), [DGSE](https://en.wikipedia.org/wiki/Directorate-General_for_External_Security), or [FSM](https://en.wikipedia.org/wiki/Flying_Spaghetti_Monster) -## Included Roles - -Ansible scripts are organized into roles. The roles used by Algo are described in detail below. - -### Required Roles - -* **Common** - * Installs several required packages and software updates, then reboots if necessary - * Configures network interfaces and enables packet forwarding on them -* **VPN** - * Installs [StrongSwan](https://www.strongswan.org/), enables AppArmor, limits CPU and memory access, and drops user privileges - * Builds a Certificate Authority (CA) with [easy-rsa-ipsec](https://github.com/ValdikSS/easy-rsa-ipsec) and creates one client certificate per user - * Bundles the appropriate certificates into Apple mobileconfig profiles for each user - -### Optional Roles - -* **Security Enhancements** - * Enables [unattended-upgrades](https://help.ubuntu.com/community/AutomaticSecurityUpdates) to ensure available patches are always applied - * Modify operating system features like core dumps, kernel parameters, and SUID binaries to limit possible attacks - * Modifies SSH to use only modern ciphers and a seccomp sandbox, and restricts access to many legacy and unwanted features, like X11 forwarding and SFTP - * Configures IPtables to block traffic that might pose a risk to VPN users, such as [SMB/CIFS](https://medium.com/@ValdikSS/deanonymizing-windows-users-and-capturing-microsoft-and-vpn-accounts-f7e53fe73834) -* **Ad Blocking and Compression HTTP Proxy** - * Installs [Privoxy](https://www.privoxy.org/) with an ad blocking ruleset - * Installs Apache with [mod_pagespeed](http://modpagespeed.com/) as an HTTP proxy - * Constrains Privoxy and Apache with AppArmor and cgroups CPU and memory limitations -* **DNS Ad Blocking** - * Install the [dnsmasq](http://www.thekelleys.org.uk/dnsmasq/doc.html) local resolver with a blacklist for advertising domains - * Constrains dnsmasq with AppArmor and cgroups CPU and memory limitations -* **Security Monitoring and Logging** - * Configures [auditd](https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Security_Guide/chap-system_auditing.html) and rsyslog to log data useful for investigating security incidents - * Emails aggregated Logs to a configured address on a regular basis -* **SSH Tunneling** - * Adds a restricted `algo` group to SSH with no shell access and limited forwarding options - * Creates one limited, local account per user and an SSH public key for each - -## Usage - -### Requirements - -* ansible >= 2.1 -* python >= 2.6 -* [dopy=0.3.5](https://github.com/Wiredcraft/dopy) -* [boto](https://github.com/boto/boto) -* [azure >= 0.7.1](https://github.com/Azure/azure-sdk-for-python) -* [apache-libcloud](https://github.com/apache/libcloud) -* [libcloud](https://curl.haxx.se/docs/caextract.html) (for Mac OS) -* [six](https://github.com/JioCloud/python-six) -* SHell or BASH -* libselinux-python (for RedHat based distros) - -### Roles and Tags -**Cloud roles:** -- role: cloud-digitalocean, tags: digitalocean -- role: cloud-ec2, tags: ec2 -- role: cloud-gce, tags: gce - -**Server roles:** -- role: vpn, tags: vpn -- role: dns_adblocking, tags: dns, adblock -- role: proxy, tags: proxy, adblock -- role: logging, tags: logging -- role: security, tags: security -- role: ssh_tunneling, tags: ssh_tunneling - -### Cloud Deployment - -To install the dependencies on OS X or Linux: +## Initial Setup +The easiest way to get an Algo server running is to let it setup a new virtual machine in the cloud for you. + +1. Install the dependencies on OS X or Linux: ``` sudo easy_install pip sudo pip install -r requirements.txt ``` -Open the file `config.cfg` in your favorite text editor. Specify the users you wish to create in the `users` list. - -Start the deploy and follow the instructions: - +2. Open the file `config.cfg` in your favorite text editor. Specify the users you wish to create in the `users` list. +3. Start the deploy and follow the instructions: ``` ./algo ``` -When the process is done, you can find `.mobileconfig` files and certificates in the `configs` directory. Send the `.mobileconfig` profile to users with Apple devices. Note that profile installation is supported over AirDrop. Do not send the mobileconfig file over plaintext (e.g., e-mail) since it contains the keys to access the VPN. For those using other clients, like Windows or Android, securely send them the X.509 certificates for the server and their user. +That's it! You now have an Algo VPN server on the internet. -### Local Deployment +Note: for local or scripted deployment instructions see the [Advanced Usage](/docs/ADVANCED.md) documentation. -It is possible to download Algo to your own Ubuntu server and run the scripts locally. You need to install ansible to run Algo on Ubuntu. Installing ansible via pip requires pulling in a lot of dependencies, including a full compiler suite. It is easier to use apt, however, Ubuntu 16.04 only comes with ansible 2.0.0.2. Therefore, to use apt you must use the ansible PPA and using a PPA requires installing `software-properties-common`. tl;dr: -``` -sudo apt-get install software-properties-common && sudo apt-add-repository ppa:ansible/ansible -sudo apt-get update && sudo apt-get install ansible -git clone https://github.com/trailofbits/algo -cd algo && ./algo -``` +## User Management + +### Configuration Files + +After Algo finishes setting up the server, you can find all the certificates and configuration files that users will need in the `config` directory. Make sure to adequately secure and transmit these files since many contain private keys. -### User Management +* [adsf].mobileconfig: Apple Configuration Profiles. These are all-in-one configuration files for iOS and macOS devices. Open them to a compatible device to fully configure the VPN. Note that they can be installed via AirDrop. +* asdf +* asdf -If you want to add or delete users, update the `users` list in `config.cfg` and run the command: +### Adding or Removing Users +Algo's own scripts can easily add and remove users from the VPN server. + +1. Update the `users` list in your `config.cfg` +2. Run the command: ``` ./algo update-users ``` +The Algo VPN server now only contains the users listed in the `config.cfg` file. + +## SSH Tunneling + +If you turned on the optional SSH tunneling role, then local user accounts will be created for each user in `config.cfg`. None of these user accounts will have shell access and their SSH tunneling options are limited. This was done to ensure that users have the least access required to tunnel through the server. + +Use the following command to SSH tunnel through the server: + +```asdf``` + +[explain the options] + ## FAQ -### Has this been audited? +### Has Algo been audited? -No. This project is under active development. We're happy to [accept and fix issues](https://github.com/trailofbits/algo/issues) as they are identified. Use algo at your own risk. +No. This project is under active development. We're happy to [accept and fix issues](https://github.com/trailofbits/algo/issues) as they are identified. Use Algo at your own risk. ### Why aren't you using Tor? -The goal of this project is not to provide anonymity, but to ensure confidentiality of network traffic while traveling. Tor introduces new risks that are unsuitable for Algo's intended users. Namely, with algo, users are in control over the gateway routing their traffic. With Tor, users are at the mercy of [actively](https://www.securityweek2016.tu-darmstadt.de/fileadmin/user_upload/Group_securityweek2016/pets2016/10_honions-sanatinia.pdf) [malicious](https://chloe.re/2015/06/20/a-month-with-badonions/) [exit](https://community.fireeye.com/people/archit.mehta/blog/2014/11/18/onionduke-apt-malware-distributed-via-malicious-tor-exit-node) [nodes](https://www.wired.com/2010/06/wikileaks-documents/). +The goal of this project is not to provide anonymity, but to ensure confidentiality of network traffic while traveling. Tor introduces new risks that are unsuitable for Algo's intended users. Namely, with Algo, users are in control over the gateway routing their traffic. With Tor, users are at the mercy of [actively](https://www.securityweek2016.tu-darmstadt.de/fileadmin/user_upload/Group_securityweek2016/pets2016/10_honions-sanatinia.pdf) [malicious](https://chloe.re/2015/06/20/a-month-with-badonions/) [exit](https://community.fireeye.com/people/archit.mehta/blog/2014/11/18/onionduke-apt-malware-distributed-via-malicious-tor-exit-node) [nodes](https://www.wired.com/2010/06/wikileaks-documents/). ### Why aren't you using Racoon, LibreSwan, or OpenSwan? -Raccoon does not support IKEv2. Racoon2 supports IKEv2 but is not actively maintained. When we looked, the documentation for StrongSwan was better than the corresponding documentation for LibreSwan or OpenSwan. StrongSwan also has the benefit of a from-scratch rewrite to support IKEv2. I consider such rewrites a positive step when supporting a major new protocol version. +Racoon does not support IKEv2. Racoon2 supports IKEv2 but is not actively maintained. When we looked, the documentation for StrongSwan was better than the corresponding documentation for LibreSwan or OpenSwan. StrongSwan also has the benefit of a from-scratch rewrite to support IKEv2. I consider such rewrites a positive step when supporting a major new protocol version. ### Why aren't you using a memory-safe or verified IKE daemon? @@ -148,4 +99,4 @@ OpenVPN does not have out-of-the-box client support on any major desktop or mobi ### Why aren't you using Alpine Linux, OpenBSD, or HardenedBSD? -Alpine Linux is not supported out-of-the-box by any major cloud provider. We are interested in supporting Free, Open, and HardenedBSD. Follow along on our progress in [this issue](https://github.com/trailofbits/algo/issues/35). +Alpine Linux is not supported out-of-the-box by any major cloud provider. We are interested in supporting Free-, Open-, and HardenedBSD. Follow along or contribute to our BSD support in [this issue](https://github.com/trailofbits/algo/issues/35). diff --git a/algo b/algo index bf1ebe4..8f406a6 100755 --- a/algo +++ b/algo @@ -4,11 +4,11 @@ set -e digitalocean () { read -p " -Enter your API Token (https://cloud.digitalocean.com/settings/api/tokens): +Enter your API token (https://cloud.digitalocean.com/settings/api/tokens): : " -rs do_access_token read -p " -Enter a valid SSH key name (https://cloud.digitalocean.com/settings/security): +Enter an existing SSH key name (https://cloud.digitalocean.com/settings/security): : " -r do_ssh_name read -p " @@ -32,9 +32,9 @@ Name the vpn server: 12. Bangalore Enter the number of your desired region: [7]: " -r region - region=${region:-7} + region=${region:-7} - case "$region" in + case "$region" in 1) do_region="ams2" ;; 2) do_region="ams3" ;; 3) do_region="fra1" ;; @@ -49,22 +49,22 @@ Enter the number of your desired region: 12) do_region="blr1" ;; esac -ansible-playbook deploy.yml -t digitalocean,vpn -e "do_access_token=$do_access_token do_ssh_name=$do_ssh_name do_server_name=$do_server_name do_region=$do_region" +ansible-playbook deploy.yml -t digitalocean,vpn -e "do_access_token=$do_access_token do_ssh_name=$do_ssh_name do_server_name=$do_server_name do_region=$do_region" } ec2 () { read -p " Enter your aws_access_key (http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSGettingStartedGuide/AWSCredentials.html): -: " -rs aws_access_key +[asdf...]: " -rs aws_access_key read -p " Enter your aws_secret_key (http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSGettingStartedGuide/AWSCredentials.html): -: " -rs aws_secret_key +[asdf...]: " -rs aws_secret_key read -p " Enter the local path to your SSH public key: -: " -r ssh_public_key +[adsf]: " -r ssh_public_key read -p " Name the vpn server: @@ -86,7 +86,7 @@ Name the vpn server: 11. sa-east-1 South America (São Paulo) Enter the number of your desired region: [1]: " -r aws_region - aws_region=${aws_region:-1} + aws_region=${aws_region:-1} case "$aws_region" in 1) region="us-east-1" ;; @@ -155,7 +155,7 @@ Please choose the number of your zone. Press enter for default (#8) zone. 13) zone="asia-east1-c" ;; esac -ansible-playbook deploy.yml -t gce,vpn -e "credentials_file=$credentials_file server_name=$server_name ssh_public_key=$ssh_public_key zone=$zone" +ansible-playbook deploy.yml -t gce,vpn -e "credentials_file=$credentials_file server_name=$server_name ssh_public_key=$ssh_public_key zone=$zone" } @@ -173,7 +173,7 @@ What user should we use to login on the server? (ignore if you're deploying to l Enter the public IP address of your server: (IMPORTANT! This IP is used to verify the certificate) : " -r IP_subject - ansible-playbook deploy.yml -t local,vpn -e "server_ip=$server_ip server_user=$server_user IP_subject_alt_name=$IP_subject" + ansible-playbook deploy.yml -t local,vpn -e "server_ip=$server_ip server_user=$server_user IP_subject_alt_name=$IP_subject" } algo_provisioning () { @@ -184,7 +184,7 @@ algo_provisioning () { 3. Google Compute Engine 4. Install to existing Ubuntu server -Enter the number of your desired provider +Enter the number of your desired provider : " read -r N @@ -198,12 +198,12 @@ Enter the number of your desired provider esac } - + user_management () { ansible-playbook users.yml } case "$1" in - update-users) user_management ;; - *) algo_provisioning ;; + update-users) user_management ;; + *) algo_provisioning ;; esac diff --git a/config.cfg b/config.cfg index 4704920..8fe2582 100644 --- a/config.cfg +++ b/config.cfg @@ -5,7 +5,7 @@ users: - dan - jack -# If you're using auditd for monitoring, add an email address to send logs +# Add an email address to send logs if you're using auditd for monitoring, auditd_action_mail_acct: email@example.com ### Advanced users only below this line ### @@ -15,7 +15,6 @@ easyrsa_ca_expire: 3650 easyrsa_cert_expire: 3650 easyrsa_p12_export_password: vpnpws - # If True re-init all existing certificates. (True or False) easyrsa_reinit_existent: False diff --git a/deploy.yml b/deploy.yml index 4e6ca20..9fbf792 100644 --- a/deploy.yml +++ b/deploy.yml @@ -38,4 +38,3 @@ handlers: - name: reload eth0 shell: sh -c 'ifdown eth0; ip addr flush dev eth0; ifup eth0' - diff --git a/docs/ADVANCED.md b/docs/ADVANCED.md new file mode 100644 index 0000000..9877033 --- /dev/null +++ b/docs/ADVANCED.md @@ -0,0 +1,135 @@ +# Advanced Usage + +## Requirements + +Before you begin, make sure you have installed all the dependencies necessary for your use case. Algo depends on the software below and most of it will be installed via the `requirements.txt` file. + +* ansible >= 2.1 +* python >= 2.6 +* [dopy=0.3.5](https://github.com/Wiredcraft/dopy) +* [boto](https://github.com/boto/boto) +* [azure >= 0.7.1](https://github.com/Azure/azure-sdk-for-python) +* [apache-libcloud](https://github.com/apache/libcloud) +* [libcloud](https://curl.haxx.se/docs/caextract.html) (for Mac OS) +* [six](https://github.com/JioCloud/python-six) +* SHell or BASH +* libselinux-python (for RedHat based distros) + +## Local Deployment + +It is possible to download the Algo scripts to your own Ubuntu server and run the scripts locally. You need to install ansible to run Algo on Ubuntu. Installing ansible via pip requires pulling in a lot of dependencies, including a full compiler suite. It is easier to use apt, however, Ubuntu 16.04 only comes with ansible 2.0.0.2. Therefore, to use apt you must use the ansible PPA, and using a PPA requires installing `software-properties-common`. + +tl;dr: + +``` +sudo apt-get install software-properties-common && sudo apt-add-repository ppa:ansible/ansible +sudo apt-get update && sudo apt-get install ansible +git clone https://github.com/trailofbits/algo +cd algo && ./algo +``` + +## Scripted Deployment + +Example for DigitalOcean: + +``` +ansible-playbook deploy.yml -t digitalocean,vpn -e 'do_access_token=my_secret_token do_ssh_name=my_ssh_key do_server_name=algo.local do_region=ams2' +``` + +### Roles + +Cloud roles: + +- role: cloud-digitalocean, tags: digitalocean +- role: cloud-ec2, tags: ec2 +- role: cloud-gce, tags: gce + +Server roles: + +- role: vpn, tags: vpn +- role: dns_adblocking, tags: dns, adblock +- role: proxy, tags: proxy, adblock +- role: logging, tags: logging +- role: security, tags: security +- role: ssh_tunneling, tags: ssh_tunneling + +### Digital Ocean + +Required variables: + +- do_access_token +- do_ssh_name +- do_server_name +- do_region + +Possible regions: + +- ams2 +- ams3 +- fra1 +- lon1 +- nyc1 +- nyc2 +- nyc3 +- sfo1 +- sfo2 +- sgp1 +- tor1 +- blr1 + +### Google Cloud Engine + +Required variables: + +- credentials_file +- server_name +- ssh_public_key +- zone + +Possible zones: + +- us-central1-a +- us-central1-b +- us-central1-c +- us-central1-f +- us-east1-b +- us-east1-c +- us-east1-d +- europe-west1-b +- europe-west1-c +- europe-west1-d +- asia-east1-a +- asia-east1-b +- asia-east1-c + +### Amazon EC2 + +Required variables: + +- aws_access_key +- aws_secret_key +- aws_server_name +- ssh_public_key +- region + +Possible regions: + +- us-east-1 +- us-west-1 +- us-west-2 +- ap-south-1 +- ap-northeast-2 +- ap-southeast-1 +- ap-southeast-2 +- ap-northeast-1 +- eu-central-1 +- eu-west-1 +- sa-east-1 + +### Local Installation + +Required variables: + +- server_ip +- server_user +- IP_subject_alt_name \ No newline at end of file diff --git a/docs/ROLES.md b/docs/ROLES.md new file mode 100644 index 0000000..8e1df28 --- /dev/null +++ b/docs/ROLES.md @@ -0,0 +1,32 @@ +# Ansible Roles + +## Required Roles + +* **Common** + * Installs several required packages and software updates, then reboots if necessary + * Configures network interfaces and enables packet forwarding on them +* **VPN** + * Installs [StrongSwan](https://www.strongswan.org/), enables AppArmor, limits CPU and memory access, and drops user privileges + * Builds a Certificate Authority (CA) with [easy-rsa-ipsec](https://github.com/ValdikSS/easy-rsa-ipsec) and creates one client certificate per user + * Bundles the appropriate certificates into Apple mobileconfig profiles for each user + * Configures IPtables to block traffic that might pose a risk to VPN users, such as [SMB/CIFS](https://medium.com/@ValdikSS/deanonymizing-windows-users-and-capturing-microsoft-and-vpn-accounts-f7e53fe73834) + +## Optional Roles + +* **Security Enhancements (Reccommended)** + * Enables [unattended-upgrades](https://help.ubuntu.com/community/AutomaticSecurityUpdates) to ensure available patches are always applied + * Modify features like core dumps, kernel parameters, and SUID binaries to limit possible attacks + * Enhances SSH with modern ciphers and seccomp, and restricts access to older, unwanted features like X11 forwarding and SFTP +* **Ad Blocking and Compression HTTP Proxy** + * Installs [Privoxy](https://www.privoxy.org/) with an ad blocking ruleset + * Installs Apache with [mod_pagespeed](http://modpagespeed.com/) as an HTTP proxy + * Constrains Privoxy and Apache with AppArmor and cgroups CPU and memory limitations +* **DNS Ad Blocking** + * Install the [dnsmasq](http://www.thekelleys.org.uk/dnsmasq/doc.html) local resolver with a blacklist for advertising domains + * Constrains dnsmasq with AppArmor and cgroups CPU and memory limitations +* **Security Monitoring and Logging** + * Configures [auditd](https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Security_Guide/chap-system_auditing.html) and rsyslog to log data useful for investigating security incidents + * Sends logs to a configured email address on a regular basis +* **SSH Tunneling** + * Adds a restricted `algo` group with no shell access and limited SSH forwarding options + * Creates one limited, local account per user and an SSH public key for each diff --git a/requirements.txt b/requirements.txt index a666d82..36b226c 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,4 @@ +ansible>=2.1 dopy==0.3.5 boto azure>=0.7.1 diff --git a/roles/cloud-ec2/tasks/main.yml b/roles/cloud-ec2/tasks/main.yml index 4f25e1b..eace8c4 100644 --- a/roles/cloud-ec2/tasks/main.yml +++ b/roles/cloud-ec2/tasks/main.yml @@ -1,4 +1,4 @@ -- name: Locate official Ubuntu 16.04 AMI for region. +- name: Locate official Ubuntu 16.04 AMI for region ec2_ami_find: aws_access_key: "{{ aws_access_key }}" aws_secret_key: "{{ aws_secret_key }}" @@ -13,7 +13,7 @@ - set_fact: ami_image: "{{ ami_search.results[0].ami_id }}" -- name: Add ssh public key. +- name: Add ssh public key ec2_key: aws_access_key: "{{ aws_access_key }}" aws_secret_key: "{{ aws_secret_key }}" From e99d5dffea1d0221e23c63d77e10d6c15bc7c529 Mon Sep 17 00:00:00 2001 From: Dan Guido Date: Thu, 13 Oct 2016 15:50:24 +0200 Subject: [PATCH 2/7] better defaults --- algo | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/algo b/algo index 8f406a6..c0cec1d 100755 --- a/algo +++ b/algo @@ -56,15 +56,15 @@ ansible-playbook deploy.yml -t digitalocean,vpn -e "do_access_token=$do_access_t ec2 () { read -p " Enter your aws_access_key (http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSGettingStartedGuide/AWSCredentials.html): -[asdf...]: " -rs aws_access_key +[AKIA...]: " -rs aws_access_key read -p " Enter your aws_secret_key (http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSGettingStartedGuide/AWSCredentials.html): -[asdf...]: " -rs aws_secret_key +[ABCD...]: " -rs aws_secret_key read -p " Enter the local path to your SSH public key: -[adsf]: " -r ssh_public_key +[~/.ssh/id_rsa.pub]: " -r ssh_public_key read -p " Name the vpn server: From 462bf29e08110b7244c2fe92267eb95e4b20f15b Mon Sep 17 00:00:00 2001 From: Dan Guido Date: Thu, 13 Oct 2016 16:35:32 +0200 Subject: [PATCH 3/7] change EC2 instructions --- algo | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/algo b/algo index c0cec1d..0e891da 100755 --- a/algo +++ b/algo @@ -55,16 +55,18 @@ ansible-playbook deploy.yml -t digitalocean,vpn -e "do_access_token=$do_access_t ec2 () { read -p " -Enter your aws_access_key (http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSGettingStartedGuide/AWSCredentials.html): +Enter your aws_access_key (http://docs.aws.amazon.com/general/latest/gr/managing-aws-access-keys.html) +Note: Make sure to use either your root key (recommended) or an IAM user with an acceptable policy attached [AKIA...]: " -rs aws_access_key read -p " -Enter your aws_secret_key (http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSGettingStartedGuide/AWSCredentials.html): +Enter your aws_secret_key (http://docs.aws.amazon.com/general/latest/gr/managing-aws-access-keys.html) +Note: Make sure to use either your root key (recommended) or an IAM user with an acceptable policy attached [ABCD...]: " -rs aws_secret_key read -p " Enter the local path to your SSH public key: -[~/.ssh/id_rsa.pub]: " -r ssh_public_key +: " -r ssh_public_key read -p " Name the vpn server: From f76c2690024268ee9fcdce2ace15a953718e4b96 Mon Sep 17 00:00:00 2001 From: Dan Guido Date: Sat, 15 Oct 2016 19:31:22 +0200 Subject: [PATCH 4/7] reorganize the readme to be even simpler --- README.md | 34 +++++++++++++--------------------- 1 file changed, 13 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 3a28e3c..3e832b0 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ Algo VPN (short for "Al Gore", the **V**ice **P**resident of **N**etworks everyw * Does not claim to provide anonymity or censorship avoidance * Does not claim to protect you from the [FSB](https://en.wikipedia.org/wiki/Federal_Security_Service), [MSS](https://en.wikipedia.org/wiki/Ministry_of_State_Security_(China)), [DGSE](https://en.wikipedia.org/wiki/Directorate-General_for_External_Security), or [FSM](https://en.wikipedia.org/wiki/Flying_Spaghetti_Monster) -## Initial Setup +## Deploy the Algo Server The easiest way to get an Algo server running is to let it setup a new virtual machine in the cloud for you. @@ -34,18 +34,13 @@ sudo pip install -r requirements.txt ``` 2. Open the file `config.cfg` in your favorite text editor. Specify the users you wish to create in the `users` list. -3. Start the deploy and follow the instructions: -``` -./algo -``` +3. Start the deploy and follow the instructions: `./algo` That's it! You now have an Algo VPN server on the internet. Note: for local or scripted deployment instructions see the [Advanced Usage](/docs/ADVANCED.md) documentation. -## User Management - -### Configuration Files +## Configure the VPN Clients After Algo finishes setting up the server, you can find all the certificates and configuration files that users will need in the `config` directory. Make sure to adequately secure and transmit these files since many contain private keys. @@ -53,19 +48,7 @@ After Algo finishes setting up the server, you can find all the certificates and * asdf * asdf -### Adding or Removing Users - -Algo's own scripts can easily add and remove users from the VPN server. - -1. Update the `users` list in your `config.cfg` -2. Run the command: -``` -./algo update-users -``` - -The Algo VPN server now only contains the users listed in the `config.cfg` file. - -## SSH Tunneling +## Setup an SSH Tunnel If you turned on the optional SSH tunneling role, then local user accounts will be created for each user in `config.cfg`. None of these user accounts will have shell access and their SSH tunneling options are limited. This was done to ensure that users have the least access required to tunnel through the server. @@ -75,6 +58,15 @@ Use the following command to SSH tunnel through the server: asdf then explain the options used +## Adding or Removing Users + +Algo's own scripts can easily add and remove users from the VPN server. + +1. Update the `users` list in your `config.cfg` +2. Run the command: `./algo update-users` + +The Algo VPN server now only contains the users listed in the `config.cfg` file. + ## FAQ ### Has Algo been audited? From d62b302b8f995a4c7dfaecfedce9aa0bc986bf6a Mon Sep 17 00:00:00 2001 From: Dan Guido Date: Sun, 16 Oct 2016 17:47:35 +0200 Subject: [PATCH 5/7] better contributor guidelines --- CONTRIBUTING.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c3a7ac5..8074f82 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,9 +1,14 @@ -### Common Issues +### Troubleshooting -* Check that you're using at least Ansible 2.1 +* Check that you installed all the dependencies with pip and have Ansible 2.1+ * If installing to a local server, use a fresh install of Ubuntu 16.04 + +### Filing New Issues + * Please review the [FAQ](https://github.com/trailofbits/algo#faq) +* Please include the full output from your terminal window if appropriate -### Coding Guidelines +### Pull Requests -* Please review any Pull Requests with [ansible-lint](https://github.com/willthames/ansible-lint) +* Run [ansible-lint](https://github.com/willthames/ansible-lint) on any new ansible scripts +* Run [shellcheck](https://github.com/koalaman/shellcheck) on any new shell scripts From 8ae80788ada7a7da9e9e14351cf2debecd2d0b8c Mon Sep 17 00:00:00 2001 From: Dan Guido Date: Sun, 16 Oct 2016 23:05:20 +0200 Subject: [PATCH 6/7] better user instructions --- README.md | 29 ++++++++++++++++++++--------- config.cfg | 5 ++++- 2 files changed, 24 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 3e832b0..e746888 100644 --- a/README.md +++ b/README.md @@ -42,21 +42,32 @@ Note: for local or scripted deployment instructions see the [Advanced Usage](/do ## Configure the VPN Clients -After Algo finishes setting up the server, you can find all the certificates and configuration files that users will need in the `config` directory. Make sure to adequately secure and transmit these files since many contain private keys. +After Algo finishes setting up the server, you can find all the certificates and configuration files that users will need in the `config` directory. Make sure to secure these files since many contain private keys. All files are prefixed with the IP address of the Algo VPN server. -* [adsf].mobileconfig: Apple Configuration Profiles. These are all-in-one configuration files for iOS and macOS devices. Open them to a compatible device to fully configure the VPN. Note that they can be installed via AirDrop. -* asdf -* asdf +### Apple Devices -## Setup an SSH Tunnel +Find the corresponding mobileconfig (Apple Profile) for the user and send it to them over AirDrop (or other secure means). Apple Configuration Profiles are all-in-one configuration files for iOS and macOS devices. Installing a profile will fully configure the VPN. -If you turned on the optional SSH tunneling role, then local user accounts will be created for each user in `config.cfg`. None of these user accounts will have shell access and their SSH tunneling options are limited. This was done to ensure that users have the least access required to tunnel through the server. +### StrongSwan Clients (e.g., OpenWRT) + +Find the included user_ipsec.conf, user_ipsec.secrets, user.crt (user certificate), and user.key (private key) files and copy them to your client device. + +### Other Devices -Use the following command to SSH tunnel through the server: +* ca.crt: CA Certificate +* user_ipsec.conf: StrongSwan client configuration +* user_ipsec.secrets: StrongSwan client configuration +* user.crt: User Certificate +* user.key: User Private Key +* user.mobileconfig: Apple Profile +* user.p12: User Certificate and Private Key (in PKCS#12 format) +* user.ssh.pem (optional): SSH authorized_key file -```asdf``` +## Setup an SSH Tunnel + +If you turned on the optional SSH tunneling role, then local user accounts will be created for each user in `config.cfg`. None of these user accounts will have shell access and their SSH tunneling options are limited. This was done to ensure that users have the least access required to tunnel through the server. -asdf then explain the options used +Make sure to access the server using 'ssh -N' for any limited accounts. ## Adding or Removing Users diff --git a/config.cfg b/config.cfg index e6c6b9a..c9cedd8 100644 --- a/config.cfg +++ b/config.cfg @@ -8,12 +8,15 @@ users: # Add an email address to send logs if you're using auditd for monitoring, auditd_action_mail_acct: email@example.com +# Exported certificates will be protected by the password below: +easyrsa_p12_export_password: vpnpws + + ### Advanced users only below this line ### easyrsa_dir: /opt/easy-rsa-ipsec easyrsa_ca_expire: 3650 easyrsa_cert_expire: 3650 -easyrsa_p12_export_password: vpnpws # If True re-init all existing certificates. (True or False) easyrsa_reinit_existent: False From c87c9f8f0e2b976c27eaf0d6b6f79c19886238eb Mon Sep 17 00:00:00 2001 From: Dan Guido Date: Mon, 17 Oct 2016 16:08:39 +0200 Subject: [PATCH 7/7] easier to read --- README.md | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index e746888..6d1e1ce 100644 --- a/README.md +++ b/README.md @@ -27,12 +27,7 @@ Algo VPN (short for "Al Gore", the **V**ice **P**resident of **N**etworks everyw The easiest way to get an Algo server running is to let it setup a new virtual machine in the cloud for you. -1. Install the dependencies on OS X or Linux: -``` -sudo easy_install pip -sudo pip install -r requirements.txt -``` - +1. Install the dependencies on OS X or Linux: `sudo easy_install pip && sudo pip install -r requirements.txt` 2. Open the file `config.cfg` in your favorite text editor. Specify the users you wish to create in the `users` list. 3. Start the deploy and follow the instructions: `./algo` @@ -42,18 +37,20 @@ Note: for local or scripted deployment instructions see the [Advanced Usage](/do ## Configure the VPN Clients -After Algo finishes setting up the server, you can find all the certificates and configuration files that users will need in the `config` directory. Make sure to secure these files since many contain private keys. All files are prefixed with the IP address of the Algo VPN server. +Certificates and configuration files that users will need are placed in the `config` directory. Make sure to secure these files since many contain private keys. All files are prefixed with the IP address of the Algo VPN server. ### Apple Devices -Find the corresponding mobileconfig (Apple Profile) for the user and send it to them over AirDrop (or other secure means). Apple Configuration Profiles are all-in-one configuration files for iOS and macOS devices. Installing a profile will fully configure the VPN. +Find the corresponding mobileconfig (Apple Profile) for each user and send it to them over AirDrop (or other secure means). Apple Configuration Profiles are all-in-one configuration files for iOS and macOS devices and installing a profile will fully configure the VPN. ### StrongSwan Clients (e.g., OpenWRT) -Find the included user_ipsec.conf, user_ipsec.secrets, user.crt (user certificate), and user.key (private key) files and copy them to your client device. +Find the included user_ipsec.conf, user_ipsec.secrets, user.crt (user certificate), and user.key (private key) files and copy them to your client device. These may be useful if you plan to set up a point-to-point VPN with OpenWRT or other custom device. ### Other Devices +Depending on the platform, you may need one or multiple of the following files. + * ca.crt: CA Certificate * user_ipsec.conf: StrongSwan client configuration * user_ipsec.secrets: StrongSwan client configuration @@ -61,13 +58,12 @@ Find the included user_ipsec.conf, user_ipsec.secrets, user.crt (user certificat * user.key: User Private Key * user.mobileconfig: Apple Profile * user.p12: User Certificate and Private Key (in PKCS#12 format) -* user.ssh.pem (optional): SSH authorized_key file ## Setup an SSH Tunnel -If you turned on the optional SSH tunneling role, then local user accounts will be created for each user in `config.cfg`. None of these user accounts will have shell access and their SSH tunneling options are limited. This was done to ensure that users have the least access required to tunnel through the server. +If you turned on the optional SSH tunneling role, then local user accounts will be created for each user in `config.cfg` and an SSH authorized_key file will be in the `config` directory (user.ssh.pem). SSH user accounts do not have shell access and their tunneling options are limited. This is done to ensure that users have the least access required to tunnel through the server. -Make sure to access the server using 'ssh -N' for any limited accounts. +Make sure to access the server using 'ssh -N' with these limited accounts. ## Adding or Removing Users