Package org.owasp.dependencycheck

Class Engine

  • All Implemented Interfaces:
    java.io.FileFilter, java.lang.AutoCloseable
    @NotThreadSafe
public class Engine
extends java.lang.Object
implements java.io.FileFilter, java.lang.AutoCloseable
    Scans files, directories, etc. for Dependencies. Analyzers are loaded and used to process the files found by the scan, if a file is encountered and an Analyzer is associated with the file type then the file is turned into a dependency.
    Author:
    Jeremy Long

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  Engine.Mode
      Engine execution modes.

    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      boolean accept​(@Nullable java.io.File file)
      Checks all analyzers to see if an extension is supported.
      void addDependency​(Dependency dependency)
      Adds a dependency.
      protected void addFileTypeAnalyzer​(@NotNull FileTypeAnalyzer fta)
      Adds a file type analyzer.
      void analyzeDependencies()
      Runs the analyzers against all of the dependencies.
      void close()
      Properly cleans up resources allocated during analysis.
      protected void closeAnalyzer​(@NotNull Analyzer analyzer)
      Closes the given analyzer.
      boolean doUpdates()
      Cycles through the cached web data sources and calls update on all of them.
      boolean doUpdates​(boolean remainOpen)
      Cycles through the cached web data sources and calls update on all of them.
      protected void executeAnalysisTasks​(@NotNull Analyzer analyzer, java.util.List<java.lang.Throwable> exceptions)
      Executes executes the analyzer using multiple threads.
      protected java.util.List<AnalysisTask> getAnalysisTasks​(Analyzer analyzer, java.util.List<java.lang.Throwable> exceptions)
      Returns the analysis tasks for the dependencies.
      @NotNull java.util.List<Analyzer> getAnalyzers()
      Returns a full list of all of the analyzers.
      java.util.List<Analyzer> getAnalyzers​(AnalysisPhase phase)
      Get the List of the analyzers for a specific phase of analysis.
      CveDB getDatabase()
      Returns a reference to the database.
      Dependency[] getDependencies()
      Returns a copy of the dependencies as an array.
      protected java.util.concurrent.ExecutorService getExecutorService​(Analyzer analyzer)
      Returns the executor service for a given analyzer.
      java.util.Set<FileTypeAnalyzer> getFileTypeAnalyzers()
      Returns the set of file type analyzers.
      Engine.Mode getMode()
      Returns the mode of the engine.
      java.lang.Object getObject​(java.lang.String key)
      Retrieve an object from the objects collection.
      Settings getSettings()
      Returns the configured settings.
      boolean hasObject​(java.lang.String key)
      Verifies if the object exists in the object store.
      protected void initializeAnalyzer​(@NotNull Analyzer analyzer)
      Initializes the given analyzer.
      protected void initializeEngine()
      Creates a new Engine using the specified classloader to dynamically load Analyzer and Update services.
      void openDatabase()
      This method is only public for unit/integration testing.
      void openDatabase​(boolean readOnly, boolean lockRequired)
      This method is only public for unit/integration testing.
      boolean purge()
      Purges the cached web data sources.
      void putObject​(java.lang.String key, java.lang.Object object)
      Put an object in the object collection.
      void removeDependency​(@NotNull Dependency dependency)
      Removes the dependency.
      void removeObject​(java.lang.String key)
      Removes an object from the object store.
      @Nullable java.util.List<Dependency> scan​(@NotNull java.io.File file, java.lang.String projectReference)
      Scans a given file or directory.
      java.util.List<Dependency> scan​(@NotNull java.lang.String path)
      Scans a given file or directory.
      java.util.List<Dependency> scan​(@NotNull java.lang.String[] paths)
      Scans an array of files or directories.
      java.util.List<Dependency> scan​(@NotNull java.lang.String[] paths, @Nullable java.lang.String projectReference)
      Scans an array of files or directories.
      java.util.List<Dependency> scan​(@NotNull java.lang.String path, java.lang.String projectReference)
      Scans a given file or directory.
      java.util.List<Dependency> scan​(java.io.File file)
      Scans a given file or directory.
      java.util.List<Dependency> scan​(java.io.File[] files)
      Scans an array of files or directories.
      java.util.List<Dependency> scan​(java.io.File[] files, java.lang.String projectReference)
      Scans an array of files or directories.
      java.util.List<Dependency> scan​(java.util.Collection<java.io.File> files)
      Scans a collection of files or directories.
      java.util.List<Dependency> scan​(java.util.Collection<java.io.File> files, java.lang.String projectReference)
      Scans a collection of files or directories.
      protected java.util.List<Dependency> scanDirectory​(@NotNull java.io.File dir, @Nullable java.lang.String projectReference)
      Recursively scans files and directories.
      protected java.util.List<Dependency> scanDirectory​(java.io.File dir)
      Recursively scans files and directories.
      protected Dependency scanFile​(@NotNull java.io.File file)
      Scans a specified file.
      protected Dependency scanFile​(@NotNull java.io.File file, @Nullable java.lang.String projectReference)
      Scans a specified file.
      void setDependencies​(@NotNull java.util.List<Dependency> dependencies)
      Sets the dependencies.
      void sortDependencies()
      Sorts the dependency list.
      void writeReports​(java.lang.String applicationName, @Nullable java.lang.String groupId, @Nullable java.lang.String artifactId, @Nullable java.lang.String version, @NotNull java.io.File outputDir, java.lang.String format)
      Deprecated.
      use writeReports(String, String, String, String, File, String, ExceptionCollection)
      void writeReports​(java.lang.String applicationName, @Nullable java.lang.String groupId, @Nullable java.lang.String artifactId, @Nullable java.lang.String version, @NotNull java.io.File outputDir, java.lang.String format, ExceptionCollection exceptions)
      Writes the report to the given output directory.
      void writeReports​(java.lang.String applicationName, java.io.File outputDir, java.lang.String format)
      Deprecated.
      use writeReports(java.lang.String, java.io.File, java.lang.String, org.owasp.dependencycheck.exception.ExceptionCollection)
      void writeReports​(java.lang.String applicationName, java.io.File outputDir, java.lang.String format, ExceptionCollection exceptions)
      Writes the report to the given output directory.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • Engine

        public Engine​(@NotNull
              @NotNull Settings settings)
        Creates a new Engine.Mode.STANDALONE Engine.
        Parameters:
        settings - reference to the configured settings

      • Engine

        public Engine​(@NotNull
              @NotNull Engine.Mode mode,
              @NotNull
              @NotNull Settings settings)
        Creates a new Engine.
        Parameters:
        mode - the mode of operation
        settings - reference to the configured settings

      • Engine

        public Engine​(@NotNull
              @NotNull java.lang.ClassLoader serviceClassLoader,
              @NotNull
              @NotNull Settings settings)
        Creates a new Engine.Mode.STANDALONE Engine.
        Parameters:
        serviceClassLoader - a reference the class loader being used
        settings - reference to the configured settings

      • Engine

        public Engine​(@NotNull
              @NotNull java.lang.ClassLoader serviceClassLoader,
              @NotNull
              @NotNull Engine.Mode mode,
              @NotNull
              @NotNull Settings settings)
        Creates a new Engine.
        Parameters:
        serviceClassLoader - a reference the class loader being used
        mode - the mode of the engine
        settings - reference to the configured settings

    • Method Detail

      • initializeEngine

        protected final void initializeEngine()
        Creates a new Engine using the specified classloader to dynamically load Analyzer and Update services.
        Throws:
        DatabaseException - thrown if there is an error connecting to the database

      • close

        public void close()
        Properly cleans up resources allocated during analysis.
        Specified by:
        close in interface java.lang.AutoCloseable

      • getAnalyzers

        public java.util.List<Analyzer> getAnalyzers​(AnalysisPhase phase)
        Get the List of the analyzers for a specific phase of analysis.
        Parameters:
        phase - the phase to get the configured analyzers.
        Returns:
        the analyzers loaded

      • addDependency

        public void addDependency​(Dependency dependency)
        Adds a dependency. In some cases, when adding a virtual dependency, the method will identify if the virtual dependency was previously added and update the existing dependency rather then adding a duplicate.
        Parameters:
        dependency - the dependency to add

      • sortDependencies

        public void sortDependencies()
        Sorts the dependency list.

      • removeDependency

        public void removeDependency​(@NotNull
                             @NotNull Dependency dependency)
        Removes the dependency.
        Parameters:
        dependency - the dependency to remove.

      • getDependencies

        public Dependency[] getDependencies()
        Returns a copy of the dependencies as an array.
        Returns:
        the dependencies identified

      • setDependencies

        public void setDependencies​(@NotNull
                            @NotNull java.util.List<Dependency> dependencies)
        Sets the dependencies.
        Parameters:
        dependencies - the dependencies

      • scan

        public java.util.List<Dependency> scan​(@NotNull
                                       @NotNull java.lang.String[] paths)
        Scans an array of files or directories. If a directory is specified, it will be scanned recursively. Any dependencies identified are added to the dependency collection.
        Parameters:
        paths - an array of paths to files or directories to be analyzed
        Returns:
        the list of dependencies scanned
        Since:
        v0.3.2.5

      • scan

        public java.util.List<Dependency> scan​(@NotNull
                                       @NotNull java.lang.String[] paths,
                                       @Nullable
                                       @Nullable java.lang.String projectReference)
        Scans an array of files or directories. If a directory is specified, it will be scanned recursively. Any dependencies identified are added to the dependency collection.
        Parameters:
        paths - an array of paths to files or directories to be analyzed
        projectReference - the name of the project or scope in which the dependency was identified
        Returns:
        the list of dependencies scanned
        Since:
        v1.4.4

      • scan

        public java.util.List<Dependency> scan​(@NotNull
                                       @NotNull java.lang.String path)
        Scans a given file or directory. If a directory is specified, it will be scanned recursively. Any dependencies identified are added to the dependency collection.
        Parameters:
        path - the path to a file or directory to be analyzed
        Returns:
        the list of dependencies scanned

      • scan

        public java.util.List<Dependency> scan​(@NotNull
                                       @NotNull java.lang.String path,
                                       java.lang.String projectReference)
        Scans a given file or directory. If a directory is specified, it will be scanned recursively. Any dependencies identified are added to the dependency collection.
        Parameters:
        path - the path to a file or directory to be analyzed
        projectReference - the name of the project or scope in which the dependency was identified
        Returns:
        the list of dependencies scanned
        Since:
        v1.4.4

      • scan

        public java.util.List<Dependency> scan​(java.io.File[] files)
        Scans an array of files or directories. If a directory is specified, it will be scanned recursively. Any dependencies identified are added to the dependency collection.
        Parameters:
        files - an array of paths to files or directories to be analyzed.
        Returns:
        the list of dependencies
        Since:
        v0.3.2.5

      • scan

        public java.util.List<Dependency> scan​(java.io.File[] files,
                                       java.lang.String projectReference)
        Scans an array of files or directories. If a directory is specified, it will be scanned recursively. Any dependencies identified are added to the dependency collection.
        Parameters:
        files - an array of paths to files or directories to be analyzed.
        projectReference - the name of the project or scope in which the dependency was identified
        Returns:
        the list of dependencies
        Since:
        v1.4.4

      • scan

        public java.util.List<Dependency> scan​(java.util.Collection<java.io.File> files)
        Scans a collection of files or directories. If a directory is specified, it will be scanned recursively. Any dependencies identified are added to the dependency collection.
        Parameters:
        files - a set of paths to files or directories to be analyzed
        Returns:
        the list of dependencies scanned
        Since:
        v0.3.2.5

      • scan

        public java.util.List<Dependency> scan​(java.util.Collection<java.io.File> files,
                                       java.lang.String projectReference)
        Scans a collection of files or directories. If a directory is specified, it will be scanned recursively. Any dependencies identified are added to the dependency collection.
        Parameters:
        files - a set of paths to files or directories to be analyzed
        projectReference - the name of the project or scope in which the dependency was identified
        Returns:
        the list of dependencies scanned
        Since:
        v1.4.4

      • scan

        public java.util.List<Dependency> scan​(java.io.File file)
        Scans a given file or directory. If a directory is specified, it will be scanned recursively. Any dependencies identified are added to the dependency collection.
        Parameters:
        file - the path to a file or directory to be analyzed
        Returns:
        the list of dependencies scanned
        Since:
        v0.3.2.4

      • scan

        @Nullable
