Polish documentation

Author: jorgectf

python/ql/src/experimental/Security/CWE-347/JWTEmptyKeyOrAlgorithm.py

@@ -0,0 +1,7 @@
+import jwt
+
+# algorithm set to None
+jwt.encode(payload, "somekey", None)
+
+# empty key
+jwt.encode(payload, key="", algorithm="HS256")

python/ql/src/experimental/Security/CWE-347/JWTEmptyKeyOrAlgorithm.qhelp

@@ -0,0 +1,30 @@
+<!DOCTYPE qhelp PUBLIC
+  "-//Semmle//qhelp//EN"
+  "qhelp.dtd">
+<qhelp>
+<overview>
+<p>Applications encoding a JSON Web Token (JWT) may be vulnerable when the applied key or algorithm
+is empty or None.</p>
+</overview>
+
+<recommendation>
+<p>Use non-empty nor None values while encoding JWT payloads.</p>
+</recommendation>
+
+<example>
+<p>This example shows two PyJWT encoding calls.
+
+In the first place, the encoding process use a None algorithm whereas the second example uses an 
+empty key. Both examples leave the payload insecurely encoded.
+</p>
+
+<sample src="JWTEmptyKeyOrAlgorithm.py" />
+</example>
+
+<references>
+<li>PyJWT: <a href="https://pyjwt.readthedocs.io/en/stable/">Documentation</a>.</li>
+<li>Authlib JWT: <a href="https://docs.authlib.org/en/latest/specs/rfc7519.html">Documentation</a>.</li>
+<li>Python-Jose: <a href="https://github.com/mpdavis/python-jose">Documentation</a>.</li>
+<li>Auth0 Blog: <a href="https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries/#Meet-the--None--Algorithm">Meet the "None" Algorithm</a>.</li>
+</references>
+</qhelp>

python/ql/src/experimental/Security/CWE-347/JWTMissingSecretOrPublicKeyVerification.py

@@ -0,0 +1,4 @@
+import jwt
+
+# unverified decoding
+jwt.decode(payload, key="somekey", verify=False)

python/ql/src/experimental/Security/CWE-347/JWTMissingSecretOrPublicKeyVerification.qhelp

@@ -0,0 +1,30 @@
+<!DOCTYPE qhelp PUBLIC
+  "-//Semmle//qhelp//EN"
+  "qhelp.dtd">
+<qhelp>
+<overview>
+<p>Applications decoding a JSON Web Token (JWT) may be vulnerable when the
+key isn't verified in the process.
+</p>
+</overview>
+
+<recommendation>
+<p>Set the <code>verify</code> argument to <code>True</code> or use
+a framework that does it by default.
+</p>
+</recommendation>
+
+<example>
+<p>This example shows a PyJWT encoding call with the <code>verify</code> 
+argument set to <code>False</code>.
+</p>
+
+<sample src="JWTMissingSecretOrPublicKeyVerification.py" />
+</example>
+
+<references>
+<li>PyJWT: <a href="https://pyjwt.readthedocs.io/en/stable/">Documentation</a>.</li>
+<li>Authlib JWT: <a href="https://docs.authlib.org/en/latest/specs/rfc7519.html">Documentation</a>.</li>
+<li>Python-Jose: <a href="https://github.com/mpdavis/python-jose">Documentation</a>.</li>
+</references>
+</qhelp>

python/ql/src/experimental/semmle/python/Concepts.qll

@@ -213,7 +213,7 @@ class JWTEncoding extends DataFlow::Node {
 /** Provides classes for modeling JWT decoding-related APIs. */
 module JWTDecoding {
   /**
-   * A data-flow node that collects functions escaping regular expressions.
+   * A data-flow node that collects methods encoding a JWT token.
    *
    * Extend this class to model new APIs. If you want to refine existing API models,
    * extend `JWTDecoding` instead.

python/ql/src/experimental/semmle/python/libraries/PyJWT.qll

@@ -13,6 +13,7 @@ private module PyJWT {
   /** Gets a reference to `jwt.decode` */
   private API::Node pyjwtDecode() { result = pyjwt().getMember("decode") }
 
+  // def encode(self, payload, key, algorithm="HS256", headers=None, json_encoder=None)
   private class PyJWTEncodeCall extends DataFlow::CallCfgNode, JWTEncoding::Range {
     PyJWTEncodeCall() { this = pyjwtEncode().getACall() }
 
@@ -34,6 +35,7 @@ private module PyJWT {
     }
   }
 
+  // def decode(self, jwt, key="", algorithms=None, options=None)
   private class PyJWTDecodeCall extends DataFlow::CallCfgNode, JWTDecoding::Range {
     PyJWTDecodeCall() { this = pyjwtDecode().getACall() }