database

Documentation

Overview

Package database defines the Clair's models and a common interface for database implementations.

Index

• Variables
• func Register(name string, driver Driver)
• type Datastore
  • func Open(cfg config.RegistrableComponentConfig) (Datastore, error)
• type Driver
• type Feature
• type FeatureVersion
• type Layer
• type MetadataMap
  • func (mm *MetadataMap) Scan(value interface{}) error
  • func (mm *MetadataMap) Value() (driver.Value, error)
• type MockDatastore
  • func (mds *MockDatastore) Close()
  • func (mds *MockDatastore) DeleteLayer(name string) error
  • func (mds *MockDatastore) DeleteNotification(name string) error
  • func (mds *MockDatastore) DeleteVulnerability(namespaceName, name string) error
  • func (mds *MockDatastore) DeleteVulnerabilityFix(vulnerabilityNamespace, vulnerabilityName, featureName string) error
  • func (mds *MockDatastore) FindLayer(name string, withFeatures, withVulnerabilities bool) (Layer, error)
  • func (mds *MockDatastore) FindLock(name string) (string, time.Time, error)
  • func (mds *MockDatastore) FindVulnerability(namespaceName, name string) (Vulnerability, error)
  • func (mds *MockDatastore) GetAvailableNotification(renotifyInterval time.Duration) (VulnerabilityNotification, error)
  • func (mds *MockDatastore) GetKeyValue(key string) (string, error)
  • func (mds *MockDatastore) GetNotification(name string, limit int, page VulnerabilityNotificationPageNumber) (VulnerabilityNotification, VulnerabilityNotificationPageNumber, error)
  • func (mds *MockDatastore) InsertKeyValue(key, value string) error
  • func (mds *MockDatastore) InsertLayer(layer Layer) error
  • func (mds *MockDatastore) InsertVulnerabilities(vulnerabilities []Vulnerability, createNotification bool) error
  • func (mds *MockDatastore) InsertVulnerabilityFixes(vulnerabilityNamespace, vulnerabilityName string, fixes []FeatureVersion) error
  • func (mds *MockDatastore) ListNamespaces() ([]Namespace, error)
  • func (mds *MockDatastore) ListVulnerabilities(namespaceName string, limit int, page int) ([]Vulnerability, int, error)
  • func (mds *MockDatastore) Lock(name string, owner string, duration time.Duration, renew bool) (bool, time.Time)
  • func (mds *MockDatastore) Ping() bool
  • func (mds *MockDatastore) SetNotificationNotified(name string) error
  • func (mds *MockDatastore) Unlock(name, owner string)
• type Model
• type Namespace
• type Vulnerability
• type VulnerabilityNotification
• type VulnerabilityNotificationPageNumber

Variables

var (
	// ErrBackendException is an error that occurs when the database backend does
	// not work properly (ie. unreachable).
	ErrBackendException = errors.New("database: an error occured when querying the backend")

	// ErrInconsistent is an error that occurs when a database consistency check
	// fails (ie. when an entity which is supposed to be unique is detected twice)
	ErrInconsistent = errors.New("database: inconsistent database")
)

var DebianReleasesMapping = map[string]string{

	"squeeze": "6",
	"wheezy":  "7",
	"jessie":  "8",
	"stretch": "9",
	"sid":     "unstable",

	"oldstable": "7",
	"stable":    "8",
	"testing":   "9",
	"unstable":  "unstable",
}

DebianReleasesMapping translates Debian code names and class names to version numbers

var NoVulnerabilityNotificationPage = VulnerabilityNotificationPageNumber{-1, -1}

var UbuntuReleasesMapping = map[string]string{
	"precise": "12.04",
	"quantal": "12.10",
	"raring":  "13.04",
	"trusty":  "14.04",
	"utopic":  "14.10",
	"vivid":   "15.04",
	"wily":    "15.10",
	"xenial":  "16.04",
	"yakkety": "16.10",
}

UbuntuReleasesMapping translates Ubuntu code names to version numbers

var VulnerabilityNotificationFirstPage = VulnerabilityNotificationPageNumber{0, 0}

Functions

func Register

func Register(name string, driver Driver)

Register makes a Constructor available by the provided name.

If this function is called twice with the same name or if the Constructor is nil, it panics.

Types

type Datastore