public @Nullable java.util.List<Dependency> scan​(@NotNull
                                                 @NotNull java.io.File file,
                                                 java.lang.String projectReference)
        Scans a given file or directory. If a directory is specified, it will be scanned recursively. Any dependencies identified are added to the dependency collection.
        Parameters:
        file - the path to a file or directory to be analyzed
        projectReference - the name of the project or scope in which the dependency was identified
        Returns:
        the list of dependencies scanned
        Since:
        v1.4.4

      • scanDirectory

        protected java.util.List<Dependency> scanDirectory​(java.io.File dir)
        Recursively scans files and directories. Any dependencies identified are added to the dependency collection.
        Parameters:
        dir - the directory to scan
        Returns:
        the list of Dependency objects scanned

      • scanDirectory

        protected java.util.List<Dependency> scanDirectory​(@NotNull
                                                   @NotNull java.io.File dir,
                                                   @Nullable
                                                   @Nullable java.lang.String projectReference)
        Recursively scans files and directories. Any dependencies identified are added to the dependency collection.
        Parameters:
        dir - the directory to scan
        projectReference - the name of the project or scope in which the dependency was identified
        Returns:
        the list of Dependency objects scanned
        Since:
        v1.4.4

      • scanFile

        protected Dependency scanFile​(@NotNull
                              @NotNull java.io.File file)
        Scans a specified file. If a dependency is identified it is added to the dependency collection.
        Parameters:
        file - The file to scan
        Returns:
        the scanned dependency

      • scanFile

        protected Dependency scanFile​(@NotNull
                              @NotNull java.io.File file,
                              @Nullable
                              @Nullable java.lang.String projectReference)
        Scans a specified file. If a dependency is identified it is added to the dependency collection.
        Parameters:
        file - The file to scan
        projectReference - the name of the project or scope in which the dependency was identified
        Returns:
        the scanned dependency
        Since:
        v1.4.4

      • analyzeDependencies

        public void analyzeDependencies()
                         throws ExceptionCollection
        Runs the analyzers against all of the dependencies. Since the mutable dependencies list is exposed via getDependencies(), this method iterates over a copy of the dependencies list. Thus, the potential for ConcurrentModificationExceptions is avoided, and analyzers may safely add or remove entries from the dependencies list.

        Every effort is made to complete analysis on the dependencies. In some cases an exception will occur with part of the analysis being performed which may not affect the entire analysis. If an exception occurs it will be included in the thrown exception collection.

        Throws:
        ExceptionCollection - a collections of any exceptions that occurred during analysis

      • executeAnalysisTasks

        protected void executeAnalysisTasks​(@NotNull
                                    @NotNull Analyzer analyzer,
                                    java.util.List<java.lang.Throwable> exceptions)
                             throws ExceptionCollection
        Executes executes the analyzer using multiple threads.
        Parameters:
        exceptions - a collection of exceptions that occurred during analysis
        analyzer - the analyzer to execute
        Throws:
        ExceptionCollection - thrown if exceptions occurred during analysis

      • getAnalysisTasks

        protected java.util.List<AnalysisTask> getAnalysisTasks​(Analyzer analyzer,
                                                        java.util.List<java.lang.Throwable> exceptions)
        Returns the analysis tasks for the dependencies.
        Parameters:
        analyzer - the analyzer to create tasks for
        exceptions - the collection of exceptions to collect
        Returns:
        a collection of analysis tasks

      • getExecutorService

        protected java.util.concurrent.ExecutorService getExecutorService​(Analyzer analyzer)
        Returns the executor service for a given analyzer.
        Parameters:
        analyzer - the analyzer to obtain an executor
        Returns:
        the executor service

      • initializeAnalyzer

        protected void initializeAnalyzer​(@NotNull
                                  @NotNull Analyzer analyzer)
                           throws InitializationException
        Initializes the given analyzer.
        Parameters:
        analyzer - the analyzer to prepare
        Throws:
        InitializationException - thrown when there is a problem initializing the analyzer

      • closeAnalyzer

        protected void closeAnalyzer​(@NotNull
                             @NotNull Analyzer analyzer)
        Closes the given analyzer.
        Parameters:
        analyzer - the analyzer to close

      • doUpdates

        public boolean doUpdates()
                  throws UpdateException,
                         DatabaseException
        Cycles through the cached web data sources and calls update on all of them.
        Returns:
        Whether any updates actually happened
        Throws:
        UpdateException - thrown if the operation fails
        DatabaseException - if the operation fails due to a local database failure

      • doUpdates

        public boolean doUpdates​(boolean remainOpen)
                  throws UpdateException,
                         DatabaseException
        Cycles through the cached web data sources and calls update on all of them.
        Parameters:
        remainOpen - whether or not the database connection should remain open
        Returns:
        Whether any updates actually happened
        Throws:
        UpdateException - thrown if the operation fails
        DatabaseException - if the operation fails due to a local database failure

      • purge

        public boolean purge()
        Purges the cached web data sources.
        Returns:
        true if the purge was successful; otherwise false

      • openDatabase

        public void openDatabase()
                  throws DatabaseException

        This method is only public for unit/integration testing. This method should not be called by any integration that uses dependency-check-core.

        Opens the database connection.

        Throws:
        DatabaseException - if the database connection could not be created

      • openDatabase

        public void openDatabase​(boolean readOnly,
                         boolean lockRequired)
                  throws DatabaseException

        This method is only public for unit/integration testing. This method should not be called by any integration that uses dependency-check-core.

        Opens the database connection; if readOnly is true a copy of the database will be made.

        Parameters:
        readOnly - whether or not the database connection should be readonly
        lockRequired - whether or not a lock needs to be acquired when opening the database
        Throws:
        DatabaseException - if the database connection could not be created

      • getDatabase

        public CveDB getDatabase()
        Returns a reference to the database.
        Returns:
        a reference to the database

      • getAnalyzers

        @NotNull
