org.owasp.dependencycheck.analyzer

Class CPEAnalyzer

java.lang.Object

org.owasp.dependencycheck.analyzer.AbstractAnalyzer

org.owasp.dependencycheck.analyzer.CPEAnalyzer

All Implemented Interfaces:

Analyzer

Direct Known Subclasses:

NpmCPEAnalyzer

@ThreadSafe
public class CPEAnalyzer
extends AbstractAnalyzer

CPEAnalyzer is a utility class that takes a project dependency and attempts to discern if there is an associated CPE. It uses the evidence contained within the dependency to search the Lucene index.

Author:

Jeremy Long

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	NVD_SEARCH_BROAD_URL The URL to search the NVD CVE data at NIST.
static java.lang.String	NVD_SEARCH_URL The URL to search the NVD CVE data at NIST.

Constructor Summary

Constructors

Constructor and Description
CPEAnalyzer()

Method Summary

Modifier and Type	Method and Description
protected void	analyzeDependency(Dependency dependency, Engine engine) Analyzes a dependency and attempts to determine if there are any CPE identifiers for this dependency.
protected java.lang.String	buildSearch(java.util.Map<java.lang.String,org.apache.commons.lang3.mutable.MutableInt> vendor, java.util.Map<java.lang.String,org.apache.commons.lang3.mutable.MutableInt> product, java.util.Set<java.lang.String> vendorWeighting, java.util.Set<java.lang.String> productWeightings) Builds a Lucene search string by properly escaping data and constructing a valid search query.
void	closeAnalyzer() Closes the data sources.
protected void	collectTerms(java.util.Map<java.lang.String,org.apache.commons.lang3.mutable.MutableInt> terms, java.lang.Iterable<Evidence> evidence) Returns the text created by concatenating the text and the values from the EvidenceCollection (filtered for a specific confidence).
protected void	determineCPE(Dependency dependency) Searches the data store of CPE entries, trying to identify the CPE for the given dependency based on the evidence contained within.
protected boolean	determineIdentifiers(Dependency dependency, java.lang.String vendor, java.lang.String product, Confidence currentConfidence) Retrieves a list of CPE values from the CveDB based on the vendor and product passed in.
AnalysisPhase	getAnalysisPhase() Returns the analysis phase that this analyzer should run in.
protected java.lang.String	getAnalyzerEnabledSettingKey() Returns the setting key to determine if the analyzer is enabled.
protected CveDB	getCveDB() returns a reference to the CveDB.
protected MemoryIndex	getMemoryIndex() Returns the memory index.
java.lang.String	getName() Returns the name of this analyzer.
static void	main(java.lang.String[] args) Command line tool for querying the Lucene CPE Index.
void	open(CveDB cve) Opens the data source.
void	prepareAnalyzer(Engine engine) Creates the CPE Lucene Index.
protected java.util.List<IndexEntry>	searchCPE(java.util.Map<java.lang.String,org.apache.commons.lang3.mutable.MutableInt> vendor, java.util.Map<java.lang.String,org.apache.commons.lang3.mutable.MutableInt> product, java.util.Set<java.lang.String> vendorWeightings, java.util.Set<java.lang.String> productWeightings, java.lang.String ecosystem) Searches the Lucene CPE index to identify possible CPE entries associated with the supplied vendor, product, and version.
protected void	setCpeSuppressionAnalyzer(CpeSuppressionAnalyzer suppression) Sets the CPE Suppression Analyzer.
protected void	setCveDB(CveDB cveDb) Sets the reference to the CveDB.
protected void	setMemoryIndex(MemoryIndex idx) Sets the MemoryIndex.

Methods inherited from class org.owasp.dependencycheck.analyzer.AbstractAnalyzer

analyze, close, getSettings, initialize, isEnabled, prepare, setEnabled, supportsParallelProcessing

Methods inherited from class java.lang.Object

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

Field Detail

NVD_SEARCH_URL

public static final java.lang.String NVD_SEARCH_URL

The URL to search the NVD CVE data at NIST. This is used by calling:

String.format(NVD_SEARCH_URL, vendor, product, version);

See Also:

Constant Field Values

NVD_SEARCH_BROAD_URL

public static final java.lang.String NVD_SEARCH_BROAD_URL

The URL to search the NVD CVE data at NIST. This is used by calling:

String.format(NVD_SEARCH_URL, vendor, product);

See Also:

Constant Field Values

Constructor Detail

CPEAnalyzer

public CPEAnalyzer()

Method Detail

getName

public java.lang.String getName()

Returns the name of this analyzer.

Returns:

the name of this analyzer.

getAnalysisPhase

public AnalysisPhase getAnalysisPhase()

Returns the analysis phase that this analyzer should run in.

Returns:

the analysis phase that this analyzer should run in.

prepareAnalyzer

public void prepareAnalyzer(Engine engine)
                     throws InitializationException

Creates the CPE Lucene Index.

Overrides:

prepareAnalyzer in class AbstractAnalyzer

Parameters:

engine - a reference to the dependency-check engine

Throws:

InitializationException - is thrown if there is an issue opening the index.

open

public void open(CveDB cve)
          throws java.io.IOException,
                 DatabaseException

Opens the data source.

Parameters:

cve - a reference to the NVD CVE database

Throws:

java.io.IOException - when the Lucene directory to be queried does not exist or is corrupt.

DatabaseException - when the database throws an exception. This usually occurs when the database is in use by another process.

closeAnalyzer

public void closeAnalyzer()

Closes the data sources.

Overrides:

