Class Engine

java.lang.Object
org.owasp.dependencycheck.Engine
All Implemented Interfaces:
FileFilter, AutoCloseable
@NotThreadSafe public class Engine extends Object implements FileFilter, 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

  • Constructor Details

    • Engine

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

    • Engine

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

    • Engine

      public Engine(@NonNull ClassLoader serviceClassLoader, @NonNull 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(@NonNull ClassLoader serviceClassLoader, @NonNull Engine.Mode mode, @NonNull 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 Details

    • 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 AutoCloseable

    • getAnalyzers

      public 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(@NonNull 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(@NonNull List<Dependency> dependencies)
      Sets the dependencies.
      Parameters:
      dependencies - the dependencies

    • scan

      public List<Dependency> scan(@NonNull 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 List<Dependency> scan(@NonNull String[] paths, @Nullable 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 List<Dependency> scan(@NonNull 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 List<Dependency> scan(@NonNull String path, 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 List<Dependency> scan(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 List<Dependency> scan(File[] files, 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 List<Dependency> scan(Collection<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 List<Dependency> scan(Collection<File> files, 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 List<Dependency> scan(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

      public @Nullable List<Dependency> scan(@NonNull File file, 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 List<Dependency> scanDirectory(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 List<Dependency> scanDirectory(@NonNull File dir, @Nullable 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(@NonNull 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(@NonNull File file, @Nullable 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(@NonNull Analyzer analyzer, List<Throwable> exceptions) throws ExceptionCollection
      Executes executes the analyzer using multiple threads.
      Parameters:
      analyzer - the analyzer to execute
      exceptions - a collection of exceptions that occurred during analysis
      Throws:
      ExceptionCollection - thrown if exceptions occurred during analysis

    • getAnalysisTasks

      protected List<AnalysisTask> getAnalysisTasks(Analyzer analyzer, List<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 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(@NonNull 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(@NonNull 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

      public @NonNull 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 File file)
      Checks all analyzers to see if an extension is supported.
      Specified by:
      accept in interface FileFilter
      Parameters:
      file - a file extension
      Returns:
      true or false depending on whether or not the file extension is supported

    • getFileTypeAnalyzers

      public 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 Object getObject(String key)
      Retrieve an object from the objects collection.
      Parameters:
      key - the key to retrieve the object
      Returns:
      the object

    • putObject

      public void putObject(String key, 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(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(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(@NonNull 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

      @Deprecated public void writeReports(String applicationName, File outputDir, String format) throws ReportException
      Deprecated.
      use writeReports(java.lang.String, java.io.File, java.lang.String, org.owasp.dependencycheck.exception.ExceptionCollection)
      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)
      Throws:
      ReportException - thrown if there is an error generating the report

    • writeReports

      public void writeReports(String applicationName, File outputDir, 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(String applicationName, @Nullable String groupId, @Nullable String artifactId, @Nullable String version, @NonNull File outputDir, 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(String applicationName, @Nullable String groupId, @Nullable String artifactId, @Nullable String version, @NonNull File outputDir, 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