github-mirrors/DependencyCheck
1
0
Fork 0
mirror of https://github.com/ysoftdevs/DependencyCheck.git synced 2026-05-02 05:04:29 +02:00
Code Issues Packages Projects Releases Wiki Activity

updated documentation

Browse Source 
Former-commit-id: a41eadec0c691ce907b64a688a60325dd61f9ae7
This commit is contained in:
Jeremy Long
2015-04-19 08:14:55 -04:00
parent 09122be7be
commit 4a2309a3f8
15 changed files with 66 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
src/site/markdown/general/internals.md Normal file
View File

@@ -0,0 +1,37 @@
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
<entry id="CVE-2012-5055">
...
<vuln:vulnerable-software-list>
<vuln:product>cpe:/a:vmware:springsource_spring_security:3.1.2</vuln:product>
<vuln:product>cpe:/a:vmware:springsource_spring_security:2.0.4</vuln:product>
<vuln:product>cpe:/a:vmware:springsource_spring_security:3.0.1</vuln:product>
```
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.).

86
src/site/markdown/general/suppression.md Normal file
View File

@@ -0,0 +1,86 @@
Suppressing False Positives
====================
Due to how dependency-check identifies libraries false positives may occur (a CPE was identified that is incorrect). Suppressing these false positives is fairly easy using the HTML report. In the report next to each CPE identified (and on CVE entries) there is a suppress button. Clicking the suppression button will create a dialogue box which you can simple hit Control-C to copy the XML that you would place into a suppression XML file. If this is the first time you are creating the suppression file you should click the "Complete XML Doc" button on the top of the dialogue box to add the necessary schema elements.
A sample suppression file would look like:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<suppressions xmlns="https://www.owasp.org/index.php/OWASP_Dependency_Check_Suppression">
<suppress>
<notes><![CDATA[
file name: some.jar
]]></notes>
<sha1>66734244CE86857018B023A8C56AE0635C56B6A1</sha1>
<cpe>cpe:/a:apache:struts:2.0.0</cpe>
</suppress>
</suppressions>
```
The above XML file will suppress the cpe:/a:apache:struts:2.0.0 from any file with the a matching SHA1 hash.
The following shows some other ways to suppress individual findings. Note the ways to select files using either
the sha1 hash or the filePath (the filePath can also be a regex). Additionally, there are several things that
can be suppressed - individual CPEs, individual CVEs, or all CVE entries below a specified CVSS score. The most common
would be suppressing CPEs based off of SHA1 hashes or filePath (regexes) - these entries can be generated using the
HTML version of the report. The other common scenario would be to ignore all CVEs below a certain CVSS threshold.
```xml
<?xml version="1.0" encoding="UTF-8"?>
<suppressions
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xmlns='https://www.owasp.org/index.php/OWASP_Dependency_Check_Suppression'
xsi:schemaLocation='https://www.owasp.org/index.php/OWASP_Dependency_Check_Suppression suppression.xsd'>
<suppress>
<notes><![CDATA[
This suppresses cpe:/a:csv:csv:1.0 for some.jar in the "c:\path\to" directory.
]]></notes>
<filePath>c:\path\to\some.jar</filePath>
<cpe>cpe:/a:csv:csv:1.0</cpe>
</suppress>
<suppress>
<notes><![CDATA[
This suppresses any jboss:jboss cpe for any test.jar in any directory.
]]></notes>
<filePath regex="true">.*\btest\.jar</filePath>
<cpe>cpe:/a:jboss:jboss</cpe>
</suppress>
<suppress>
<notes><![CDATA[
This suppresses a specific cve for any test.jar in any directory.
]]></notes>
<filePath regex="true">.*\btest\.jar</filePath>
<cve>CVE-2013-1337</cve>
</suppress>
<suppress>
<notes><![CDATA[
This suppresses a specific cve for any dependency in any directory that has the specified sha1 checksum.
]]></notes>
<sha1>384FAA82E193D4E4B0546059CA09572654BC3970</sha1>
<cve>CVE-2013-1337</cve>
</suppress>
<suppress>
<notes><![CDATA[
This suppresses all CVE entries that have a score below CVSS 7.
]]></notes>
<cvssBelow>7</cvssBelow>
</suppress>
<suppress>
<notes><![CDATA[
This suppresses false positives identified on spring security.
]]></notes>
<gav regex="true">org\.springframework\.security:spring.*</gav>
<cpe>cpe:/a:vmware:springsource_spring_framework</cpe>
<cpe>cpe:/a:springsource:spring_framework</cpe>
<cpe>cpe:/a:mod_security:mod_security</cpe>
</suppress>
</suppressions>
```
The full schema for suppression files can be found here: [suppression.xsd](https://github.com/jeremylong/DependencyCheck/blob/master/dependency-check-core/src/main/resources/schema/suppression.xsd "Suppression Schema")
Please see the appropriate configuration option in each interfaces configuration guide:
- [Command Line Tool](dependency-check-cli/arguments.html)
- [Maven Plugin](dependency-check-maven/configuration.html)
- [Ant Task](dependency-check-ant/configuration.html)
- [Jenkins Plugin](dependency-check-jenkins/index.html)

46
src/site/markdown/general/thereport.md Normal file
View File

@@ -0,0 +1,46 @@
How To Read The Reports
========
The top of the report contains a list of the identified vulnerable components. By clicking the 'Showing Vulnerable
Dependencies' link the list will be expanded to include all of the dependencies scanned. The table lists:
* Dependency - the file name of the dependency scanned.
* CPE - any Common Platform Enumeration identifiers found.
* GAV - the Maven Group, Artifact, Version (GAV).
* Highest Severity - the highest severity of any associated CVEs.
* CVE Count - the number of associated CVEs.
* CPE Confidence - a ranking of how confident dependency-check is that the CPE was identified correctly.
* Evidence Count - the quantity of data extracted from the dependency that was used to identify the CPE.
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 identified CPE is correct. Due to the way dependency-check works (see
[How it works](./internals.html) for more information) 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, 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 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 [Suppressing 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 we 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.
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.