From 173947fd7d081f533b48ec624f8467bbbbc90b08 Mon Sep 17 00:00:00 2001 From: Jeremy Long Date: Sun, 23 Mar 2014 23:03:51 -0400 Subject: [PATCH] updated documentation Former-commit-id: b2036f354cc3d16db7e01bef9aad6aa494650fd2 --- .../src/site/markdown/configuration.md | 86 ++++++++++++------- .../src/site/markdown/arguments.md | 52 ++++++----- .../src/site/markdown/installation.md.vm | 14 ++- .../src/site/markdown/configuration.md | 53 ++++++++---- .../src/site/markdown/usage.md.vm | 20 ++--- 5 files changed, 140 insertions(+), 85 deletions(-) diff --git a/dependency-check-ant/src/site/markdown/configuration.md b/dependency-check-ant/src/site/markdown/configuration.md index d10b69d7a..b73d81160 100644 --- a/dependency-check-ant/src/site/markdown/configuration.md +++ b/dependency-check-ant/src/site/markdown/configuration.md @@ -18,34 +18,60 @@ the project's dependencies. ``` -The following table lists the configurable properties: -Property | Description | Requirement | Default Value -----------------------|-------------|-------------|------------ -applicationName | The name of the application to use in the generated report. | Required |   -reportFormat | The format of the report to be generated. Allowed values are: HTML, XML, VULN, or ALL. The default value is HTML.| Optional | HTML -reportOutputDirectory | The directory where dependency-check will store data used for analysis. Defaults to the current working directory. | Optional |   -failBuildOn | If set and a CVE is found that is greater then the specified value the build will fail. The default value is 11 which means that the build will not fail. Valid values are 0-11. | Optional | 11 -autoUpdate | If set to false the NVD CVE data is not automatically updated. Setting this to false could result in false negatives. However, this may be required in some environments. | Optional | true -dataDirectory | The directory where dependency-check will store data used for analysis. Defaults to a folder called, called 'dependency-check-data', that is in the same directory as the dependency-check-ant jar file was installed in. *It is not recommended to change this.* | Optional |   -logFile | The file path to write verbose logging information. | Optional |   -suppressionFile | An XML file conforming to the suppression schema that suppresses findings; this is used to hide [false positives](../suppression.html). | Optional |   -proxyUrl | Defines the proxy used to connect to the Internet. | Optional |   -proxyPort | Defines the port for the proxy. | Optional |   -proxyUsername | Defines the proxy user name. | Optional |   -proxyPassword | Defines the proxy password. | Optional |   -connectionTimeout | The connection timeout used when downloading data files from the Internet. | Optional |   -nexusAnalyzerEnabled | The connection timeout used when downloading data files from the Internet. | Optional |   -nexusUrl | The connection timeout used when downloading data files from the Internet. | Optional |   -nexusUsesProxy | Whether or not the defined proxy should be used when connecting to Nexus. | Optional | true -databaseDriverName | The name of the database driver. Example: org.h2.Driver. | Optional |   -databaseDriverPath | The path to the database driver JAR file; only used if the driver is not in the class path. | Optional |   -connectionString | The connection string used to connect to the database. | Optional |   -databaseUser | The username used when connecting to the database. | Optional | dcuser -databasePassword | The password used when connecting to the database. | Optional |   -zipExtensions | A comma-separated list of additional file extensions to be treated like a ZIP file, the contents will be extracted and analyzed. | Optional |   -cveUrl12Modified | URL for the modified CVE 1.2 | Optional | http://nvd.nist.gov/download/nvdcve-modified.xml -cveUrl20Modified | URL for the modified CVE 2.0 | Optional | http://static.nvd.nist.gov/feeds/xml/cve/nvdcve-2.0-modified.xml -cveUrl12Base | Base URL for each year's CVE 1.2, the %d will be replaced with the year | Optional | http://nvd.nist.gov/download/nvdcve-%d.xml -cveUrl20Base | Base URL for each year's CVE 2.0, the %d will be replaced with the year | Optional | http://static.nvd.nist.gov/feeds/xml/cve/nvdcve-2.0-%d.xml -pathToMono | The path to Mono for .NET assembly analysis on non-windows systems | Optional |   +Configuration +==================== +The following properties can be set on the dependency-check-maven plugin. + +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 +externalReport | When using as a Site plugin this parameter sets whether or not the external report format should be used. | false +outputDirectory | The location to write the report(s). Note, this is not used if generating the report as part of a `mvn site` build | 'target' +failBuildOnCVSS | Specifies if the build should be failed if a CVSS score above a specified level is identified. The default is 11 which means 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). This configuration option has no affect if using this within the Site plugin unless the externalReport is set to true. | HTML +logFile | The file path to write verbose logging information. |   +suppressionFile | The file path to the XML suppression file \- used to suppress [false positives](../suppression.html) |   +proxyUrl | The Proxy URL. |   +proxyPort | The Proxy Port. |   +proxyUsername | Defines the proxy user name. |   +proxyPassword | Defines the proxy password. |   +connectionTimeout | The URL Connection Timeout. |   + +Analyzer Configuration +==================== +The following properties are used to configure the various file type analyzers. +These properties can be used to turn off specific analyzers if it is not needed. +Note, that specific analyzers will automatically disable themselves if no file +types that they support are detected - so specifically disabling them may not +be needed. + +Property | Description | Default Value +------------------------|------------------------------------|------------------ +archiveAnalyzerEnabled | 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. |   +jarAnalyzer | Sets whether Jar Analyzer will be used. | true +nexusAnalyzerEnabled | Sets whether Nexus Analyzer will be used. | true +nexusUrl | Defines the Nexus URL. | http://repository.sonatype.org/service/local/ +nexusUsesProxy | Whether or not the defined proxy should be used when connecting to Nexus. | true +nuspecAnalyzerEnabled | Sets whether or not the .NET Nuget Nuspec Analyzer will be used. | true +assemblyAnalyzerEnabled | 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 |   + +Advanced Configuration +==================== +The following properties can be configured in the plugin. 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. + +Property | Description | Default Value +---------------------|-------------------------------------------------------------------------|------------------ +cveUrl12Modified | URL for the modified CVE 1.2 | http://nvd.nist.gov/download/nvdcve-modified.xml +cveUrl20Modified | URL for the modified CVE 2.0 | http://static.nvd.nist.gov/feeds/xml/cve/nvdcve-2.0-modified.xml +cveUrl12Base | Base URL for each year's CVE 1.2, the %d will be replaced with the year | http://nvd.nist.gov/download/nvdcve-%d.xml +cveUrl20Base | Base URL for each year's CVE 2.0, the %d will be replaced with the year | http://static.nvd.nist.gov/feeds/xml/cve/nvdcve-2.0-%d.xml +dataDirectory | Data directory to hold SQL CVEs contents. This should generally not be changed. |   +databaseDriverName | The name of the database driver. Example: org.h2.Driver. |   +databaseDriverPath | The path to the database driver JAR file; only used if the driver is not in the class path. |   +connectionString | The connection string used to connect to the database. |   +databaseUser | The username used when connecting to the database. |   +databasePassword | The password used when connecting to the database. |   diff --git a/dependency-check-cli/src/site/markdown/arguments.md b/dependency-check-cli/src/site/markdown/arguments.md index 2e164ed2f..d15ecbc61 100644 --- a/dependency-check-cli/src/site/markdown/arguments.md +++ b/dependency-check-cli/src/site/markdown/arguments.md @@ -1,33 +1,43 @@ Command Line Arguments -==================== +====================== The following table lists the command line arguments: Short | Argument Name | Parameter | Description | Requirement -------|-----------------------|-----------------|-------------|------------ \-a | \-\-app | \ | The name of the application being scanned. This is a required argument. | Required - \-c | \-\-connectiontimeout | \ | The connection timeout (in milliseconds) to use when downloading resources. | Optional - \-d | \-\-data | \ | The location of the data directory used to store persistent data. This option should generally not be set. | Optional + \-s | \-\-scan | \ | The path to scan \- this option can be specified multiple times. | Required + \-o | \-\-out | \ | The folder to write reports to. This defaults to the current directory. | Optional \-f | \-\-format | \ | The output format to write to (XML, HTML, VULN, ALL). The default is HTML. | Required - \-h | \-\-help | | Print the help message. | Optional \-l | \-\-log | \ | The file path to write verbose logging information. | Optional \-n | \-\-noupdate | | Disables the automatic updating of the CPE data. | Optional - \-o | \-\-out | \ | The folder to write reports to. This defaults to the current directory. | Optional - \-p | \-\-proxyport | \ | The proxy port to use when downloading resources. | Optional - | \-\-proxypass | \ | The proxy password to use when downloading resources. | Optional - | \-\-proxyuser | \ | The proxy username to use when downloading resources. | Optional - \-s | \-\-scan | \ | The path to scan \- this option can be specified multiple times. | Required | \-\-suppression | \ | The file path to the suppression XML file; used to suppress [false positives](../suppression.html). | Optional - \-u | \-\-proxyurl | \ | The proxy url to use when downloading resources. | Optional - \-v | \-\-version | | Print the version information. | Optional + \-h | \-\-help | | Print the help message. | Optional | \-\-advancedHelp | | Print the advanced help message. | Optional - | \-\-connectionString | \ | The connection string to the database. | Optional - | \-\-dbDriverName | \ | The database driver name. | Optional - | \-\-dbDriverPath | \ | The path to the database driver; note, this does not need to be set unless the JAR is outside of the class path. | Optional - | \-\-dbPassword | \ | The password for connecting to the database. | Optional - | \-\-dbUser | \ | The username used to connect to the database. | Optional - | \-\-disableNexus | | Disable the Nexus Analyzer. | Optional - | \-\-nexus | \ | The url to the Nexus Server. | Optional - | \-\-nexusUsesProxy | \ | Whether or not the defined proxy should be used when connecting to Nexus. | Optional - | \-\-zipExtensions | \ | A comma-separated list of additional file extensions to be treated like a ZIP file, the contents will be extracted and analyzed. | Optional - | \-\-pathToMono | \ | The path to Mono for .NET Assembly analysis on non-windows systems. | Optional \ No newline at end of file + \-v | \-\-version | | Print the version information. | Optional + +Advanced Options +================ +Short | Argument Name | Parameter | Description | Default Value +-------|-----------------------|-----------------|-------------|--------------- + | \-\-disableArchive | | Sets whether the Archive Analyzer will be used. | false + | \-\-zipExtensions | \ | A comma-separated list of additional file extensions to be treated like a ZIP file, the contents will be extracted and analyzed. |   + | \-\-disableJar | | Sets whether Jar Analyzer will be used. | false + | \-\-disableNexus | | Sets whether Nexus Analyzer will be used. | false + | \-\-disableNexus | | Disable the Nexus Analyzer. |   + | \-\-nexus | \ | The url to the Nexus Server. | http://repository.sonatype.org/service/local/ + | \-\-nexusUsesProxy | \ | Whether or not the defined proxy should be used when connecting to Nexus. | true + | \-\-disableNuspec | | Sets whether or not the .NET Nuget Nuspec Analyzer will be used. | false + | \-\-disableAssembly | | Sets whether or not the .NET Assembly Analyzer should be used. | false + | \-\-pathToMono | \ | The path to Mono for .NET Assembly analysis on non-windows systems. |   + | \-\-proxyurl | \ | The proxy url to use when downloading resources. |   + | \-\-proxyport | \ | The proxy port to use when downloading resources. |   + | \-\-connectiontimeout | \ | The connection timeout (in milliseconds) to use when downloading resources. |   + | \-\-proxypass | \ | The proxy password to use when downloading resources. |   + | \-\-proxyuser | \ | The proxy username to use when downloading resources. |   + | \-\-connectionString | \ | The connection string to the database. |   + | \-\-dbDriverName | \ | The database driver name. |   + | \-\-dbDriverPath | \ | The path to the database driver; note, this does not need to be set unless the JAR is outside of the class path. |   + | \-\-dbPassword | \ | The password for connecting to the database. |   + | \-\-dbUser | \ | The username used to connect to the database. |   + \-d | \-\-data | \ | The location of the data directory used to store persistent data. This option should generally not be set. |   diff --git a/dependency-check-cli/src/site/markdown/installation.md.vm b/dependency-check-cli/src/site/markdown/installation.md.vm index 1f9a8f1e0..504de5fcf 100644 --- a/dependency-check-cli/src/site/markdown/installation.md.vm +++ b/dependency-check-cli/src/site/markdown/installation.md.vm @@ -8,20 +8,18 @@ script executable: $ chmod +777 dependency-check.sh To scan a folder on the system you can run: +#set( $H = '#' ) -Windows -------- +$H$H$H Windows dependency-check.bat --app "My App Name" --scan "c:\java\application\lib" -\*nix -------- +$H$H$H *nix dependency-check.sh --app "My App Name" --scan "/java/application/lib" To view the command line arguments, see the arguments page, or you can run: -Windows -------- + +$H$H$H Windows dependency-check.bat --help -\*nix -------- +$H$H$H *nix dependency-check.sh --help \ No newline at end of file diff --git a/dependency-check-maven/src/site/markdown/configuration.md b/dependency-check-maven/src/site/markdown/configuration.md index 3d6f23cf5..b722e1fa9 100644 --- a/dependency-check-maven/src/site/markdown/configuration.md +++ b/dependency-check-maven/src/site/markdown/configuration.md @@ -11,28 +11,51 @@ failBuildOnCVSS | Specifies if the build should be failed if a CVSS score a format | 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. | HTML logFile | The file path to write verbose logging information. |   suppressionFile | The file path to the XML suppression file \- used to suppress [false positives](../suppression.html) |   -connectionTimeout | The Connection Timeout. |   -nexusAnalyzerEnabled | Sets whether Nexus Analyzer will be used. |   -nexusUrl | Defines the Nexus URL. |   -nexusUsesProxy | Whether or not the defined proxy should be used when connecting to Nexus. | true -databaseDriverName | The name of the database driver. Example: org.h2.Driver. |   -databaseDriverPath | The path to the database driver JAR file; only used if the driver is not in the class path. |   -connectionString | The connection string used to connect to the database. |   -databaseUser | The username used when connecting to the database. |   -databasePassword | The password used when connecting to the database. |   -zipExtensions | A comma-separated list of additional file extensions to be treated like a ZIP file, the contents will be extracted and analyzed. |   skipTestScope | Should be skip analysis for artifacts with Test Scope | true skipProvidedScope | Should be skip analysis for artifacts with Provided Scope | false skipRuntimeScope | Should be skip analysis for artifacts with Runtime Scope | false -dataDirectory | Data directory to hold SQL CVEs contents. This should generally not be changed. |   -cveUrl12Modified | URL for the modified CVE 1.2 | http://nvd.nist.gov/download/nvdcve-modified.xml -cveUrl20Modified | URL for the modified CVE 2.0 | http://static.nvd.nist.gov/feeds/xml/cve/nvdcve-2.0-modified.xml + +Analyzer Configuration +==================== +The following properties are used to configure the various file type analyzers. +These properties can be used to turn off specific analyzers if it is not needed. +Note, that specific analyzers will automatically disable themselves if no file +types that they support are detected - so specifically disabling them may not +be needed. + +Property | Description | Default Value +------------------------|------------------------------------|------------------ +archiveAnalyzerEnabled | 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. |   +jarAnalyzer | Sets whether Jar Analyzer will be used. | true +nexusAnalyzerEnabled | Sets whether Nexus Analyzer will be used. | true +nexusUrl | Defines the Nexus URL. | http://repository.sonatype.org/service/local/ +nexusUsesProxy | Whether or not the defined proxy should be used when connecting to Nexus. | true +nuspecAnalyzerEnabled | Sets whether or not the .NET Nuget Nuspec Analyzer will be used. | true +assemblyAnalyzerEnabled | 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 |   + +Advanced Configuration +==================== +The following properties can be configured in the plugin. 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. + +Property | Description | Default Value +---------------------|-------------------------------------------------------------------------|------------------ +cveUrl12Modified | URL for the modified CVE 1.2 | http://nvd.nist.gov/download/nvdcve-modified.xml +cveUrl20Modified | URL for the modified CVE 2.0 | http://static.nvd.nist.gov/feeds/xml/cve/nvdcve-2.0-modified.xml cveUrl12Base | Base URL for each year's CVE 1.2, the %d will be replaced with the year | http://nvd.nist.gov/download/nvdcve-%d.xml cveUrl20Base | Base URL for each year's CVE 2.0, the %d will be replaced with the year | http://static.nvd.nist.gov/feeds/xml/cve/nvdcve-2.0-%d.xml -pathToMono | The path to Mono for .NET assembly analysis on non-windows systems |   +connectionTimeout | The URL Connection Timeout. |   +dataDirectory | Data directory to hold SQL CVEs contents. This should generally not be changed. |   +databaseDriverName | The name of the database driver. Example: org.h2.Driver. |   +databaseDriverPath | The path to the database driver JAR file; only used if the driver is not in the class path. |   +connectionString | The connection string used to connect to the database. |   +databaseUser | The username used when connecting to the database. |   +databasePassword | The password used when connecting to the database. |   -Deprecated Properties +Deprecated Configuration ==================== The following properties have been deprecated. These can stell be set in the dependency-check-maven plugin's configuration. However, future versions diff --git a/dependency-check-maven/src/site/markdown/usage.md.vm b/dependency-check-maven/src/site/markdown/usage.md.vm index 33bdaea06..c04b26e9f 100644 --- a/dependency-check-maven/src/site/markdown/usage.md.vm +++ b/dependency-check-maven/src/site/markdown/usage.md.vm @@ -10,8 +10,9 @@ 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. -Example 1: ---------------------- +#set( $H = '#' ) + +$H$H$H Example 1: Create the DependencyCheck-report.html in the target directory ```xml @@ -39,8 +40,7 @@ Create the DependencyCheck-report.html in the target directory ``` -Example 2: ---------------------- +$H$H$H Example 2: Create the DependencyCheck-report.html and fail the build for CVSS greater then 8 ```xml @@ -71,8 +71,7 @@ Create the DependencyCheck-report.html and fail the build for CVSS greater then ``` -Example 3: ---------------------- +$H$H$H Example 3: Create the dependency-check report within the site ```xml @@ -103,8 +102,8 @@ Create the dependency-check report within the site ... ``` -Example 4: ---------------------- + +$H$H$H Example 4: Create the DependencyCheck-report.html and skip artifacts no bundled in distribution (Provided and Runtime scope) ```xml @@ -135,8 +134,8 @@ Create the DependencyCheck-report.html and skip artifacts no bundled in distribu ... ``` -Example 5: ---------------------- + +$H$H$H Example 5: Create the DependencyCheck-report.html and use internal mirroring of CVE contents ```xml @@ -169,4 +168,3 @@ Create the DependencyCheck-report.html and use internal mirroring of CVE content ... ``` -