[v8,9/9] docs/manual: new security management section

Message ID 1552082667-46877-10-git-send-email-matthew.weber@rockwellcollins.com
State New
Headers show
Series
  • Package CPE Reporting
Related show

Commit Message

Matthew Weber March 8, 2019, 10:04 p.m.
This changeset captures an initial discussion on the use of CPE
reporting within a target build.  It notes the reporting limitations
and provides actions a user could take to improve upon the current
report information.

There is also an example of how one might do CVE analysis using the
CPE report information.

Signed-off-by: Matthew Weber <matthew.weber@rockwellcollins.com>
---
Changes

v8
 - Updated for cpe-report changes
 - Added notes on doing CVE searches and submissions

v7
 - New
---
 docs/manual/cpe-reporting.txt | 103 ++++++++++++++++++++++++++++++++++++++++++
 docs/manual/manual.txt        |   2 +
 2 files changed, 105 insertions(+)
 create mode 100644 docs/manual/cpe-reporting.txt

Patch

diff --git a/docs/manual/cpe-reporting.txt b/docs/manual/cpe-reporting.txt
new file mode 100644
index 0000000..a6f32d5
--- /dev/null
+++ b/docs/manual/cpe-reporting.txt
@@ -0,0 +1,103 @@ 
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[cpe-info]]
+
+== Security Vulnerability Management
+
+There are many different vulnerability databases (open/paid). This
+section documents the use of the National Vulnerability Database(NVD)
+provided by the National Institute of Standards and Technology (NIST).
+
+Within Buildroot, the intent is to provide good reporting of the build
+configuration's inventory of software. The vulnerability analysis is
+assumed to occur outside of the Buildroot environment (at this time).
+
+=== Common Platform Enumeration (CPE) Reporting
+
+Buildroot consists of a series of upstream packages.  Each of those
+packages may have a CPE definition used to map vulnerabilities to Common
+Vulnerabilities and Exposures (CVE). A single package CPE has many versions
+and each version may have a suite of CVEs associated.
+
+To make the gathering of the software inventory of CPE easier, Buildroot can
+collect for you all the CPE related to the configured defconfig. To produce
+this material, after you have configured Buildroot with +make menuconfig+,
++make xconfig+ or +make gconfig+, run:
+
+--------------------
+make cpe-info
+--------------------
+
+Buildroot then collects and writes the +$(TOPDIR)/cpe-manifest.csv+. This file
+can be used for manual inspection against a CVE database or provided to
+external tools which perform CVE inventory/analysis.
+
+*CPE Maintenance*
+
+To maintain these CPE strings for version changes against the NIST dictionary,
+the manifest can be further processed. First, navigate to your Buildroot
+directory and execute the script below. The script has some optional arguments
+for providing a alternate dictionary URL or caching a processed dictionary.
+
+--------------------
+support/scripts/cpe-report -c $(TOPDIR)/cpe-manifest.csv
+--------------------
+
+This script retrieves the NIST dictionary and classifies each CPE as either
+matched, requires version update or missing. Based on this analysis, the script
+automatically uses the NIST dictionary entries to produce a draft of XML which
+can be submitted to NIST to update a version of an entry in the dictionary. It
+is important to review the generated xml files in the cpe folder as they may
+need refined reference tags and adjustments to how the version is represented
+in the title.
+
+In the case of missing items, a +cpe-report-missing.txt+ report is output by
+the script and can be used as a starting point to manually create a xml file
+to submit. Note, some manual analysis using the NIST search engine (https://nvd.nist.gov/products/cpe/search)
+is suggested for these missing item as the Buildroot +CPE_ID_+ variables maybe
+slightly incorrect and cause the cpe-report script to catagorize the package
+as missing. If that is the case, a change can be made by adjusting the default
+CPE variables in the specific package's +.mk+. See xref:_infrastructure_for_packages_with_specific_build_systems[]
+discussion on the use of +LIBFOO_CPE_*+.
+If the package is truely missing, the package's Kconfig help material and .mk
+should provide most of the information to construct a new NIST submission.
+
+To submit a new entry or updated entry to NIST, create an request email to the
+cpe_dictionary@nist.gov recipient and attach a individual xml file per package
+being added/updated.  It is OK to have multiple version updates in a single
+file as long as they are all for the same package. For reference the guidance
+can be found on the NIST CPE site (https://nvd.nist.gov/products/cpe).
+
+*Limitations*
+
+Buildroot does not produce or accurately present some of the CPE material. Items
+such as any versions which are non-number/hash are not compliant with the CPE
+string specification and would require a manual analysis to update the CPE list
+before any external CVE analysis should occur. This is a similar situation for
+packages like the Linux kernel or U-Boot which may not have a version which
+directly maps to a CPE.
+
+There is an assumed default CPE string for each package which is auto-generated
+using existing package information. The output of +make cpe-info+ is based on
+this default information and the packages which have been individually tailored
+to match existing CPE strings. The Buildroot developers try to do their best to
+keep those declarative statements as accurate as possible, to the best of their
+knowledge. However, it is very well possible that those declarative statements
+are not all fully accurate nor exhaustive. Similar to legal-info, it is your
+responsibility to verify this information.
+
+=== Common Vulnerability and Exposures (CVE) Anaylsis
+The Common Vulnerabilities and Exposures (CVE) system provides a
+reference-method for publicly known information-security vulnerabilities and
+exposures. (https://en.wikipedia.org/wiki/Common_Vulnerabilities_and_Exposures)
+
+Like previously stated, there are many tools and methods to perform this
+analysis. The most basic example is to do a manual CVE analysis by navigating
+to the NVD search engine (https://nvd.nist.gov/vuln/search) and using the CPE
+string identified in the first field of the +$(TOPDIR)/cpe-manifest.csv+.
+Here's an example for tcpdump (https://nvd.nist.gov/vuln/search/results?form_type=Basic&results_type=overview&query=cpe%3A2.3%3Aa%3Atcpdump%3Atcpdump%3A4.9.1%3A*%3A*%3A*%3A*%3A*%3A*%3A*&search_type=all).
+
+Beyond the manual search approach, the next step would be a more centralized
+shared database with multi-feed support (NVD+).  The cve-search project aims
+to offer that type of solution (https://github.com/cve-search/cve-search).
diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
index 4eb4ba9..fad8bf2 100644
--- a/docs/manual/manual.txt
+++ b/docs/manual/manual.txt
@@ -46,6 +46,8 @@  include::legal-notice.txt[]
 
 include::beyond-buildroot.txt[]
 
+include::cpe-reporting.txt[]
+
 = Developer guide
 
 include::how-buildroot-works.txt[]