voucher

package module
v2.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 4, 2022 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var DefaultCheckFactories = make(CheckFactories)

DefaultCheckFactories is the default CheckFactory collection.

View Source 
var ErrNoAuth = errors.New("no configured Auth")

ErrNoAuth should be returned when something that depends on an Auth does not have one.

View Source 
var ErrNoCheck = errors.New("requested check doesn't exist")

ErrNoCheck is an error that is returned when a requested check hasn't been registered.

Functions

func AuthToClient 

func AuthToClient(ctx context.Context, auth Auth, image reference.Named) (*http.Client, error)

AuthToClient takes a struct implementing Auth and returns a new http.Client with the authentication details setup by Auth.GetTokenSource.

DEPRECATED: This function has been superceded by Auth.ToClient. This function now calls that method directly.

func GetCheckFactories 

func GetCheckFactories(names ...string) (map[string]Check, error)

GetCheckFactories gets new copies of the Checks from their registered CheckFactories.

func IsCheckFactoryRegistered 

func IsCheckFactoryRegistered(name string) bool

IsCheckFactoryRegistered returns true if the passed CheckFactory was registered.

func IsNoMetadataError 

func IsNoMetadataError(err error) bool

IsNoMetadataError returns true if the passed error is a NoMetadataError.

func NewVulnerabilityError 

func NewVulnerabilityError(vuls []Vulnerability) (err error)

NewVulnerabilityError creates a new VulnerabilityError with the passed Vulnerabilities.

func RegisterCheckFactory 

func RegisterCheckFactory(name string, creator CheckFactory)

RegisterCheckFactory adds a CheckFactory to the DefaultCheckFactories that can be run. Once a Check is added, it can be referenced by the name that was passed in when this function was called.

func ShouldIncludeVulnerability 

func ShouldIncludeVulnerability(test Vulnerability, baseline Severity) bool

ShouldIncludeVulnerability returns true if the passed vulnerability should be included in our vulnerability report.

Types

type Attestation 

type Attestation struct {
	CheckName string
	Body      string
}

Attestation is a structure that contains the Attestation data that we want to create an MetadataItem from.

func NewAttestation 

func NewAttestation(checkName string, payload string) Attestation

NewAttestation creates a new Attestation for the check with the passed name, with the payload as the body. The payload will then be signed by the key associated with the check (referenced by the checkName).

type Auth 

type Auth interface {
	GetTokenSource(context.Context, reference.Named) (oauth2.TokenSource, error)
	ToClient(ctx context.Context, image reference.Named) (*http.Client, error)
	IsForDomain(url reference.Named) bool
}

Auth is an interface that wraps an to an OAuth2 system, to simplify the path from having an image reference to getting access to the data that makes up that image from the registry it lives in.

type AuthorizedCheck 

type AuthorizedCheck interface {
	Check
	SetAuth(Auth)
}

AuthorizedCheck represents a Voucher check that needs to be authorized. For example, a check that needs to connect to the registry will need to implement AuthorizedCheck.

type Check 

type Check interface {
	Check(context.Context, ImageData) (bool, error)
}

Check represents a Voucher test.

type CheckFactories 

type CheckFactories map[string]CheckFactory

CheckFactories is a map of registered CheckFactories.

func (CheckFactories) Get 

func (cf CheckFactories) Get(name string) CheckFactory

Get returns the CheckFactory with the passed name.

func (CheckFactories) GetNewChecks 

func (cf CheckFactories) GetNewChecks(names ...string) (map[string]Check, error)

GetNewChecks gets new copies of the Checks from each of their registered CheckFactory.

func (CheckFactories) Register 

func (cf CheckFactories) Register(name string, creator CheckFactory)

Register adds a new CheckFactory to this CheckFactories.

type CheckFactory 

type CheckFactory func() Check

CheckFactory is a type of function that creates a new Check.

type CheckResult 

type CheckResult struct {
	ImageData ImageData   `json:"-"`
	Name      string      `json:"name"`
	Err       string      `json:"error,omitempty"`
	Success   bool        `json:"success"`
	Attested  bool        `json:"attested"`
	Details   interface{} `json:"details,omitempty"`
}

CheckResult describes the result of a Check. If a check failed, it will have a status of false. If a check succeeded, but its Attestation creation failed, Success will be true, Attested will be false. Err will contain the first error to occur.

func SignedAttestationToResult 

func SignedAttestationToResult(attestation SignedAttestation) CheckResult

SignedAttestationToResult returns a CheckResults from the SignedAttestation passed to it. Check names is set as appropriate.

type ImageData 

type ImageData = reference.Canonical

ImageData is a Canonical Reference to the Image (includes digest and URL).

func NewImageData 

func NewImageData(url string) (ImageData, error)

NewImageData creates a new ImageData item with the passed URL as a reference to the target image.

type Interface 

type Interface interface {
	Check(ctx context.Context, check string, image reference.Canonical) (Response, error)
	Verify(ctx context.Context, check string, image reference.Canonical) (Response, error)
}