type Datastore interface {
	// # Namespace
	// ListNamespaces returns the entire list of known Namespaces.
	ListNamespaces() ([]Namespace, error)

	// # Layer
	// InsertLayer stores a Layer in the database.
	// A Layer is uniquely identified by its Name. The Name and EngineVersion fields are mandatory.
	// If a Parent is specified, it is expected that it has been retrieved using FindLayer.
	// If a Layer that already exists is inserted and the EngineVersion of the given Layer is higher
	// than the stored one, the stored Layer should be updated.
	// The function has to be idempotent, inserting a layer that already exists shouln'd return an
	// error.
	InsertLayer(Layer) error

	// FindLayer retrieves a Layer from the database.
	// withFeatures specifies whether the Features field should be filled. When withVulnerabilities is
	// true, the Features field should be filled and their AffectedBy fields should contain every
	// vulnerabilities that affect them.
	FindLayer(name string, withFeatures, withVulnerabilities bool) (Layer, error)

	// DeleteLayer deletes a Layer from the database and every layers that are based on it,
	// recursively.
	DeleteLayer(name string) error

	// # Vulnerability
	// ListVulnerabilities returns the list of vulnerabilies of a certain Namespace.
	// The Limit and page parameters are used to paginate the return list.
	// The first given page should be 0. The function will then return the next available page.
	// If there is no more page, -1 has to be returned.
	ListVulnerabilities(namespaceName string, limit int, page int) ([]Vulnerability, int, error)

	// InsertVulnerabilities stores the given Vulnerabilities in the database, updating them if
	// necessary. A vulnerability is uniquely identified by its Namespace and its Name.
	// The FixedIn field may only contain a partial list of Features that are affected by the
	// Vulnerability, along with the version in which the vulnerability is fixed. It is the
	// responsibility of the implementation to update the list properly. A version equals to
	// types.MinVersion means that the given Feature is not being affected by the Vulnerability at
	// all and thus, should be removed from the list. It is important that Features should be unique
	// in the FixedIn list. For example, it doesn't make sense to have two `openssl` Feature listed as
	// a Vulnerability can only be fixed in one Version. This is true because Vulnerabilities and
	// Features are Namespaced (i.e. specific to one operating system).
	// Each vulnerability insertion or update has to create a Notification that will contain the
	// old and the updated Vulnerability, unless createNotification equals to true.
	InsertVulnerabilities(vulnerabilities []Vulnerability, createNotification bool) error

	// FindVulnerability retrieves a Vulnerability from the database, including the FixedIn list.
	FindVulnerability(namespaceName, name string) (Vulnerability, error)

	// DeleteVulnerability removes a Vulnerability from the database.
	// It has to create a Notification that will contain the old Vulnerability.
	DeleteVulnerability(namespaceName, name string) error

	// InsertVulnerabilityFixes adds new FixedIn Feature or update the Versions of existing ones to
	// the specified Vulnerability in the database.
	// It has has to create a Notification that will contain the old and the updated Vulnerability.
	InsertVulnerabilityFixes(vulnerabilityNamespace, vulnerabilityName string, fixes []FeatureVersion) error

	// DeleteVulnerabilityFix removes a FixedIn Feature from the specified Vulnerability in the
	// database. It can be used to store the fact that a Vulnerability no longer affects the given
	// Feature in any Version.
	// It has has to create a Notification that will contain the old and the updated Vulnerability.
	DeleteVulnerabilityFix(vulnerabilityNamespace, vulnerabilityName, featureName string) error

	// # Notification
	// GetAvailableNotification returns the Name, Created, Notified and Deleted fields of a
	// Notification that should be handled. The renotify interval defines how much time after being
	// marked as Notified by SetNotificationNotified, a Notification that hasn't been deleted should
	// be returned again by this function. A Notification for which there is a valid Lock with the
	// same Name should not be returned.
	GetAvailableNotification(renotifyInterval time.Duration) (VulnerabilityNotification, error)

	// GetNotification returns a Notification, including its OldVulnerability and NewVulnerability
	// fields. On these Vulnerabilities, LayersIntroducingVulnerability should be filled with
	// every Layer that introduces the Vulnerability (i.e. adds at least one affected FeatureVersion).
	// The Limit and page parameters are used to paginate LayersIntroducingVulnerability. The first
	// given page should be VulnerabilityNotificationFirstPage. The function will then return the next
	// availage page. If there is no more page, NoVulnerabilityNotificationPage has to be returned.
	GetNotification(name string, limit int, page VulnerabilityNotificationPageNumber) (VulnerabilityNotification, VulnerabilityNotificationPageNumber, error)

	// SetNotificationNotified marks a Notification as notified and thus, makes it unavailable for
	// GetAvailableNotification, until the renotify duration is elapsed.
	SetNotificationNotified(name string) error

	// DeleteNotification marks a Notification as deleted, and thus, makes it unavailable for
	// GetAvailableNotification.
	DeleteNotification(name string) error

	// # Key/Value
	// InsertKeyValue stores or updates a simple key/value pair in the database.
	InsertKeyValue(key, value string) error

	// GetKeyValue retrieves a value from the database from the given key.
	// It returns an empty string if there is no such key.
	GetKeyValue(key string) (string, error)

	// # Lock
	// Lock creates or renew a Lock in the database with the given name, owner and duration.
	// After the specified duration, the Lock expires by itself if it hasn't been unlocked, and thus,
	// let other users create a Lock with the same name. However, the owner can renew its Lock by
	// setting renew to true. Lock should not block, it should instead returns whether the Lock has
	// been successfully acquired/renewed. If it's the case, the expiration time of that Lock is
	// returned as well.
	Lock(name string, owner string, duration time.Duration, renew bool) (bool, time.Time)

	// Unlock releases an existing Lock.
	Unlock(name, owner string)

	// FindLock returns the owner of a Lock specified by the name, and its experation time if it
	// exists.
	FindLock(name string) (string, time.Time, error)

	// # Miscellaneous
	// Ping returns the health status of the database.
	Ping() bool

	// Close closes the database and free any allocated resource.
	Close()
}

