CWE-330: Use of Insufficiently Random Values Documentation

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

@@ -0,0 +1,100 @@
+# 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 [[sonar 2024](https://rules.sonarsource.com/python/RSPEC-2245/)]. 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 can lead to a vulnerability due to its predictability. The random module is based on the Mersenne Twister `MT19937`
+[[MATSUMOTO, NISHIMURA 1998](https://dl.acm.org/doi/pdf/10.1145/272991.272995)], which is a deterministic algorithm, that, given a particular input, will always produce the same output [[Wikipedia 2024](https://en.wikipedia.org/wiki/Deterministic_algorithm)]. An attacker knowing or guessing the seed value 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 security as it does not incorporate cryptographic randomness, which means it is predictable. Its use makes it easy for attackers to deduce the internal state of the generator and predict future outputs.
+
+Instead, for generating random numbers for security purposes, use an appropriate option, such as 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 an 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)|
+|[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: [https://docs.python.org/3/library/random.html](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: [https://docs.python.org/3/library/secrets.html](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: [https://docs.python.org/3/library/os.html](https://docs.python.org/3/library/os.html) [accessed 23 August 2023].|
+|[[sonar 2024](https://rules.sonarsource.com/python/RSPEC-2245/)]|Sonar Rules - Using pseudorandom number generators (PRNGs) is security-sensitive [online]. Available from: [https://rules.sonarsource.com/python/RSPEC-2245/](https://rules.sonarsource.com/python/RSPEC-2245/) [accessed 7 September 2023]|
+|[[Cloudflare 2017](https://blog.cloudflare.com/)]| Randomness 101: LavaRand in Production (cloudflare.com) [online]. Available from:[https://blog.cloudflare.com/randomness-101-lavarand-in-production/](https://blog.cloudflare.com/randomness-101-lavarand-in-production/). [accessed 12 December 2024]|
+|[LavaRnd]|LAVARND ... truely random since 2000 [online]. Available from: [https://www.lavarand.org/](https://www.lavarand.org/) [accessed 12 December 2024]|
+|[MATSUMOTO, NISHIMURA 1998]|Mersenne Twister: A 623-Dimensionally Equidistributed Uniform Pseudo-Random Number Generator [online]. Available from: [https://dl.acm.org/doi/pdf/10.1145/272991.272995](https://dl.acm.org/doi/pdf/10.1145/272991.272995) [accessed 12 December 2024]|
+|[[Wikipedia 2024](https://en.wikipedia.org/wiki/Deterministic_algorithm)]|Deterministic algorithm [online]. Available from: [https://en.wikipedia.org/wiki/Deterministic_algorithm](https://en.wikipedia.org/wiki/Deterministic_algorithm) [accessed 12 December 2024]|

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

@@ -13,4 +13,4 @@ def generate_web_token():
 # 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/readme.md

@@ -70,7 +70,7 @@ It is **not production code** and requires code-style or python best practices t
 |[CWE-693: Protection Mechanism Failure](https://cwe.mitre.org/data/definitions/693.html)|Prominent CVE|
 |:----------------------------------------------------------------|:----|
 |[CWE-184: Incomplete List of Disallowed Input](CWE-693/CWE-184/.)||
-|[CWE-330: Use of Insufficiently Random Values](CWE-693/CWE-330/.)||
+|[CWE-330: Use of Insufficiently Random Values](CWE-693/CWE-330/README.md)|[CVE-2020-7548](https://www.cvedetails.com/cve/CVE-2020-7548),<br/>CVSSv3.1: **9.8**,<br/>EPSS: **0.22** (12.12.2024)|
 |[CWE-798: Use of hardcoded credentials](CWE-693/CWE-798/.)||
 
 |[CWE-697: Incorrect Comparison](https://cwe.mitre.org/data/definitions/703.html)|Prominent CVE|