epss

Documentation

Overview

Package epss provides a client for the FIRST EPSS API. It supports batch requests, exponential backoff, and caching.

Index

• Constants
• type Client
  • func NewClient(opts ...Option) *Client
  • func (c *Client) CacheSize() int
  • func (c *Client) ClearCache()
  • func (c *Client) GetScore(ctx context.Context, cveID string) (Score, error)
  • func (c *Client) GetScores(ctx context.Context, cveIDs []string) (map[string]Score, error)
  • func (c *Client) PreloadCache(scores []Score)
• type Option
  • func WithBackoff(initial, max time.Duration) Option
  • func WithBaseURL(url string) Option
  • func WithCacheTTL(ttl time.Duration) Option
  • func WithHTTPClient(client *http.Client) Option
  • func WithLogger(logger *slog.Logger) Option
  • func WithMaxRetries(n int) Option
• type Score

Constants

const (
	// DefaultBaseURL is the EPSS API base URL.
	DefaultBaseURL = "https://api.first.org/data/v1/epss"

	// DefaultTimeout is the default HTTP request timeout.
	DefaultTimeout = 30 * time.Second

	// MaxBatchSize is the maximum number of CVEs per API request.
	MaxBatchSize = 100

	// DefaultMaxRetries is the default number of retry attempts.
	DefaultMaxRetries = 3

	// DefaultInitialBackoff is the initial backoff duration for retries.
	DefaultInitialBackoff = 1 * time.Second

	// DefaultMaxBackoff is the maximum backoff duration.
	DefaultMaxBackoff = 30 * time.Second
)

Types

type Client

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

Client is an EPSS API client with batching and caching support.

func NewClient

func NewClient(opts ...Option) *Client

NewClient creates a new EPSS API client.

func (*Client) CacheSize

func (c *Client) CacheSize() int

CacheSize returns the number of cached EPSS scores.

func (*Client) ClearCache

func (c *Client) ClearCache()

ClearCache clears all cached EPSS scores.

func (*Client) GetScore

func (c *Client) GetScore(ctx context.Context, cveID string) (Score, error)

GetScore fetches the EPSS score for a single CVE ID.

func (*Client) GetScores

func (c *Client) GetScores(ctx context.Context, cveIDs []string) (map[string]Score, error)

GetScores fetches EPSS scores for the given CVE IDs. It automatically batches requests if more than MaxBatchSize CVEs are provided. Results are cached according to the configured TTL.

func (*Client) PreloadCache

func (c *Client) PreloadCache(scores []Score)

PreloadCache loads scores into the cache from an external source. This is useful for initializing the cache from a database.

type Option

type Option func(*Client)

Option is a functional option for configuring the Client.

func WithBackoff

func WithBackoff(initial, max time.Duration) Option

WithBackoff sets the initial and maximum backoff durations.

func WithBaseURL

func WithBaseURL(url string) Option

WithBaseURL sets a custom base URL for the API.

func WithCacheTTL

func WithCacheTTL(ttl time.Duration) Option

WithCacheTTL sets the cache time-to-live duration. Set to 0 to disable caching.

func WithHTTPClient

func WithHTTPClient(client *http.Client) Option

WithHTTPClient sets a custom HTTP client.

func WithLogger

func WithLogger(logger *slog.Logger) Option

WithLogger sets a custom logger.

func WithMaxRetries

func WithMaxRetries(n int) Option

WithMaxRetries sets the maximum number of retry attempts.

type Score

type Score struct {
	CVE        string    `json:"cve"`
	EPSS       float64   `json:"epss,string"`
	Percentile float64   `json:"percentile,string"`
	Date       string    `json:"date"`
	FetchedAt  time.Time `json:"-"`
}

Score represents an EPSS score for a CVE.