org.owasp.dependencycheck

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

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 ClassLoader serviceClassLoader, @NotNull Engine.Mode mode, @NotNull Settings settings) Creates a new Engine.
Engine(@NotNull 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 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.
void	doUpdates() Cycles through the cached web data sources and calls update on all of them.
void	doUpdates(boolean remainOpen) Cycles through the cached web data sources and calls update on all of them.
protected void	executeAnalysisTasks(@NotNull Analyzer analyzer, List<Throwable> exceptions) Executes executes the analyzer using multiple threads.
protected List<AnalysisTask>	getAnalysisTasks(Analyzer analyzer, List<Throwable> exceptions) Returns the analysis tasks for the dependencies.
@NotNull List<Analyzer>	getAnalyzers() Returns a full list of all of the analyzers.
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 ExecutorService	getExecutorService(Analyzer analyzer) Returns the executor service for a given analyzer.
Set<FileTypeAnalyzer>	getFileTypeAnalyzers() Returns the set of file type analyzers.
Engine.Mode	getMode() Returns the mode of the engine.
Settings	getSettings() Returns the configured settings.
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	removeDependency(@NotNull Dependency dependency) Removes the dependency.
List<Dependency>	scan(Collection<File> files) Scans a collection of files or directories.
List<Dependency>	scan(Collection<File> files, String projectReference) Scans a collection of files or directories.
List<Dependency>	scan(File file) Scans a given file or directory.
List<Dependency>	scan(File[] files) Scans an array of files or directories.
List<Dependency>	scan(File[] files, String projectReference) Scans an array of files or directories.
@Nullable List<Dependency>	scan(@NotNull File file, String projectReference) Scans a given file or directory.
List<Dependency>	scan(@NotNull String path) Scans a given file or directory.
List<Dependency>	scan(@NotNull String[] paths) Scans an array of files or directories.
List<Dependency>	scan(@NotNull String[] paths, @Nullable String projectReference) Scans an array of files or directories.
List<Dependency>	scan(@NotNull String path, String projectReference) Scans a given file or directory.
protected List<Dependency>	scanDirectory(File dir) Recursively scans files and directories.
protected List<Dependency>	scanDirectory(@NotNull File dir, @Nullable String projectReference) Recursively scans files and directories.
protected Dependency	scanFile(@NotNull File file) Scans a specified file.
protected Dependency	scanFile(@NotNull File file, @Nullable String projectReference) Scans a specified file.
void	setDependencies(@NotNull List<Dependency> dependencies) Sets the dependencies.
void	sortDependencies() Sorts the dependency list.
void	writeReports(String applicationName, File outputDir, String format) Deprecated. use writeReports(java.lang.String, java.io.File, java.lang.String, org.owasp.dependencycheck.exception.ExceptionCollection)
void	writeReports(String applicationName, File outputDir, String format, ExceptionCollection exceptions) Writes the report to the given output directory.
void	writeReports(String applicationName, @Nullable String groupId, @Nullable String artifactId, @Nullable String version, @NotNull File outputDir, String format) Deprecated. use writeReports(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.io.File, java.lang.String, org.owasp.dependencycheck.exception.ExceptionCollection)
void	writeReports(String applicationName, @Nullable String groupId, @Nullable String artifactId, @Nullable String version, @NotNull File outputDir, 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 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 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 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.

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 List<Dependency> dependencies)

Sets the dependencies.

Parameters:

dependencies - the dependencies

scan

public List<Dependency> scan(@NotNull
                             @NotNull 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(@NotNull
                             @NotNull String[] paths,
                             @Nullable
                             @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(@NotNull
                             @NotNull 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(@NotNull
                             @NotNull 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

@Nullable
public @Nullable List<Dependency> scan(@NotNull
                                                 @NotNull 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(@NotNull
                                         @NotNull File dir,
                                         @Nullable
                                         @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(@NotNull
                              @NotNull 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 File file,
                              @Nullable
                              @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(@NotNull
                                    @NotNull Analyzer analyzer,
                                    List<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 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(@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 void doUpdates()
               throws UpdateException,
                      DatabaseException

Cycles through the cached web data sources and calls update on all of them.

Throws:

UpdateException - thrown if the operation fails

DatabaseException - if the operation fails due to a local database failure

doUpdates

public void 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

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

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(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 (ALL, HTML, CSV, JSON, etc.)

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 (ALL, HTML, CSV, JSON, etc.)

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
                                     @Nullable String groupId,
                                     @Nullable
                                     @Nullable String artifactId,
                                     @Nullable
                                     @Nullable String version,
                                     @NotNull
                                     @NotNull File outputDir,
                                     String format)
                              throws ReportException

Deprecated. use writeReports(java.lang.String, java.lang.String, java.lang.String, 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

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 (ALL, HTML, CSV, JSON, etc.)

Throws:

ReportException - thrown if there is an error generating the report

writeReports

public void writeReports(String applicationName,
                         @Nullable
                         @Nullable String groupId,
                         @Nullable
                         @Nullable String artifactId,
                         @Nullable
                         @Nullable String version,
                         @NotNull
                         @NotNull 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 (ALL, HTML, CSV, JSON, etc.)

exceptions - a collection of exceptions that may have occurred during the analysis

Throws:

ReportException - thrown if there is an error generating the report