Documentation ¶
Index ¶
- Variables
- func AuthToClient(ctx context.Context, auth Auth, image reference.Named) (*http.Client, error)
- func GetCheckFactories(names ...string) (map[string]Check, error)
- func IsCheckFactoryRegistered(name string) bool
- func IsNoMetadataError(err error) bool
- func NewVulnerabilityError(vuls []Vulnerability) (err error)
- func RegisterCheckFactory(name string, creator CheckFactory)
- func ShouldIncludeVulnerability(test Vulnerability, baseline Severity) bool
- type Attestation
- type Auth
- type AuthorizedCheck
- type Check
- type CheckFactories
- type CheckFactory
- type CheckResult
- type ImageData
- type Interface
- type MetadataCheck
- type MetadataClient
- type MetadataScanner
- type MetadataType
- type MockCheck
- type MockMetadataClient
- func (m *MockMetadataClient) AddAttestationToImage(ctx context.Context, imageData ImageData, attestation Attestation) (SignedAttestation, error)
- func (m *MockMetadataClient) CanAttest() bool
- func (m *MockMetadataClient) Close()
- func (m *MockMetadataClient) GetAttestations(ctx context.Context, imageData ImageData) ([]SignedAttestation, error)
- func (m *MockMetadataClient) GetBuildDetail(ctx context.Context, ref reference.Canonical) (repository.BuildDetail, error)
- func (m *MockMetadataClient) GetVulnerabilities(ctx context.Context, imageData ImageData) ([]Vulnerability, error)
- func (m *MockMetadataClient) NewPayloadBody(imageData ImageData) (string, error)
- type NoMetadataError
- type ProvenanceCheck
- type RepoValidatorCheck
- type RepositoryCheck
- type Request
- type Response
- type Severity
- type SignedAttestation
- type Suite
- func (cs *Suite) Add(name string, check Check)
- func (cs *Suite) Attest(ctx context.Context, metricsClient metrics.Client, ...) []CheckResult
- func (cs *Suite) Get(name string) (Check, error)
- func (cs *Suite) Has(name string) bool
- func (cs *Suite) Run(ctx context.Context, metricsClient metrics.Client, imageData ImageData) []CheckResult
- func (cs *Suite) RunAndAttest(ctx context.Context, metadataClient MetadataClient, ...) []CheckResult
- type VulnerabilitiesError
- type Vulnerability
- type VulnerabilityCheck
- type VulnerabilityScanner
Constants ¶
This section is empty.
Variables ¶
var DefaultCheckFactories = make(CheckFactories)
DefaultCheckFactories is the default CheckFactory collection.
var ErrNoAuth = errors.New("no configured Auth")
ErrNoAuth should be returned when something that depends on an Auth does not have one.
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 ¶
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 ¶
GetCheckFactories gets new copies of the Checks from their registered CheckFactories.
func IsCheckFactoryRegistered ¶
IsCheckFactoryRegistered returns true if the passed CheckFactory was registered.
func IsNoMetadataError ¶
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 ¶
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 ¶
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 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 ¶
ImageData is a Canonical Reference to the Image (includes digest and URL).
func NewImageData ¶
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 MockMetadataClient ¶
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 ¶
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 ¶
StringToSeverity returns the matching Severity to the passed string. Returns an error if there isn't a matching 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 (*Suite) Add ¶
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) 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 ¶
- attestation.go
- auth.go
- authorizedcheck.go
- check.go
- imagedata.go
- interface.go
- metadatacheck.go
- metadataclient.go
- metadatatype.go
- mock_check.go
- mock_metadataclient.go
- provenancecheck.go
- register.go
- repositorycheck.go
- request.go
- response.go
- result.go
- scanner.go
- severity.go
- suite.go
- validrepocheck.go
- vulnerability.go
- vulnerability_error.go
- vulnerability_scanner.go
- vulnerabilitycheck.go