diff --git a/docs/security.rst b/docs/security.rst index 5033ddda..0d4cfdeb 100644 --- a/docs/security.rst +++ b/docs/security.rst @@ -108,90 +108,101 @@ arrays. Security Headers ---------------- -This section contains a list of HTTP security headers supported by Flask. -To configure HTTPS and handle the headers listed below we suggest the package `flask-talisman `_. +Browsers recognize various response headers in order to control security. We +recommend reviewing each of the headers below for use in your application. +The `Flask-Talisman`_ extension can be used to manage HTTPS and the security +headers for you. + +.. _Flask-Talisman: https://github.com/GoogleCloudPlatform/flask-talisman HTTP Strict Transport Security (HSTS) -------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Redirects HTTP requests to HTTPS on all URLs, preventing man-in-the-middle (MITM) attacks. +Tells the browser to convert all HTTP requests to HTTPS, preventing +man-in-the-middle (MITM) attacks. :: -Example: + response.haders['Strict-Transport-Security'] = 'max-age=31536000; includeSubDomains' -.. sourcecode:: none - - Strict-Transport-Security: max-age=; includeSubDomains - Strict-Transport-Security: max-age=; preload +- https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security -See also `Strict Transport Security `_. +Content Security Policy (CSP) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -HTTP Public Key Pinning (HPKP) ------------------------------- +Tell the browser where it can load various types of resource from. This header +should be used whenever possible, but requires some work to define the correct +policy for your site. A very strict policy would be:: -This enables your web server to authenticate with a client browser using a specific certificate key to prevent man-in-the-middle (MITM) attacks. + response.headers['Content-Security-Policy'] = "default-src: 'self'" -Example: +- https://csp.withgoogle.com/docs/index.html +- https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy -.. sourcecode:: none +X-Content-Type-Options +~~~~~~~~~~~~~~~~~~~~~~ - Public-Key-Pins: pin-sha256="base64=="; max-age=expireTime [; includeSubDomains][; report-uri="reportURI"] +Forces the browser to honor the response content type instead of trying to +detect it, which can be abused to generate a cross-site scripting (XSS) +attack. :: -See also `Public Key Pinning `_. + response.headers['X-Content-Type-Options'] = 'nosniff' -X-Frame-Options (Clickjacking Protection) ------------------------------------------ +- https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options -Prevents the client from clicking page elements outside of the website, avoiding hijacking or UI redress attacks. +X-Frame-Options +~~~~~~~~~~~~~~~ -.. sourcecode:: none - - X-Frame-Options: DENY - X-Frame-Options: SAMEORIGIN - X-Frame-Options: ALLOW-FROM https://example.com/ +Prevents external sites from embedding your site in an ``iframe``. This +prevents a class of attacks where clicks in the outer frame can be translated +invisibly to clicks on your page's elements. This is also known as +"clickjacking". :: -See also `X-Frame-Options `_. + response.headers['X-Frame-Options'] = 'SAMEORIGIN' -X-Content-Type-Options ----------------------- +- https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options -This header prevents Cross-site scripting (XSS) by blocking requests on clients and forcing them to first read and validate the content-type before reading any of the contents of the request. +X-XSS-Protection +~~~~~~~~~~~~~~~~ -.. sourcecode:: none - - X-Content-Type-Options: nosniff +The browser will try to prevent reflected XSS attacks by not loading the page +if the request contains something that looks like JavaScript and the response +contains the same data. :: -See also `X-Content-Type-Options `_. + response.headers['X-XSS-Protection'] = '1; mode=block' -Content Security Policy (CSP) ------------------------------ +- https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-XSS-Protection -Enhances security and prevents common web vulnerabilities such as cross-site scripting (XSS) and man-in-the-middle (MITM) related attacks. +Set-Cookie options +~~~~~~~~~~~~~~~~~~ -Example: +These options can be added to a ``Set-Cookie`` header to improve their +security. Flask has configuration options to set these on the session cookie. +They can be set on other cookies too. -.. sourcecode:: none - - Content-Security-Policy: default-src https:; script-src 'nonce-{random}'; object-src 'none' +- ``Secure`` limits cookies to HTTPS traffic only. +- ``HttpOnly`` protects the contents of cookies from being read with + JavaScript. +- ``SameSite`` ensures that cookies can only be requested from the same + domain that created them. It is not supported by Flask yet. -See also `Content Security Policy `_. +:: -Cookie Options --------------- + app.config.update( + SESSION_COOKIE_SECURE=True, + SESSION_COOKIE_HTTPONLY=True, + ) -While these headers are not directly security related, they have important options that may affect your Flask application. + response.set_cookie('username', 'flask', secure=True, httponly=True) -- ``Secure`` limits your cookies to HTTPS traffic only. -- ``HttpOnly`` protects the contents of your cookie from being visible to XSS. -- ``SameSite`` ensures that cookies can only be requested from the same domain that created them but this feature is not yet fully supported across all browsers. +- https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#Secure_and_HttpOnly_cookies -Example: +HTTP Public Key Pinning (HPKP) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. sourcecode:: none - - Set-Cookie: [cookie-name]=[cookie-value] +This tells the browser to authenticate with the server using only the specific +certificate key to prevent MITM attacks. -See also: +.. warning:: + Be careful when enabling this, as it is very difficult to undo if you set up + or upgrade your key incorrectly. -- Mozilla guide to `HTTP cookies `_. -- `OWASP HTTP Only `_. +- https://developer.mozilla.org/en-US/docs/Web/HTTP/Public_Key_Pinning