|
1 | | -Reporting Security Vulnerabilities |
2 | | -================================== |
| 1 | +# Security |
| 2 | +Copyright (c) 2020-2022 The MathWorks, Inc. All rights reserved. |
| 3 | + |
| 4 | +---- |
| 5 | +**Table of Contents:** |
| 6 | +- [Reporting Security Vulnerabilities](#reporting-security-vulnerabilities) |
| 7 | +- [Security Features](#security-features) |
| 8 | +- [**SSL Support**](#ssl-support) |
| 9 | +- [**Token-Based Authentication**](#token-based-authentication) |
| 10 | + - [**Use with auto-generated tokens**](#use-with-auto-generated-tokens) |
| 11 | + - [**Specify your own token**](#specify-your-own-token) |
| 12 | + - [**Use Token Authentication with SSL enabled**](#use-token-authentication-with-ssl-enabled) |
| 13 | + - [**Token Recovery**](#token-recovery) |
| 14 | + - [**Recover tokens from the machine**](#recover-tokens-from-the-machine) |
| 15 | + - [**Recover token from a previously authenticated browser session**](#recover-token-from-a-previously-authenticated-browser-session) |
| 16 | +- [Security Best Practices](#security-best-practices) |
| 17 | + |
| 18 | +## Reporting Security Vulnerabilities |
3 | 19 | If you believe you have discovered a security vulnerability, please report it to |
4 | 20 | [email protected] instead of GitHub. Please see |
5 | 21 | [MathWorks Vulnerability Disclosure Policy for Security Researchers](https://www.mathworks.com/company/aboutus/policies_statements/vulnerability-disclosure-policy.html) |
6 | | -for additional information. |
| 22 | +for additional information. |
| 23 | + |
| 24 | +---- |
| 25 | + |
| 26 | +## Security Features |
| 27 | +The following features are available in `matlab-proxy` to provide secure access to MATLAB: |
| 28 | + - [SSL Support](#ssl-support) |
| 29 | + - [Token-Based Authentication](#token-based-authentication) |
| 30 | + |
| 31 | +---- |
| 32 | + |
| 33 | +## **SSL Support** |
| 34 | +Configure `matlab-proxy` to use SSL by providing the desired SSL certificates using the following environment variables at server launch: |
| 35 | +The following environment variables must be set to enable `matlab-proxy` to run on SSL: |
| 36 | +1. *MWI_SSL_CERT_FILE* |
| 37 | + |
| 38 | + A string with the full path to a single file in PEM format containing the certificate as well as any number of CA certificates needed to establish the certificate’s authenticity. |
| 39 | + |
| 40 | +2. *MWI_SSL_KEY_FILE* |
| 41 | + |
| 42 | + A string with the full path to a file containing the private key. If absent, the private key must be present in the certfile provided with *MWI_SSL_CERT_FILE*. |
| 43 | + |
| 44 | +Example: |
| 45 | +```bash |
| 46 | +# Launch matlab-proxy with SSL enabled |
| 47 | +$ env MWI_SSL_CERT_FILE="/path/to/certificate.pem" MWI_SSL_KEY_FILE="/path/to/keyfile.key" matlab-proxy-app |
| 48 | + |
| 49 | +# The access link is presented in the terminal upon startup like follows: |
| 50 | +================================================================================================== |
| 51 | + MATLAB can be accessed at: |
| 52 | + https://127.0.0.1:37109 |
| 53 | +================================================================================================== |
| 54 | + |
| 55 | +# NOTE: The server is running HTTP(S) ! |
| 56 | + |
| 57 | +``` |
| 58 | + |
| 59 | +---- |
| 60 | + |
| 61 | +## **Token-Based Authentication** |
| 62 | + |
| 63 | +`matlab-proxy` is a web server and that allows one to launch and access MATLAB on the machine the server is running on. |
| 64 | +By default anyone with access to the server can access MATLAB and thereby the machine on which its running. |
| 65 | + |
| 66 | +When `Token-Based Authentication` is enabled, the server will require a token to authenticate access. |
| 67 | +This token can be provided to the server in 2 ways: |
| 68 | + |
| 69 | +1. Through the [URL parameter](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) : `mwi_auth_token`. Example: |
| 70 | + ```html |
| 71 | + https://localhost:8888/?mwi_auth_token=abcdef... |
| 72 | + ``` |
| 73 | + Once provided, this information is cached in the browser and will be used in subsequent interactions |
| 74 | + |
| 75 | +2. Through the password field on the page that is presented when the user is not already logged in. |
| 76 | + <p align="left"> |
| 77 | + <img width="600" src="./img/token_authentication_page.png"> |
| 78 | + </p> |
| 79 | + |
| 80 | +**NOTE** : Its highly recommended to use this feature along with SSL enabled as shown [here](#use-token-authentication-with-ssl-enabled). |
| 81 | + |
| 82 | +### **Use with auto-generated tokens** |
| 83 | + |
| 84 | +Enable `Token-Based Authentication` by setting the environment variable `MWI_ENABLE_TOKEN_AUTH` to `True` on server launch. |
| 85 | + |
| 86 | +When enabled, `matlab-proxy` will require the URL to specify the access token using the [query component](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) `mwi_auth_token`. |
| 87 | + |
| 88 | +Example: |
| 89 | + |
| 90 | +```bash |
| 91 | + |
| 92 | +# Launch matlab-proxy with Token-Based Authentication enabled |
| 93 | +$ env MWI_ENABLE_TOKEN_AUTH=True matlab-proxy-app |
| 94 | + |
| 95 | +# The access link is presented in the terminal upon startup like follows: |
| 96 | +================================================================================================== |
| 97 | + MATLAB can be accessed at: |
| 98 | + http://127.0.0.1:37109?mwi_auth_token=SY78vUw5qyf0JTJzGK4mKJlk_exkzL_SMFJyilbGtNI |
| 99 | +================================================================================================== |
| 100 | +``` |
| 101 | +In this example `SY78vUw5qyf0JTJzGK4mKJlk_exkzL_SMFJyilbGtNI` is the token that the server would need for all future communication. |
| 102 | + |
| 103 | +After initial access, this token is cached by the browser, and all subsequent access from the same browser to the server will not require this token. |
| 104 | +You will however need this token to access the server from a new browser session or if you have cleared cookies or have cookies disabled. |
| 105 | + |
| 106 | +### **Specify your own token** |
| 107 | + |
| 108 | +*Optionally*, you can also specify your own secret token using the environment variable `MWI_AUTH_TOKEN`. |
| 109 | +Ensure that your custom token is url safe. |
| 110 | +A token can safely contain any combination of alpha numeric text along with the following permitted characters: `- . _ ~` |
| 111 | + |
| 112 | +See [URI Specification RFC3986](https://www.ietf.org/rfc/rfc3986.txt) for more information on URL safe characters. |
| 113 | + |
| 114 | +Example: |
| 115 | +```bash |
| 116 | + |
| 117 | +# Launch matlab-proxy with Token-Based Authentication enabled, and with custom token with a value of "MyCustomSecretToken" |
| 118 | +$ env MWI_ENABLE_TOKEN_AUTH=True MWI_AUTH_TOKEN=MyCustomSecretToken matlab-proxy-app |
| 119 | + |
| 120 | +# The access link is presented in the terminal upon startup like follows: |
| 121 | +================================================================================================== |
| 122 | + MATLAB can be accessed at: |
| 123 | + http://127.0.0.1:37109?mwi_auth_token=MyCustomSecretToken |
| 124 | +================================================================================================== |
| 125 | +``` |
| 126 | + |
| 127 | +### **Use Token Authentication with SSL enabled** |
| 128 | + |
| 129 | +It is recommended to enable both `Token-Based Authentication` and `SSL` to secure your access to MATLAB via matlab-proxy. As an example, the following command enables access to MATLAB using HTTPS and token-based authentication |
| 130 | + |
| 131 | +For example, the following command launches the server to deliver content on `HTTPS` along with Token-Based Authentication enabled: |
| 132 | +```bash |
| 133 | +# Launch matlab-proxy with Token-Based Authentication & SSL enabled with custom token with a value of "asdf" |
| 134 | +$ env MWI_SSL_CERT_FILE="/path/to/certificate.pem" MWI_SSL_KEY_FILE="/path/to/keyfile.key" MWI_ENABLE_TOKEN_AUTH=True MWI_AUTH_TOKEN=asdf matlab-proxy-app |
| 135 | + |
| 136 | +# The access link is presented in the terminal upon startup like follows: |
| 137 | +================================================================================================== |
| 138 | + MATLAB can be accessed at: |
| 139 | + https://127.0.0.1:37109?mwi_auth_token=asdf |
| 140 | +================================================================================================== |
| 141 | + |
| 142 | +# NOTE: This server is running HTTP(S) ! |
| 143 | + |
| 144 | +``` |
| 145 | + |
| 146 | +### **Token Recovery** |
| 147 | + |
| 148 | +To recover tokens for a previously launched server, you will need access to either: |
| 149 | + |
| 150 | +1. The machine on which the server was launched, while being logged in as the user that launched the server. |
| 151 | +2. An authenticated browser session launched for the same user. |
| 152 | + |
| 153 | +#### **Recover tokens from the machine** |
| 154 | + |
| 155 | +1. Login to the machine on which the servers are running, as the user that launched matlab-proxy. |
| 156 | +1. Activate the python environment from which the server was launched. |
| 157 | + * This should be the same environment from which the server was launched. |
| 158 | + * Run the executable `matlab-proxy-app-list-servers` |
| 159 | + |
| 160 | +Example: |
| 161 | +```bash |
| 162 | + |
| 163 | +# Connect to the machine on which the server was started: |
| 164 | +$ ssh test-user@usermachine |
| 165 | + |
| 166 | +# Running this command should print all running servers! |
| 167 | +(usermachine) $ matlab-proxy-app-list-servers |
| 168 | + |
| 169 | +------------------------------------------------------------------------------------------------------------------- |
| 170 | + Your running servers are: |
| 171 | +------------------------------------------------------------------------------------------------------------------- |
| 172 | +1. https://127.0.0.1:46525/asdf?mwi_auth_token=asdfasdf |
| 173 | +2. http://127.0.0.1:39057/test?mwi_auth_token=_qNJIXEbnXwrj9nxZwbJiWno0YqYSh8BMdQOR6K67y0 |
| 174 | +3. http://127.0.0.1:35647/test?mwi_auth_token=r6djdrcf591PttYlDZcVL78xIa1XgCviM9dQD-BrqDE |
| 175 | +4. http://127.0.0.1:36537/test?mwi_auth_token=HdQ-9tooAzA0A0CrpUxP1e5crQBErMQC3tPGTkTtrVo |
| 176 | +5. http://127.0.0.1:35433/test |
| 177 | +------------------------------------------------------------------------------------------------------------------- |
| 178 | + Thank you. |
| 179 | +------------------------------------------------------------------------------------------------------------------- |
| 180 | +``` |
| 181 | + |
| 182 | +For servers for which `Token-Based Authentication` were enabled, the URLs above will include their tokens. |
| 183 | +You can use them to gain access to your server as described in the [Introduction](#introduction). |
| 184 | + |
| 185 | +#### **Recover token from a previously authenticated browser session** |
| 186 | + |
| 187 | +1. Navigate to a browser window in which you had previously used the server. |
| 188 | + ```bash |
| 189 | + # Lets assume this was the server: |
| 190 | + http://127.0.0.1:36537/test |
| 191 | + ``` |
| 192 | +1. Edit the URL to access the endpoint `mwi_auth_token` |
| 193 | + ```html |
| 194 | + http://127.0.0.1:36537/test/get_mwi_auth_token |
| 195 | + ``` |
| 196 | + This should take you to a screen which prints the `mwi_auth_token` for that server, as shown below: |
| 197 | + <p align="left"> |
| 198 | + <img width="600" src="./img/recover_mwi_auth_token.png"> |
| 199 | + </p> |
| 200 | + |
| 201 | +## Security Best Practices |
| 202 | + |
| 203 | +* Never share access to your server |
| 204 | + Never share URLs from `matlab-proxy` with others. Doing so is equivalent to sharing your user account. |
| 205 | + |
| 206 | +* System administrators who launch `matlab-proxy` for other users, must launch the proxy as the user for whom the server is intended. |
0 commit comments