Datastore is the interface that describes a database backend implementation.

func Open

func Open(cfg config.RegistrableComponentConfig) (Datastore, error)

Open opens a Datastore specified by a configuration.

type Driver

type Driver func(config.RegistrableComponentConfig) (Datastore, error)

Driver is a function that opens a Datastore specified by its database driver type and specific configuration.

type Feature

type Feature struct {
	Model

	Name      string
	Namespace Namespace
}

type FeatureVersion

type FeatureVersion struct {
	Model

	Feature    Feature
	Version    string
	AffectedBy []Vulnerability

	// For output purposes. Only make sense when the feature version is in the context of an image.
	AddedBy Layer
}

type Layer

type Layer struct {
	Model

	Name          string
	EngineVersion int
	Parent        *Layer
	Namespace     *Namespace
	Features      []FeatureVersion
}

type MetadataMap

type MetadataMap map[string]interface{}

func (*MetadataMap) Scan

func (mm *MetadataMap) Scan(value interface{}) error

func (*MetadataMap) Value

func (mm *MetadataMap) Value() (driver.Value, error)

type MockDatastore

type MockDatastore struct {
	FctListNamespaces           func() ([]Namespace, error)
	FctInsertLayer              func(Layer) error
	FctFindLayer                func(name string, withFeatures, withVulnerabilities bool) (Layer, error)
	FctDeleteLayer              func(name string) error
	FctListVulnerabilities      func(namespaceName string, limit int, page int) ([]Vulnerability, int, error)
	FctInsertVulnerabilities    func(vulnerabilities []Vulnerability, createNotification bool) error
	FctFindVulnerability        func(namespaceName, name string) (Vulnerability, error)
	FctDeleteVulnerability      func(namespaceName, name string) error
	FctInsertVulnerabilityFixes func(vulnerabilityNamespace, vulnerabilityName string, fixes []FeatureVersion) error
	FctDeleteVulnerabilityFix   func(vulnerabilityNamespace, vulnerabilityName, featureName string) error
	FctGetAvailableNotification func(renotifyInterval time.Duration) (VulnerabilityNotification, error)
	FctGetNotification          func(name string, limit int, page VulnerabilityNotificationPageNumber) (VulnerabilityNotification, VulnerabilityNotificationPageNumber, error)
	FctSetNotificationNotified  func(name string) error
	FctDeleteNotification       func(name string) error
	FctInsertKeyValue           func(key, value string) error
	FctGetKeyValue              func(key string) (string, error)
	FctLock                     func(name string, owner string, duration time.Duration, renew bool) (bool, time.Time)
	FctUnlock                   func(name, owner string)
	FctFindLock                 func(name string) (string, time.Time, error)
	FctPing                     func() bool
	FctClose                    func()
}

