About security vulnerability importers
This topic describes the conversion mechanism used by a security vulnerability importer, canned importers, and a sample stylesheet that you can use as a template.
Conversion mechanisms
A security vulnerability importer converts a vendor's source file into the internal XML format, then parses that format to populate a security vulnerability into the security vulnerability database. An importer can convert a vendor's source file in one of the following ways:
- Conversion using a stylesheet: If the vendor provides an XML or JSON file, you can develop a stylesheet using the XSLT version 2.0 syntax that parses the XML or JSON file into the internal format that is supported by . If vendor provides a JSON file, first converts it into XML and then converts that XML into internal XML format.
- Conversion using an executable script or program: If the vendor provides any other type of file that can be parsed, you can develop a script or program and place it in the BCAN_DATA\endorsed directory. This script or program converts the source file into the internal format. The script or program must accept one argument that specifies the name of the source file, and must print the converted results to its standard output (stdout). The program or script must exit with a return code of 0 to indicate success, and any other value to indicate failure.
- No conversion: Manually-generated file that is already in the internal format and does not need conversion.
Importers contained in TrueSight Network Automation
contains the following canned importers:
Import Advisories From NVD APIv2 JSON File: Supports the import of security advisories for the following device types from the National Vulnerability Database (NVD) repository. This importer uses a stylesheet that detects references to the supported devices in NVD's APIv2 JSON files.
- Aruba
- Cisco (Applicable for versions 20.02.01 and later)
- Juniper
- Extreme Networks
- Hewlett Packard Enterprise (HPE) Aruba
- Palo Alto
- (Not applicable for versions 23.2 and later)
- no longer supports the Import Advisories From NVD JSON File importer. Also, the NVD JSON files are no longer shipped with the product. If you upgrade to version 23.2 or later from a version that supports this importer, a backup copy is created for this importer.
no longer supports the Import Advisories From NVD XML File importer. Also, the NVD XML files are no longer shipped with the product. If you upgrade to version 23.2 or later from a version that supports this importer, a backup copy is created for this importer.
- (Not applicable for versions 20.02.01 and later) no longer supports the Cisco Advisory From CVRF XML File importer. The Cisco CVRF files are not shipped with the product. If you upgrade to version 20.02.01 or later from a version that supports this importer, a backup copy is created for this importer.
You might want to use stylesheets of these importers as examples to develop your own stylesheets. When you upgrade , these stylesheets are replaced by the canned version. If you have customized any of the stylesheets, it will be saved in a backup version of the importer. You can delete the backup importer if not needed.
TrueSight Network Automation internal XML format
The internal format defines an XML structure that captures all the attributes of a security vulnerability supported by . The exact format is defined in the SecurityVulnerability.xsd file, which is included in the BCAN_HOME\public\bmc\bca-networks\xml directory.
The following is an example of the internal format that includes all the available elements. You can use this format as a template.
<securityVulnerability>
<!-- id and title are required -->
<id> unique ID string within the vendor (required) </id>
<title> a descriptive title (required) </title>
<vendor> vendor GUID (required) </vendor>
<!-- the rest is optional -->
<status> string describing state of this report </status>
<!-- date/time this report was initially released; must match one of these formats:
yyyy-MM-dd'T'HH:mm:ss
yyyy-MM-dd'T'HH:mm:ssX
yyyy-MM-dd'T'HH:mm:ss.SSS
yyyy-MM-dd'T'HH:mm:ss.SSSX
yyyy-MM-dd'T'HH:mm'Z'
(per java SimpleDateFormat syntax) -->
<initialRelease> 2014-05-21T16:00:00.000+00:00 </initialRelease>
<!-- dotted set of numbers; used when re-importing to detect a newer
version of an existing vulnerability in-case of Cisco CVRF's xml -->
<version> 1.0 </version>
<!-- date/time this when the report is last updated; must match same formats as
initialRelease. used when re-importing to detect a newer version of an
existing vulnerability in-case of NVD xml -->
<lastModified> 2017-07-26T16:15:23 </lastModified>
<!-- URLs to vendor's full report, since what is imported is a summary -->
<notificationUrl primary="true"> http://URL1 </notificationUrl>
<notificationUrl> http://URL2 </notificationUrl><!-- can have multiple notificationUrl tags -->
<!-- identifier(s) into Mitre's CVE database -->
<cveId> CVE-2013-5503 </cveId>
<cveId> CVE-2013-5504 </cveId> <!-- can have multiple cveId tags -->
<!-- severity, ranges from 0.0 to 10.0 -->
<baseScore> 7.0 </baseScore>
<!-- product(s) that are vulnerable to the security threat, one per
operating system version -->
<product>
<affectedProductName> descriptive name of the product </affectedProductName>
<affectedOsVersion> vulnerable version that can be mapped to a TSNA version string </affectedOsVersion>
<!-- The range of operating system versions that are at risk. -->
<affectedOsVersionRange>
<affectedOsName> Name of the operating system for which this range is applicable </affectedOsName>
<!-- Minimum OS version for the operating system range. When exclusive set to true, the range is exclusive of the minimum OS version. -->
<start exclusive="true"> </start>
<!-- Minimum OS version for the operating system range. When exclusive set to true, the range is exclusive of the maximum OS version. -->
<end exclusive="false"> </end>
<affectedOsVersionRange>
<deviceType> Cisco IOS Switch/Router </deviceType>
<!-- name or GUID -->
</product>
<product>
<affectedProductName> descriptive name of the product </affectedProductName>
<unenforceableVersion> some version that cannot be mapped to a TSNA version string </unenforceableVersion>
</product>
<description> detailed description of the issue </description>
<description> ...can have multiple descriptions </description>
<remediation> instructions for working around or correcting the issue </remediation>
<remediation> ...can have multiple remediaions </remediation>
</securityVulnerability>
</securityVulnerabilities>
This templates includes the following elements:
XML Element | Description |
|---|---|
<id> | (Required) This element must appear only once. It contains the unique identifier or name of the security vulnerability, advisory, bulletin, or issue using the naming conventions that are defined by the vendor. Its value must be unique within a vendor. It is used to locate an existing security vulnerability when updating. |
<title> | (Required) This element must appear at least once. It contains text that summarizes the nature of the security vulnerability. |
<vendor> | (Required) This element must appear only once. It contains the GUID of the vendor from which the security vulnerabilities are originated that this importer can process. |
<status> | (Optional) This element can appear only once. It contains text that describes the current state of the security vulnerability. |
<initialRelease> | (Optional) This element can appear only once. It contains the date/time the security vulnerability was first published. It must match the following format (as per Java SimpleDateFormat syntax): The timezone is optional. If it is missing, timezone +00:00 (UTC or GMT) is assumed. |
<version> | (Optional) This element can appear only once. It contains the latest version of the security vulnerability, usually a dotted numerical version string (for example, 1.2.3). It is used to determine if an existing security vulnerability is older than the one being imported. Only newer versions are imported successfully. |
<lastModified> | (Optional) This element can appear only once. It contains the date/time the security vulnerability was modified last by the vulnerability reporting source. It is used when re-importing a vulnerability to detect a newer version of an existing vulnerability in case of NVD XML. The date/time must match a recognized format, as defined for the <initialRelease> element above. |
<notificationUrl> | (Optional) This element can appear more than once. It contains the links to the vendor's pages, which contain complete details about the security vulnerability. At least one notificationURL should have the primary="true" attribute. The URL which has this attribute set to true appears in the reports. |
<cveId> | (Optional) This element can appear any number of times. It contains the Common Vulnerabilities and Exposures (CVE) identifiers from the central CVE database. |
<baseScore> | (Optional) This element can appear any number of times. It contains the numerical severity of the security vulnerability, ranging from 0.0 to 10.0. The highest value is used when this element appears more than once. |
<product> | (Optional) This element can appear any number of times. It contains information about one product affected by the security vulnerability. |
<affectedProductName> | (Optional) This element can appear only once. It contains text that describes one particular product, model, or operating system affected by the security vulnerability. |
<affectedOsVersion> | (Optional) This element can appear only once. It contains text specifying one particular operating system version that is at risk. The OS version should be expressed by using the same syntax as the OS versions discovered by for devices of the affected type, or as close as possible. Once OS Image Name Conversions defined in the importer are applied, OS version should look like a version string that you would see associated with a device. Use Admin > Network Admin > OS Images to review your image library and closely observe the image names and their formats. Be aware of delimiters (such as dots, commas, parentheses, dashes, and spaces) that the security vulnerability report might not include or might format differently. |
<affectedOsVersionRange> | (Optional) This element can appear any number of times. It contains information about the range of operating system versions that are at risk. |
<affectedOsName> | (Required) This element must appear at least once. It contains the text specifying the name of the operating system for which this range is applicable. |
<start> | (Optional) This element can appear only once. It contains the text specifying minimum OS version for the operating system range. This element must have the exclusive attribute. When set to true, the range is exclusive of the minimum OS version. The OS version range start should be expressed by using the same syntax as the OS versions discovered by for devices of the affected type, or as close as possible. Once OS Image Name Conversions defined in the importer are applied, OS version should look like a version string that you would see associated with a device. Use Admin > Network Admin > OS Images to review your image library and closely observe the image names and their formats. Be aware of delimiters (such as dots, commas, parentheses, dashes, and spaces) that the security vulnerability report might not include or might format differently. |
<end> | (Optional) This element can appear only once. It contains the text specifying maximum OS version for the operating system range. This element must have the exclusive attribute. When set to true, the range is exclusive of the maximum OS version. The OS version range start should be expressed by using the same syntax as the OS versions discovered by for devices of the affected type, or as close as possible. Once OS Image Name Conversions defined in the importer are applied, OS version should look like a version string that you would see associated with a device. Use Admin > Network Admin > OS Images to review your image library and closely observe the image names and their formats. Be aware of delimiters (such as dots, commas, parentheses, dashes, and spaces) that the security vulnerability report might not include or might format differently. |
<deviceType> | (Optional) This element can appear only once. It contains the GUID of the device type associated with the devices that are running the affected OS version. This element is used when generating a rule to make the rule applicable to the device type, when a vulnerability refers to only one device type. If there are several different device types or no device types, the generated rule is applicable to all device types. If this element refers to a disabled device type or the value does not map to a known device type, it is ignored. |
<unenforceableVersion> | (Optional) This element can appear only once. It contains text specifying an operating system that lacks any version that can be matched to a specific device OS version string. This might be a very broad version or a generalized description of an operating system (for example, "all 6509 models"). This text is displayed when viewing this vulnerability (because it might still apply to your network), but cannot be converted into a pattern appropriate for use in a rule, thus making it unenforceable. |
<description> | (Optional) This element can appear any number of times. It contains text that describes details about the nature of the security vulnerability, its impact, and so on. |
<remediation> | (Optional) This element can appear any number of times. It contains text that describes what steps might be taken to mitigate, correct, or avoid the security vulnerability. |
Where to go from here