open-vulnerability-clients

open-vulnerability-clients

A collection of Java clients to access various vulnerability data-sources available on the internet. Some of the data-sources require an API Key or Token to access the API.

NVD Links

• Getting Started
• Vulnerabilities API
• Request an NVD API Key

See API usage examples below.

GitHub Security Advisory Links

• GitHub Security Advisory Database
• Explorer

See API usage examples below.

Exploit Prediction Scoring System (EPSS) Links

• https://www.first.org/epss/

See API usage examples in the open-vulnerability-store project.

CISA Known Exploited Vulnerabilities Catalog

• https://www.cisa.gov/known-exploited-vulnerabilities-catalog

See API usage examples in the open-vulnerability-store project.

usage

maven

<dependency>
   <groupId>io.github.jeremylong</groupId>
   <artifactId>open-vulnerability-clients</artifactId>
   <version>5.1.1</version>
</dependency>

gradle

implementation 'io.github.jeremylong:open-vulnerability-clients:5.1.1'

api usage

The APIs are intended to be fairly simple; an example implementation is given below to retrieve the entire GitHub Security Advisory data set - including a mechanism to keep the data up to date.

GitHub Security Advisory Example

A Personal Access Token is required to access the GitHub Security Advisory GraphQL endpoint.

import io.github.jeremylong.openvulnerability.client.ghsa.GitHubSecurityAdvisoryClient;
import io.github.jeremylong.openvulnerability.client.ghsa.GitHubSecurityAdvisoryClientBuilder;
import io.github.jeremylong.openvulnerability.client.ghsa.SecurityAdvisory;

import java.time.ZoneOffset;
import java.time.ZonedDateTime;
import java.util.List;

public class Example {
    
    ZonedDateTime retrieveLastUpdated() {
        // TODO implement a storage/retrieval mechanism for the last updated date.
        return ZonedDateTime.now(ZoneOffset.UTC).minusDays(1);
    }

    void storeLastUpdated(ZonedDateTime lastUpdated) {
        // TODO implement a storage/retrieval mechanism for the last update time.
    }

    @Test
    void testNext() throws Exception {
        String apiKey = System.getenv("GITHUB_TOKEN");

        GitHubSecurityAdvisoryClientBuilder builder = GitHubSecurityAdvisoryClientBuilder
                .aGitHubSecurityAdvisoryClient()
                .withApiKey(apiKey);

        ZonedDateTime lastUpdated = retrieveLastUpdated();
        if (lastUpdated != null) {
            builder.withUpdatedSinceFilter(lastUpdated);
        }
        try (GitHubSecurityAdvisoryClient client = builder.build()) {
            if (client.hasNext()) {
                List<SecurityAdvisory> result = client.next();
                if (result != null && !result.isEmpty()) {
                    //TODO do something useful with the SecurityAdvisories
                }
            }
            storeLastUpdated(client.getLastUpdated());
        }
    }
}

NVD API Example

An API Key for the NVD API is highly recommended - especially when downloading the full Vulnerability Catalog from the NVD. Without an API key downloading takes 10+ minutes; whereas with an API key (and using 4 threads) the entire NVD Vulnerability Catalog can be downloaded in ~90 seconds.

import io.github.jeremylong.openvulnerability.client.nvd.NvdCveClient;
import io.github.jeremylong.openvulnerability.client.nvd.NvdCveClientBuilder;
import io.github.jeremylong.openvulnerability.client.nvd.DefCveItem;

import java.time.ZonedDateTime;
import java.util.Collection;

public class Example {

    ZonedDateTime retrieveLastUpdated() {
        // TODO implement a storage/retrieval mechanism.
        return null;
    }

    void storeLasUpdated(ZonedDateTime lastUpdated) {
        // TODO implement a storage/retrieval mechanism.
    }

    public void update() {
        ZonedDateTime lastModifiedRequest = retrieveLastUpdated();
        NvdCveClientBuilder builder = NvdCveClientBuilder.aNvdCveApi();
        if (lastModifiedRequest != null) {
            ZonedDateTime end = lastModifiedRequest.minusDays(-120);
            builder.withLastModifiedFilter(lastModifiedRequest, end);
        }
        //TODO add API key with builder's `withApiKey()`
        //TODO if an API Key is used consider adding `withThreadCount(4)`
        //TODO add any additional filters via the builder's `withFilter()`
        try (NvdCveClient api = builder.build()) {
            while (api.hasNext()) {
                Collection<DefCveItem> items = api.next();
                if (items != null && !items.isEmpty()) {
                    //TODO do something with the items
                }
            }
            lastModifiedRequest = api.getLastModifiedRequest();
        } catch (Exception e) {
            e.printStackTrace();
        }
        storeLasUpdated(lastModifiedRequest);
    }
}