From 6ccc053d7e949f3f1a8388b1a55f552e4bcef25a Mon Sep 17 00:00:00 2001 From: Jeremy Long Date: Tue, 5 Aug 2014 09:16:38 -0400 Subject: [PATCH] added more documentation Former-commit-id: 87a761ffe89d36fb2011d5a38d607c35178d70ec --- src/site/markdown/internals.md | 35 ++++++++++++++++++++++++++++++++++ src/site/markdown/thereport.md | 26 +++++++++++++++++++++++++ 2 files changed, 61 insertions(+) create mode 100644 src/site/markdown/internals.md create mode 100644 src/site/markdown/thereport.md diff --git a/src/site/markdown/internals.md b/src/site/markdown/internals.md new file mode 100644 index 000000000..3eeeb7086 --- /dev/null +++ b/src/site/markdown/internals.md @@ -0,0 +1,35 @@ +How does dependency-check work? +=========== +Dependency-check works by collecting information about the files it scans (using Analyzers). The information collected +is called Evidence; there are three types of evidence collected: vendor, product, and version. For instance, the +JarAnalyzer will collect information from the Manifest, pom.xml, and the package names within the JAR files scanned and +it has heuristics to place the information from the various sources into one or more buckets of evidence. + +Within the NVD CVE Data (schema can be found [here](http://nvd.nist.gov/schema/nvd-cve-feed_2.0.xsd)) each CVE Entry has a list of vulnerable software: +```xml + + ... + + cpe:/a:vmware:springsource_spring_security:3.1.2 + cpe:/a:vmware:springsource_spring_security:2.0.4 + cpe:/a:vmware:springsource_spring_security:3.0.1 +``` + +These CPE entries are read "cpe:/[Entry Type]:[Vendor]:[Product]:[Version]:[Revision]:...". The CPE data is collected +and stored in a [Lucene Index](http://lucene.apache.org/). Dependency-check then use the Evidence collected and attempt +to match an entry from the Lucene CPE Index. If found, the CPEAnalyzer will add an Identifier to the Dependency and +subsequently to the report. Once a CPE has been identified the associated CVE entries are added to the report. + +One important point about the evidence is that it is rated using different confidence levels - low, medium, high, and +highest. These confidence levels are applied to each item of evidence. When the CPE is determined it is given a confidence +level that is equal to the lowest level confidence level of evidence used during identification. If only highest confidence +evidence was used in determining the CPE then the CPE would have a highest confidence level. + +Because of the way dependency-check works both false positives and false negatives may exist. Please read +(How to read the report)[thereport.html] to get a better understanding of sorting through the false positives and false +negatives. + +Dependency-check does not currently use file hashes for identification. If the dependency was built from source the hash +likely will not match the "published" hash. While the evidence based mechanism currently used can also be unreliable the +design decision was to avoid maintaining a hash database of known vulnerable libraries. A future enhancement may add some +hash matching for very common well known libraries (Spring, Struts, etc.). \ No newline at end of file diff --git a/src/site/markdown/thereport.md b/src/site/markdown/thereport.md new file mode 100644 index 000000000..ab3c31525 --- /dev/null +++ b/src/site/markdown/thereport.md @@ -0,0 +1,26 @@ +How To Read The Report +======== +There is a lot of information contained in the HTML version of the report. When analyzing the results, the first thing one should do is determine if the CPE looks +appropriate. Due to the way dependency-check works (see above) the report may contain false positives; these false positives are primarily on the CPE values. If the CPE value +is wrong, this is usually obvious and one should use the suppression feature in the report to generate a suppression XML file that can be used on future scans. In addition +to just looking at the CPE values in comparison to the name of the dependency - one may also consider the confidence of the CPE (as discussed in (How does dependency-check +work)[internals.html]). See the (Suppression False Positives)[suppression.html] page for more information on how to generate and use the suppression file. + +Once you have weeded out any obvious false positives one can then look at the remaining entries and determine if any of the identified CVE entries are actually +exploitable in your environment. Determining if a CVE is exploitable in your environment can be tricky - for this I do not currently have any tips other then +upgrade the library if you can just to be safe. Note, some CVE entries can be fixed by either upgrading the library or changing configuration options. + +One item that dependency-check flags that many may think is a false positive are old database drivers. One thing to consider about an old database driver is that the +CPE/CVEs identified are usually for the server rather then the driver. However, the presence of an old driver may indicate that you have an older version of the server +running in your environment and that server may need to be patched or upgraded. However, in some cases the old database drivers are actually unused, transitive dependencies +from other dependencies. + +Regarding False Negatives +======= +As stated above, due to the nature of dependency-check there may be publicly disclosed vulnerabilities in the project dependencies scanned by dependency-check that +are not identified. With the current version of dependency-check the HTML report has a table at the top that initially displays just the dependencies with identified +vulnerabilities. This can be toggled to show all dependencies. If you examine the rows that do not have identified CPE/CVE entries you will see an "evidence count". +If the evidence count is extremely low (0-5 entries) then there may not have been enough information contained in the dependency to identify a CPE and associated CVEs. + +It should be noted that while the false positives described above are bad, more concerning is that there may be vulnerabilities within the project dependencies that +have yet to be publicly known. If one has the resources consider performing security assessments on the project dependencies.