Add an update only option

Former-commit-id: 67253232762acb61e1400dc60443e556f71db874

dependency-check-ant/src/main/java/org/owasp/dependencycheck/taskdefs/DependencyCheckTask.java

@@ -261,6 +261,27 @@ public class DependencyCheckTask extends Task {
     public void setAutoUpdate(boolean autoUpdate) {
         this.autoUpdate = autoUpdate;
     }
+
+    private boolean updateOnly = false;
+
+    /**
+     * Get the value of updateOnly
+     *
+     * @return the value of updateOnly
+     */
+    public boolean isUpdateOnly() {
+        return updateOnly;
+    }
+
+    /**
+     * Set the value of updateOnly
+     *
+     * @param updateOnly new value of updateOnly
+     */
+    public void setUpdateOnly(boolean updateOnly) {
+        this.updateOnly = updateOnly;
+    }
+
     /**
      * 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. Default is HTML.
@@ -912,7 +933,11 @@ public class DependencyCheckTask extends Task {
         Engine engine = null;
         try {
             engine = new Engine(DependencyCheckTask.class.getClassLoader());
-
+            //todo - should this be its own task?
+            if (updateOnly) {
+                engine.doUpdates();
+            } else {
+                try {
                     for (Resource resource : path) {
                         final FileProvider provider = resource.as(FileProvider.class);
                         if (provider != null) {
@@ -922,7 +947,7 @@ public class DependencyCheckTask extends Task {
                             }
                         }
                     }
-            try {
+
                     engine.analyzeDependencies();
                     DatabaseProperties prop = null;
                     CveDB cve = null;
@@ -953,6 +978,7 @@ public class DependencyCheckTask extends Task {
                     LOGGER.log(Level.FINE, "An exception occurred; unable to continue task", ex);
                     throw new BuildException("An exception occurred; unable to continue task", ex);
                 }
+            }
         } catch (DatabaseException ex) {
             LOGGER.log(Level.SEVERE, "Unable to connect to the dependency-check database; analysis has stopped");
             LOGGER.log(Level.FINE, "", ex);

dependency-check-ant/src/site/markdown/configuration.md

@@ -26,6 +26,7 @@ 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
+updateOnly           | If set to true only the update phase of dependency-check will be executed; no scan will be executed and no report will be generated. | false
 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
@@ -53,7 +54,7 @@ zipExtensions           | A comma-separated list of additional file extensions t
 jarAnalyzer             | Sets whether the Jar Analyzer will be used.                                   | true
 centralAnalyzerEnabled  | Sets whether the Central Analyzer will be used. **Disabling this analyzer is not recommended as it could lead to false negatives (e.g. libraries that have vulnerabilities may not be reported correctly).** If this analyzer is being disabled there is a good chance you also want to disable the Nexus Analyzer (see below).                                  | true
 nexusAnalyzerEnabled    | 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 Pro URL. If not set the Nexus Analyzer will be disabled. |  
+nexusUrl                | Defines the Nexus web service endpoint (example http://domain.enterprise/nexus/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
 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

dependency-check-cli/src/main/java/org/owasp/dependencycheck/App.java

@@ -95,6 +95,9 @@ public class App {
 
         if (cli.isGetVersion()) {
             cli.printVersionInfo();
+        } else if (cli.isUpdateOnly()) {
+            populateSettings(cli);
+            runUpdateOnly();
         } else if (cli.isRunScan()) {
             populateSettings(cli);
             try {
@@ -212,11 +215,29 @@ public class App {
         }
     }
 
+    /**
+     * Only executes the update phase of dependency-check.
+     */
+    private void runUpdateOnly() {
+        Engine engine = null;
+        try {
+            engine = new Engine();
+            engine.doUpdates();
+        } catch (DatabaseException ex) {
+            LOGGER.log(Level.SEVERE, "Unable to connect to the dependency-check database; analysis has stopped");
+            LOGGER.log(Level.FINE, "", ex);
+        } finally {
+            if (engine != null) {
+                engine.cleanup();
+            }
+        }
+    }
+
     /**
      * Updates the global Settings.
      *
-     * @param cli a reference to the CLI Parser that contains the command line arguments used to set the corresponding
+     * @param cli a reference to the CLI Parser that contains the command line arguments used to set the corresponding settings in
-     * settings in the core engine.
+     * the core engine.
      */
     private void populateSettings(CliParser cli) {
 

dependency-check-cli/src/main/java/org/owasp/dependencycheck/CliParser.java

@@ -266,6 +266,9 @@ public final class CliParser {
     @SuppressWarnings("static-access")
     private void addAdvancedOptions(final Options options) throws IllegalArgumentException {
 
+        final Option updateOnly = OptionBuilder.withLongOpt(ARGUMENT.UPDATE_ONLY)
+                .withDescription("Only update the local NVD data cache; no scan will be executed.").create();
+
         final Option data = OptionBuilder.withArgName("path").hasArg().withLongOpt(ARGUMENT.DATA_DIRECTORY)
                 .withDescription("The location of the H2 Database file. This option should generally not be set.")
                 .create(ARGUMENT.DATA_DIRECTORY_SHORT);
@@ -319,6 +322,7 @@ public final class CliParser {
         final Option disableNuspecAnalyzer = OptionBuilder.withLongOpt(ARGUMENT.DISABLE_NUSPEC)
                 .withDescription("Disable the Nuspec Analyzer.")
                 .create();
+
         final Option disableAssemblyAnalyzer = OptionBuilder.withLongOpt(ARGUMENT.DISABLE_ASSEMBLY)
                 .withDescription("Disable the .NET Assembly Analyzer.")
                 .create();
@@ -350,7 +354,8 @@ public final class CliParser {
                 .withDescription("The path to Mono for .NET Assembly analysis on non-windows systems.")
                 .create();
 
-        options.addOption(proxyPort)
+        options.addOption(updateOnly)
+                .addOption(proxyPort)
                 .addOption(proxyServer)
                 .addOption(proxyUsername)
                 .addOption(proxyPassword)
@@ -689,12 +694,21 @@ public final class CliParser {
     /**
      * Checks if the auto update feature has been disabled. If it has been disabled via the command line this will return false.
      *
-     * @return if auto-update is allowed.
+     * @return <code>true</code> if auto-update is allowed; otherwise <code>false</code>
      */
     public boolean isAutoUpdate() {
         return (line == null) || !line.hasOption(ARGUMENT.DISABLE_AUTO_UPDATE);
     }
 
+    /**
+     * Checks if the update only flag has been set.
+     *
+     * @return <code>true</code> if the update only flag has been set; otherwise <code>false</code>.
+     */
+    public boolean isUpdateOnly() {
+        return (line == null) || line.hasOption(ARGUMENT.UPDATE_ONLY);
+    }
+
     /**
      * Returns the database driver name if specified; otherwise null is returned.
      *
@@ -770,6 +784,10 @@ public final class CliParser {
          * The short CLI argument name specifying that the CPE/CVE/etc. data should not be automatically updated.
          */
         public static final String DISABLE_AUTO_UPDATE_SHORT = "n";
+        /**
+         * The long CLI argument name specifying that only the update phase should be executed; no scan should be run.
+         */
+        public static final String UPDATE_ONLY = "updateonly";
         /**
          * The long CLI argument name specifying the directory to write the reports to.
          */

dependency-check-cli/src/site/markdown/arguments.md

@@ -20,14 +20,15 @@ Short  | Argument Name   | Parameter       | Description | Requir
 Advanced Options
 ================
 Short  | Argument Name        | Parameter | Description                                     | Default Value
--------|-----------------------|-----------------|-----------------------------------------------------------------------------|---------------
+-------|-----------------------|-----------------|----------------------------------------------------------------------------------|-------------------
  \-P   | \-\-propertyfile      | \<file\>        | Specifies a file that contains properties to use instead of applicaion defaults. | &nbsp;
+       | \-\-updateonly        |                 | If set only the update phase of dependency-check will be executed; no scan will be executed and no report will be generated. | &nbsp;
        | \-\-disableArchive    |                 | Sets whether the Archive Analyzer will be used.                                  | false
        | \-\-zipExtensions     | \<strings\>     | A comma-separated list of additional file extensions to be treated like a ZIP file, the contents will be extracted and analyzed. | &nbsp;
        | \-\-disableJar        |                 | Sets whether the Jar Analyzer will be used.                                      | false
        | \-\-disableCentral    |                 | Sets whether the Central Analyzer will be used. **Disabling this analyzer is not recommended as it could lead to false negatives (e.g. libraries that have vulnerabilities may not be reported correctly).** If this analyzer is being disabled there is a good chance you also want to disable the Nexus Analyzer. | false
        | \-\-disableNexus      |                 | Sets whether the Nexus Analyzer will be used. Note, this has been superceded by the Central Analyzer. However, you can configure the Nexus URL to utilize an internally hosted Nexus Pro server. | false
-       | \-\-nexus             | \<url\>         | The url to the Nexus Pro Server. If not set the Nexus Analyzer will be disabled. | &nbsp;
+       | \-\-nexus             | \<url\>         | The url to the Nexus Server's web service end point (example: http://domain.enterprise/nexus/service/local/). If not set the Nexus Analyzer will be disabled. | &nbsp;
        | \-\-nexusUsesProxy    | \<true\|false\> | 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

dependency-check-core/src/main/java/org/owasp/dependencycheck/Engine.java

@@ -44,9 +44,8 @@ import org.owasp.dependencycheck.utils.InvalidSettingException;
 import org.owasp.dependencycheck.utils.Settings;
 
 /**
- * Scans files, directories, etc. for Dependencies. Analyzers are loaded and used to process the files found by the
+ * Scans files, directories, etc. for Dependencies. Analyzers are loaded and used to process the files found by the scan, if a
- * scan, if a file is encountered and an Analyzer is associated with the file type then the file is turned into a
+ * file is encountered and an Analyzer is associated with the file type then the file is turned into a dependency.
- * dependency.
  *
  * @author Jeremy Long <jeremy.long@owasp.org>
  */
@@ -163,8 +162,8 @@ public class Engine {
     }
 
     /**
-     * Scans an array of files or directories. If a directory is specified, it will be scanned recursively. Any
+     * Scans an array of files or directories. If a directory is specified, it will be scanned recursively. Any dependencies
-     * dependencies identified are added to the dependency collection.
+     * identified are added to the dependency collection.
      *
      * @param paths an array of paths to files or directories to be analyzed
      * @return the list of dependencies scanned
@@ -184,8 +183,8 @@ public class Engine {
     }
 
     /**
-     * Scans a given file or directory. If a directory is specified, it will be scanned recursively. Any dependencies
+     * Scans a given file or directory. If a directory is specified, it will be scanned recursively. Any dependencies identified
-     * identified are added to the dependency collection.
+     * are added to the dependency collection.
      *
      * @param path the path to a file or directory to be analyzed
      * @return the list of dependencies scanned
@@ -196,8 +195,8 @@ public class Engine {
     }
 
     /**
-     * Scans an array of files or directories. If a directory is specified, it will be scanned recursively. Any
+     * Scans an array of files or directories. If a directory is specified, it will be scanned recursively. Any dependencies
-     * dependencies identified are added to the dependency collection.
+     * identified are added to the dependency collection.
      *
      * @param files an array of paths to files or directories to be analyzed.
      * @return the list of dependencies
@@ -216,8 +215,8 @@ public class Engine {
     }
 
     /**
-     * Scans a list of files or directories. If a directory is specified, it will be scanned recursively. Any
+     * Scans a list of files or directories. If a directory is specified, it will be scanned recursively. Any dependencies
-     * dependencies identified are added to the dependency collection.
+     * identified are added to the dependency collection.
      *
      * @param files a set of paths to files or directories to be analyzed
      * @return the list of dependencies scanned
@@ -236,8 +235,8 @@ public class Engine {
     }
 
     /**
-     * Scans a list of files or directories. If a directory is specified, it will be scanned recursively. Any
+     * Scans a list of files or directories. If a directory is specified, it will be scanned recursively. Any dependencies
-     * dependencies identified are added to the dependency collection.
+     * identified are added to the dependency collection.
      *
      * @param files a set of paths to files or directories to be analyzed
      * @return the list of dependencies scanned
@@ -256,8 +255,8 @@ public class Engine {
     }
 
     /**
-     * Scans a given file or directory. If a directory is specified, it will be scanned recursively. Any dependencies
+     * Scans a given file or directory. If a directory is specified, it will be scanned recursively. Any dependencies identified
-     * identified are added to the dependency collection.
+     * are added to the dependency collection.
      *
      * @param file the path to a file or directory to be analyzed
      * @return the list of dependencies scanned
@@ -468,7 +467,7 @@ public class Engine {
     /**
      * Cycles through the cached web data sources and calls update on all of them.
      */
-    private void doUpdates() {
+    public void doUpdates() {
         LOGGER.info("Checking for updates");
         final UpdateService service = new UpdateService(serviceClassLoader);
         final Iterator<CachedWebDataSource> iterator = service.getDataSources();

dependency-check-maven/src/main/java/org/owasp/dependencycheck/maven/Engine.java

@@ -27,8 +27,8 @@ import org.owasp.dependencycheck.data.nvdcve.DatabaseException;
 import org.owasp.dependencycheck.utils.Settings;
 
 /**
- * A modified version of the core engine specifically designed to persist some
+ * A modified version of the core engine specifically designed to persist some data between multiple executions of a multi-module
- * data between multiple executions of a multi-module Maven project.
+ * Maven project.
  *
  * @author Jeremy Long <jeremy.long@owasp.org>
  */
@@ -51,8 +51,7 @@ public class Engine extends org.owasp.dependencycheck.Engine {
      */
     private List<MavenProject> reactorProjects;
     /**
-     * Key used in the MavenProject context values to note whether or not an
+     * Key used in the MavenProject context values to note whether or not an update has been executed.
-     * update has been executed.
      */
     public static final String UPDATE_EXECUTED_FLAG = "dependency-check-update-executed";
 
@@ -60,10 +59,8 @@ public class Engine extends org.owasp.dependencycheck.Engine {
      * Creates a new Engine to perform anyalsis on dependencies.
      *
      * @param project the current Maven project
-     * @param reactorProjects the reactor projects for the current Maven
+     * @param reactorProjects the reactor projects for the current Maven execution
-     * execution
+     * @throws DatabaseException thrown if there is an issue connecting to the database
-     * @throws DatabaseException thrown if there is an issue connecting to the
-     * database
      */
     public Engine(MavenProject project, List<MavenProject> reactorProjects) throws DatabaseException {
         this.currentProject = project;
@@ -91,18 +88,28 @@ public class Engine extends org.owasp.dependencycheck.Engine {
         }
     }
 
+    /**
+     * Runs the update steps of dependency-check.
+     */
+    public void update() {
+        final MavenProject root = getExecutionRoot();
+        if (root != null && root.getContextValue(UPDATE_EXECUTED_FLAG) != null) {
+            System.setProperty(Settings.KEYS.AUTO_UPDATE, Boolean.FALSE.toString());
+        }
+        this.doUpdates();
+    }
+
     /**
      * This constructor should not be called. Use Engine(MavenProject) instead.
      *
-     * @throws DatabaseException thrown if there is an issue connecting to the
+     * @throws DatabaseException thrown if there is an issue connecting to the database
-     * database
      */
     private Engine() throws DatabaseException {
     }
 
     /**
-     * Initializes the given analyzer. This skips the initialization of the
+     * Initializes the given analyzer. This skips the initialization of the CPEAnalyzer if it has been initialized by a previous
-     * CPEAnalyzer if it has been initialized by a previous execution.
+     * execution.
      *
      * @param analyzer the analyzer to initialize
      * @return the initialized analyzer
@@ -121,8 +128,7 @@ public class Engine extends org.owasp.dependencycheck.Engine {
     }
 
     /**
-     * Releases resources used by the analyzers by calling close() on each
+     * Releases resources used by the analyzers by calling close() on each analyzer.
-     * analyzer.
      */
     @Override
     public void cleanup() {
@@ -209,10 +215,8 @@ public class Engine extends org.owasp.dependencycheck.Engine {
     }
 
     /**
-     * Resets the file type analyzers so that they can be re-used to scan
+     * Resets the file type analyzers so that they can be re-used to scan additional directories. Without the reset the analyzer
-     * additional directories. Without the reset the analyzer might be disabled
+     * might be disabled because the first scan/analyze did not identify any files that could be processed by the analyzer.
-     * because the first scan/analyze did not identify any files that could be
-     * processed by the analyzer.
      */
     public void resetFileTypeAnalyzers() {
         for (FileTypeAnalyzer a : getFileTypeAnalyzers()) {

dependency-check-maven/src/main/java/org/owasp/dependencycheck/maven/UpdateMojo.java

@@ -0,0 +1,101 @@
+/*
+ * This file is part of dependency-check-maven.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * Copyright (c) 2013 Jeremy Long. All Rights Reserved.
+ */
+package org.owasp.dependencycheck.maven;
+
+import java.util.Locale;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+import org.apache.maven.artifact.Artifact;
+import org.apache.maven.plugin.MojoExecutionException;
+import org.apache.maven.plugin.MojoFailureException;
+import org.apache.maven.plugins.annotations.LifecyclePhase;
+import org.apache.maven.plugins.annotations.Mojo;
+import org.apache.maven.plugins.annotations.ResolutionScope;
+import org.owasp.dependencycheck.data.nvdcve.DatabaseException;
+import org.owasp.dependencycheck.utils.Settings;
+
+/**
+ * Maven Plugin that checks the project dependencies to see if they have any known published vulnerabilities.
+ *
+ * @author Jeremy Long <jeremy.long@owasp.org>
+ */
+@Mojo(
+        name = "update-only",
+        defaultPhase = LifecyclePhase.GENERATE_RESOURCES,
+        threadSafe = true,
+        requiresDependencyResolution = ResolutionScope.NONE,
+        requiresOnline = true
+)
+public class UpdateMojo extends BaseDependencyCheckMojo {
+
+    /**
+     * Logger field reference.
+     */
+    private static final Logger LOGGER = Logger.getLogger(UpdateMojo.class.getName());
+
+    /**
+     * Returns false; this mojo cannot generate a report.
+     *
+     * @return <code>false</code>
+     */
+    @Override
+    public boolean canGenerateReport() {
+        return false;
+    }
+
+    /**
+     * Executes the dependency-check engine on the project's dependencies and generates the report.
+     *
+     * @throws MojoExecutionException thrown if there is an exception executing the goal
+     * @throws MojoFailureException thrown if dependency-check is configured to fail the build
+     */
+    @Override
+    public void runCheck() throws MojoExecutionException, MojoFailureException {
+        final Engine engine;
+        try {
+            engine = initializeEngine();
+            engine.update();
+        } catch (DatabaseException ex) {
+            LOGGER.log(Level.FINE, "Database connection error", ex);
+            throw new MojoExecutionException("An exception occured connecting to the local database. Please see the log file for more details.", ex);
+        }
+        engine.cleanup();
+        Settings.cleanup();
+    }
+
+    /**
+     * Returns the report name.
+     *
+     * @param locale the location
+     * @return the report name
+     */
+    public String getName(Locale locale) {
+        return "dependency-check-update";
+    }
+
+    /**
+     * Gets the description of the Dependency-Check report to be displayed in the Maven Generated Reports page.
+     *
+     * @param locale The Locale to get the description for
+     * @return the description
+     */
+    public String getDescription(Locale locale) {
+        return "Updates the local cache of the NVD data from NIST.";
+    }
+
+}

dependency-check-maven/src/site/markdown/configuration.md

@@ -2,9 +2,10 @@ Goals
 ====================
 
 Goal        | Description
------------|-----------------------
+------------|-----------------------
 aggregate   | Runs dependency-check against the child projects and aggregates the results into a single report.
 check       | Runs dependency-check against the project and generates a report.
+update-only | Updates the local cache of the NVD data from NIST.
 
 Configuration
 ====================
@@ -38,7 +39,7 @@ zipExtensions           | A comma-separated list of additional file extensions t
 jarAnalyzer             | Sets whether Jar Analyzer will be used.                                   | true
 centralAnalyzerEnabled  | 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
 nexusAnalyzerEnabled    | 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 Pro Server URL. If not set the Nexus Analyzer will be disabled. |  
+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
 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

dependency-check-maven/src/site/markdown/usage.md.vm

@@ -176,3 +176,33 @@ Create the DependencyCheck-report.html and use internal mirroring of CVE content
     ...
 </project>
 ```
+
+$H$H$H Example 6:
+Update the local cache of the NVD data from NIST without analyzing the dependencies.
+
+```xml
+<project>
+    ...
+    <build>
+        ...
+        <plugins>
+            ...
+            <plugin>
+                <groupId>org.owasp</groupId>
+                <artifactId>dependency-check-maven</artifactId>
+                <version>${project.version}</version>
+                <executions>
+                    <execution>
+                        <goals>
+                            <goal>update-only</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+            ...
+        </plugins>
+        ...
+    </build>
+    ...
+</project>
+```