Interface represents an interface to the Voucher API. Typically Voucher API clients would implement it.

type MetadataCheck 

type MetadataCheck interface {
	Check
	SetMetadataClient(MetadataClient)
}

MetadataCheck represents a Voucher check that interacts directly with a metadata server.

type MetadataClient 

type MetadataClient interface {
	CanAttest() bool
	NewPayloadBody(ImageData) (string, error)
	GetVulnerabilities(context.Context, ImageData) ([]Vulnerability, error)
	GetBuildDetail(context.Context, reference.Canonical) (repository.BuildDetail, error)
	AddAttestationToImage(context.Context, ImageData, Attestation) (SignedAttestation, error)
	GetAttestations(context.Context, ImageData) ([]SignedAttestation, error)
	Close()
}

MetadataClient is an interface that represents something that communicates with the Metadata server.

type MetadataScanner 

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

MetadataScanner implements voucher.VulnerabilityScanner, and connects to Grafeas to obtain vulnerability information.

func NewScanner 

func NewScanner(client MetadataClient) *MetadataScanner

NewScanner creates a new MetadataScanner.

func (*MetadataScanner) FailOn 

func (s *MetadataScanner) FailOn(severity Severity)

FailOn sets severity level that a vulnerability must match or exheed to prompt a failure.

func (*MetadataScanner) Scan 

func (s *MetadataScanner) Scan(ctx context.Context, i ImageData) ([]Vulnerability, error)

Scan gets the vulnerabilities for an Image.

type MetadataType 

type MetadataType string

MetadataType is a type which represents a MetadataClient's MetadataItem type. 

const (
	// VulnerabilityType is specific to MetadataItem containing vulnerabilities.
	VulnerabilityType MetadataType = "vulnerability"
	// BuildDetailsType refers to MetadataItems containing image build details.
	BuildDetailsType MetadataType = "build details"
	// AttestationType refers to MetadataItems containing Binary Authorization Attestations.
	AttestationType MetadataType = "attestation"
)

type MockCheck 

type MockCheck struct {
	mock.Mock
}

func (*MockCheck) Check 

func (m *MockCheck) Check(ctx context.Context, i ImageData) (bool, error)

type MockMetadataClient 

type MockMetadataClient struct {
	mock.Mock
}

func (*MockMetadataClient) AddAttestationToImage 

func (m *MockMetadataClient) AddAttestationToImage(ctx context.Context, imageData ImageData, attestation Attestation) (SignedAttestation, error)

func (*MockMetadataClient) CanAttest 

func (m *MockMetadataClient) CanAttest() bool

func (*MockMetadataClient) Close 

func (m *MockMetadataClient) Close()

func (*MockMetadataClient) GetAttestations 

func (m *MockMetadataClient) GetAttestations(ctx context.Context, imageData ImageData) ([]SignedAttestation, error)

func (*MockMetadataClient) GetBuildDetail 

func (m *MockMetadataClient) GetBuildDetail(ctx context.Context, ref reference.Canonical) (repository.BuildDetail, error)

func (*MockMetadataClient) GetVulnerabilities 

func (m *MockMetadataClient) GetVulnerabilities(ctx context.Context, imageData ImageData) ([]Vulnerability, error)

func (*MockMetadataClient) NewPayloadBody 

func (m *MockMetadataClient) NewPayloadBody(imageData ImageData) (string, error)

type NoMetadataError 

type NoMetadataError struct {
	Type MetadataType
	Err  error
}

NoMetadataError is an error that is returned when we request metadata that should exist but doesn't. It's a general error that will wrap more specific errors if desired.

func (*NoMetadataError) Error 

func (err *NoMetadataError) Error() string

Error returns the error value of this NoMetadataError as a string.

type ProvenanceCheck 

type ProvenanceCheck interface {
	Check
	SetTrustedBuildCreators([]string)
	SetTrustedProjects([]string)
}

ProvenanceCheck represents a Voucher check that sets trusted projects and build creators

type RepoValidatorCheck 

type RepoValidatorCheck interface {
	Check
	SetValidRepos(repos []string)
}

RepoValidatorCheck represents a Voucher check that validates the passed image is from a valid repo.

type RepositoryCheck 

type RepositoryCheck interface {
	MetadataCheck
	SetRepositoryClient(repository.Client)
}

RepositoryCheck represents a Voucher check that needs to lookup information about an image from the repository that it's source code is stored in.

RepositoryCheck implements a MetadataCheck, as containers normally do not contain information about their source repositories. This enables us to take advantage of Grafeas (or other metadata systems) which track build information for an image, in addition to signatures and (possibly) vulnerability information.

type Request 

type Request struct {
	ImageURL string `json:"image_url"`
}

Request describes the Voucher API request structure.

type Response 

type Response struct {
	Image   string        `json:"image"`
	Success bool          `json:"success"`
	Results []CheckResult `json:"results"`
}

