Address documentation comments.

Author: taus-semmle

python/ql/src/Security/CWE-327/InsecureDefaultProtocol.qhelp

@@ -23,16 +23,18 @@
      </recommendation>
      <example>
 
-          <p>
-            The following code shows a variety of ways of setting up a
-            connection using SSL or TLS. They are all potentially insecure because the
-            default version is used.
+       <p>
+         The following code shows two different ways of setting up a connection
+         using SSL or TLS. They are both potentially insecure because the
+         default version is used.
           </p>
 
           <sample src="examples/insecure_default_protocol.py" />
 
           <p>
-            In all of the above cases, a secure protocol should be used instead.
+            Both of the cases above should be updated to use a secure protocol
+            instead, for instance by specifying
+            <code>ssl_version=PROTOCOL_TLSv1_1</code> as a keyword argument.
           </p>
           <p>
             Note that <code>ssl.wrap_socket</code> has been deprecated in

python/ql/src/Security/CWE-327/InsecureDefaultProtocol.ql

@@ -1,7 +1,7 @@
 /**
  * @name Default version of SSL/TLS may be insecure
- * @description No SSL/TLS version has been specified in a call to 'ssl.wrap_socket'.
- *              This may result in an insecure protocol being used.
+ * @description Leaving the SSL/TLS version unspecified may result in an insecure
+ *              default protocol being used.
  * @id py/insecure-default-protocol
  * @kind problem
  * @problem.severity warning

python/ql/src/Security/CWE-327/InsecureProtocol.qhelp

@@ -29,7 +29,8 @@
           <sample src="examples/insecure_protocol.py" />
 
           <p>
-            In all of the above cases, a secure protocol should be used instead.
+            All cases should be updated to use a secure protocol, such as
+            <code>PROTOCOL_TLSv1_1</code>.
           </p>
           <p>
             Note that <code>ssl.wrap_socket</code> has been deprecated in

python/ql/src/Security/CWE-327/InsecureProtocol.ql

@@ -1,7 +1,6 @@
 /**
  * @name Use of insecure SSL/TLS version
- * @description An insecure version of SSL/TLS has been specified. This may
- *              leave the connection open to attacks.
+ * @description Using an insecure SSL/TLS version may leave the connection vulnerable to attacks.
  * @id py/insecure-protocol
  * @kind problem
  * @problem.severity warning