org.owasp.dependencycheck

Class Engine

java.lang.Object

org.owasp.dependencycheck.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 and Description
static class	Engine.Mode Engine execution modes.

Constructor Summary

Constructors

Constructor and Description
Engine(@NotNull java.lang.ClassLoader serviceClassLoader, @NotNull Engine.Mode mode, @NotNull Settings settings) Creates a new Engine.
Engine(@NotNull java.lang.ClassLoader serviceClassLoader, @NotNull Settings settings) Creates a new Engine.Mode.STANDALONE Engine.
Engine(@NotNull Engine.Mode mode, @NotNull Settings settings) Creates a new Engine.
Engine(@NotNull Settings settings) Creates a new Engine.Mode.STANDALONE Engine.

Method Summary

Modifier and Type	Method and 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.
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.
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.
@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.
protected java.util.List<Dependency>	scanDirectory(java.io.File dir) Recursively scans files and directories.
protected java.util.List<Dependency>	scanDirectory(@NotNull java.io.File dir, @Nullable java.lang.String projectReference) 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, 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.
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.

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

@Deprecated
public void writeReports(java.lang.String applicationName,
                                     java.io.File outputDir,
                                     java.lang.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(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