CWE-330: Use of Insufficiently Random Values Documentation

docs/Secure-Coding-Guide-for-Python/CWE-693/CWE-330/README.md

@@ -0,0 +1,97 @@
+# CWE-330: Use of Insufficiently Random Values
+
+When programming cryptographic functions ensure to use a Pseudo-Random Number Generator (PRNG) source that is random enough to be suitable for encryption.
+
+Certain algorithms can create sequences of numbers that approximate random distributions. These algorithms, known as pseudorandom number generators (PRNGs) are numbers generated by a computational process and appear random, even though they are produced by a deterministic algorithm. This means that, unlike truly random numbers, which are inherently unpredictable, pseudorandom numbers are generated in a predictable sequence as long as you know the starting point, or the seed, and the algorithm used to generate them.
+
+PRNGs suitable for encryption must mix non-computational sources such as a mouse, keyboard, or even  Lava Lamps [LavaRnd] to be random enough for encryption.
+
+Python's random module is a standard library module that provides functions to generate pseudorandom numbers for various distributions. This module however can lead to a vulnerability due to its predictability. The random module is based on the Mersenne Twister [Mersenne Twister - an overview | ScienceDirect Topics], which is a deterministic algorithm, hence, if an attacker knows or can guess the seed value, they can predict the entire sequence of the pseudorandom numbers. This also means that if two Random class objects are created using an identical seed, they will generate the same sequence of numbers, regardless of the Python environment.
+
+Therefore, the random module is unsuitable for applications requiring high security as it does not incorporate cryptographic randomness, which means it is not resistant to reverse engineering. Its limited entropy makes it easier for attackers to deduce the internal state of the generator and predict future outputs.
+
+Instead, for generating random numbers, it is recommended to use a more robust option, like Python's secrets module.
+
+## Non-compliant Code Example
+
+In `noncompliant01.py`, we generate a random web token using Python's random module. This makes the token predictable and vulnerable to exploitation, as the sequence of numbers is always the same for any specified seed value.
+
+*[noncompliant01.py](noncompliant01.py):*
+
+```py
+# SPDX-FileCopyrightText: OpenSSF project contributors
+# SPDX-License-Identifier: MIT
+""" Non-compliant Code Example """
+import random
+
+
+def generate_web_token():
+    """Poor random number generator"""
+    return random.randrange(int("1" + "0" * 31), int("9" * 32), 1)
+
+
+#####################
+# attempting to exploit above code example
+#####################
+TOKEN = generate_web_token()
+print(f"Your insecure token is: {TOKEN}")
+```
+
+## Compliant Code Example
+
+ [!NOTE]
+> The `secrets` module `os.urandom()` is called by `"secrets.token_urlsafe()"` causing its cryptographic strength to depend on the operating system and its entropy sources.
+Pure randomness can not be produced in software alone [[cloudflare 2017]](https://blog.cloudflare.com/randomness-101-lavarand-in-production/).
+
+ The `compliant01.py` solution uses the secrets module to generate the random numbers. The secrets module provides access to the most secure source of randomness that the os provides through `os.urandom()`.
+
+*[compliant01.py](compliant01.py):*
+
+```py
+# SPDX-FileCopyrightText: OpenSSF project contributors
+# SPDX-License-Identifier: MIT
+""" Compliant Code Example """
+import secrets
+
+
+def generate_web_token():
+    """Better cryptographic number generator"""
+    return secrets.token_urlsafe()
+
+
+#####################
+# attempting to exploit above code example
+#####################
+TOKEN = generate_web_token()
+print(f"Your secure token is: {TOKEN}")
+```
+
+## Automated Detection
+
+|Tool|Version|Checker|Description|
+|:----|:----|:----|:----|
+|[sonarlint](https://www.sonarsource.com/products/sonarlint/)|9.0.0.75308|SonarQube 9.7+|When in Connected mode Sonarlint can be configured to detect the Sonar rule ["Using pseudorandom number generators (PRNGs) is security-sensitive"](https://rules.sonarsource.com/python/RSPEC-2245/)|
+|[Bandit](https://bandit.readthedocs.io/en/latest/)|1.7.4|[B311](https://bandit.readthedocs.io/en/latest/blacklists/blacklist_calls.html?highlight=B311#b311-random)|Standard pseudo-random generators are not suitable for security/cryptographic purposes.|
+
+## Related Guidelines
+
+|||
+|:---|:---|
+|[SEI CERT C Coding Standard](https://wiki.sei.cmu.edu/confluence/display/c/SEI+CERT+C+Coding+Standard)|[MSC30-C. Do not use the rand() function for generating pseudorandom numbers](https://wiki.sei.cmu.edu/confluence/display/c/MSC30-C.+Do+not+use+the+rand%28%29+function+for+generating+pseudorandom+numbers)|
+|[SEI CERT C++ Coding Standard](https://wiki.sei.cmu.edu/confluence/pages/viewpage.action?pageId=88046682)|[MSC50-CPP. Do not use std::rand() for generating pseudorandom numbers](https://wiki.sei.cmu.edu/confluence/display/cplusplus/MSC50-CPP.+Do+not+use+std%3A%3Arand%28%29+for+generating+pseudorandom+numbers)|
+|[The CERT C++ Secure Coding Standard](https://wiki.sei.cmu.edu/confluence/pages/viewpage.action?pageId=88046682) |[VOID FLP02-CPP. Avoid using floating point numbers when precise computation is needed](https://wiki.sei.cmu.edu/confluence/pages/viewpage.action?pageId=88046687)|
+|[SEI CERT Java Coding Standards](https://wiki.sei.cmu.edu/confluence/display/seccode/SEI+CERT+Coding+Standards)| [MSC02-J. Generate strong random numbers](https://wiki.sei.cmu.edu/confluence/display/java/MSC02-J.+Generate+strong+random+numbers)|
+|MITRE CWE Pillar| [CWE-693: Protection Mechanism Failure (4.12) (mitre.org)](https://cwe.mitre.org/data/definitions/693.html)|
+|MITRE CWE Class|[CWE-330, Use of Insufficiently Random Values](http://cwe.mitre.org/data/definitions/330.html)|
+
+## Biblography
+
+|||
+|:---|:---|
+|[[Python docs - random]](https://docs.python.org/3/library/random.html)|Python Software Foundation. (2023). random- Generate pseudo-random numbers[online].Available from: [Python docs - random](https://docs.python.org/3/library/random.html) [accessed 23 August 2023].|
+|[[Python docs - secrets]](https://docs.python.org/3/library/secrets.html)|Python Software Foundation. (2023). secrets - Generate secure random numbers for managing secrets [online]. Available from: [Python docs - secrets](https://docs.python.org/3/library/secrets.html) [accessed 23 August 2023].|
+|[[Python docs - os]](https://docs.python.org/3/library/os.html)|Python Software Foundation. (2023). os - Miscellaneous operating system interfaces [online].Available from: [Python docs - os](https://docs.python.org/3/library/os.html) [accessed 23 August 2023].|
+|[sonar docs - Using pseudorandom number generators (PRNGs) is security-sensitive](https://rules.sonarsource.com/python/RSPEC-2245/)|Sonar Rules - Using pseudorandom number generators (PRNGs) is security-sensitive. Available from [Using pseudorandom number generators (PRNGs) is security-sensitive](https://rules.sonarsource.com/python/RSPEC-2245/) [accessed 7 September 2023].|
+|[[Cloudflare 2017]](https://blog.cloudflare.com/)| [Randomness 101: LavaRand in Production (cloudflare.com)](https://blog.cloudflare.com/randomness-101-lavarand-in-production/)|
+|LavaRnd|[LavaRnd](https://www.lavarand.org/)|
+|[Science Direct - Mersenne Twister]|[Mersenne Twister - an overview / ScienceDirect Topics](https://www.sciencedirect.com/topics/computer-science/mersenne-twister)|

docs/Secure-Coding-Guide-for-Python/CWE-693/CWE-330/compliant01.py

@@ -2,15 +2,15 @@
 # SPDX-License-Identifier: MIT
 """ Compliant Code Example """
 import secrets
-
-
+ 
+ 
 def generate_web_token():
     """Better cryptographic number generator"""
     return secrets.token_urlsafe()
-
-
+ 
+ 
 #####################
 # attempting to exploit above code example
 #####################
 TOKEN = generate_web_token()
-print(f"Your secure tokens is: {TOKEN}")
+print(f"Your secure token is: {TOKEN}")

docs/Secure-Coding-Guide-for-Python/CWE-693/CWE-330/noncompliant01.py

@@ -2,13 +2,13 @@
 # SPDX-License-Identifier: MIT
 """ Non-compliant Code Example """
 import random
-
-
+ 
+ 
 def generate_web_token():
     """Poor random number generator"""
     return random.randrange(int("1" + "0" * 31), int("9" * 32), 1)
-
-
+ 
+ 
 #####################
 # attempting to exploit above code example
 #####################