added README.md

README.md

@@ -0,0 +1,56 @@
+<h1>hei-vpn-for-linux</h1>
+
+This is a Python script which allows you to continue to use the HEI VPN on Linux.
+
+## Table of contents
+
+- [Table of contents](#table-of-contents)
+- [Requirements](#requirements)
+- [Usage](#usage)
+- [What is the problem with Pulse Secure or Juniper Secure Connect ?](#what-is-the-problem-with-pulse-secure-or-juniper-secure-connect-)
+- [How does this script work ?](#how-does-this-script-work-)
+- [Why is it asking me for sudo privileges ?](#why-is-it-asking-me-for-sudo-privileges-)
+- [Contributions](#contributions)
+
+
+## Requirements
+
+- Python 3+ with the following modules:
+  - `psutil`: to access PIDs in the workaround for Firefox profiles trickery
+  - `requests`: to check whether the user is already in the HEI network (using its public IP)
+  - `selenium`: to control Firefox
+
+- Firefox
+- [Geckodriver](https://github.com/mozilla/geckodriver)
+
+## Usage
+
+To use the script, simply run it with the default python interpreter like so:
+```bash
+python3 main.py
+```
+
+## What is the problem with Pulse Secure or Juniper Secure Connect ?
+
+Since 2FA has become mandatory to connect to the VPN, standard VPN clients fail to parse the login forms correctly.
+
+## How does this script work ?
+
+The script uses Selenium, a Python module capable of controlling a headless web browser, to load the gateway webpage.
+When redirected to the login form, the user is prompted to enter their credentials, which are then saved in a Firefox profile.
+The next time it is used, the connection is made automatically.
+
+Then, the session id cookie is extracted and passed to a commandline VPN client (openconnect).
+
+## Why is it asking me for sudo privileges ?
+
+There are two points for which sudo is required.
+The first and most obvious is to enable the VPN, since your network interfaces are being modified.
+The second one is due to how Firefox profiles work when installed as a snap package.
+In fact, when launching Firefox with a given profile, a copy of said profile is made in a temporary directory. However, when Firefox is a snap, this temporary directory is isolated from the rest of the system, and sudo permissions are needed to copy the profile back to a persistent directory.
+
+If you don't trust me, I encourage you to take a look at the source code and see by yourself that nothing suspicious is done.
+
+## Contributions
+
+I made this mainly for myself but thought I would share it in the hope it could help at least one other person. Feel free to make suggestions, create issues and/or pull requests.