public @NotNull java.util.List<Analyzer> getAnalyzers()
        Returns a full list of all of the analyzers. This is useful for reporting which analyzers where used.
        Returns:
        a list of Analyzers

      • accept

        public boolean accept​(@Nullable
                      @Nullable java.io.File file)
        Checks all analyzers to see if an extension is supported.
        Specified by:
        accept in interface java.io.FileFilter
        Parameters:
        file - a file extension
        Returns:
        true or false depending on whether or not the file extension is supported

      • getFileTypeAnalyzers

        public java.util.Set<FileTypeAnalyzer> getFileTypeAnalyzers()
        Returns the set of file type analyzers.
        Returns:
        the set of file type analyzers

      • getSettings

        public Settings getSettings()
        Returns the configured settings.
        Returns:
        the configured settings

      • getObject

        public java.lang.Object getObject​(java.lang.String key)
        Retrieve an object from the objects collection.
        Parameters:
        key - the key to retrieve the object
        Returns:
        the object

      • putObject

        public void putObject​(java.lang.String key,
                      java.lang.Object object)
        Put an object in the object collection.
        Parameters:
        key - the key to store the object
        object - the object to store

      • hasObject

        public boolean hasObject​(java.lang.String key)
        Verifies if the object exists in the object store.
        Parameters:
        key - the key to retrieve the object
        Returns:
        true if the object exists; otherwise false

      • removeObject

        public void removeObject​(java.lang.String key)
        Removes an object from the object store.
        Parameters:
        key - the key to the object

      • getMode

        public Engine.Mode getMode()
        Returns the mode of the engine.
        Returns:
        the mode of the engine

      • addFileTypeAnalyzer

        protected void addFileTypeAnalyzer​(@NotNull
                                   @NotNull FileTypeAnalyzer fta)
        Adds a file type analyzer. This has been added solely to assist in unit testing the Engine.
        Parameters:
        fta - the file type analyzer to add

      • writeReports

        public void writeReports​(java.lang.String applicationName,
                         java.io.File outputDir,
                         java.lang.String format,
                         ExceptionCollection exceptions)
                  throws ReportException
        Writes the report to the given output directory.
        Parameters:
        applicationName - the name of the application/project
        outputDir - the path to the output directory (can include the full file name if the format is not ALL)
        format - the report format (see ReportGenerator.Format)
        exceptions - a collection of exceptions that may have occurred during the analysis
        Throws:
        ReportException - thrown if there is an error generating the report

      • writeReports

        @Deprecated
