Package io.github.jeremylong.openvulnerability.client.nvd

Class NvdCveClientBuilder

  • All Implemented Interfaces:
    java.lang.Cloneable
    public final class NvdCveClientBuilder
extends java.lang.Object
implements java.lang.Cloneable
    Used to build an NVD CVE API client. As the NvdCveClient client is autocloseable the builder should be used in a try with resources: 
     try (NvdCveClient api = NvdCveClientBuilder.aNvdCveApi().build()) {
     while (api.hasNext()) {
         Collection<DefCveItem> items = api.next();
     }
 }

    • Method Detail

      • aNvdCveApi

        public static NvdCveClientBuilder aNvdCveApi()
        Begin building the NVD CVE API Object.
        Returns:
        the builder

      • withEndpoint

        public NvdCveClientBuilder withEndpoint​(java.lang.String endpoint)
        Use an alternative endpoint for the NVD CVE API.
        Parameters:
        endpoint - the endpoint for the NVD CVE API
        Returns:
        the builder

      • withCacheDirectory

        public NvdCveClientBuilder withCacheDirectory​(java.nio.file.Path cacheDirectory)
        Sets the directory to cache the NVD CVE API responses. This should only be used if downloading the entire set of CVE data from the NVD API. If the cache directory is used and there is an interruption in the download - under rare cases if the NVD updated the CVE data - the cache directory will not be updated and as such, the mirror may be out of sync. If using the cache directory and an interruption occurs, it is recommended to try again within 20 hours and if succesful, perform another update to retrieve the entries modified within the last 20 hours.
        Parameters:
        cacheDirectory - the directory to cache the NVD CVE API responses
        Returns:
        the builder

      • withDelay

        public NvdCveClientBuilder withDelay​(long milliseconds)
        Use a minimum delay in milliseconds between API calls; useful if you run into issues with rate limiting.
        Parameters:
        milliseconds - the minimum number of milliseconds between API calls to the NVD CVE API
        Returns:
        the builder

      • withMaxRetryCount

        public NvdCveClientBuilder withMaxRetryCount​(int maxRetryCount)
        Set the maximum number of retries for 503 and 429 responses from the NVD; default is 10.
        Parameters:
        maxRetryCount - the maximum number of retries for 503 and 429 responses from the NVD.
        Returns:
        the builder

      • withThreadCount

        public NvdCveClientBuilder withThreadCount​(int count)
        Set the number of threads to use when calling the NVD API.
        Parameters:
        count - the number of threads to use when calling the NVD API
        Returns:
        the builder

      • withMaxPageCount

        public NvdCveClientBuilder withMaxPageCount​(int count)
        Set the maximum number of pages to retrieve from the NVD API.
        Parameters:
        count - the maximum number of pages to retrieve from the NVD API
        Returns:
        the builder

      • withResultsPerPage

        public NvdCveClientBuilder withResultsPerPage​(int resultsPerPage)
        Use a specific number of results per page. Value must be between 1 and 2000. The default value is 2000.
        Parameters:
        resultsPerPage - the number of results per page
        Returns:
        the builder

      • withFilter

        public NvdCveClientBuilder withFilter​(java.lang.String filter,
                                      java.lang.String value)
        Add a querystring parameter to filter the call to the NVD CVE API.
        Parameters:
        filter - the querystring parameter
        value - the querystring parameter value
        Returns:
        the builder

      • withFilter

        public NvdCveClientBuilder withFilter​(NvdCveClientBuilder.Filter filter,
                                      java.lang.String value)
        Add a querystring parameter to filter the call to the NVD CVE API.
        Parameters:
        filter - the querystring parameter
        value - the querystring parameter value
        Returns:
        the builder

      • withLastModifiedFilter

        public NvdCveClientBuilder withLastModifiedFilter​(java.time.ZonedDateTime utcStartDate,
                                                  java.time.ZonedDateTime utcEndDate)
        Use a range of no more than 120 days on the last modified dates to filter the results. The ZonedDateTime objects must be set to UTC.
        Parameters:
        utcStartDate - the UTC date time for the range start
        utcEndDate - the UTC date time for the range end
        Returns:
        the builder

      • withAdditionalUserAgent

        public NvdCveClientBuilder withAdditionalUserAgent​(java.lang.String userAgent)
        Use an additional identifier as part of the User-Agent when making requests.
        Parameters:
        userAgent - the user agent string to append
        Returns:
        the builder

      • withPublishedDateFilter

        public NvdCveClientBuilder withPublishedDateFilter​(java.time.ZonedDateTime utcStartDate,
                                                   java.time.ZonedDateTime utcEndDate)
        Filter the results with a range of published date times. The ZonedDateTime objects must be set to UTC.
        Parameters:
        utcStartDate - the UTC date time for the range start
        utcEndDate - the UTC date time for the range end
        Returns:
        the builder

      • withVirtualMatchString

        public NvdCveClientBuilder withVirtualMatchString​(java.lang.String virtualMatchString)
        This parameter filters CVE more broadly than cpeName. The exact value of {cpe match string} is compared against the CPE Match Criteria present on CVE applicability statements.
        Parameters:
        virtualMatchString - virtual matching CPE
        Returns:
        the builder
        See Also:
        cves-virtualMatchString

      • withVersionStart

        public NvdCveClientBuilder withVersionStart​(java.lang.String versionStart)
        The virtualMatchString parameter may be combined with versionStart and versionStartType to return only the CVEs associated with CPEs in specific version ranges.
        Parameters:
        versionStart - the version start
        Returns:
        the builder
        See Also:
        cves-versionStart

      • withVersionStart

        public NvdCveClientBuilder withVersionStart​(java.lang.String versionStart,
                                            NvdCveClientBuilder.VersionType startType)
        The virtualMatchString parameter may be combined with versionStart and versionStartType to return only the CVEs associated with CPEs in specific version ranges.
        Parameters:
        versionStart - the version start
        startType - including or excluding
        Returns:
        the builder
        See Also:
        cves-versionStart

      • withVersionEnd

        public NvdCveClientBuilder withVersionEnd​(java.lang.String versionEnd)
        The virtualMatchString parameter may be combined with versionEnd and versionEndType to return only the CVEs associated with CPEs in specific version ranges.
        Parameters:
        versionEnd - the version end
        Returns:
        the builder
        See Also:
        cves-versionEnd

      • withVersionEnd

        public NvdCveClientBuilder withVersionEnd​(java.lang.String versionEnd,
                                          NvdCveClientBuilder.VersionType endType)
        The virtualMatchString parameter may be combined with versionEnd and versionEndType to return only the CVEs associated with CPEs in specific version ranges.
        Parameters:
        versionEnd - the version end
        endType - including or excluding
        Returns:
        the builder
        See Also:
        cves-versionEnd

      • build

        public NvdCveClient build()
        Build the NVD CVE API client.
        Returns:
        the NVD CVE API client

      • clone

        public NvdCveClientBuilder clone()
        Clone the builder.
        Overrides:
        clone in class java.lang.Object
        Returns:
        the clone