From 0c5dfdbe248d27690ff35aad062a4e8f6f4b1cbb Mon Sep 17 00:00:00 2001 From: Jeremy Long Date: Mon, 4 May 2015 06:21:46 -0400 Subject: [PATCH] added more documentation Former-commit-id: 1f3ef3a136bf05da797236b898371b4f7edb56a4 --- src/site/markdown/data/database.md | 33 +++++++++++++++++++++++++++++ src/site/markdown/data/index.md | 25 ++++++++++++++++++++++ src/site/markdown/data/mirrornvd.md | 16 ++++++++++++++ src/site/markdown/data/proxy.md | 11 ++++++++++ 4 files changed, 85 insertions(+) create mode 100644 src/site/markdown/data/database.md create mode 100644 src/site/markdown/data/index.md create mode 100644 src/site/markdown/data/mirrornvd.md create mode 100644 src/site/markdown/data/proxy.md diff --git a/src/site/markdown/data/database.md b/src/site/markdown/data/database.md new file mode 100644 index 000000000..e82551d0b --- /dev/null +++ b/src/site/markdown/data/database.md @@ -0,0 +1,33 @@ +Using a Database Server +======================= +Out of the box dependency-check uses a local H2 database. The location of the database +file is configured using the data directory configuration option (see +[CLI](https://jeremylong.github.io/DependencyCheck/dependency-check-cli/arguments.html)). + +Some organizations may want to use a more robust centralized database. Currently, [H2 in +server mode](http://www.h2database.com/html/tutorial.html#using_server) and +[MySQL](https://www.mysql.com/) have been tested. In general, the setup is done by creating +a central database, setting up a single instance of dependency-check, which can connect to the +Internet, that is run in update-only mode once a day. Then the other dependency-check clients +can connect, using a read-only connection, to perform the analysis. Please note that if the +clients are unable to access the Internet the analysis may result in a few false negatives; +see the note about Central [here](./index.html). + +To setup a centralized database the following generalized steps can be used: + +1. Create the database and tables using either [initialize.sql](https://github.com/jeremylong/DependencyCheck/blob/master/dependency-check-core/src/main/resources/data/initialize.sql) +or [initialize_mysql.sql](https://github.com/jeremylong/DependencyCheck/blob/master/dependency-check-core/src/main/resources/data/initialize_mysql.sql). +2. The account that the clients will connect using must have select granted on the tables. + * Note, if the clients performing the scans should run with the noupdate setting. A single + instance of the dependency-check client should be setup with update enabled and the account + used during the update process will need to be granted update rights on the tables. +3. Dependency-check clients running scans will need to be configured to use the central database: + * The database driver will need to be specified using the dbDriver and if the driver is not + already in the classpath the dbDriverPath options will need to be set (see the specific configuration + options for Maven, Ant, CLI, and Jenkins). + * The connection string, database user name, and the database user's password will also need to be configured. + +Depending on the database being used, you may need to customize the [dbStatements.properties](https://github.com/jeremylong/DependencyCheck/blob/master/dependency-check-core/src/main/resources/data/dbStatements.properties). + +As always, feel free to open an [issue](https://github.com/jeremylong/DependencyCheck/issues) +or post a question to the [dependency-check google group](https://groups.google.com/forum/#!forum/dependency-check). diff --git a/src/site/markdown/data/index.md b/src/site/markdown/data/index.md new file mode 100644 index 000000000..4059f1864 --- /dev/null +++ b/src/site/markdown/data/index.md @@ -0,0 +1,25 @@ +Local Database Updates +==================== +OWASP dependency-check maintains a local copy of the NVD data hosted by NIST. By default, +a local [H2 database](http://www.h2database.com/html/main.html) instance is used. +This works well for local storage of the NVD data used by dependency-check. This requires +each instance of dependency-check to create its own database and the machine will need access +to nvd.nist.gov in order to download the NVD data feeds. While the initial download of the NVD +data feed is large, if after the initial download the tool is run at least once every seven +days only two small XML files containing the recent modifications will need to be downloaded. + +If your build servers are using dependency-check and are unable to access the Internet you +have a few options: + +1) Configure the [proxy settings](proxy.md) so that the build server can access the Internet +2) [Mirror the NVD](./mirrornvd.md) locally within your organization +3) Use a more robust [centralized database](./database.md) with a single update node + +However, if the machine that is running dependency-check cannot reach the [Central Repository](http://search.maven.org) +the analysis may result in false negatives. This is because some POM files, that are not +contained within the JAR file itself, contain evidence that is used to create an accurate +library identification. If Central cannot be reached, it is highly recommended to setup a +Nexus server within your organization and to configure dependency-check to use the local +Nexus server if the machine running dependency-check cannot connect to the Internet. +**Note**, even with a Nexus server setup I have seen dependency-check be directed to other +repositories on the Internet to download the actual POM file. diff --git a/src/site/markdown/data/mirrornvd.md b/src/site/markdown/data/mirrornvd.md new file mode 100644 index 000000000..b7cbfd2e4 --- /dev/null +++ b/src/site/markdown/data/mirrornvd.md @@ -0,0 +1,16 @@ +Mirroring the NVD from NIST +=========================== +Several organizations have opted to mirror the NVD on an internal server +and have the dependency-check clients simply pull the updates from the +mirror. This setup is fairly simple: + +1) Setup a nightly job to pull down the latest NVD files files from NIST + * See the [Nist-Data-Mirror](https://github.com/stevespringett/nist-data-mirror/) + project on github. + * All of the NVD +2) Configure the dependency-check clients to use the internal CVE urls. Note, all four URLs + must be specified (see the configuration for the specific dependency-check client used): + * cveUrl12Modified + * cveUrl20Modified + * cveUrl12Base + * cveUrl20Base diff --git a/src/site/markdown/data/proxy.md b/src/site/markdown/data/proxy.md new file mode 100644 index 000000000..e6fdf6a63 --- /dev/null +++ b/src/site/markdown/data/proxy.md @@ -0,0 +1,11 @@ +Proxy Configuration +=================== +All of the dependency-check clients (CLI, Maven, Ant, Jenkins) can be configured +to use a proxy to connect to the Internet. See the configuration settings for each: + +* [Ant Task](https://jeremylong.github.io/DependencyCheck/dependency-check-ant/configuration.html) +* [Command Line](https://jeremylong.github.io/DependencyCheck/dependency-check-cli/arguments.html) +* [Maven Plugin](https://jeremylong.github.io/DependencyCheck/dependency-check-maven/configuration.html) + +Note, it may also be possible to use the core [Java proxy](https://docs.oracle.com/javase/8/docs/technotes/guides/net/proxies.html) +system properties instead of the configuration above.