0.7.0

vehemont · Oct 31, 2022 · cf8ee4e · cf8ee4e
1 parent 8256570
commit cf8ee4e
Show file tree

Hide file tree

Showing 26 changed files with 1,163 additions and 505 deletions.
diff --git a/HISTORY.md b/HISTORY.md
@@ -1,13 +1,23 @@
 Release History
 ===============
 
+0.7.0 (2022-10-31)
+-------------------
+
+- Overhauled NVDLib to utilize the new version of the NVD API (version 2).
+- `nvdlib.getCVE()` no longer exists and is now combined into `nvdlib.searchCVE()` using the `cvdId` parameter.
+- `nvdlib.searchCPE()` no longer has the `cves` parameter to pass CVEs. 
+- New parameters for `nvdlib.searchCVE()`
+- For a full list of changes, see the https://nvdlib.com/docs/build/html/v1/changesv1.html
+
+Happy Halloween! 🎃
+
 0.6.1 (2022-10-18)
 -------------------
 **Bugfixes**
 
 - Updated `cve.py` to utilize the correct parameter to allow sorting by exact match. The parameter is `isExactMatch` with a value of `True`. The argument used in `searchCVE` is still `exactMatch` with a value of `True`, NVDLib will now use the correct parameter when building the search query.
 
-
 0.6.0 (2022-09-15)
 -------------------
 **Bugfixes**

diff --git a/README.md b/README.md
@@ -27,14 +27,14 @@ $ pip install nvdlib
 ### Demo
 ```python
 >>> import nvdlib
->>> r = nvdlib.getCVE('CVE-2021-26855')
->>> print(r.v3severity + ' - ' + str(r.v3score))
-   CRITICAL - 9.8
->>> print(r.cve.description.description_data[0].value)
-   Microsoft Exchange Server Remote Code Execution Vulnerability This CVE ID is unique from CVE-2021-26412, 
-   CVE-2021-26854, CVE-2021-26857, CVE-2021-26858, CVE-2021-27065, CVE-2021-27078.
->>> print(r.v3vector)
-   CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H 
+>>> r = nvdlib.searchCVE(cveId='CVE-2021-26855')[0]
+>>> print(r.v31severity + ' - ' + str(r.v31score))
+CRITICAL - 9.8
+>>> print(r.descriptions[0].value)
+Microsoft Exchange Server Remote Code Execution Vulnerability This CVE ID is unique from CVE-2021-26412, 
+CVE-2021-26854, CVE-2021-26857, CVE-2021-26858, CVE-2021-27065, CVE-2021-27078.
+>>> print(r.v31vector)
+CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H 
 ```
 
 
@@ -51,8 +51,6 @@ $ pytest
 
 https://nvdlib.com
 
-
-
 #### More information
 
 This is my first attempt at creating a library while utilizing all my Python experience from classes to functions.

diff --git a/docs/images/logo.png b/docs/images/logo.png
diff --git a/docs/images/logo_small.png b/docs/images/logo_small.png
diff --git a/docs/source/_static/logo_small.png b/docs/source/_static/logo_small.png
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -18,11 +18,11 @@
 # -- Project information -----------------------------------------------------
 
 project = 'NVDLib'
-copyright = '2021'
+copyright = '2022'
 author = 'Vehemont'
 
 # The full version, including alpha/beta/rc tags
-release = '0.6.1'
+release = '0.7.0'
 
 
 # -- General configuration ---------------------------------------------------
@@ -50,11 +50,14 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'renku'
+html_theme = 'insegel'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+#html_static_path = ['_static']
 
-html_baseurl = 'nvdlib.com'
+html_baseurl = 'nvdlib.com'
+
+master_doc = "index"
+html_logo = "_static/logo_small.png"
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,5 +1,5 @@
 NVDLib: NIST National Vulnerability Database API Wrapper
-===================================
+########################################################
 
 .. image:: https://img.shields.io/github/license/bradleeriley/nvdlib
    :target: https://pypi.org/project/nvdlib/
@@ -18,60 +18,79 @@ NVDLib: NIST National Vulnerability Database API Wrapper
 Demo::
 
    >>> import nvdlib
-   >>> r = nvdlib.getCVE('CVE-2021-26855')
-   >>> print(r.v3severity + ' - ' + str(r.v3score))
+   >>> r = nvdlib.searchCVE(cveId='CVE-2021-26855')[0]
+   >>> print(r.v31severity + ' - ' + str(r.v31score))
    CRITICAL - 9.8
-   >>> print(r.cve.description.description_data[0].value)
+   >>> print(r.descriptions[0].value)
    Microsoft Exchange Server Remote Code Execution Vulnerability This CVE ID is unique from CVE-2021-26412, 
    CVE-2021-26854, CVE-2021-26857, CVE-2021-26858, CVE-2021-27065, CVE-2021-27078.
-   >>> print(r.v3vector)
+   >>> print(r.v31vector)
    CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H 
 
 **NVDLib** is able to pull all data on known CVEs, search the NVD for CVEs 
 or `Common Platform Enumeration (CPE) <https://nvd.nist.gov/products/cpe>`_ names.
 
 
 Features:
-----------------
+---------
 
 * Pull data on individual CVEs:
- * CVE ID, description, reference links, CWE.
- * CPE applicability statements and optional CPE names.
- * CVSS severity scores.
- * CVE publication date.
- * CVE modified date.
-
+   * CVE ID, description, reference links, CWE
+   * CPE applicability statements and optional CPE names
+   * CVSS severity scores or metrics
+   * CVE publication date
+   * CVE modified date
 * Search the NVD for CVEs by: 
