This white paper explains design decisions behind the 1.1. Release of the Common Vulnerability Reporting Framework (CVRF); specifically, the use of required elements and the Product Tree. The white paper further demonstrates conversion of a recent Cisco security advisory into a well-formed and valid CVRF document. Enhancements that are planned for future versions of CVRF are also discussed. It is assumed that the reader has a working knowledge of CVRF and of XML.
After the release of CVRF 1.0 in May 2011, at a dinner with security professionals, security automation was briefly discussed. I scribbled a phrase that succinctly captured what CVRF did, does, and will do on a napkin: "...the goal of CVRF is to homogenize and automate the creation and consumption of vulnerability documentation." Simple, profound, and complete enough to be a mission statement. Figure 1 expands on the original statement and restates the keywords.
Figure 1. CVRF Mission Statement: Homogenizing and Automating Vulnerability Documents
The goal of CVRF was simple in concept yet complex in execution, taking three years to deliver from idea to standard. The work evolved, but always with the same goal in mind. Currently, CVRF is positioned to be the standard in vulnerability documentation automation. CVRF 1.0 was the initial foray into this space. Now, almost a year later, CVRF 1.1 is a major leap forward and represents the current best-of-breed solution. An exploration of core CVRF concepts follows.
A primary tool of development for CVRF is the mind map. Mind maps are wonderful tools for representing ideas and brainstorming in real-time. Three years of CVRF development is shown to in this white paper through a mind map diagram. The legend is shown in Table 1, and the CVRF mind map is shown in Figure 2.
Table 1. CVRF Mind Mapping Legend
Figure 2. CVRF Mind Mapping
One of the major design tenets of CVRF was objectivity over subjectivity. Computer security can be an emotional topic at times, but the framework that is used to convey information pertaining to that subject should be free from opinion and bias and report only facts. With this in mind, CVRF was grown in a lab. Each element was named and defined as objectively as possible so that all users, regardless of background, could understand CVRF the same way.
Another design decision made midway through the engineering process was for CVRF to adhere to a data-driven model. This is to say that CVRF is concerned only with packaging up and structuring the data, without regard for how that data will be presented to the end-user. There are no presentation markup elements (for example, HTML<b>|</b> or <i>|</i>) included in CVRF.
CVRF is a language. It is a structured way for one machine to communicate with another machine about a topic human operators find very interesting: information system vulnerabilities. CVRF was built using XML. XML is a meta-language – it doesn't actually do anything. CVRF, like XML, is a static framework used to structure, store, and transport information. CVRF is a structured container for information about information system vulnerabilities. How that information is ultimately transported, parsed, or used is completely up to its users.
Another design decision of CVRF revolved around the consensus that the document must contain a modicum of mandatory, root-level elements. Required elements ensure a solid and consistent foundation on which to construct documents. The required fields are shown in Figure 3.
Figure 3. Required Fields
Throughout CVRF, optional container elements that use a plural term as the identifier (for example, Threats) are followed by a child container that uses the singular version of the same identifier (for example, Threat). The parent container is usually optional (MinOccurs=0) and cannot occur more than once (MaxOccurs=1), while the child container is required (MinOccurs=1) and can have unlimited instances (MaxOccurs=unbounded).
As an example, the Threats container can contain multiple Threat containers. If no threats are to be documented, the Threats container should be omitted altogether. However, if a Threat container is defined, at least one (more are allowed) child Threat container must be specified, as shown in the following example:
<Threats> <Threat Type="Impact"> <Description> Successful exploit this vulnerability results in every byte on the target network being replaced by the ones’ compliment of itself. </Description> </Threat> <Threat Type="Exploit Status"> <Description> The exploit is being carried as part of the OKBDGLOBAL.A1 worm and is in widespread use. </Description> </Threat> <Threat Type="Target Set"> <Description> Every network known to man. </Description> </Threat> </Threats>
CVRF has several unrestricted string-type fields that are assumed to be human consumable. These fields allow a document producer to input arbitrary character data without constraints around length or content. The best common practice here is to ensure this character data is free from markup language tags (for example, XML, HTML, XHTML, or other markup). However, in some cases, a document producer may be forced to copy data into a CVRF document that contains markup. Often in a Notes or Entitlement element, unwanted markup is sometimes unavoidable. General guidance in this scenario follows.
The XML construct CDATA instructs the parser to ignore whatever text is being enclosed. To migrate an existing document as-is without worrying about encoding XML entities, either escape each special character or use CDATA. Note that if the parser is meant to be able to interpret the text within string sections, CDATA can make it difficult for document consumers to parse and transform CVRF documents.
An exception to this rule is when you want to include un-rendered markup elements inside a string element for illustrative purposes, as shown in the following example:
<Notes> <Note Type="Details" Ordinal="120" Title="Quick Fix" Audience="Technical"> If you change the Tomcat web.xml to the following, the problem will go away: <![CDATA[<parameter timeout="0" />]]> </Note> </Notes>
A CDATA example is below in the section "Converting an Existing Document to CVRF."
Many elements in a CVRF document allow (or require) the document producer to specify one or more Product ID or Group ID references, indicating that the current element applies to one or more products. In most cases, specifying a Product ID or Group ID is optional and as such, omitting the ID indicates that the current entry is general or non-specific. If an element applies to more than one product, the document producer can choose to list all corresponding Product ID values separately or define a group first and then reference the corresponding Group ID.
In the Vulnerability section, the following containers allow product referencing: Products/Product, Threats/Threat, CVSS Score Sets/Score Set, and Remediations/Remediation. Additionally, all of these containers follow the previously mentioned conventions for plural or singular container notation.
The Product Tree is a new construct for CVRF 1.1 and is a total redesign of the way CVRF enumerates products in a vulnerability. In earlier versions, several issues emerged in the way products were specified:
To solve these problems, Product Family and Affected elements were eliminated and replaced with a hierarchical Product Tree, as shown in Figure 4.
Figure 4. CVRF v.1.1 Product Tree
On a high level, the tree contains all of the fully qualified product names that can be referenced elsewhere in a CVRF document. The tree resolved inefficiency, confusion, and lack of enforcement issues.
Additionally, it affords the user a way to specify complex relationships between products or components (as a precondition for being vulnerable) using the Relationship container.
This section walks the user through a manual conversion of the Cisco RVS4000 and WRVS4400N Web Management Interface Vulnerabilities Security Advisory (//www.cisco.com/en/US/products/csa/cisco-sa-20110525-rvs4000.html) into a CVRF document. Note that this process is meant to be an instructive narrative of how to manually build a CVRF document. In a typical security content environment, this process would be automated and CVRF document producers would have in-house code to parse documents and emit CVRF.
Remember that an XML schema defines the structure and content of the elements inside an XML document, as well as the order they can be in. This means that we might have to hunt around the security advisory to find all of the elements we want or need, but we must conform to the order set out by the schema. Before starting this section, have a quick look at the security advisory and be comfortable with its format and sections.
Note: The following is only a tutorial. The entire security advisory is not translated into the CVRF document and the security advisory is neither a Cisco PSIRT-authored or Cisco PSIRT-endorsed document.
Begin with a standard XML prologue specifying the version, encoding, and the namespace for the schema as shown in the following example
<?xml version="1.0"encoding="UTF-8"?> <cvrfdoc xmlns="http://www.icasi.org/CVRF/schema/cvrf/1.1"
Choose a title for the CVRF document. This is a required, human-readable field, and can be copied from the security advisory title as shown in the following example
<DocumentTitle>Cisco Security Advisory: Cisco RVS4000 and WRVS4400N Web Management Interface Vulnerabilities</DocumentTitle>
Add the required field, Document Type, another human-readable field that is called Security Advisory, as shown in the following example
Add the required field, Document Publisher. All that is required is the type, which can be filled in as Vendor. Note that unlike the previous fields, there are only five different values (vendor, discoverer, coordinator, user, other) to choose from. The following example shows the Document Publisher field.
Add the monolithic and required Document Tracking container. Comments are inline.
The required Identification container holds one ID string and additional optional Alias strings that identify the CVRF document. The required ID element is set to the Cisco specific identifier for the SA, which is derived from the "Advisory ID" field of "cisco-sa-20110525-rvs4000" and is shown in the following example
<Identification> <ID>cisco-sa-20110525-rvs4000</ID> </Identification>
The required Status element is set from the Status of this Notice field in the security advisory, which is Final, as shown in the following example
The required Version element is set from the Revision field of the security advisory, which is "1.1." The Revision History is taken from the security advisory fields of the same name, as shown in the example that follows. All elements are required.
<Version>1.1</Version> <RevisionHistory> <Revision> <Number>1.1</Number> <Date>2011-06-17T00:00:00+00:00</Date> <Description> Modified software table to indicate that First Fixed release for RVS4000v1 is 18.104.22.168. </Description> </Revision> <Revision> <Number>1.0</Number> <Date>2011-05-25T00:00:00+00:00</Date> <Description>Initial public release.</Description> </Revision> </RevisionHistory>
The required Initial and Current Release Date elements are adapted from the security advisory fields Initial Public Release and Last Updated, as shown in the following example
<InitialReleaseDate>2011-05-25T00:00:00+00:00</InitialReleaseDate> <CurrentReleaseDate>2011-06-17T00:00:00+00:00</CurrentReleaseDate> </DocumentTracking>
The next container is Document Notes. This is where all freeform, human-readable text from the security advisory is stored and its use is completely optional. The first Note is created is to hold the security advisory Summary. The only required attributes are Type, which is Summary for the Note, Legal Disclaimer, and Ordinal, which is a locally significant counter used to track all of the Document Notes and that is set to "001" and "002". In the example that follows, the first Note is labeled Summary and the second is called Legal Disclaimer. Both texts include an Audience set to All. Both attributes are human-readable fields. Finally, the XML:lang attribute is included to indicate the language of both Notes, in this case, English. The use of the XML:lang attribute is completely optional when writing in English because it is the default language. Use the XML:lang attribute to specify to a different language. The following example shows this practice in use.
<DocumentNotes> <Note Title="Summary" Audience="All" Type="Summary" Ordinal="001" xml:lang="en"> Cisco RVS4000 4-port Gigabit Security Routers and Cisco WRVS4400N Wireless-N Gigabit Security Routers have several
Acknowledgements is an optional container, but because the security advisory credits the original discoverer, an acknowledgement is included here, as shown in the following example
<Acknowledgments> <Acknowledgment> <Name>Michal Sajdak</Name> <Organization>Securitum, Poland</Organization> </Acknowledgment> </Acknowledgments>
Another optional container is Document References. For posterity, a single Related Document that refers to the original HTML security advisory is included. The type of reference is self, because it refers to a different representation of the same document. The URL points to the HTML security advisory and the human-readable Description is trivial, as shown in the example that follows. Note that a CRLF is inserted to preserve readability in the whitepaper but should not be used in an actual CVRF document.
<DocumentReferences> <Reference Type="Self"> <URL>http://tools.cisco.com/security/center/content/CiscoSecurityAdvisory/cisco-sa-20110525-rvs4000</URL> <Description xml:lang="en">URL to the html advisory.</Description> </Reference> </DocumentReferences>
The Document Distribution comes next and is located in the security advisory under "Distribution." This is another human-readable field and the document producer may prefer to remove all non-character data. The following example shows the location of the Document Distribution field.
<DocumentDistribution> This advisory is posted on Cisco's worldwide website at
The Product Tree is built to contain all of the products that are referenced in the Vulnerability section of the CVRF document. In the security advisory, within the Affected Products section, there are five products affected by the vulnerability and in the Software Versions and Fixes section, there are three "first fixed" products (two of the affected versions are end-of-life and no longer supported).
In the following example, the Branched method of Product Tree creation is used to insert the products listed above. It affords the most machine-readable method of product enumeration (the Concatenated method does a similar job, but this security advisory contains no product dependencies).
The first element is the Product Tree container that specifies the schema, as shown in the following example
Each product is then constructed using the Branched method. Because all of the products are Cisco products, the top-level Branch container is Type Vendor and Name "Cisco". Both attributes are required, and are shown in the example that follows.
<Branch Type="Vendor" Name="Cisco">
This level of nesting actually splits. We first handle the "RVS4000" products and finish up with the "WRVS4400N" products. This is the Product Family and we assign Type and Name accordingly. The following example shows the split branch type with Type and Name assigned.
<Branch Type="Product Family" Name="RVS4000">
Next is the canonical name of the product. This Type is assigned as Product Name with a Name value of "Gigabit Security Router,"as shown in the following example
<Branch Type="Product Name" Name="Gigabit Security Router">
The last branch contains the product version. Assign this Type as Product Version with a Name value of "1". Terminate this branch with a Full Product Name and the first Product ID. The FullProductName contains the canonical or “friendly” name of the referenced product. In this (and probably most) cases, it is the additive result of the individual branches, or “Cisco RVS4000 Gigabit Security Router version 1”. The ProductID is chosen to be illustrative and demonstrative at “CVRF1.1-PID-0001”. In practice, it can be anything unique to Product Tree. The following example illustrates the product version branch.
<Branch Type="Product Version" Name="1"> <FullProductName ProductID="CVRF1.1-PID-0001">Cisco RVS4000 Gigabit Security Router version 1</FullProductName> </Branch>
Construct the remainder of the Product Tree elements in the same manner, as shown in the following example
<Branch Type="Product Version" Name="2"> <FullProductName ProductID="CVRF1.1-PID-0002">Cisco RVS4000 Gigabit Security Router version 2</FullProductName> </Branch> <Branch Type="Product Version" Name="22.214.171.124"> <FullProductName ProductID="CVRF1.1-PID-0006">Cisco RVS4000 Gigabit Security Router version 126.96.36.199</FullProductName> </Branch> <Branch Type="Product Version" Name="188.8.131.52"> <FullProductName ProductID="CVRF1.1-PID-0007">Cisco RVS4000 Gigabit Security Router version 184.108.40.206</FullProductName> </Branch> </Branch> </Branch> <Branch Type="Product Family" Name="WRVS4400N"> <Branch Type="Product Name" Name="Wireless-N Gigabit Security Router"> <Branch Type="Product Version" Name="1.0”> <FullProductName ProductID="CVRF1.1-PID-0003">Cisco WRVS4400N Wireless-N Gigabit Security Router version 1.0</FullProductName> </Branch> <Branch Type="Product Version" Name="1.1"> <FullProductName ProductID="CVRF1.1-PID-0004">Cisco WRVS4400N Wireless-N Gigabit Security Router version 1.1 </FullProductName> </Branch> <Branch Type="Product Version" Name="2.0"> <FullProductName ProductID="CVRF1.1-PID-0005">Cisco WRVS4400N Wireless-N Gigabit Security Router version 2.0</FullProductName> </Branch> <Branch Type="Product Version" Name="220.127.116.11"> <FullProductName ProductID="CVRF1.1-PID-0008">Cisco WRVS4400N Wireless-N Gigabit Security Router version 18.104.22.168</FullProductName> </Branch> </Branch> </Branch> </Branch> </ProductTree>
The final section contains the actual vulnerabilities documented in the security advisory. The Details section of the security advisory notes that there are three vulnerabilities in the security advisory.
Each vulnerability is documented in its own Vulnerability container.
<Vulnerability Ordinal="1" xmlns="http://www.icasi.org/CVRF/schema/vuln/1.1">
2) The human readable Title follows and may be copied as the canonical name from the security advisory, as shown in the following example
<Title>Retrieval of the configuration file</Title>
3) The Notes container follows the Title, and structurally, it is the same as the Document Notes container above. In this case, it contains details about the vulnerability and is typed and titled as such. The first usage of CDATA may be observed here, because there is an ampersand (&) in the original text which, from an XML point of view, tells the parser an escape sequence is forthcoming. The following example shows the Notes container
<Notes> <Note Type="Details" Ordinal="003" Title="Details" Audience="All"> <![CDATA[ The Cisco RVS4000 and WRVS4400N Gigabit Security Routers deliver high-speed network access
4) The release date of the vulnerability is set as the initial release date of the advisory, as shown in the following example
5) The Involvements container houses information about the document producer’s engagement status of vulnerability. In this case, the Party is Cisco (the vendor of the product) and the involvement Status is considered Completed (that is, the vulnerability is fully identified and scoped and the remediation process is finished). The following example shows an SA in Completed status.
<Involvements> <Involvement Party="Vendor" Status="Completed"> <Description>Cisco has completed involvement in this vulnerability.</Description> </Involvement> </Involvements>
6) The CVE number for the vulnerability is found in the Details section of the security advisory, as shown in the following example
7) The Product Statuses enumerates the products that are directly concerned with vulnerability. The guidance here is to list the affected products followed by the fixed or recommended products, as shown in the following example
8) Threat types are found in the Threats container. The Impact section of the security advisory contains a description that relates to the Impact-typed Threat container. The omission of any Product or Group IDs means this threat applies to all of the vulnerable products. The following example shows Threat types.
<Threats> <Threat Type="Impact"> <Description>
9) The CVSS Score Sets can be found in the “Vulnerability Scoring Details” section. A Score Set will always have a Base Score, but the Temporal and Environmental scores, as well as the Vector, are optional. The example that follows shows a temporal score and a Vector.
<CVSSScoreSets> <ScoreSet> <BaseScore>9.3</BaseScore> <TemporalScore>7.7</TemporalScore> <Vector>AV:N/AC:M/Au:N/C:C/I:C/A:C/E:F/RL:OF/RC:C/CDP:ND/TD:ND/CR:ND/IR:ND/AR:ND</Vector> </ScoreSet> </CVSSScoreSets>
10) The final section for Vulnerability is the Remediation container and is shown in the following example
11) The remaining two vulnerabilities are quite similar to the first in terms of construction and content, and to close out the CVRF document, they are left to the reader to complete. The following example shows the remaining two vulnerabilities.
<Vulnerability Ordinal=”2” xmlns="http://www.icasi.org/CVRF/schema/vuln/1.1"> <Title>Root operating system arbitrary command injection by an authenticated attacker</Title> ... </Vulnerability> <Vulnerability Ordinal=”3” xmlns="http://www.icasi.org/CVRF/schema/vuln/1.1"> <Title>Retrieval of admin SSL certificate private key</Title> ... </Vulnerability> </cvrfdoc>
As CVRF evolves, the standard will change and grow according to the feedback from its users. The following items are on the docket for inclusion in subsequent release(s) of CVRF. The list is not exhaustive and subject to change.
Mike Schiffman (firstname.lastname@example.org)
The author would like to thank Joe Clarke, Cisco Systems; Troy Fridley, Cisco Systems; and Joe Hemmerlein, Microsoft Corporation, for their assistance.
This document is part of Cisco Security Intelligence Operations.
This document is provided on an "as is" basis and does not imply any kind of guarantee or warranty, including the warranties of merchantability or fitness for a particular use. Your use of the information on the document or materials linked from the document is at your own risk. Cisco reserves the right to change or update this document at any time.