openstack/security-doc
Code Issues Proposed changes

Conslidated many of the small sections.

Browse Source 
Change-Id: I948890e188245d3b32ead599f1c219215b0e0364
Closes-Bug: #1459040
This commit is contained in:
Emett Speer
2015-05-31 19:15:15 -07:00
committed by Andreas Jaeger
parent 9c61847a70
commit 9bcdfaf2cb
14 changed files with 149 additions and 204 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
security-guide/ch_dashboard.xml
View File

@@ -22,21 +22,13 @@
and has good <link
xlink:href="http://docs.openstack.org/developer/horizon/topics/deployment.html"
>deployment and configuration documentation</link>.</para>
<xi:include href="section_dashboard-basic-web-server-configuration.xml"/>
<xi:include href="section_dashboard-https.xml"/>
<xi:include href="section_dashboard-http-strict-transport-security-hsts.xml"/>
<xi:include href="section_dashboard-front-end-caching.xml"/>
<xi:include href="section_dashboard-domain-names.xml"/>
<xi:include href="section_dashboard-domains-dashboard-upgrades-basic-web-server-configuration.xml"/>
<xi:include href="section_dashboard-https-hsts-xss-ssrf.xml"/>
<xi:include href="section_dashboard-front-end-caching-session-back-end.xml"/>
<xi:include href="section_dashboard-static-media.xml"/>
<xi:include href="section_dashboard-secret-key.xml"/>
<xi:include href="section_dashboard-session-back-end.xml"/>
<xi:include href="section_dashboard-allowed-hosts.xml"/>
<xi:include href="section_dashboard-cross-site-request-forgery-csrf.xml"/>
<xi:include href="section_dashboard-cookies.xml"/>
<xi:include href="section_dashboard-cross-site-scripting-xss.xml"/>
<xi:include href="section_dashboard-cross-origin-resource-sharing-cors.xml"/>
<xi:include href="section_dashboard-horizon-image-upload.xml"/>
<xi:include href="section_dashboard-upgrading.xml"/>
<xi:include href="section_dashboard-debug.xml"/>
<xi:include href="section_case-studies-dashboard.xml"/>

18
security-guide/section_dashboard-allowed-hosts.xml
View File

@@ -1,18 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dashboard-allowed-hosts">
<?dbhtml stop-chunking?>
<title>Allowed hosts</title>
<para>Configure the <option>ALLOWED_HOSTS</option> setting with
the domain or domains where the dashboard is available. Failure
to configure this setting (especially if not following the
recommendation above regarding second level domains) opens the
dashboard to a number of serious attacks. Wild card domains
should be avoided.</para>
<para>For further details, see the <link
xlink:href="https://docs.djangoproject.com/"
>Django documentation</link>.</para>
</section>

19
security-guide/section_dashboard-basic-web-server-configuration.xml
View File

@@ -1,19 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dashboard-basic-web-server-configuration">
<?dbhtml stop-chunking?>
<title>Basic web server configuration</title>
<para>The dashboard should be deployed as a Web Services Gateway
Interface (WSGI) application behind an HTTPS proxy such as
Apache or nginx. If Apache is not already in use, we recommend
nginx since it is lightweight and easier to configure
correctly.</para>
<para>When using nginx, we recommend <link
xlink:href="http://docs.gunicorn.org/en/latest/deploy.html"
>gunicorn</link> as the WSGI host with an appropriate number
of synchronous workers. When using Apache, we recommend
<literal>mod_wsgi</literal> to host the dashboard.</para>
</section>

19
security-guide/section_dashboard-cross-site-request-forgery-csrf.xml
View File

@@ -1,19 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dashboard-cross-site-request-forgery-csrf">
<?dbhtml stop-chunking?>
<title>Cross Site Request Forgery (CSRF)</title>
<para>Django has dedicated middleware for cross-site request forgery (CSRF).
For further details, see the <link xlink:href="https://docs.djangoproject.com/">
Django documentation</link>.</para>
<para>Dashboard is designed to discourage developers from
introducing cross-site scripting vulnerabilities with custom
dashboards. However, it is important to audit custom dashboards,
especially ones that are JavaScript-heavy for inappropriate use
of the <literal>@csrf_exempt</literal> decorator. Dashboards
which do not follow these recommended security settings should
be carefully evaluated before restrictions are relaxed.</para>
</section>

