github.com/quay/claircore@v1.5.28/libvuln/driver/enrichment.go (about)

     1  package driver
     2  
     3  import (
     4  	"context"
     5  	"encoding/json"
     6  	"io"
     7  
     8  	"github.com/quay/claircore"
     9  )
    10  
    11  // EnrichmentRecord is a simple container for JSON enrichment data
    12  // and the tags it will be queried by.
    13  type EnrichmentRecord struct {
    14  	Tags       []string
    15  	Enrichment json.RawMessage
    16  }
    17  
    18  // This EnrichmentRecord is basically using json.RawMessage to represent "Any"
    19  // in a way that will be able to be queried if needed in the future.
    20  
    21  // EnrichmentUpdater fetches an Enrichment data source, parses its contents,
    22  // and returns individual EnrichmentRecords.
    23  type EnrichmentUpdater interface {
    24  	// Name is a unique name for this updater.
    25  	//
    26  	// The name preferably indicates the vendor who implemented it and the
    27  	// enrichment data source it's fetching and interpreting.
    28  	// This must be paired with an Enricher using the same value.
    29  	Name() string
    30  	// FetchEnrichment should use the provided Fingerprint to determine if
    31  	// there's new data to download, and if so return it in an io.ReadCloser and
    32  	// a new Fingerprint.
    33  	//
    34  	// If there's no new data, the method should report Unchanged.
    35  	FetchEnrichment(context.Context, Fingerprint) (io.ReadCloser, Fingerprint, error)
    36  	// ParseEnrichment reads from the provided io.ReadCloser, parses its contents,
    37  	// and returns a slice of EnrichmentRecords or an error.
    38  	ParseEnrichment(context.Context, io.ReadCloser) ([]EnrichmentRecord, error)
    39  }
    40  
    41  // NoopUpdater is designed to be embedded into other Updater types so they can
    42  // be used in the original updater machinery.
    43  //
    44  // This may go away if the Updater interface becomes Vulnerability agnostic
    45  // in the future.
    46  type NoopUpdater struct{}
    47  
    48  // Fetch implements Updater.
    49  func (u NoopUpdater) Fetch(_ context.Context, _ Fingerprint) (io.ReadCloser, Fingerprint, error) {
    50  	return (*nilRC)(nil), "", nil
    51  }
    52  
    53  // Parse implements Updater.
    54  func (u NoopUpdater) Parse(_ context.Context, _ io.ReadCloser) ([]*claircore.Vulnerability, error) {
    55  	return []*claircore.Vulnerability{}, nil
    56  }
    57  
    58  // NilRC is a type whose nil pointer implements io.ReadCloser.
    59  type nilRC struct{}
    60  
    61  func (*nilRC) Close() error               { return nil }
    62  func (*nilRC) Read(_ []byte) (int, error) { return 0, io.EOF }
    63  
    64  // EnrichmentGetter is a handle to obtain Enrichments with a given tag.
    65  //
    66  // The implementation provided to an Enricher will make use of the Enricher's
    67  // name to scope down results.
    68  type EnrichmentGetter interface {
    69  	GetEnrichment(context.Context, []string) ([]EnrichmentRecord, error)
    70  }
    71  
    72  // Enricher is the interface for enriching a vulnerability report.
    73  //
    74  // Enrichers are called after the VulnerabilityReport is constructed.
    75  type Enricher interface {
    76  	// Name is a unique name for this Enricher.
    77  	//
    78  	// The name preferably indicates the vendor who implemented it and matches
    79  	// the corresponding EnrichmentUpdater.
    80  	Name() string
    81  	// Enrich extracts a set of tags from the provided VulnerabilityReport and utilizes
    82  	// the provided EnrichmentGetter to retrieve any Enrichments associated with the query tags.
    83  	//
    84  	// Enrichers may not modify the passed VulnerabilityReport. Doing so may
    85  	// panic the program.
    86  	//
    87  	// The implemented Enricher returns JSON blobs of Enrichment data and a key
    88  	// explaining to the client how to interpret the data.
    89  	Enrich(context.Context, EnrichmentGetter, *claircore.VulnerabilityReport) (string, []json.RawMessage, error)
    90  }