MockDatastore implements Datastore and enables overriding each available method. The default behavior of each method is to simply panic.

func (*MockDatastore) Close

func (mds *MockDatastore) Close()

func (*MockDatastore) DeleteLayer

func (mds *MockDatastore) DeleteLayer(name string) error

func (*MockDatastore) DeleteNotification

func (mds *MockDatastore) DeleteNotification(name string) error

func (*MockDatastore) DeleteVulnerability

func (mds *MockDatastore) DeleteVulnerability(namespaceName, name string) error

func (*MockDatastore) DeleteVulnerabilityFix

func (mds *MockDatastore) DeleteVulnerabilityFix(vulnerabilityNamespace, vulnerabilityName, featureName string) error

func (*MockDatastore) FindLayer

func (mds *MockDatastore) FindLayer(name string, withFeatures, withVulnerabilities bool) (Layer, error)

func (*MockDatastore) FindLock

func (mds *MockDatastore) FindLock(name string) (string, time.Time, error)

func (*MockDatastore) FindVulnerability

func (mds *MockDatastore) FindVulnerability(namespaceName, name string) (Vulnerability, error)

func (*MockDatastore) GetAvailableNotification

func (mds *MockDatastore) GetAvailableNotification(renotifyInterval time.Duration) (VulnerabilityNotification, error)

func (*MockDatastore) GetKeyValue

func (mds *MockDatastore) GetKeyValue(key string) (string, error)

func (*MockDatastore) GetNotification

func (mds *MockDatastore) GetNotification(name string, limit int, page VulnerabilityNotificationPageNumber) (VulnerabilityNotification, VulnerabilityNotificationPageNumber, error)

func (*MockDatastore) InsertKeyValue

func (mds *MockDatastore) InsertKeyValue(key, value string) error

func (*MockDatastore) InsertLayer

func (mds *MockDatastore) InsertLayer(layer Layer) error

func (*MockDatastore) InsertVulnerabilities

func (mds *MockDatastore) InsertVulnerabilities(vulnerabilities []Vulnerability, createNotification bool) error

func (*MockDatastore) InsertVulnerabilityFixes

func (mds *MockDatastore) InsertVulnerabilityFixes(vulnerabilityNamespace, vulnerabilityName string, fixes []FeatureVersion) error

func (*MockDatastore) ListNamespaces

func (mds *MockDatastore) ListNamespaces() ([]Namespace, error)

func (*MockDatastore) ListVulnerabilities

func (mds *MockDatastore) ListVulnerabilities(namespaceName string, limit int, page int) ([]Vulnerability, int, error)

func (*MockDatastore) Lock

func (mds *MockDatastore) Lock(name string, owner string, duration time.Duration, renew bool) (bool, time.Time)

func (*MockDatastore) Ping

func (mds *MockDatastore) Ping() bool

func (*MockDatastore) SetNotificationNotified

func (mds *MockDatastore) SetNotificationNotified(name string) error

func (*MockDatastore) Unlock

func (mds *MockDatastore) Unlock(name, owner string)

type Model

type Model struct {
	ID int
}

ID is only meant to be used by database implementations and should never be used for anything else.

type Namespace

type Namespace struct {
	Model

	Name          string
	VersionFormat string
}

type Vulnerability

type Vulnerability struct {
	Model

	Name      string
	Namespace Namespace

	Description string
	Link        string
	Severity    types.Priority

	Metadata MetadataMap

	FixedIn                        []FeatureVersion
	LayersIntroducingVulnerability []Layer

	// For output purposes. Only make sense when the vulnerability
	// is already about a specific Feature/FeatureVersion.
	FixedBy string `json:",omitempty"`
}

type VulnerabilityNotification

type VulnerabilityNotification struct {
	Model

	Name string

	Created  time.Time
	Notified time.Time
	Deleted  time.Time

	OldVulnerability *Vulnerability
	NewVulnerability *Vulnerability
}

type VulnerabilityNotificationPageNumber

type VulnerabilityNotificationPageNumber struct {
	// -1 means that we reached the end already.
	OldVulnerability int
	NewVulnerability int
}