22
security-guide/section_dashboard-cross-site-scripting-xss.xml
View File

@@ -1,22 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dashboard-cross-site-scripting-xss">
<?dbhtml stop-chunking?>
<title>Cross Site Scripting (XSS)</title>
<para>Unlike many similar systems, the OpenStack dashboard allows the
entire Unicode character set in most fields. This means
developers have less latitude to make escaping mistakes that
open attack vectors for cross-site scripting (XSS).</para>
<para>Dashboard provides tools for developers to avoid creating
XSS vulnerabilities, but they only work if developers use them
correctly. Audit any custom dashboards, paying particular
attention to use of the <literal>mark_safe</literal> function,
use of <literal>is_safe</literal> with
custom template tags, the <literal>safe</literal> template tag, anywhere
auto escape
is turned off, and any JavaScript which might evaluate
improperly escaped data.</para>
</section>

39
security-guide/section_dashboard-domain-names.xml → security-guide/section_dashboard-domains-dashboard-upgrades-basic-web-server-configuration.xml
View File

@@ -3,7 +3,10 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dashboard-domain-names">
xml:id="dashboard-domain-names-upgrades-configuration">
<?dbhtml stop-chunking?>
<title>Domain names, dashboard upgrades, and basic web server configuration</title>
<section xml:id="dashboard-domain-names">
<title>Domain names</title>
<para>Many organizations typically deploy web applications at
subdomains of an overarching organization domain. It is natural
@@ -33,4 +36,38 @@
employ HTTP Strict Transport Security (HSTS). When deployed on
a subdomain, the dashboard's security is equivalent to the least secure
application deployed on the same second-level domain.</para>
</section>
<section xml:id="dashboard-basic-web-server-configuration">
<title>Basic web server configuration</title>
<para>The dashboard should be deployed as a Web Services Gateway
Interface (WSGI) application behind an HTTPS proxy such as
Apache or nginx. If Apache is not already in use, we recommend
nginx since it is lightweight and easier to configure
correctly.</para>
<para>When using nginx, we recommend <link
xlink:href="http://docs.gunicorn.org/en/latest/deploy.html"
>gunicorn</link> as the WSGI host with an appropriate number
of synchronous workers. When using Apache, we recommend
<literal>mod_wsgi</literal> to host the dashboard.</para>
</section>
<section xml:id="dashboard-allowed-hosts">
<title>Allowed hosts</title>
<para>Configure the <option>ALLOWED_HOSTS</option> setting with
the domain or domains where the dashboard is available. Failure
to configure this setting (especially if not following the
recommendation above regarding second level domains) opens the
dashboard to a number of serious attacks. Wild card domains
should be avoided.</para>
<para>For further details, see the <link
xlink:href="https://docs.djangoproject.com/"
>Django documentation</link>.</para>
</section>
<section xml:id="dashboard-horizon-image-upload">
<title>Horizon image upload</title>
<para>We recommend that implementers <link
xlink:href="http://docs.openstack.org/developer/horizon/topics/deployment.html#file-uploads"
>disable HORIZON_IMAGES_ALLOW_UPLOAD</link> unless they have
implemented a plan to prevent resource exhaustion and denial of
service.</para>
</section>
</section>

41
security-guide/section_dashboard-front-end-caching-session-back-end.xml Normal file
View File

