diff --git a/doc/source/crossdomain.rst b/doc/source/crossdomain.rst
index 3ea578eb5e..d2d55facc7 100644
--- a/doc/source/crossdomain.rst
+++ b/doc/source/crossdomain.rst
@@ -9,10 +9,12 @@ with the Swift API.
 See http://www.adobe.com/devnet/articles/crossdomain_policy_file_spec.html for
 a description of the purpose and structure of the cross-domain policy
 file. The cross-domain policy file is installed in the root of a web
-server (i.e., the path is /crossdomain.xml).
+server (i.e., the path is ``/crossdomain.xml``).
 
-The crossdomain middleware responds to a path of /crossdomain.xml with an
-XML document such as::
+The crossdomain middleware responds to a path of ``/crossdomain.xml`` with an
+XML document such as:
+
+.. code:: xml
 
     <?xml version="1.0"?>
     <!DOCTYPE cross-domain-policy SYSTEM "http://www.adobe.com/xml/dtds/cross-domain-policy.dtd" >
@@ -31,12 +33,16 @@ Configuration
 To enable this middleware, add it to the pipeline in your proxy-server.conf
 file. It should be added before any authentication (e.g., tempauth or
 keystone) middleware. In this example ellipsis (...) indicate other
-middleware you may have chosen to use::
+middleware you may have chosen to use:
+
+.. code:: cfg
 
     [pipeline:main]
     pipeline =  ... crossdomain ... authtoken ... proxy-server
 
-And add a filter section, such as::
+And add a filter section, such as:
+
+.. code:: cfg
 
     [filter:crossdomain]
     use = egg:swift#crossdomain
@@ -45,11 +51,19 @@ And add a filter section, such as::
 
 For continuation lines, put some whitespace before the continuation
 text. Ensure you put a completely blank line to terminate the
-cross_domain_policy value.
+``cross_domain_policy`` value.
 
-The cross_domain_policy name/value is optional. If omitted, the policy
-defaults as if you had specified::
+The ``cross_domain_policy`` name/value is optional. If omitted, the policy
+defaults as if you had specified:
+
+.. code:: cfg
 
     cross_domain_policy = <allow-access-from domain="*" secure="false" />
 
+.. note::
+
+   The default policy is very permissive; this is appropriate
+   for most public cloud deployments, but may not be appropriate
+   for all deployments. See also:
+   `CWE-942 <https://cwe.mitre.org/data/definitions/942.html>`__
 
diff --git a/swift/common/middleware/crossdomain.py b/swift/common/middleware/crossdomain.py
index ffe73d43fc..c15e524548 100644
--- a/swift/common/middleware/crossdomain.py
+++ b/swift/common/middleware/crossdomain.py
@@ -23,20 +23,24 @@ class CrossDomainMiddleware(object):
     Cross domain middleware used to respond to requests for cross domain
     policy information.
 
-    If the path is /crossdomain.xml it will respond with an xml cross domain
-    policy document. This allows web pages hosted elsewhere to use client
-    side technologies such as Flash, Java and Silverlight to interact
+    If the path is ``/crossdomain.xml`` it will respond with an xml cross
+    domain policy document. This allows web pages hosted elsewhere to use
+    client side technologies such as Flash, Java and Silverlight to interact
     with the Swift API.
 
     To enable this middleware, add it to the pipeline in your proxy-server.conf
     file. It should be added before any authentication (e.g., tempauth or
     keystone) middleware. In this example ellipsis (...) indicate other
-    middleware you may have chosen to use::
+    middleware you may have chosen to use:
+
+    .. code:: cfg
 
         [pipeline:main]
         pipeline =  ... crossdomain ... authtoken ... proxy-server
 
-    And add a filter section, such as::
+    And add a filter section, such as:
+
+    .. code:: cfg
 
         [filter:crossdomain]
         use = egg:swift#crossdomain
@@ -45,13 +49,22 @@ class CrossDomainMiddleware(object):
 
     For continuation lines, put some whitespace before the continuation
     text. Ensure you put a completely blank line to terminate the
-    cross_domain_policy value.
+    ``cross_domain_policy`` value.
 
-    The cross_domain_policy name/value is optional. If omitted, the policy
-    defaults as if you had specified::
+    The ``cross_domain_policy`` name/value is optional. If omitted, the policy
+    defaults as if you had specified:
+
+    .. code:: cfg
 
         cross_domain_policy = <allow-access-from domain="*" secure="false" />
 
+    .. note::
+
+       The default policy is very permissive; this is appropriate
+       for most public cloud deployments, but may not be appropriate
+       for all deployments. See also:
+       `CWE-942 <https://cwe.mitre.org/data/definitions/942.html>`__
+
 
     """