About the CERT Feed structure and formats
=========================================

Date:      2013-02-13
Author(s): Timo Pollmeier <timo.pollmeier@greenbone.net>
           Jan-Oliver Wagner <jan-oliver.wagner@greenbone.net>


Purpose of CERT Feed
--------------------

The CERT Feed contains advisories as published by Computer Emergency
Response Teams (CERTs). Many CERTs act regional and publish the advisories
in local languages. The regional focus is a helpful complementation of
the english CVE publications. In most cases, CERT advisories are
referring to one or more CVEs and therfore can be linked
into the vulnerability management, for example into scan results.

In the following, relevant aspects on format and structure are documented
for the integrated CERTs.

Currently, only a single CERT is integrated, the german DFN-CERT. This
serves as a reference for integration of further CERT advisories.
A major hurdle is usually the license of the advistories. It needs
to allow use for any purpose, re-distribution etc. Of course authorship
and/or Copyright needs to be documented and kept reproduced.


DFN-CERT advisories
*******************

Location: cert-data/dfn-cert-YYYY.xml

File name format
----------------
Files must be "dfn-cert-%04d.xml" where %04d is a four-digit year number
as used in the DFN-CERT IDs of the advisories.

Short vs. long ID
-----------------
In this document a "short" or "DFN-CERT" ID is defined as an identifier
of the format "DFN-CERT-%04d-%04d" where the first %04d is a year number,
and %04d is another 4 digit number, including leading zeros.

A "long" or "Atom" ID is defined as an identifier that should conform to the
rules for atom:id elements as defined by the Atom standard and that also should
include the "short" ID of an advisory.

<feed> root tag
---------------
The root tag must be <feed> and define the "dfncert" and default namespaces.
It must be made sure that the URLs
("http://www.dfn-cert.de/dfncert.dtd" for xmlns:dfncert and
 "http://www.w3.org/2005/Atom" for the default namespace) remain constant:

The root element must contain the <entry> elements directly (i.e. as children
and not nested within other elements).
The root element may also optionally contain other elements like <title> or
<updated>, as long as they apply to all pages of the DFN feed or can be
aggregated in a sensible manner (e.g. by taking the latest <updated> date).

Selection of <entry> elements
-----------------------------
Each file for the CERT Feed must contain <entry> elements for all
the newest versions of the advisories that have a short id that also contains
the same year number as the current file name, but not others.

For example, the file "dfn-cert-2012.xml" will contain the latest version of
all existing advisories with the short IDs "DFN-CERT-2012-0001" to
"DFN-CERT-2012-9999" but not "DFN-CERT-2013-0001".

Duplicate advisories with the same short ID must be either:
A) avoided by ensuring that only the latest version is included.
   or less preferably
B) sorted so that the newer elements will overwrite the older ones when
   the GVM database is synced by the user.

Contents of <entry> elements
----------------------------
Each <entry> element must contain the following sub-elements:
* <dfncert:refnum> which contains the short ID of the advisory.
  This is implemented by the current feed supplied by DFN-CERT,
  but is missing in some older archive and test data.

  It can be generated for these files with:

  <xsl:value-of
       select="substring-before(substring-after(atom:id/text(),$feed_id),'/')"/>

  where $feed_id is the value of the <id> element directly nested in the <feed>
  root (not the one in the <entry>!)

* <published> which should contain the date when the advisory was _first_
              published.
              (is the same as <updated> date of <feed> in sample data!)

* <updated> which should contain the date when the advisory was last updated.

* <title> which should contain the title of the advisory

* <summary> which must be either the original escaped html or unescaped or with
            "harmless" format tags like "<br \>" or "<i>...</i>" escaped and
            validated to not cause any trouble.
            This element should contain a short description as found in the
            original <summary> element.

* all <dfncert:cve> elements that are also present in the original <entry>,
   containing only a valid CVE ID (e.g. "CVE-2009-4015") as text.

* one <link> with attribute rel="alt" and attribute href="{...}" with {...}
  being an URL referring to the full advisory, e.g.
  "https://portal.cert.dfn.de/adv/DFN-CERT-2010-0001/"

Other sub-elements like the original <id> containing the long ID or future
additions should be no problem, so for the most part it would probably be the
easiest to simply copy the sub-elements and attributes of <entry> elements and
add missing ones like a generated short ID until they are implemented by DFN.


Example (file "dfn-cert-2010.xml"):
-------------------------------
<?xml version="1.0" encoding="utf-8"?>

<feed xmlns:dfncert="http://www.dfn-cert.de/dfncert.dtd"
      xmlns="http://www.w3.org/2005/Atom">
  <entry>
    <dfncert:refnum>DFN-CERT-2010-9876</dfncert:refnum>
    <published>2010-12-28T09:39:59+01:00</published>
    <updated>2011-03-02T10:11:32+01:00</updated>
    <title>Test Advisory</title>
    <summary>This is a test advisory</summary>
    <dfncert:cve>CVE-2009-4015</dfncert:cve>
    <dfncert:cve>CVE-2010-0005</dfncert:cve>
    <link rel="alt" href="https://portal.cert.dfn.de/adv/DFN-CERT-2010-9876/" />
  </entry>
</feed>