@@ -0,0 +1,41 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dashboard-front-end-caching-session-back-end">
<?dbhtml stop-chunking?>
<title>Front-end caching and session back end</title>
<section xml:id="dashboard-front-end-caching">
<title>Front-end caching</title>
<para>Since the dashboard is rendering dynamic content passed directly
from OpenStack API requests, we do not recommend front-end
caching layers such as varnish. In Django, static media is
directly served from Apache or nginx and already benefits from
web host caching.</para>
</section>
<section xml:id="dashboard-session-back-end">
<title>Session back end</title>
<para>The default session back end for horizon
(<literal>django.contrib.sessions.backends.signed_cookies</literal>)
saves user data in signed, but unencrypted cookies stored in the
browser. Due to the fact that each dashboard instance is
stateless, the previously mentioned methodology provides the
ability to implement the most simple session back-end scaling.</para>
<para>It should be noted that with this type of implementation
sensitive access tokens will be stored in the browser and will be
transmitted with each request made. The back end ensures the
integrity of session data, even though the transmitted data
is only encrypted by HTTPS.</para>
<para>If your architecture allows it, we recommend using
<literal>django.contrib.sessions.backends.cache</literal> as
your session back end with memcache as the cache. Memcache must
not be exposed publicly, and should communicate over a secured
private channel. If you choose to use the signed cookies
back end, refer to the Django documentation to understand the
security trade-offs.</para>
<para>For further details, see the <link
xlink:href="https://docs.djangoproject.com/"
>Django documentation</link>.</para>
</section>
</section>

14
security-guide/section_dashboard-front-end-caching.xml
View File

@@ -1,14 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dashboard-front-end-caching">
<?dbhtml stop-chunking?>
<title>Front end caching</title>
<para>Since the dashboard is rendering dynamic content passed directly
from OpenStack API requests, we do not recommend front end
caching layers such as varnish. In Django, static media is
directly served from Apache or nginx and already benefits from
web host caching.</para>
</section>

14
security-guide/section_dashboard-horizon-image-upload.xml
View File

@@ -1,14 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dashboard-horizon-image-upload">
<?dbhtml stop-chunking?>
<title>Horizon image upload</title>
<para>We recommend that implementers <link
xlink:href="http://docs.openstack.org/developer/horizon/topics/deployment.html#file-uploads"
>disable HORIZON_IMAGES_ALLOW_UPLOAD</link> unless they have
implemented a plan to prevent resource exhaustion and denial of
service.</para>
</section>

23
security-guide/section_dashboard-http-strict-transport-security-hsts.xml
View File

@@ -1,23 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dashboard-http-strict-transport-security-hsts">
<?dbhtml stop-chunking?>
<title>HTTP Strict Transport Security (HSTS)</title>
<para>It is highly recommended to use HTTP Strict Transport
Security (HSTS).</para>
<note>
<para>If you are using an HTTPS proxy in front of your web
server, rather than using an HTTP server with HTTPS
functionality, modify the <literal>SECURE_PROXY_SSL_HEADER</literal>
variable. Refer to the <link
xlink:href="https://docs.djangoproject.com/"
>Django documentation</link> for information about modifying the
<literal>SECURE_PROXY_SSL_HEADER</literal> variable.</para>
</note>
<para>See the chapter on PKI/SSL Everywhere for more specific
recommendations and server configurations for HTTPS
configurations, including the configuration of HSTS.</para>
</section>

67
security-guide/section_dashboard-https-hsts-xss-ssrf.xml Normal file
View File

