github-mirrors/DependencyCheck
1
0
Fork 0
mirror of https://github.com/ysoftdevs/DependencyCheck.git synced 2026-01-14 07:43:40 +01:00
Code Issues Packages Projects Releases Wiki Activity

updated documentation

Browse Source
This commit is contained in:
Jeremy Long
2015-11-22 07:31:17 -05:00
parent fc05471086
commit eb03c90d7a
7 changed files with 423 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

139
dependency-check-ant/README.md
View File

@@ -1,25 +1,134 @@
Dependency-Check Ant Task
Dependency-Check-Gradle
=========
Dependency-Check Ant Task can be used to check the project dependencies for published security vulnerabilities. The checks
performed are a "best effort" and as such, there could be false positives as well as false negatives. However,
vulnerabilities in 3rd party components is a well-known problem and is currently documented in the 2013 OWASP
Top 10 as [A9 - Using Components with Known Vulnerabilities](https://www.owasp.org/index.php/Top_10_2013-A9-Using_Components_with_Known_Vulnerabilities).
**Working in progress**
Documentation and links to production binary releases can be found on the [github pages](http://jeremylong.github.io/DependencyCheck/dependency-check-ant/installation.html).
This is a DependencyCheck gradle plugin designed for project which use Gradle as build script.
Mailing List
------------
Dependency-Check is a utility that attempts to detect publicly disclosed vulnerabilities contained within project dependencies. It does this by determining if there is a Common Platform Enumeration (CPE) identifier for a given dependency. If found, it will generate a report linking to the associated CVE entries.
Subscribe: [dependency-check+subscribe@googlegroups.com](mailto:dependency-check+subscribe@googlegroups.com)
=========
Post: [dependency-check@googlegroups.com](mailto:dependency-check@googlegroups.com)
## What's New
Current latest version is `0.0.8`
Copyright & License
-------------------
## Usage
Dependency-Check is Copyright (c) 2012-2014 Jeremy Long. All Rights Reserved.
### Step 1, Apply dependency check gradle plugin
Permission to modify and redistribute is granted under the terms of the Apache 2.0 license. See the [LICENSE.txt](https://raw.githubusercontent.com/jeremylong/DependencyCheck/master/LICENSE.txt) file for the full license.
Install from Maven central repo
Dependency-Check-Ant makes use of other open source libraries. Please see the [NOTICE.txt](https://raw.githubusercontent.com/jeremylong/DependencyCheck/master/dependency-check-ant/NOTICE.txt) file for more information.
```groovy
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath 'org.owasp:dependency-check-gradle:1.3.2'
}
}
apply plugin: 'dependency-check-gradle'
```
### Step 2, Run gradle task
Once gradle plugin applied, run following gradle task to check dependencies:
```
gradle dependencyCheck --info
```
The reports will be generated automatically under `./reports` folder.
If your project includes multiple sub-projects, the report will be generated for each sub-project in different sub-directory.
## FAQ
> **Questions List:**
> - What if I'm behind a proxy?
> - What if my project includes multiple sub-project? How can I use this plugin for each of them including the root project?
> - How to customize the report directory?
### What if I'm behind a proxy?
Maybe you have to use proxy to access internet, in this case, you could configure proxy settings for this plugin:
```groovy
dependencyCheck {
proxy {
server = "127.0.0.1" // required, the server name or IP address of the proxy
port = 3128 // required, the port number of the proxy
// optional, the proxy server might require username
// username = "username"
// optional, the proxy server might require password
// password = "password"
}
}
```
In addition, if the proxy only allow HTTP `GET` or `POST` methods, you will find that the update process will always fail,
the root cause is that every time you run `dependencyCheck` task, it will try to query the latest timestamp to determine whether need to perform an update action,
and for performance reason the HTTP method it uses by default is `HEAD`, which probably is disabled or not supported by the proxy. To avoid this problem, you can simply change the HTTP method by below configuration:
```groovy
dependencyCheck {
quickQueryTimestamp = false // when set to false, it means use HTTP GET method to query timestamp. (default value is true)
}
```
### What if my project includes multiple sub-project? How can I use this plugin for each of them including the root project?
Try put 'apply plugin: "dependency-check"' inside the 'allprojects' or 'subprojects' if you'd like to check all sub-projects only, see below:
(1) For all projects including root project:
```groovy
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath "gradle.plugin.com.tools.security:dependency-check:0.0.8"
}
}
allprojects {
apply plugin: "dependency-check"
}
```
(2) For all sub-projects:
```groovy
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath "gradle.plugin.com.tools.security:dependency-check:0.0.8"
}
}
subprojects {
apply plugin: "dependency-check"
}
```
In this way, the dependency check will be executed for all projects (including root project) or just sub projects.
### How to customize the report directory?
By default, all reports will be placed under `./reports` folder, to change the default directory, just modify it in the configuration section like this:
```groovy
subprojects {
apply plugin: "dependency-check"
dependencyCheck {
outputDirectory = "./customized-path/security-report"
}
}
```

7
dependency-check-gradle/README.md
View File

@@ -1,11 +1,8 @@
Dependency-Check-Gradle
=========
**Working in progress**
This is a DependencyCheck gradle plugin designed for project which use Gradle as build script.
Dependency-Check is a utility that attempts to detect publicly disclosed vulnerabilities contained within project dependencies. It does this by determining if there is a Common Platform Enumeration (CPE) identifier for a given dependency. If found, it will generate a report linking to the associated CVE entries.
The dependency-check gradle plugin allows projects to monitor dependent libraries for
known, published vulnerabilities.
=========

10
dependency-check-gradle/src/main/groovy/com/tools/security/extension/CheckExtension.groovy
View File

@@ -40,14 +40,14 @@ class CheckExtension extends UpdateExtension {
* Sets whether auto-updating of the NVD CVE/CPE data is enabled.
*/
Boolean autoUpdate
/**
* When set to true dependency groups that start with 'test' will not be included in the analysis.
*/
Boolean skipTestGroups
//The following properties are not used via the settings object, instead
// they are directly used by the check task.
/**
* When set to true dependency groups that start with 'test' will not be included in the analysis.
* The default value is true.
*/
Boolean skipTestGroups = true
/**
* The report format to be generated (HTML, XML, VULN, ALL). This configuration option has
* no affect if using this within the Site plugin unless the externalReport is set to true.

116
dependency-check-gradle/src/site/markdown/configuration-update.md Normal file
View File

@@ -0,0 +1,116 @@
Tasks
====================
Task | Description
------------------------------------------|-----------------------
[dependencyCheck](configuration.html) | Runs dependency-check against the project and generates a report.
dependencyCheckUpdate | Updates the local cache of the NVD data from NIST.
[dependencyCheckPurge](config-purge.html) | Deletes the local copy of the NVD. This is used to force a refresh of the data.
Configuration: dependencyCheckUpdate
====================
The following properties can be configured for the dependencyCheckUpdate task:
Property | Description | Default Value
---------------------|------------------------------------|------------------
autoUpdate | Sets whether auto-updating of the NVD CVE/CPE data is enabled. It is not recommended that this be turned to false. | true
cveValidForHours | Sets the number of hours to wait before checking for new updates from the NVD. | 4
failBuildOnCVSS | Specifies if the build should be failed if a CVSS score above a specified level is identified. The default is 11; since the CVSS scores are 0-10, by default the build will never fail. | 11
format | The report format to be generated (HTML, XML, VULN, ALL). | HTML
reportsDirName | The location to write the report(s). This directory will be located in the build directory. | reports
skipTestGroups | When set to true (the default) all dependency groups that being with 'test' will be skipped. | true
suppressionFile | The file path to the XML suppression file \- used to suppress [false positives](../general/suppression.html) |  
$H$H$H$H Example
```groovy
dependencyCheck {
autoUpdate=false
cveValidForHours=1
format=ALL
}
```
$H$H$H Proxy Configuration
Property | Description | Default Value
------------------|------------------------------------|------------------
server | The proxy server. |  
port | The proxy port. |  
username | Defines the proxy user name. |  
password | Defines the proxy password. |  
connectionTimeout | The URL Connection Timeout. |  
$H$H$H$H Example
```groovy
dependencyCheck {
proxy {
server=some.proxy.server
port=8989
}
}
```
$H$H$H Advanced Configuration
The following properties can be configured in the dependencyCheck task. However, they are less frequently changed. One exception
may be the cvedUrl properties, which can be used to host a mirror of the NVD within an enterprise environment.
Note, if ANY of the cve configuration group are set - they should all be set to ensure things work as expected.
Config Group | Property | Description | Default Value
-------------|-------------------|---------------------------------------------------------------------------------------------|------------------
cve | url12Modified | URL for the modified CVE 1.2. | https://nvd.nist.gov/download/nvdcve-Modified.xml.gz
cve | url20Modified | URL for the modified CVE 2.0. | https://nvd.nist.gov/feeds/xml/cve/nvdcve-2.0-Modified.xml.gz
cve | url12Base | Base URL for each year's CVE 1.2, the %d will be replaced with the year. | https://nvd.nist.gov/download/nvdcve-%d.xml.gz
cve | url20Base | Base URL for each year's CVE 2.0, the %d will be replaced with the year. | https://nvd.nist.gov/feeds/xml/cve/nvdcve-2.0-%d.xml.gz
data | directory | Sets the data directory to hold SQL CVEs contents. This should generally not be changed. |  
data | driver | The name of the database driver. Example: org.h2.Driver. |  
data | driverPath | The path to the database driver JAR file; only used if the driver is not in the class path. |  
data | connectionString | The connection string used to connect to the database. |  
data | username | The username used when connecting to the database. |  
data | password | The password used when connecting to the database. |  
$H$H$H$H Example
```groovy
dependencyCheck {
data {
directory='d:/nvd'
}
}
```
$H$H$H Analyzer Configuration
In addition to the above, the dependencyCheck plugin can be configured to enable or disable specific
analyzers by configuring the `analyzer` section. Note, specific file type analyzers will automatically
disable themselves if no file types that they support are detected - so specifically disabling the
analyzers is likely not needed.
Property | Description | Default Value
----------------------|---------------------------------------------------------------------------|------------------
archiveEnabled | Sets whether the Archive Analyzer will be used. | true
zipExtensions | A comma-separated list of additional file extensions to be treated like a ZIP file, the contents will be extracted and analyzed. |  
jarEnabled | Sets whether Jar Analyzer will be used. | true
centralEnabled | Sets whether Central Analyzer will be used. If this analyzer is being disabled there is a good chance you also want to disable the Nexus Analyzer (see below). | true
nexusEnabled | Sets whether Nexus Analyzer will be used. This analyzer is superceded by the Central Analyzer; however, you can configure this to run against a Nexus Pro installation. | true
nexusUrl | Defines the Nexus Server's web service end point (example http://domain.enterprise/service/local/). If not set the Nexus Analyzer will be disabled. |  
nexusUsesProxy | Whether or not the defined proxy should be used when connecting to Nexus. | true
pyDistributionEnabled | Sets whether the Python Distribution Analyzer will be used. | true
pyPackageEnabled | Sets whether the Python Package Analyzer will be used. | true
rubygemsEnabled | Sets whether the Ruby Gemspec Analyzer will be used. | true
opensslEnabled | Sets whether or not the openssl Analyzer should be used. | true
cmakeEnabled | Sets whether or not the CMake Analyzer should be used. | true
autoconfEnabled | Sets whether or not the autoconf Analyzer should be used. | true
composerEnabled | Sets whether or not the PHP Composer Lock File Analyzer should be used. | true
nodeEnabled | Sets whether or not the Node.js Analyzer should be used. | true
nuspecEnabled | Sets whether or not the .NET Nuget Nuspec Analyzer will be used. | true
assemblyEnabled | Sets whether or not the .NET Assembly Analyzer should be used. | true
pathToMono | The path to Mono for .NET assembly analysis on non-windows systems. |  
$H$H$H$H Example
```groovy
dependencyCheck {
analyzer {
assemblyEnabled=false
}
}
```

116
dependency-check-gradle/src/site/markdown/configuration.md Normal file
View File

@@ -0,0 +1,116 @@
Tasks
====================
Task | Description
--------------------------------------------|-----------------------
dependencyCheck | Runs dependency-check against the project and generates a report.
[dependencyCheckUpdate](config-update.html) | Updates the local cache of the NVD data from NIST.
[dependencyCheckPurge](config-purge.html) | Deletes the local copy of the NVD. This is used to force a refresh of the data.
Configuration: dependencyCheck
====================
The following properties can be configured for the dependencyCheck task:
Property | Description | Default Value
---------------------|------------------------------------|------------------
autoUpdate | Sets whether auto-updating of the NVD CVE/CPE data is enabled. It is not recommended that this be turned to false. | true
cveValidForHours | Sets the number of hours to wait before checking for new updates from the NVD. | 4
failBuildOnCVSS | Specifies if the build should be failed if a CVSS score above a specified level is identified. The default is 11; since the CVSS scores are 0-10, by default the build will never fail. | 11
format | The report format to be generated (HTML, XML, VULN, ALL). | HTML
reportsDirName | The location to write the report(s). This directory will be located in the build directory. | reports
skipTestGroups | When set to true (the default) all dependency groups that being with 'test' will be skipped. | true
suppressionFile | The file path to the XML suppression file \- used to suppress [false positives](../general/suppression.html) |  
$H$H$H$H Example
```groovy
dependencyCheck {
autoUpdate=false
cveValidForHours=1
format=ALL
}
```
$H$H$H Proxy Configuration
Property | Description | Default Value
------------------|------------------------------------|------------------
server | The proxy server. |  
port | The proxy port. |  
username | Defines the proxy user name. |  
password | Defines the proxy password. |  
connectionTimeout | The URL Connection Timeout. |  
$H$H$H$H Example
```groovy
dependencyCheck {
proxy {
server=some.proxy.server
port=8989
}
}
```
$H$H$H Advanced Configuration
The following properties can be configured in the dependencyCheck task. However, they are less frequently changed. One exception
may be the cvedUrl properties, which can be used to host a mirror of the NVD within an enterprise environment.
Note, if ANY of the cve configuration group are set - they should all be set to ensure things work as expected.
Config Group | Property | Description | Default Value
-------------|-------------------|---------------------------------------------------------------------------------------------|------------------
cve | url12Modified | URL for the modified CVE 1.2. | https://nvd.nist.gov/download/nvdcve-Modified.xml.gz
cve | url20Modified | URL for the modified CVE 2.0. | https://nvd.nist.gov/feeds/xml/cve/nvdcve-2.0-Modified.xml.gz
cve | url12Base | Base URL for each year's CVE 1.2, the %d will be replaced with the year. | https://nvd.nist.gov/download/nvdcve-%d.xml.gz
cve | url20Base | Base URL for each year's CVE 2.0, the %d will be replaced with the year. | https://nvd.nist.gov/feeds/xml/cve/nvdcve-2.0-%d.xml.gz
data | directory | Sets the data directory to hold SQL CVEs contents. This should generally not be changed. |  
data | driver | The name of the database driver. Example: org.h2.Driver. |  
data | driverPath | The path to the database driver JAR file; only used if the driver is not in the class path. |  
data | connectionString | The connection string used to connect to the database. |  
data | username | The username used when connecting to the database. |  
data | password | The password used when connecting to the database. |  
$H$H$H$H Example
```groovy
dependencyCheck {
data {
directory='d:/nvd'
}
}
```
$H$H$H Analyzer Configuration
In addition to the above, the dependencyCheck plugin can be configured to enable or disable specific
analyzers by configuring the `analyzer` section. Note, specific file type analyzers will automatically
disable themselves if no file types that they support are detected - so specifically disabling the
analyzers is likely not needed.
Property | Description | Default Value
----------------------|---------------------------------------------------------------------------|------------------
archiveEnabled | Sets whether the Archive Analyzer will be used. | true
zipExtensions | A comma-separated list of additional file extensions to be treated like a ZIP file, the contents will be extracted and analyzed. |  
jarEnabled | Sets whether Jar Analyzer will be used. | true
centralEnabled | Sets whether Central Analyzer will be used. If this analyzer is being disabled there is a good chance you also want to disable the Nexus Analyzer (see below). | true
nexusEnabled | Sets whether Nexus Analyzer will be used. This analyzer is superceded by the Central Analyzer; however, you can configure this to run against a Nexus Pro installation. | true
nexusUrl | Defines the Nexus Server's web service end point (example http://domain.enterprise/service/local/). If not set the Nexus Analyzer will be disabled. |  
nexusUsesProxy | Whether or not the defined proxy should be used when connecting to Nexus. | true
pyDistributionEnabled | Sets whether the Python Distribution Analyzer will be used. | true
pyPackageEnabled | Sets whether the Python Package Analyzer will be used. | true
rubygemsEnabled | Sets whether the Ruby Gemspec Analyzer will be used. | true
opensslEnabled | Sets whether or not the openssl Analyzer should be used. | true
cmakeEnabled | Sets whether or not the CMake Analyzer should be used. | true
autoconfEnabled | Sets whether or not the autoconf Analyzer should be used. | true
composerEnabled | Sets whether or not the PHP Composer Lock File Analyzer should be used. | true
nodeEnabled | Sets whether or not the Node.js Analyzer should be used. | true
nuspecEnabled | Sets whether or not the .NET Nuget Nuspec Analyzer will be used. | true
assemblyEnabled | Sets whether or not the .NET Assembly Analyzer should be used. | true
pathToMono | The path to Mono for .NET assembly analysis on non-windows systems. |  
$H$H$H$H Example
```groovy
dependencyCheck {
analyzer {
assemblyEnabled=false
}
}
```

28
dependency-check-gradle/src/site/markdown/index.md
View File

@@ -1,28 +0,0 @@
Dependency-Check Gradle Plugin
==============================
Dependency-Check is a utility that identifies project dependencies and checks if there are any known, publicly disclosed, vulnerabilities. This tool can be part of the solution to the OWASP Top 10 2013: A9 - Using Components with Known Vulnerabilities.
The Gradle Plugin is still a work in progress. The core dependency-check functionality works; however, the configuration options available in the other plugins still need to be completed.
For more information about the plugin, including usage, please see the github repo's [readme](https://github.com/jeremylong/DependencyCheck/blob/master/dependency-check-gradle/README.md).
Mailing List
------------
Subscribe: [dependency-check+subscribe@googlegroups.com] [subscribe]
Post: [dependency-check@googlegroups.com] [post]
License
-------------------
Permission to modify and redistribute is granted under the terms of the Apache 2.0 license. See the [LICENSE.txt] [license] file for the full license.
Dependency-Check makes use of several other open source libraries. Please see the [NOTICE.txt] [notices] file for more information.
[subscribe]: mailto:dependency-check+subscribe@googlegroups.com
[post]: mailto:dependency-check@googlegroups.com
[license]: https://github.com/jeremylong/DependencyCheck/blob/master/dependency-check-gradle/LICENSE.txt
[notices]: https://github.com/jeremylong/DependencyCheck/blob/master/dependency-check-gradle/NOTICE.txt

60
dependency-check-gradle/src/site/markdown/index.md.vm Normal file
View File

@@ -0,0 +1,60 @@
Usage
==============================
The OWASP dependency-check-gradle plugin provides monitoring of the projects dependent
libraries; creating a report of known vulnerable components that are included in the build.
It is important to understand that the first time this task is executed it may
take 5-20 minutes as it downloads and processes the data from the National
Vulnerability Database (NVD) hosted by NIST: https://nvd.nist.gov
After the first batch download, as long as the plugin is executed at least once every
seven days the update will only take a few seconds.
#set( $H = '#' )
$H$H$H Step 1, Apply dependency-check-gradle plugin
Install from Maven central repo
```groovy
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath 'org.owasp:dependency-check-gradle:${project.version}'
}
}
apply plugin: 'dependencyCheck'
```
$H$H$H Step 2, Run the dependencyCheck task
Once gradle plugin applied, run following gradle task to check dependencies:
```
gradle dependencyCheck --info
```
The reports will be generated automatically under `buildDir/reports` folder.
Mailing List
------------
Subscribe: [dependency-check+subscribe@googlegroups.com] [subscribe]
Post: [dependency-check@googlegroups.com] [post]
License
-------------------
Permission to modify and redistribute is granted under the terms of the Apache 2.0 license. See the [LICENSE.txt] [license] file for the full license.
Dependency-Check makes use of several other open source libraries. Please see the [NOTICE.txt] [notices] file for more information.
[subscribe]: mailto:dependency-check+subscribe@googlegroups.com
[post]: mailto:dependency-check@googlegroups.com
[license]: https://github.com/jeremylong/DependencyCheck/blob/master/dependency-check-gradle/LICENSE.txt
[notices]: https://github.com/jeremylong/DependencyCheck/blob/master/dependency-check-gradle/NOTICE.txt