www/nginx: add some hardening background (#146)

source/manual/how-tos/nginx_header_hardening.rst

@@ -0,0 +1,132 @@
+=======================
+nginx: Header Hardening
+=======================
+
+.. Note::
+
+    Except for some specific configuration directives, this is **NOT**
+    specific to the nginx plugin. Please note that you can also debug your
+    frontend code this way.
+
+
+Background Information
+======================
+
+HTTP headers can control what a web application is allowed to do and what it is
+not. This can be used to harden the web application against some **client side risks**.
+
+
+Testing Web Applications Using A Local Proxy
+============================================
+
+Configuration of Firefox
+------------------------
+
+For this tests, you should install and configure FoxyProxy_.
+
+.. _FoxyProxy: https://addons.mozilla.org/de/firefox/addon/foxyproxy-standard/
+
+After it is installed, click on the proxy settings and add a new one:
+
+.. image:: images/zap_foxyproxy.png
+
+As a proxy, enter localhost (or 127.0.0.1 in case localhost does not work) and
+the port 8080. Save the settings.
+
+
+Downloading A Proxy Software For Testing
+----------------------------------------
+
+Well known Test tools are:
+
+* OWASP ZAP (https://github.com/zaproxy/zaproxy)
+* Burp (https://portswigger.net/burp)
+* mitmproxy (https://mitmproxy.org/)
+
+
+When it is downloaded, you usually have to unpack it into a fitting directory.``
+When it is unpacked, you need to run it. In case of ZAP, doubleclick the
+``zap.sh`` or ``zap.bat`` depending on your operating system.
+
+Next regenerate and export the certificate under
+:menuselection:`Tools --> Options --> Dynamic SSL certificates` and import it into the Firefox
+key store (:menuselection:`Preferences --> Data Protection & Security --> Show Certificates`) with
+full trust.
+
+Start Testing
+-------------
+
+Click on the FoxyProxy icon and select the localhost proxy defined first.
+Next just use the application as usual. If you click the red button,
+can stop the request in ZAP and it allows you to edit it:
+
+.. image:: images/zap_request.png
+
+When you are done, just click one of the play buttons to disable halting or wait
+for the next request / response to edit that as well. For example the response
+could look like this one:
+
+.. image:: images/zap_response.png
+
+You can see a lot of important information here like the used protocol (HTTP/1.1),
+the status code 200 (which means it was successful) and a lot of headers.
+Some of those headers impact security and ZAP will try to make a recommendation,
+which may not be always correct but it may help you to find some (forgotten)
+issues:
+
+.. image:: images/zap_warnings.png
+
+The colors of the flags show how high the risk is rated so the redder it is,
+the more impact it has on security. The left view contains a list of the
+findings, the right view contains a detailed description of them.
+Based on this information, you have to decide your further actions.
+
+
+Testing Web Applications Using Developer Tools
+==============================================
+
+
+When you right click on the web site, you can inspect the element but the
+opening tools also have a tab for networking.
+
+.. image:: images/firefox_devtools_network.png
+
+The network tab works like the main view of the proxy.
+You can see which headers are sent and which ones are received.
+The advantage here is that you get some errors on the console tab (for example
+if the CSP has an error). The disadvantage of the console is, that is is not so
+easy to intercept and modify data.
+
+
+Inject Missing Headers Via The nginx Plugin
+===========================================
+
+Security headers in the nginx plugin can be injected by creating a new security
+header configuration:
+
+.. Image:: images/nginx_security_headers.png
+
+If you set a setting here, it will override what the webserver sets.
+You can inject this security setting into a location or HTTP server.
+
+You can read about the headers in the `Mozilla Wiki <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers>`_ or in the RFCs.
+
+.. Warning::
+
+   Not all headers are supported by all browsers.
+
+In short, the headers are:
+   
+========================= ======================================================================
+Referrer                  Control what a page sees when you link on it
+XSS Protection            Enable or disable the detection for (reflected) XSS
+Don't Sniff Content Type  Disable content type detection when the original is incorrect
+Strict Transport Security TLS only and enforce valid certificate
+HPKP                      Pin the public key, not widely used and dangerous [1]_ if misconfigured
+Content Security Policy   Controls resources and JS functions
+========================= ======================================================================
+
+.. [1] If you switch the certificate without announcing its public key first
+    via this header in a rollover time span, you will lock this clients out
+    because they expect being targetted by a MITM attack and refuse the connection
+    and it is hard to reset this pin in the browser.

source/manual/howtos.rst

@@ -46,6 +46,7 @@ How-tos
    how-tos/multiwan
    how-tos/netflow_exporter
    how-tos/nginx
+   how-tos/nginx_header_hardening
    how-tos/nginx_hosting
    how-tos/nginx_basic_auth
    how-tos/nginx_ip_acl