closeAnalyzer in class AbstractAnalyzer

determineCPE

protected void determineCPE(Dependency dependency)
                     throws org.apache.lucene.index.CorruptIndexException,
                            java.io.IOException,
                            org.apache.lucene.queryparser.classic.ParseException,
                            AnalysisException

Searches the data store of CPE entries, trying to identify the CPE for the given dependency based on the evidence contained within. The dependency passed in is updated with any identified CPE values.

Parameters:

dependency - the dependency to search for CPE entries on

Throws:

org.apache.lucene.index.CorruptIndexException - is thrown when the Lucene index is corrupt

java.io.IOException - is thrown when an IOException occurs

org.apache.lucene.queryparser.classic.ParseException - is thrown when the Lucene query cannot be parsed

AnalysisException - thrown if the suppression rules failed

collectTerms

protected void collectTerms(java.util.Map<java.lang.String,org.apache.commons.lang3.mutable.MutableInt> terms,
                            java.lang.Iterable<Evidence> evidence)

Returns the text created by concatenating the text and the values from the EvidenceCollection (filtered for a specific confidence). This attempts to prevent duplicate terms from being added.

Note, if the evidence is longer then 1000 characters it will be truncated.

Parameters:

terms - the collection of terms

evidence - an iterable set of evidence to concatenate

searchCPE

protected java.util.List<IndexEntry> searchCPE(java.util.Map<java.lang.String,org.apache.commons.lang3.mutable.MutableInt> vendor,
                                               java.util.Map<java.lang.String,org.apache.commons.lang3.mutable.MutableInt> product,
                                               java.util.Set<java.lang.String> vendorWeightings,
                                               java.util.Set<java.lang.String> productWeightings,
                                               java.lang.String ecosystem)

Searches the Lucene CPE index to identify possible CPE entries associated with the supplied vendor, product, and version.

If either the vendorWeightings or productWeightings lists have been populated this data is used to add weighting factors to the search.

Parameters:

vendor - the text used to search the vendor field

product - the text used to search the product field

vendorWeightings - a list of strings to use to add weighting factors to the vendor field

productWeightings - Adds a list of strings that will be used to add weighting factors to the product search

ecosystem - the dependency's ecosystem

Returns:

a list of possible CPE values

buildSearch

protected java.lang.String buildSearch(java.util.Map<java.lang.String,org.apache.commons.lang3.mutable.MutableInt> vendor,
                                       java.util.Map<java.lang.String,org.apache.commons.lang3.mutable.MutableInt> product,
                                       java.util.Set<java.lang.String> vendorWeighting,
                                       java.util.Set<java.lang.String> productWeightings)

Builds a Lucene search string by properly escaping data and constructing a valid search query.

If either the possibleVendor or possibleProducts lists have been populated this data is used to add weighting factors to the search string generated.

Parameters:

vendor - text to search the vendor field

product - text to search the product field

vendorWeighting - a list of strings to apply to the vendor to boost the terms weight

productWeightings - a list of strings to apply to the product to boost the terms weight

Returns:

the Lucene query

analyzeDependency

protected void analyzeDependency(Dependency dependency,
                                 Engine engine)
                          throws AnalysisException

Analyzes a dependency and attempts to determine if there are any CPE identifiers for this dependency.

Specified by:

analyzeDependency in class AbstractAnalyzer

Parameters:

dependency - The Dependency to analyze.

engine - The analysis engine

Throws:

AnalysisException - is thrown if there is an issue analyzing the dependency.

determineIdentifiers

protected boolean determineIdentifiers(Dependency dependency,
                                       java.lang.String vendor,
                                       java.lang.String product,
                                       Confidence currentConfidence)
                                throws java.io.UnsupportedEncodingException,
                                       AnalysisException

Retrieves a list of CPE values from the CveDB based on the vendor and product passed in. The list is then validated to find only CPEs that are valid for the given dependency. It is possible that the CPE identified is a best effort "guess" based on the vendor, product, and version information.

Parameters:

dependency - the Dependency being analyzed

vendor - the vendor for the CPE being analyzed

product - the product for the CPE being analyzed

currentConfidence - the current confidence being used during analysis

Returns:

true if an identifier was added to the dependency; otherwise false

Throws:

java.io.UnsupportedEncodingException - is thrown if UTF-8 is not supported

AnalysisException - thrown if the suppression rules failed

getAnalyzerEnabledSettingKey

protected java.lang.String getAnalyzerEnabledSettingKey()

Returns the setting key to determine if the analyzer is enabled.

Specified by:

getAnalyzerEnabledSettingKey in class AbstractAnalyzer

Returns:

the key for the analyzer's enabled property

main

public static void main(java.lang.String[] args)

Command line tool for querying the Lucene CPE Index.

Parameters:

args - not used

setCveDB

protected void setCveDB(CveDB cveDb)

Sets the reference to the CveDB.

Parameters:

cveDb - the CveDB

getCveDB

protected CveDB getCveDB()

returns a reference to the CveDB.

Returns:

a reference to the CveDB

setMemoryIndex

protected void setMemoryIndex(MemoryIndex idx)

Sets the MemoryIndex.

Parameters:

idx - the memory index

getMemoryIndex

protected MemoryIndex getMemoryIndex()

Returns the memory index.

Returns:

the memory index

setCpeSuppressionAnalyzer

protected void setCpeSuppressionAnalyzer(CpeSuppressionAnalyzer suppression)

Sets the CPE Suppression Analyzer.

Parameters:

suppression - the CPE Suppression Analyzer