epss

README

Go-EPSS

A Golang library for interacting with the EPSS (Exploit Prediction Scoring System).

Data Set

EPSS (Exploit Prediction Scoring System) is a framework used to assess the likelihood of a vulnerability being exploited. FIRST organization regularly updates and publishes this data through their website.

Key Features

• Fetch latest EPSS data directly from source;
• Local EPSS querying interface instead of FIRST remote API;
• Access individual CVE scores;
• Manage update intervals to ensure fresh data;
• Leverages Golang's concurrency features for efficient performance;
• Custom *http.Client can be injected.

Getting Started

1. Install Go-EPSS package:

   go get github.com/KaanSK/go-epss
   

2. Import the package and create a client with default values:

   import (
       "github.com/KaanSK/go-epss"
   )
   
   client := epss.NewClient()
   ...
   

Providing Client Options and Custom *http.Client

    import (
        "github.com/KaanSK/go-epss"
    )

	client := epss.NewClient(
		epss.WithHTTPClient(&http.Client{Timeout: 10 * time.Second,}),
		epss.WithDataURL("test.com"),
		epss.WithUpdateInterval(10 * time.Minute),
		)

Getting All Score List

Use the client to retrieve scores:

    scores, err := client.GetAllScores()
    if err != nil {
        // Handle error
    }

    for _, score := range scores {
        fmt.Printf("CVE: %s, EPSS: %.4f, Percentile: %.4f\n", score.CVE, score.EPSS, score.Percentile)
    }
    ...

Getting Individual Score for CVE ID

Use the client to retrieve individual CVE score:

    score, err := client.GetScore("CVE-1999-0002")
    if err != nil {
        // Handle error
    }

    fmt.Printf("CVE: %s, EPSS: %.4f, Percentile: %.4f\n", score.CVE, score.EPSS, score.Percentile)
    ...

Test & Benchmarks

To run tests only:

go test -v -run Test

To run benchmarks only (will fetch remote data):

go test -bench=.

Disclaimer

• EPSS data retrieved from FIRST organization. As of the projects publishing date, data is open-sourced and available for individual projects.

Documentation

Index

• type Client
  • func NewClient(options ...ClientOption) *Client
  • func (c *Client) GetAllScores() ([]*Score, error)
  • func (c *Client) GetLastUpdated() time.Time
  • func (c *Client) GetScore(cve string) (*Score, error)
  • func (c *Client) GetUpdateInterval() time.Duration
• type ClientOption
  • func WithDataURL(dataURL string) ClientOption
  • func WithHTTPClient(httpClient HttpClient) ClientOption
  • func WithUpdateInterval(updateInterval time.Duration) ClientOption
• type HttpClient
• type Score

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

func NewClient

func NewClient(options ...ClientOption) *Client

NewClient creates a new EPSS client with the given options.

func (*Client) GetAllScores

func (c *Client) GetAllScores() ([]*Score, error)

GetAllScores returns all the scores.

func (*Client) GetLastUpdated

func (c *Client) GetLastUpdated() time.Time

GetLastUpdated returns the last updated time of the scores.

func (*Client) GetScore

func (c *Client) GetScore(cve string) (*Score, error)

GetScore returns the score for the given CVE.

func (*Client) GetUpdateInterval

func (c *Client) GetUpdateInterval() time.Duration

GetUpdateInterval returns the update interval of the scores.

type ClientOption

type ClientOption func(*Client)

func WithDataURL

func WithDataURL(dataURL string) ClientOption

WithDataURL sets the data URL for the client.

func WithHTTPClient

func WithHTTPClient(httpClient HttpClient) ClientOption

WithHTTPClient sets the HTTP client for the client.

func WithUpdateInterval

func WithUpdateInterval(updateInterval time.Duration) ClientOption

WithUpdateInterval sets the update interval for the client.

type HttpClient

type HttpClient interface {
	Get(url string) (*http.Response, error)
}

type Score

type Score struct {
	CVE        string
	EPSS       float32
	Percentile float32
}