@@ -0,0 +1,67 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dashboard-https-hsts-xss-ssrf">
<?dbhtml stop-chunking?>
<title>HTTPS, HSTS, XSS, and SSRF</title>
<section xml:id="dashboard-cross-site-scripting-xss">
<title>Cross Site Scripting (XSS)</title>
<para>Unlike many similar systems, the OpenStack dashboard allows the
entire Unicode character set in most fields. This means
developers have less latitude to make escaping mistakes that
open attack vectors for cross-site scripting (XSS).</para>
<para>Dashboard provides tools for developers to avoid creating
XSS vulnerabilities, but they only work if developers use them
correctly. Audit any custom dashboards, paying particular
attention to use of the <literal>mark_safe</literal> function,
use of <literal>is_safe</literal> with
custom template tags, the <literal>safe</literal> template tag, anywhere
auto escape
is turned off, and any JavaScript which might evaluate
improperly escaped data.</para>
</section>
<section xml:id="dashboard-cross-site-request-forgery-csrf">
<title>Cross Site Request Forgery (CSRF)</title>
<para>Django has dedicated middleware for cross-site request forgery (CSRF).
For further details, see the <link xlink:href="https://docs.djangoproject.com/">
Django documentation</link>.</para>
<para>Dashboard is designed to discourage developers from
introducing cross-site scripting vulnerabilities with custom
dashboards. However, it is important to audit custom dashboards,
especially ones that are JavaScript-heavy for inappropriate use
of the <literal>@csrf_exempt</literal> decorator. Dashboards
which do not follow these recommended security settings should
be carefully evaluated before restrictions are relaxed.</para>
</section>
<section xml:id="dashboard-https">
<title>HTTPS</title>
<para>
Deploy the dashboard behind a secure
<glossterm>HTTPS</glossterm> server by using a valid, trusted
certificate from a recognized certificate authority
(CA). Private organization-issued certificates are only
appropriate when the root of trust is pre-installed in all user
browsers.</para>
<para>Configure HTTP requests to the dashboard domain to redirect
to the fully qualified HTTPS URL.</para>
</section>
<section xml:id="dashboard-http-strict-transport-security-hsts">
<title>HTTP Strict Transport Security (HSTS)</title>
<para>It is highly recommended to use HTTP Strict Transport
Security (HSTS).</para>
<note>
<para>If you are using an HTTPS proxy in front of your web
server, rather than using an HTTP server with HTTPS
functionality, modify the <literal>SECURE_PROXY_SSL_HEADER</literal>
variable. Refer to the <link
xlink:href="https://docs.djangoproject.com/"
>Django documentation</link> for information about modifying the
<literal>SECURE_PROXY_SSL_HEADER</literal> variable.</para>
</note>
<para>See the chapter on PKI/SSL Everywhere for more specific
recommendations and server configurations for HTTPS
configurations, including the configuration of HSTS.</para>
</section>
</section>

18
security-guide/section_dashboard-https.xml
View File

@@ -1,18 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dashboard-https">
<?dbhtml stop-chunking?>
<title>HTTPS</title>
<para>
Deploy the dashboard behind a secure
<glossterm>HTTPS</glossterm> server by using a valid, trusted
certificate from a recognized certificate authority
(CA). Private organization-issued certificates are only
appropriate when the root of trust is pre-installed in all user
browsers.</para>
<para>Configure HTTP requests to the dashboard domain to redirect
to the fully qualified HTTPS URL.</para>
</section>

30
security-guide/section_dashboard-session-back-end.xml
View File

@@ -1,30 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dashboard-session-back-end">
<?dbhtml stop-chunking?>
<title>Session back end</title>
<para>The default session back end for horizon
(<literal>django.contrib.sessions.backends.signed_cookies</literal>)
saves user data in signed, but unencrypted cookies stored in the
browser. Due to the fact that each dashboard instance is
stateless, the previously mentioned methodology provides the
ability to implement the most simple session back-end scaling.</para>
<para>It should be noted that with this type of implementation
sensitive access tokens will be stored in the browser and will be
transmitted with each request made. The back end ensures the
integrity of session data, even though the transmitted data
is only encrypted by HTTPS.</para>
<para>If your architecture allows it, we recommend using
<literal>django.contrib.sessions.backends.cache</literal> as
your session back end with memcache as the cache. Memcache must
not be exposed publicly, and should communicate over a secured
private channel. If you choose to use the signed cookies
back end, refer to the Django documentation to understand the
security trade-offs.</para>
<para>For further details, see the <link
xlink:href="https://docs.djangoproject.com/"
>Django documentation</link>.</para>
</section>

15
security-guide/section_dashboard-upgrading.xml
View File

@@ -1,15 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dashboard-upgrading">
<?dbhtml stop-chunking?>
<title>Upgrading</title>
<para>Django security releases are generally well tested and
aggressively backwards compatible. In almost all cases, new
major releases of Django are also fully backwards compatible
with previous releases. Dashboard implementers are strongly
encouraged to run the latest stable release of Django with
up-to-date security releases.</para>
</section>