vtests.py - Vulnerability testing functionality — ppklib - v0.2.0rc3 Documentation

# vtests.py - Vulnerability testing functionality

Purpose:

  This module provides the vulnerability tests to the project.

  Any wheel which is downloaded from PyPI is subject to the following tests, as contained in this module:

  > - MD5 checksum verification

  > - OSV security vulnerability checks

  > - Snyk security vulnerability checks

Platform:

  Linux/Windows | Python 3.6+

Developer:

  J Berendt

Email:

  development@s3dev.uk

Comments:

  This module is designed to be as self-contained as practical.

  All tests should be contained in this module as individual methods, while following the DRY paradigm to the extent possible.

class VTests

  Bases: `object`

  Wrapper class for the vulnerability tests.

  Usage:

    For specific usage examples, please refer to the docstrings for the following test methods:

    > - `md5()`

    > - `osv()`

    > - `snyk()`

  static md5(fpath: str, name: str, version: str, **kwargs) → tuple

    Perform an MD5 check against the PyPI database to verify integrity.

    Parameters:

      - fpath (str) – Complete path to the package (wheel) to be verified.

      - name (str) – Package name.

      - version (str) – Package version to be tested.

    Keyword Arguments:

      None

    Example:

      Perform an MD5 check on a specific wheel:

          >>> from ppklib.vtests import VTests

          >>> tst = VTests.md5(fpath='path/to/ppklib-0.1.0-py3-none-any.whl',
                               name='ppklib',
                               version='0.1.0')

          # Check the result of the test; True == pass
          >>> tst
          (True,)

    Returns:

      A tuple containing the verification flag. True if the MD5 hashes match, otherwise False.

      The second element of the tuple is empty, but used for consistency in test return values.

    Return type:

      tuple

  static osv(*, fpath: str = '', name: str = '', version: str = '', verbose: bool = True, **kwargs) → tuple

    Query the OSV database for any reported vulnerabilities.

    Parameters:

      - fpath (str, optional) – Complete path to the package (wheel) to be verified. Defaults to ‘’.

      - name (str, optional) – Package name. Defaults to ‘’.

      - version (str, optional) – Package version to be tested. Defaults to ‘’.

      - verbose (bool, optional) – Print all reported vulnerabilities to the terminal on test completion. Defaults to True.

    Keyword Arguments:

      None

    Example:

      Check the OSV vulnerability database for any reported vulnerabilities, for a library:

          >>> from ppklib.vtests import VTests

          >>> tst = VTests.osv(fpath='path/to/ppklib-0.1.0-py3-none-any.whl',
                               name='ppklib',
                               version='0.1.0')

          # Check the result of the test; True == pass
          >>> tst
          (True,0, 0, 0, 0)

      Check the OSV vulnerability database for any reported vulnerabilities, for a library with vulnerabilities:

          >>> from ppklib.vtests import VTests

          >>> tst = VTests.osv(name='numpy', version='1.13.1')

          numpy v1.13.1 has the following reported direct vulnerabilities, per OSV:

          Severity  Title                                   Alias
          --------  -----                                   -----
          HIGH      NumPy NULL Pointer Dereference          CVE-2021-41495
          MODERATE  NumPy Buffer Overflow (Disputed)        CVE-2021-33430
          CRITICAL  Numpy Deserialization of Untrusted Data CVE-2019-6446
          MODERATE  Buffer Copy without Checking Size of Input in NumPyCVE-2021-41496
          MODERATE  Incorrect Comparison in NumPy           CVE-2021-34141
          HIGH      Numpy missing input validation          CVE-2017-12852
          HIGH      Numpy missing input validation          CVE-2017-12852
          HIGH      Numpy missing input validation          CVE-2017-12852
          HIGH      Numpy missing input validation          CVE-2017-12852
          HIGH      Numpy missing input validation          CVE-2017-12852

          # Check the result of the test.
          >>> tst
          (False, 1, 6, 3, 0)

    Returns:

      A tuple containing the verification flag, and supporting data.

      True if there are no reported ‘Critical’ or ‘High’ vulnerabilities, otherwise False. The trailing elements are the number of vulnerabilities found in each category, of descending severity (i.e. C, H, M, L).

      If the `verbose` flag is `True`, the known vulnerabilities are reported to the terminal on test completion.

    Return type:

      tuple

  static snyk(name: str, version: str, verbose: bool = True, **kwargs) → tuple

    Use Snyk.io to test for reported vulnerabilities.

    If a package has reported direct vulnerabilities, these are captured and reported to the terminal at the end of processing.

    A package is considered ‘passing’ if no ‘Critical’ and ‘High’ vulnerabilities have been reported.

    Parameters:

      - name (str) – Package name.

      - version (str) – Package version to be tested.

      - verbose (bool, optional) – Print all reported vulnerabilities to the terminal on test completion. Defaults to True.

    Keyword Arguments:

      None

    Examples:

      Check the Snyk vulnerability database for any reported vulnerabilities:

          >>> from ppklib.vtests import VTests

          >>> tst = VTests.snyk(name='utils4',
                                version='1.5.0',
                                verbose=False)

          utils4 v1.5.0 has no reported direct vulnerabilities.

          # Check the result of the test.
          >>> tst
          (True, 0, 0, 0, 0)

      Check the Snyk vulnerability database for any reported vulnerabilities, for a library with vulnerabilities:

          >>> from ppklib.vtests import VTests

          >>> tst = VTests.snyk(name='numpy',
                                version='1.13.1',
                                verbose=True)

          numpy v1.13.1 has the following reported direct vulnerabilities:

          Severity  Title                                   Versions
          --------  -----                                   --------
          L         Buffer Overflow                         [,1.21.0rc1)
          L         Denial of Service (DoS)                 [,1.22.0rc1)
          H         Denial of Service (DoS)                 [,1.13.3)
          L         NULL Pointer Dereference                [0,1.22.2)
          C         Arbitrary Code Execution                [0,1.16.3)
          L         Buffer Overflow                         [,1.22.0)

          # Check the result of the test.
          >>> tst
          (False, 1, 1, 0, 4)

    Returns:

      A tuple containing the verification flag, and supporting data.

      True if there are no reported ‘Critical’ or ‘High’ vulnerabilities, otherwise False. The trailing elements are the number of vulnerabilities found in each category, of descending severity (i.e. C, H, M, L).

      If the `verbose` flag is `True`, the known vulnerabilities are reported to the terminal on test completion.

    Return type:

      tuple