Response describes the response from a Check call.

func NewResponse 

func NewResponse(reference reference.Reference, results []CheckResult) (checkResponse Response)

NewResponse creates a new Response for the passed ImageData, with the passed results.

type Severity 

type Severity int

Severity is a integer that represents how severe a vulnerability is. 

const (
	NegligibleSeverity Severity = iota
	LowSeverity        Severity = iota
	MediumSeverity     Severity = iota
	UnknownSeverity    Severity = iota
	HighSeverity       Severity = iota
	CriticalSeverity   Severity = iota
)

Severity constants, which represent the severities that we track. Other systems' severities should be converted to one of the following.

func StringToSeverity 

func StringToSeverity(s string) (Severity, error)

StringToSeverity returns the matching Severity to the passed string. Returns an error if there isn't a matching Severity.

func (Severity) String 

func (s Severity) String() string

String returns a string representation of a Severity.

type SignedAttestation 

type SignedAttestation struct {
	Attestation
	Signature string
	KeyID     string
}

SignedAttestation is a structure that contains the Attestation data as well as the signature and signing key ID.

func SignAttestation 

func SignAttestation(s signer.AttestationSigner, attestation Attestation) (SignedAttestation, error)

SignAttestation takes a keyring and attestation and signs the body of the payload with it, updating the Attestation's Signature field.

type Suite 

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

Suite is a suite of Checks, which

func NewSuite 

func NewSuite() *Suite

NewSuite creates a new Suite.

func (*Suite) Add 

func (cs *Suite) Add(name string, check Check)

Add adds a Check to the checks that can be run. Once a Check is added, it can be referenced by the name that was passed in when this function was called.

func (*Suite) Attest 

func (cs *Suite) Attest(ctx context.Context, metricsClient metrics.Client, metadataClient MetadataClient, results []CheckResult) []CheckResult

Attest runs through the passed []CheckResult and if a CheckResult is marked as successful, runs the CreateAttestion function in the Check corresponding to that CheckResult. Each CheckResult is updated with the details (or error) and the resulting []CheckResult is returned.

func (*Suite) Get 

func (cs *Suite) Get(name string) (Check, error)

Get returns the requested Check, or nil if one does not exist.

func (*Suite) Has 

func (cs *Suite) Has(name string) bool

Has returns true if the passed check exists. Returns false if it does not.

func (*Suite) Run 

func (cs *Suite) Run(ctx context.Context, metricsClient metrics.Client, imageData ImageData) []CheckResult

Run executes each of the Checks specified by the activeChecks parameter.

For example, if a Suite has the "diy" and "nobody" tests, calling 

Run(imageData)

will run the "diy" and "nobody" tests.

Run returns a []CheckResult with a CheckResult for each Check that was run.

func (*Suite) RunAndAttest 

func (cs *Suite) RunAndAttest(ctx context.Context, metadataClient MetadataClient, metricsClient metrics.Client, imageData ImageData) []CheckResult

RunAndAttest calls Run, followed by Attest, and returns the final []CheckResult.

type VulnerabilitiesError 

type VulnerabilitiesError struct {
	Vulnerabilities []Vulnerability
}

VulnerabilitiesError is an error that also contains a list of vulnerabilities.

func (VulnerabilitiesError) Error 

func (err VulnerabilitiesError) Error() string

Error returns the error message for the VulnerabilitiesError

type Vulnerability 

type Vulnerability struct {
	Name        string   `json:"name"`        // Name of the Vulnerability, or it's CVE number.
	Description string   `json:"description"` // Description of the Vulnerability.
	Severity    Severity `json:"severity"`    // Severity of the Vulnerability.
	FixedBy     string   `json:"fixed_by"`    // If this vulnerability was fixed, what it was fixed by.
}

Vulnerability is a type that describes a security vulnerability. Third-party scanner vulnerabilities should be converted to this type.

type VulnerabilityCheck 

type VulnerabilityCheck interface {
	Check
	SetScanner(VulnerabilityScanner)
}

VulnerabilityCheck represents a Voucher test.

type VulnerabilityScanner 

type VulnerabilityScanner interface {

	// FailOn sets the minimum Severity to consider an image vulnerable.
	FailOn(Severity)

	// Scan runs a scan against the passed ImageData and returns a slice of
	// Vulnerabilities.
	Scan(context.Context, ImageData) ([]Vulnerability, error)
}

VulnerabilityScanner is an interface which represents a scanners that can be used to check an image for vulnerabilities. VulnerabilityScanners implement the Scan method, which takes ImageData as input and returns a slice of Vulnerabilities.

Source Files

View all Source files

Directories

Path Synopsis
google
checks
approved
diy
nobody
org
provenance
snakeoil
cmd
config
voucher_client
voucher_server
voucher_subscriber
schema1
schema2
uri
mocks
Package mock_grafeas is a generated GoMock package.
 Package mock_grafeas is a generated GoMock package.
objects
github
kms
pgp

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.