Feature/platform mapper (#489)

* Creating a Platform Mapping utility for breaking down platforms into their bits --------- Co-authored-by: Brandon Minnix <bminnix@Brandons-MacBook-Pro.local> Co-authored-by: Brandon Minnix <brandon.minnix@networktocode.com> Co-authored-by: Przemek Rogala <progala@progala.net> Co-authored-by: Ken Celenza <ken@celenza.org> Co-authored-by: Brandon Minnix <bminnix@Brandons-MacBook-Pro-2.local>
networktocode · May 15, 2024 · 373e5cc · 373e5cc
1 parent 3b1004e
commit 373e5cc
Show file tree

Hide file tree

Showing 16 changed files with 768 additions and 1 deletion.
diff --git a/development_scripts.py b/development_scripts.py
@@ -131,6 +131,18 @@
             "_dict": lib_mapper.NETUTILSPARSER_LIB_MAPPER_REVERSE,
             "_file": "docs/user/lib_mapper/netutilsparser_reverse.md",
         },
+        "nist": {
+            "header_src": "NIST",
+            "header_dst": "NORMALIZED",
+            "_dict": lib_mapper.NIST_LIB_MAPPER,
+            "_file": "docs/user/lib_mapper/nist.md",
+        },
+        "nist_reverse": {
+            "header_src": "NORMALIZED",
+            "header_dst": "NIST",
+            "_dict": lib_mapper.NIST_LIB_MAPPER_REVERSE,
+            "_file": "docs/user/lib_mapper/nist_reverse.md",
+        },
         "ntctemplates": {
             "header_src": "NTCTEMPLATES",
             "header_dst": "NORMALIZED",

diff --git a/docs/dev/code_reference/nist.md b/docs/dev/code_reference/nist.md
@@ -0,0 +1,5 @@
+# NIST URLs
+
+::: netutils.nist
+    options:
+        show_submodules: True
diff --git a/docs/user/include_jinja_list.md b/docs/user/include_jinja_list.md
@@ -60,9 +60,12 @@
 | mac_to_format | netutils.mac.mac_to_format |
 | mac_to_int | netutils.mac.mac_to_int |
 | mac_type | netutils.mac.mac_type |
+| get_nist_urls | netutils.nist.get_nist_urls |
+| get_nist_vendor_platform_urls | netutils.nist.get_nist_vendor_platform_urls |
 | compare_version_loose | netutils.os_version.compare_version_loose |
 | compare_version_strict | netutils.os_version.compare_version_strict |
 | get_upgrade_path | netutils.os_version.get_upgrade_path |
+| version_metadata | netutils.os_version.version_metadata |
 | compare_cisco_type5 | netutils.password.compare_cisco_type5 |
 | compare_cisco_type7 | netutils.password.compare_cisco_type7 |
 | compare_cisco_type9 | netutils.password.compare_cisco_type9 |

diff --git a/docs/user/lib_mapper/nist.md b/docs/user/lib_mapper/nist.md
@@ -0,0 +1,9 @@
+| NIST | | NORMALIZED |
+| ---------- | -- | ------ |
+| adaptive_security_appliance_software | → | cisco_asa |
+| eos | → | arista_eos |
+| ios | → | cisco_ios |
+| ios_xe | → | cisco_xe |
+| ios_xr | → | cisco_xr |
+| junos | → | juniper_junos |
+| nx-os | → | cisco_nxos |
diff --git a/docs/user/lib_mapper/nist_reverse.md b/docs/user/lib_mapper/nist_reverse.md
@@ -0,0 +1,9 @@
+| NORMALIZED | | NIST |
+| ---------- | -- | ------ |
+| arista_eos | → | eos |
+| cisco_asa | → | adaptive_security_appliance_software |
+| cisco_ios | → | ios |
+| cisco_nxos | → | nx-os |
+| cisco_xe | → | ios_xe |
+| cisco_xr | → | ios_xr |
+| juniper_junos | → | junos |
diff --git a/docs/user/lib_use_cases.md b/docs/user/lib_use_cases.md
@@ -21,6 +21,7 @@ Functions are grouped with like functions, such as IP or MAC address based funct
 - Library Helpers - Provides helpers to pull useful information, e.g. NAPALM getters.
 - Library Mapper - Provides mappings in expected vendor names between Netmiko, NAPALM, pyntc, ntc-templates, pyats, and scrapli.
 - MAC Address - Provides the ability to work with MAC addresses such as validating or converting to integer.
+- NIST - Provides the ability to obtain a URL formatted for NIST CPE Query.
 - OS Version - Provides the ability to work with OS version, such as defining an upgrade path.
 - Password - Provides the ability to compare and encrypt common password schemas such as type5 and type7 Cisco passwords.
 - Ping - Provides the ability to ping, currently only tcp ping.

diff --git a/docs/user/lib_use_cases_nist.md b/docs/user/lib_use_cases_nist.md
@@ -0,0 +1,42 @@
+# NIST
+
+The NIST utility is used for functionality based around NIST DB Queries, and is primarily used to create URLs for the API based queries.
+
+## Requirements
+
+In order to use the URLs generated by `netutils.nist.get_nist_urls*`, you will need an api key provided by NIST [here]('https://nvd.nist.gov/developers/request-an-api-key').  This key will need to be passed in as an additional header in your request in the form of `{"apiKey": "<key_value>"}` as stated by NIST in their [Getting Started]('https://nvd.nist.gov/developers/start-here') section.
+
+
+## Custom URLs
+
+The largest caveat in this functionality is the consistency of the URL values needed to obtain the CVE information.  NIST NVD has specific parameters that can be used for standardization, however this does not mean that entries are standardized.  Manually combing through a large amount of CPE Vendor submissions has shown that there are variations in how CPE Vendor data is presented.
+
+For this reason, for certain Vendor/OS combinations, a custom URL needs to be built.
+- **Cisco IOS CPE String** - `cpe:2.3:o:cisco:ios:15.5\\(2\\)s1c:*`
+    - `15.5\\(2\\)s1c:*` - As seen here, Cisco uses CPE strings that do not include the `:` delimiter, which can be queried using escape characters in the search string.  **This is the format of ALL "generic" OS/Other platforms that do not have their own custom NIST URL builder when querying NIST.**
+    - Default URL Output - `'https://services.nvd.nist.gov/rest/json/cves/2.0?virtualMatchString=cpe:2.3:o:cisco:ios:15.5\\(2\\)s1c:*'`
+
+- **Juniper JunOS CPE String** - `cpe:2.3:o:juniper:junos:10.2:r2:*:*:*:*:*:*` 
+    - `10.2:r2:*:*:*:*:*:*` - As noted here, one of the provided URLs to query for this Juniper JunOS OS platform includes additional values that follow NIST delimiter structures.  In the case where the parser provides multiple URLs, they will both be evaluated and the CVE from both will be added and associated.
+    - Custom URL Output - `['https://services.nvd.nist.gov/rest/json/cves/2.0?virtualMatchString=cpe:2.3:o:juniper:junos:10.2r2:*:*:*:*:*:*:*', 'https://services.nvd.nist.gov/rest/json/cves/2.0?virtualMatchString=cpe:2.3:o:juniper:junos:10.2:r2:*:*:*:*:*:*']`
+
+
+## Examples
+Here are a few examples showing how to use this in your python code.
+
+```python
+
+from netutils.nist import get_nist_urls
+
+# Get NIST URL for the Cisco IOS object
+get_nist_urls("cisco_ios", "15.5(2)S1c")
+# ['https://services.nvd.nist.gov/rest/json/cves/2.0?virtualMatchString=cpe:2.3:o:cisco:ios:15.5\\(2\\)s1c:*']
+
+# Get NIST URL(s) for the Juniper JunOS object
+get_nist_urls("juniper_junos", "10.2R2.11")
+# ['https://services.nvd.nist.gov/rest/json/cves/2.0?virtualMatchString=cpe:2.3:o:juniper:junos:10.2r2:*:*:*:*:*:*:*', 'https://services.nvd.nist.gov/rest/json/cves/2.0?virtualMatchString=cpe:2.3:o:juniper:junos:10.2:r2:*:*:*:*:*:*']
+```
+
+Currently known OS/Other Platform types that require a custom NIST URL:
+
+- Juniper JunOS
diff --git a/docs/user/lib_use_cases_os_version.md b/docs/user/lib_use_cases_os_version.md
@@ -0,0 +1,41 @@
+# OS Version Tools
+
+The OS Version Tools are used for working with versioning systems.
+
+## Version Parsing/Deconstruction
+Version parsing takes the software version given as a string, and deconstructs that value into the standards of the vendor.  The version parsing takes place in the `netutils.os_version` module.  This is necessary when specific values or flags from a software version are required to make a logical decision.  
+
+Current Version Parsers:
+
+- Default Parser
+- Juniper JunOS
+
+**See the following Default and Juniper JunOS parsed versions:**
+
+```python
+>>> from netutils.os_version import version_metadata
+
+>>> version_metadata("Cisco", "IOS", "15.5")
+{
+    "major": "15",
+    "minor": "5",
+    "vendor_metadata": False,
+}
+>>> version_metadata("juniper", "junos", "12.4R")
+{
+    "isservice": False,
+    "ismaintenance": False,
+    "isfrs": True,
+    "isspecial": False,
+    "service": None,
+    "service_build": None,
+    "service_respin": None,
+    "main": "12",
+    "minor": "4",
+    "type": "R",
+    "build": None,
+    "major": "12",
+    "patch": None,
+    "vendor_metadata": True,
+}
+```
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -149,6 +149,7 @@ nav:
           - Library Helpers: "dev/code_reference/lib_helpers.md"
           - Library Mapping: "dev/code_reference/lib_mapping.md"
           - Mac Address: "dev/code_reference/mac.md"
+          - NIST: "dev/code_reference/nist.md"
           - OS Version: "dev/code_reference/os_version.md"
           - Password: "dev/code_reference/password.md"
           - Ping: "dev/code_reference/ping.md"

diff --git a/netutils/lib_mapper.py b/netutils/lib_mapper.py
@@ -407,6 +407,17 @@
     "SRX": "juniper_junos",  # no reverse
 }
 
+# NIST | Normalized
+NIST_LIB_MAPPER = {
+    "adaptive_security_appliance_software": "cisco_asa",
+    "nx-os": "cisco_nxos",
+    "ios_xr": "cisco_xr",
+    "ios_xe": "cisco_xe",
+    "eos": "arista_eos",
+    "ios": "cisco_ios",
+    "junos": "juniper_junos",
+}
+
 # Normalized | NAPALM
 NAPALM_LIB_MAPPER_REVERSE: t.Dict[str, str] = {
     "arista_eos": "eos",
@@ -557,6 +568,18 @@
     "paloalto_panos": "PAN_OS",
 }
 
+# Normalized | NIST
+NIST_LIB_MAPPER_REVERSE = {
+    "cisco_asa": "adaptive_security_appliance_software",
+    "cisco_nxos": "nx-os",
+    "cisco_xr": "ios_xr",
+    "cisco_xe": "ios_xe",
+    "arista_eos": "eos",
+    "cisco_ios": "ios",
+    "juniper_junos": "junos",
+}
+
+
 # Deep copy the reverse, where there is no actual translation happening with special
 # consideration for OS's not in netmiko.
 _MAIN_LIB_MAPPER = copy.deepcopy(NETMIKO_LIB_MAPPER)