Update docstrings (#138)

Signed-off-by: Eric Brown <eric.brown@securesauce.dev>

docs/source/rules/python/stdlib/hmac/hmac_timing_attack.rst

@@ -0,0 +1,5 @@
+=======
+PRE0005
+=======
+
+.. automodule:: precli.rules.python.stdlib.hmac.hmac_timing_attack

docs/source/rules/python/stdlib/imaplib/imap_cleartext.rst

@@ -0,0 +1,5 @@
+=======
+PRE0005
+=======
+
+.. automodule:: precli.rules.python.stdlib.imaplib.imap_cleartext

docs/source/rules/python/stdlib/imaplib/index.rst

@@ -0,0 +1,8 @@
+imaplib
+=======
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   *

docs/source/rules/python/stdlib/index.rst

@@ -71,10 +71,15 @@ Standard Library
    ftplib/index
    hashlib/index
    hmac/index
+   imaplib/index
    json/index
    logging/index
    marshal/index
+   nntplib/index
    pickle/index
+   poplib/index
    shelve/index
+   smtplib/index
    ssl/index
    telnetlib/index
+   tempfile/index

docs/source/rules/python/stdlib/nntplib/index.rst

@@ -0,0 +1,8 @@
+nntplib
+=======
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   *

docs/source/rules/python/stdlib/nntplib/nntp_cleartext.rst

@@ -0,0 +1,5 @@
+=======
+PRE0008
+=======
+
+.. automodule:: precli.rules.python.stdlib.nntplib.nntp_cleartext

docs/source/rules/python/stdlib/poplib/index.rst

@@ -0,0 +1,8 @@
+poplib
+======
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   *

docs/source/rules/python/stdlib/poplib/pop_cleartext.rst

@@ -0,0 +1,5 @@
+=======
+PRE0009
+=======
+
+.. automodule:: precli.rules.python.stdlib.poplib.pop_cleartext

docs/source/rules/python/stdlib/smtplib/index.rst

@@ -0,0 +1,8 @@
+smtplib
+=======
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   *

docs/source/rules/python/stdlib/smtplib/smtp_cleartext.rst

@@ -0,0 +1,5 @@
+=======
+PRE0010
+=======
+
+.. automodule:: precli.rules.python.stdlib.smtplib.smtp_cleartext

docs/source/rules/python/stdlib/tempfile/index.rst

@@ -0,0 +1,8 @@
+tempfile
+========
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   *

docs/source/rules/python/stdlib/tempfile/mktemp_race_condition.rst

@@ -0,0 +1,5 @@
+=======
+PRE0013
+=======
+
+.. automodule:: precli.rules.python.stdlib.tempfile.mktemp_race_condition

precli/rules/__init__.py

@@ -35,9 +35,7 @@ def __init__(
         self._targets = targets
         self._wildcards = wildcards
         self._config = Config() if not config else config
-        if not help_url:
-            # TDOO: generate URL based on rule
-            self._help_url = ""
+        self._help_url = f"https://docs.securesauce.dev/rules/{id}"
         Rule._rules[id] = self
 
     @property

precli/rules/python/stdlib/crypt/crypt_weak_hash.py

@@ -89,6 +89,7 @@
 
 .. seealso::
 
+ - `Reversible One Way Hash in Crypt Module <https://docs.securesauce.dev/rules/PRE0002>`_
  - `crypt — Function to check Unix passwords <https://docs.python.org/3/library/crypt.html>`_
  - `CWE-328: Use of Weak Hash <https://cwe.mitre.org/data/definitions/328.html>`_
  - `NIST Policy on Hash Functions <https://csrc.nist.gov/projects/hash-functions>`_

precli/rules/python/stdlib/ftplib/ftp_cleartext.py

@@ -75,6 +75,7 @@
 
 .. seealso::
 
+ - `Cleartext Transmission of Sensitive Information in the Ftplib Module <https://docs.securesauce.dev/rules/PRE0003>`_
  - `ftplib — FTP protocol client <https://docs.python.org/3/library/ftplib.html>`_
  - `CWE-319: Cleartext Transmission of Sensitive Information <https://cwe.mitre.org/data/definitions/319.html>`_
  - https://www.paramiko.org/

precli/rules/python/stdlib/hashlib/hashlib_weak_hash.py

@@ -75,6 +75,7 @@
 
 .. seealso::
 
+ - `Reversible One Way Hash in Hashlib Module <https://docs.securesauce.dev/rules/PRE0004>`_
  - `hashlib — Secure hashes and message digests <https://docs.python.org/3/library/hashlib.html>`_
  - `CWE-328: Use of Weak Hash <https://cwe.mitre.org/data/definitions/328.html>`_
  - `NIST Policy on Hash Functions <https://csrc.nist.gov/projects/hash-functions>`_

precli/rules/python/stdlib/hmac/hmac_timing_attack.py

@@ -49,8 +49,8 @@
 Remediation
 -----------
 
-The recommendation is to swap the insecure hashing method to one of the more
-secure alternatives, ``SHA256``, ``SHA-384``, or ``SHA512``.
+The recommendation is to replace the == operator with the function
+``compare_digest``.
 
 .. code-block:: python
    :linenos:
@@ -72,6 +72,7 @@
 
 .. seealso::
 
+ - `Observable Timing Discrepancy in Hmac Module <https://docs.securesauce.dev/rules/PRE0005>`_
  - `hmac — Keyed-Hashing for Message Authentication <https://docs.python.org/3/library/hmac.html>`_
  - `CWE-208: Observable Timing Discrepancy <https://cwe.mitre.org/data/definitions/208.html>`_
 

precli/rules/python/stdlib/hmac/hmac_weak_hash.py

@@ -67,6 +67,7 @@
 
 .. seealso::
 
+ - `Reversible One Way Hash in Hmac Module <https://docs.securesauce.dev/rules/PRE0006>`_
  - `hmac — Keyed-Hashing for Message Authentication <https://docs.python.org/3/library/hmac.html>`_
  - `CWE-328: Use of Weak Hash <https://cwe.mitre.org/data/definitions/328.html>`_
  - `NIST Policy on Hash Functions <https://csrc.nist.gov/projects/hash-functions>`_

precli/rules/python/stdlib/imaplib/imap_cleartext.py

@@ -63,6 +63,7 @@
 
 .. seealso::
 
+ - `Cleartext Transmission of Sensitive Information in the Imaplib Module <https://docs.securesauce.dev/rules/PRE0007>`_
  - `imaplib — IMAP4 protocol client <https://docs.python.org/3/library/imaplib.html>`_
  - `CWE-319: Cleartext Transmission of Sensitive Information <https://cwe.mitre.org/data/definitions/319.html>`_
 

precli/rules/python/stdlib/json/json_load.py

@@ -33,6 +33,7 @@
 
 .. seealso::
 
+ - `Deserialization of Untrusted Data in the Json Module <https://docs.securesauce.dev/rules/PRE0008>`_
  - `json — JSON encoder and decoder <https://docs.python.org/3/library/json.html>`_
  - `CWE-502: Deserialization of Untrusted Data <https://cwe.mitre.org/data/definitions/502.html>`_
 

precli/rules/python/stdlib/logging/insecure_listen_config.py

@@ -48,6 +48,7 @@ def validate(recv: bytes):
 
 .. seealso::
 
+ - `Code Injection in Logging Config <https://docs.securesauce.dev/rules/PRE0009>`_
  - `logging.config — Logging configuration <https://docs.python.org/3/library/logging.config.html#module-logging.config>`_
  - `CWE-94: Improper Control of Generation of Code ('Code Injection') <https://cwe.mitre.org/data/definitions/94.html>`_
 

precli/rules/python/stdlib/marshal/marshal_load.py

@@ -38,6 +38,7 @@
 
 .. seealso::
 
+ - `Deserialization of Untrusted Data in the Marshal Module <https://docs.securesauce.dev/rules/PRE0010>`_
  - `marshal — Internal Python object serialization <https://docs.python.org/3/library/marshal.html>`_
  - `CWE-502: Deserialization of Untrusted Data <https://cwe.mitre.org/data/definitions/502.html>`_
 

precli/rules/python/stdlib/nntplib/nntp_cleartext.py

@@ -48,6 +48,7 @@
 
 .. seealso::
 
+ - `Cleartext Transmission of Sensitive Information in the Nntplib Module <https://docs.securesauce.dev/rules/PRE0011>`_
  - `nntplib — NNTP protocol client <https://docs.python.org/3/library/nntplib.html>`_
  - `CWE-319: Cleartext Transmission of Sensitive Information <https://cwe.mitre.org/data/definitions/319.html>`_
 

precli/rules/python/stdlib/pickle/pickle_load.py

@@ -49,6 +49,7 @@ def load_pickle_file(file_path):
 
 .. seealso::
 
+ - `Deserialization of Untrusted Data in Pickle Module <https://docs.securesauce.dev/rules/PRE0012>`_
  - `pickle — Python object serialization <https://docs.python.org/3/library/pickle.html>`_
  - `CWE-502: Deserialization of Untrusted Data <https://cwe.mitre.org/data/definitions/502.html>`_
  - `json — JSON encoder and decoder <https://docs.python.org/3/library/json.html>`_

precli/rules/python/stdlib/poplib/pop_cleartext.py

@@ -11,7 +11,7 @@
 to intercept and read this data.
 
 The Python module poplib should only in a secure mannner to protect sensitive
-data when accessing NNTP servers.
+data when accessing POP servers.
 
 -------
 Example
@@ -59,6 +59,7 @@
 
 .. seealso::
 
+ - `Cleartext Transmission of Sensitive Information in the Poplib Module <https://docs.securesauce.dev/rules/PRE0013>`_
  - `poplib — POP3 protocol client <https://docs.python.org/3/library/poplib.html>`_
  - `CWE-319: Cleartext Transmission of Sensitive Information <https://cwe.mitre.org/data/definitions/319.html>`_
 

precli/rules/python/stdlib/shelve/shelve_open.py

@@ -37,6 +37,7 @@
 
 .. seealso::
 
+ - `Deserialization of Untrusted Data in the Shelve Module <https://docs.securesauce.dev/rules/PRE0014>`_
  - `shelve — Python object persistence <https://docs.python.org/3/library/shelve.html>`_
  - `CWE-502: Deserialization of Untrusted Data <https://cwe.mitre.org/data/definitions/502.html>`_
 

precli/rules/python/stdlib/smtplib/smtp_cleartext.py

@@ -92,6 +92,7 @@ def prompt(prompt):
 
 .. seealso::
 
+ - `Cleartext Transmission of Sensitive Information in the Smtplib Module <https://docs.securesauce.dev/rules/PRE0015>`_
  - `smtplib — SMTP protocol client <https://docs.python.org/3/library/smtplib.html>`_
  - `CWE-319: Cleartext Transmission of Sensitive Information <https://cwe.mitre.org/data/definitions/319.html>`_
 

precli/rules/python/stdlib/ssl/create_unverified_context.py

@@ -49,6 +49,7 @@
 
 .. seealso::
 
+ - `Improper Certificate Validation Using ssl._create_unverified_context <https://docs.securesauce.dev/rules/PRE0016>`_
  - `ssl — TLS/SSL wrapper for socket objects <https://docs.python.org/3/library/ssl.html>`_
  - `CWE-295: Improper Certificate Validation <https://cwe.mitre.org/data/definitions/295.html>`_
 

precli/rules/python/stdlib/ssl/insecure_tls_version.py

@@ -66,6 +66,7 @@
 
 .. seealso::
 
+ - `Inadequate Encryption Strength Using Weak SSL Protocols <https://docs.securesauce.dev/rules/PRE0017>`_
  - `ssl — TLS/SSL wrapper for socket objects <https://docs.python.org/3/library/ssl.html>`_
  - `CWE-326: Inadequate Encryption Strength <https://cwe.mitre.org/data/definitions/326.html>`_
 

precli/rules/python/stdlib/telnetlib/telnetlib_cleartext.py

@@ -101,6 +101,7 @@
 
 .. seealso::
 
+ - `Cleartext Transmission of Sensitive Information in the Telnetlib Module <https://docs.securesauce.dev/rules/PRE0018>`_
  - `telnetlib — Telnet client <https://docs.python.org/3/library/telnetlib.html>`_
  - `CWE-319: Cleartext Transmission of Sensitive Information <https://cwe.mitre.org/data/definitions/319.html>`_
  - https://www.paramiko.org/

precli/rules/python/stdlib/tempfile/mktemp_race_condition.py

@@ -47,6 +47,7 @@
 
 .. seealso::
 
+ - `Insecure Temporary File in the Tempfile Module <https://docs.securesauce.dev/rules/PRE0019>`_
  - `tempfile — Generate temporary files and directories <https://docs.python.org/3/library/tempfile.html#tempfile.mktemp>`_
  - `CWE-377: Insecure Temporary File <https://cwe.mitre.org/data/definitions/377.html>`_
 

precli/rules/python/third_party/PyYAML/yaml_load.py

@@ -1,4 +1,56 @@
 # Copyright 2023 Secure Saurce LLC
+r"""
+======================================================
+Deserialization of Untrusted Data in the PyYAML Module
+======================================================
+
+The Python ``PyYAML`` module provides a way to parse and generate YAML data.
+However, it is important to be aware that malicious YAML strings can be used
+to attack applications that use the json module. For example, a malicious YAML
+string could be used to cause the decoder to consume considerable CPU and
+memory resources, which could lead to a denial-of-service attack.
+
+-------
+Example
+-------
+
+.. code-block:: python
+   :linenos:
+   :emphasize-lines: 4
+
+    import yaml
+
+
+    yaml.load("{}")
+
+-----------
+Remediation
+-----------
+
+To avoid this vulnerability, it is important to only parse YAML data from
+trusted sources. If you are parsing YAML data from an untrusted source, you
+should first sanitize the data to remove any potential malicious code. You
+can also switch to the ``safe_load`` function or use the ``SafeLoader`` value
+to the ``Loader`` argument.
+
+.. code-block:: python
+   :linenos:
+   :emphasize-lines: 4
+
+    import yaml
+
+
+    yaml.safe_load("{}")
+
+.. seealso::
+
+ - `Deserialization of Untrusted Data in the PyYAML Module <https://docs.securesauce.dev/rules/PRE0511>`_
+ - `PyYAML Documentation <https://pyyaml.org/wiki/PyYAMLDocumentation>`_
+ - `CWE-502: Deserialization of Untrusted Data <https://cwe.mitre.org/data/definitions/502.html>`_
+
+.. versionadded:: 1.0.0
+
+"""  # noqa: E501
 from precli.core.config import Config
 from precli.core.location import Location
 from precli.core.result import Result

precli/rules/python/third_party/cryptography/cryptography_weak_hash.py

@@ -1,4 +1,61 @@
 # Copyright 2023 Secure Saurce LLC
+r"""
+==============================================
+Reversible One Way Hash in Cryptography Module
+==============================================
+
+The Python module ``cryptography`` provides a number of functions for hashing
+data. However, some of the hash algorithms supported by ``cryptography`` are
+insecure and should not be used. These insecure hash algorithms include ``MD5``
+and ``SHA1``.
+
+The MD5 hash algorithm is a cryptographic hash function that was designed in
+the early 1990s. MD5 is no longer considered secure, and passwords hashed with
+MD5 can be easily cracked by attackers.
+
+The SHA-1 hash algorithm is also a cryptographic hash function that was
+designed in the early 1990s. SHA-1 is no longer considered secure, and
+passwords hashed with SHA-1 can be easily cracked by attackers.
+
+-------
+Example
+-------
+
+.. code-block:: python
+   :linenos:
+   :emphasize-lines: 4
+
+    import cryptography
+
+
+    cryptography.hazmat.primitives.hashes.MD5()
+
+-----------
+Remediation
+-----------
+
+The recommendation is to swap the insecure hashing method to one of the more
+secure alternatives, ``SHA256`` or ``SHA512``.
+
+.. code-block:: python
+   :linenos:
+   :emphasize-lines: 4
+
+    import cryptography
+
+
+    cryptography.hazmat.primitives.hashes.SHA256()
+
+.. seealso::
+
+ - `Reversible One Way Hash in Cryptography Module <https://docs.securesauce.dev/rules/PRE0501>`_
+ - `Message digests (Hashing) — Cryptography <https://cryptography.io/en/latest/hazmat/primitives/cryptographic-hashes/>`_
+ - `CWE-328: Use of Weak Hash <https://cwe.mitre.org/data/definitions/328.html>`_
+ - `NIST Policy on Hash Functions <https://csrc.nist.gov/projects/hash-functions>`_
+
+.. versionadded:: 1.0.0
+
+"""  # noqa: E501
 from precli.core.config import Config
 from precli.core.level import Level
 from precli.core.location import Location