diff --git a/dependency-check-ant/README.md b/dependency-check-ant/README.md index d3496c649..d12265b6c 100644 --- a/dependency-check-ant/README.md +++ b/dependency-check-ant/README.md @@ -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" + } +} +``` \ No newline at end of file diff --git a/dependency-check-gradle/README.md b/dependency-check-gradle/README.md index d12265b6c..b06d653c7 100644 --- a/dependency-check-gradle/README.md +++ b/dependency-check-gradle/README.md @@ -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. ========= diff --git a/dependency-check-gradle/src/main/groovy/com/tools/security/extension/CheckExtension.groovy b/dependency-check-gradle/src/main/groovy/com/tools/security/extension/CheckExtension.groovy index e92326729..8c1647666 100644 --- a/dependency-check-gradle/src/main/groovy/com/tools/security/extension/CheckExtension.groovy +++ b/dependency-check-gradle/src/main/groovy/com/tools/security/extension/CheckExtension.groovy @@ -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. diff --git a/dependency-check-gradle/src/site/markdown/configuration-update.md b/dependency-check-gradle/src/site/markdown/configuration-update.md new file mode 100644 index 000000000..a95a6b402 --- /dev/null +++ b/dependency-check-gradle/src/site/markdown/configuration-update.md @@ -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 + } +} +``` diff --git a/dependency-check-gradle/src/site/markdown/configuration.md b/dependency-check-gradle/src/site/markdown/configuration.md new file mode 100644 index 000000000..6ba6c9266 --- /dev/null +++ b/dependency-check-gradle/src/site/markdown/configuration.md @@ -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 + } +} +``` diff --git a/dependency-check-gradle/src/site/markdown/index.md b/dependency-check-gradle/src/site/markdown/index.md deleted file mode 100644 index d7085ebb6..000000000 --- a/dependency-check-gradle/src/site/markdown/index.md +++ /dev/null @@ -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 diff --git a/dependency-check-gradle/src/site/markdown/index.md.vm b/dependency-check-gradle/src/site/markdown/index.md.vm new file mode 100644 index 000000000..1653d3e88 --- /dev/null +++ b/dependency-check-gradle/src/site/markdown/index.md.vm @@ -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