Package org.owasp.dependencycheck.analyzer

Class 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 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 Description
      CPEAnalyzer()  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method 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 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.

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

      • 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