Add documentation.

Author: taus-semmle

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

@@ -0,0 +1,51 @@
+<!DOCTYPE qhelp PUBLIC
+"-//Semmle//qhelp//EN"
+"qhelp.dtd">
+<qhelp>
+     <overview>
+          <p> The <code>ssl</code> library defaults to an insecure version of
+          SSL/TLS when no specific protocol version is specified. This may leave
+          the connection vulnerable to attack.
+          </p>
+
+     </overview>
+     <recommendation>
+
+          <p>
+            Ensure that a modern, strong protocol is used. All versions of SSL,
+            and TLS 1.0 are known to be vulnerable to attacks. Using TLS 1.1 or
+            above is strongly recommended. If no explicit
+            <code>ssl_version</code> is specified, the default
+            <code>PROTOCOL_TLS</code> is chosen. This protocol is insecure and
+            should not be used.
+          </p>
+
+     </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>
+
+          <sample src="examples/insecure_default_protocol.py" />
+
+          <p>
+            In all of the above cases, a secure protocol should be used instead.
+          </p>
+          <p>
+            Note that <code>ssl.wrap_socket</code> has been deprecated in
+            Python 3.7. A preferred alternative is to use
+            <code>ssl.SSLContext</code>, which is supported in Python 2.7.9 and
+            3.2 and later versions.
+          </p>
+     </example>
+
+     <references>
+       <li>Wikipedia: <a href="https://en.wikipedia.org/wiki/Transport_Layer_Security"> Transport Layer Security</a>.</li>
+       <li>Python 3 documentation: <a href="https://docs.python.org/3/library/ssl.html#ssl.SSLContext"> class ssl.SSLContext</a>.</li>
+       <li>Python 3 documentation: <a href="https://docs.python.org/3/library/ssl.html#ssl.wrap_socket"> ssl.wrap_socket</a>.</li>
+     </references>
+
+</qhelp>

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

@@ -0,0 +1,49 @@
+<!DOCTYPE qhelp PUBLIC
+"-//Semmle//qhelp//EN"
+"qhelp.dtd">
+<qhelp>
+     <overview>
+          <p>
+            Using a broken or weak cryptographic protocol may make a connection
+            vulnerable to interference from an attacker.
+          </p>
+
+     </overview>
+     <recommendation>
+
+          <p>
+            Ensure that a modern, strong protocol is used. All versions of SSL,
+            and TLS 1.0 are known to be vulnerable to attacks. Using TLS 1.1 or
+            above is strongly recommended.
+          </p>
+
+     </recommendation>
+     <example>
+
+          <p>
+            The following code shows a variety of ways of setting up a
+            connection using SSL or TLS. They are all insecure because of the
+            version specified.
+          </p>
+
+          <sample src="examples/insecure_protocol.py" />
+
+          <p>
+            In all of the above cases, a secure protocol should be used instead.
+          </p>
+          <p>
+            Note that <code>ssl.wrap_socket</code> has been deprecated in
+            Python 3.7. A preferred alternative is to use
+            <code>ssl.SSLContext</code>, which is supported in Python 2.7.9 and
+            3.2 and later versions.
+          </p>
+     </example>
+
+     <references>
+       <li>Wikipedia: <a href="https://en.wikipedia.org/wiki/Transport_Layer_Security"> Transport Layer Security</a>.</li>
+       <li>Python 3 documentation: <a href="https://docs.python.org/3/library/ssl.html#ssl.SSLContext"> class ssl.SSLContext</a>.</li>
+       <li>Python 3 documentation: <a href="https://docs.python.org/3/library/ssl.html#ssl.wrap_socket"> ssl.wrap_socket</a>.</li>
+       <li>pyOpenSSL documentation: <a href="https://pyopenssl.org/en/stable/api/ssl.html"> An interface to the SSL-specific parts of OpenSSL</a>.</li>
+     </references>
+
+</qhelp>

python/ql/src/Security/CWE-327/examples/insecure_default_protocol.py

@@ -0,0 +1,8 @@
+import ssl
+import socket
+
+# Using the deprecated ssl.wrap_socket method
+ssl.wrap_socket(socket.socket())
+
+# Using SSLContext
+context = ssl.SSLContext()

python/ql/src/Security/CWE-327/examples/insecure_protocol.py

@@ -0,0 +1,16 @@
+import ssl
+import socket
+
+# Using the deprecated ssl.wrap_socket method
+ssl.wrap_socket(socket.socket(), ssl_version=ssl.PROTOCOL_SSLv2)
+
+# Using SSLContext
+context = ssl.SSLContext(ssl_version=ssl.PROTOCOL_SSLv3)
+
+# Using pyOpenSSL
+
+from pyOpenSSL import SSL
+
+context = SSL.Context(SSL.TLSv1_METHOD)
+
+