public void writeReports​(java.lang.String applicationName,
                         @Nullable
                         @Nullable java.lang.String groupId,
                         @Nullable
                         @Nullable java.lang.String artifactId,
                         @Nullable
                         @Nullable java.lang.String version,
                         @NotNull
                         @NotNull java.io.File outputDir,
                         java.lang.String format)
                  throws ReportException
        Deprecated.
        use writeReports(String, String, String, String, File, String, ExceptionCollection)
        Writes the report to the given output directory.
        Parameters:
        applicationName - the name of the application/project
        groupId - the Maven groupId
        artifactId - the Maven artifactId
        version - the Maven version
        outputDir - the path to the output directory (can include the full file name if the format is not ALL)
        format - the report format (see ReportGenerator.Format)
        Throws:
        ReportException - thrown if there is an error generating the report

      • writeReports

        public void writeReports​(java.lang.String applicationName,
                         @Nullable
                         @Nullable java.lang.String groupId,
                         @Nullable
                         @Nullable java.lang.String artifactId,
                         @Nullable
                         @Nullable java.lang.String version,
                         @NotNull
                         @NotNull java.io.File outputDir,
                         java.lang.String format,
                         ExceptionCollection exceptions)
                  throws ReportException
        Writes the report to the given output directory.
        Parameters:
        applicationName - the name of the application/project
        groupId - the Maven groupId
        artifactId - the Maven artifactId
        version - the Maven version
        outputDir - the path to the output directory (can include the full file name if the format is not ALL)
        format - the report format (see ReportGenerator.Format)
        exceptions - a collection of exceptions that may have occurred during the analysis
        Throws:
        ReportException - thrown if there is an error generating the report