- * Keywords
- * Publish or modification start/end dates
- * cweID
- * CVSS V2/V3, score, severity, or metrics.
- * CPE match string
- * CPE name.
-
+   * Keywords
+   * Publish or modification start/end dates
+   * cweID
+   * CVSS V2/V3, score, severity, or metrics.
+   * CPE match string/virtual match string
+   * CPE name
+   * US-CERT alerts, KEV Catalog or OVAL
+   * Source identifier
+   * Vulnerable status
 * Search the NVD for CPE names by:
- * Modification start/End dates 
- * Keywords 
- * CPE match string. 
- * Dump data into objects to be accessible easily as class attributes. 
+   * Modification start/End dates 
+   * Keywords 
+   * CPE match string. 
+   * Dump data into objects to be accessible easily as class attributes. 
 
 
 For more information on the NIST NVD API for CPE and CVEs, see the documentation here:
-https://nvd.nist.gov/General/News/New-NVD-CVE-CPE-API-and-SOAP-Retirement
-
-This product uses data from the NVD API but is not endorsed or certified by the NVD.
+https://nvd.nist.gov/developers
 
-.. note:: NVDLib version 0.5.3 now includes `NIST NVD rate limiting recommendations <https://nvd.nist.gov/developers>`_. Requests will now sleep for 6 seconds to 
-   complete with no API key. Requests with an API key will sleep 0.6 seconds. 
+.. note:: NVDLib allows use of an NVD API key to define the delay between requests. NVD recommends sleeping scripts for 6 seconds in between requests. 
+   If no API key is provided, NVDLib will sleep for 6 seconds in between requests by default.
+
    Get an API key here (free): https://nvd.nist.gov/developers/request-an-api-key
 
 Navigation:
-----------------
+-----------
+
+.. toctree::
+   :maxdepth: 2
+
+   v2/startedv2
+   v2/CVEv2
+   v2/CPEv2
 
+Version 1 API Documentation (<=0.6.1):
+--------------------------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   v1/changesv1
+   v1/v1
+
+Updates
+-------
 .. toctree::
    :maxdepth: 2
 
-   started
-   CVE
-   CPE
    release
+
+|
+
+This product uses data from the NVD API but is not endorsed or certified by the NVD.
diff --git a/docs/source/release.rst b/docs/source/release.rst
@@ -1,5 +1,5 @@
 Updates
-===========
+#######
 
 
 Get updates on `the GitHub repo <https://github.com/Vehemont/nvdlib>`_.
diff --git a/docs/source/v1/changesv1.rst b/docs/source/v1/changesv1.rst
@@ -0,0 +1,62 @@
+NVD API Version 2 changes
+#########################
+
+NVDLib version 0.7.0 and onward will be utilizing version 2 of the NVD API. All versions before 0.7.0 will utilize version 1.
+Version 1 of the API is planned to be decomissioned around `September 2023 <https://nvd.nist.gov/General/News/change-timeline>`_. There
+has been a lot of changes in version 2 of the API. This page will describe the changes seen within NVDLib, not neccesarily the new version of the API.
+
+.. note:: 
+    For a more in-depth look at what has changed in version 2 see the NVD page here: https://nvd.nist.gov/General/News/api-20-announcements
+
+
+nvdlib.getCVE
+-------------
+
+* No longer exists. It is now bundled into :func:`nvdlib.searchCVE` with the arguement *cveId*.
+* Keep in mind *searchCVE* will always return a list, so when using the argument *cveId* you must access the first element of the list.
+
+>>> r = nvdlib.searchCVE(cveId='CVE-2021-26855')
+>>> r[0].id
+'CVE-2021-26855'
+
+Or more conveniently:
+
+>>> r = nvdlib.searchCVE(cveId='CVE-2021-26855')[0]
+>>> r.id
+'CVE-2021-26855'
+
+|
+
+nvdlib.searchCVE
+----------------
+
+* Arguments now match exactly stated in `NVD API documentation <https://nvd.nist.gov/developers/vulnerabilities>`_, instead of a shorthand. 
+  For example, version 0.6.1 used the argument *keyword*, it is now *keywordSearch* in NVDLib 0.7.0. Changes include:
+    * modStartDate -> lastModStartDate
+    * modEndDate -> lastModEndDate
+    * keyword -> keywordSearch
+    * isExactMatch -> keywordExactMatch
+    * cpeMatchString -> virtualMatchString
+    * sortby -> No longer exists
+    * includeMatchStringChange -> No longer exists
+* Scores are now elaborated beyond 2 and 3 to include 3.1. \
+  This means the *score* attribute on CVEs will now prefer 3.1 CVSS scoring over 3.0 and 2.0. 
+
+>>> r[0].score
+['V31', 9.8, 'CRITICAL']
+
+* The CVE structure has changed, meaning information you were obtaining manually previously, may be in a new location. 
+  I recommend looking at the new CVE page to get an idea of what it looks like now.
+* New parameters! Check out :doc:`/v2/CVEv2`.
+
+|
+
+nvdlib.searchCPE
+----------------
+
+* *cves* parameter in :func:`nvdlib.searchCPE` no longer exists, as CPE searches cannot return CVEs anymore. 
+* The same parameter changes in *searchCVE* are applies to :func:`nvdlib.searchCPE`.
+* New parameters! Check out :doc:`/v2/CPEv2`.
+
+
+