Documentation
¶
Index ¶
- Constants
- Variables
- func BatchSubmitter(signer *SignerContext) string
- func PruneBatches(ctx context.Context, db *gorm.DB, acceptedBefore time.Time) (int64, error)
- func RejectBatchItem(err error) error
- type AgentSignerContext
- type BatchItemFunc
- type BatchItemRejectedError
- type BatchItemResult
- type BatchJobEnqueuer
- type BatchService
- func (s *BatchService) Available() error
- func (s *BatchService) Get(ctx context.Context, batchID uuid.UUID, submittedBy string) (*BatchSummary, error)
- func (s *BatchService) GetAny(ctx context.Context, batchID uuid.UUID) (*BatchSummary, error)
- func (s *BatchService) ProcessChunk(ctx context.Context, batchID uuid.UUID, chunk int, finalAttempt bool) error
- func (s *BatchService) Submit(ctx context.Context, payloads []json.RawMessage, signer *SignerContext) (*BatchSummary, error)
- type BatchStatus
- type BatchSummary
- type ComponentDefinitionResolver
- type CreateEvidenceParams
- type EvidenceOrigin
- type EvidenceService
- func (s *EvidenceService) Create(ctx context.Context, params CreateEvidenceParams) (*relational.Evidence, error)
- func (s *EvidenceService) GetByID(id uuid.UUID) (*relational.Evidence, error)
- func (s *EvidenceService) GetControlByID(id string) (*relational.Control, error)
- func (s *EvidenceService) GetFilterByID(id uuid.UUID) (*relational.Filter, error)
- func (s *EvidenceService) GetHistory(streamUUID uuid.UUID) ([]relational.Evidence, error)
- func (s *EvidenceService) GetHistoryPaginated(streamUUID uuid.UUID, limit, offset int) ([]relational.Evidence, int64, error)
- func (s *EvidenceService) GetLatestByUUID(streamUUID uuid.UUID) (*relational.Evidence, error)
- func (s *EvidenceService) GetLatestForFilters(filters ...labelfilter.Filter) ([]relational.Evidence, error)
- func (s *EvidenceService) GetSignatureByID(id uuid.UUID) (*SignatureDetail, error)
- func (s *EvidenceService) GetStatusCountsAtPoint(filter labelfilter.Filter, endBefore *time.Time) ([]StatusCount, error)
- func (s *EvidenceService) GetStatusCountsByFilters(filters ...labelfilter.Filter) ([]StatusCount, error)
- func (s *EvidenceService) GetStatusCountsByUUIDAtPoint(streamUUID uuid.UUID, endBefore *time.Time) ([]StatusCount, error)
- func (s *EvidenceService) ManualEvidenceRequiresSubject() bool
- func (s *EvidenceService) Search(filter labelfilter.Filter) ([]relational.Evidence, error)
- func (s *EvidenceService) SearchPaginated(filter labelfilter.Filter, opts SearchOptions) ([]relational.Evidence, int64, error)
- func (s *EvidenceService) VerifyByID(id uuid.UUID) (*VerificationResult, error)
- type EvidenceServiceOption
- type RiskJobEnqueuer
- type SearchOptions
- type SearchSortBy
- type SearchSortDirection
- type SignatureDetail
- type SignerContext
- type SigningService
- type StatusCount
- type UserSignerContext
- type VerificationChecks
- type VerificationResult
Constants ¶
const ( SignatureStatusSigned = "signed" SignatureStatusUnsigned = "unsigned" )
Variables ¶
var ( // ErrBatchSubmitterRequired is returned when a batch is submitted without an // authenticated user or agent: its evidence is signed and only its submitter may // read the batch back. ErrBatchSubmitterRequired = errors.New("evidence batches need an authenticated user or agent") // ErrBatchNotFound is returned for a batch that doesn't exist or wasn't submitted by // the caller. ErrBatchNotFound = errors.New("evidence batch not found") )
var ErrSubjectRequired = errors.New("evidence has no subject")
ErrSubjectRequired is returned when evidence that must have a subject has none.
var ErrTooManySubjects = errors.New("too many subjects")
ErrTooManySubjects is returned when evidence names more subjects than one lookup allows.
var ErrUnknownSubject = errors.New("unknown subject")
ErrUnknownSubject is returned when evidence names a subject that doesn't exist.
Functions ¶
func BatchSubmitter ¶ added in v0.22.0
func BatchSubmitter(signer *SignerContext) string
BatchSubmitter is the identity a batch is stored under: "user:<subject>" for a user, "agent:<agent id>" for an agent, or "" when the signer identifies no one.
func PruneBatches ¶ added in v0.22.0
PruneBatches deletes the evidence batches accepted before acceptedBefore, with their items, and returns how many batches it deleted. The evidence the batches stored is kept. Batches still pending are deleted too: a batch whose jobs were never queued (see BatchService.Submit) would otherwise stay pending forever, and nobody polls a batch that old. A chunk job that runs after its batch is gone does nothing.
func RejectBatchItem ¶ added in v0.22.0
RejectBatchItem wraps err as a BatchItemRejectedError.
Types ¶
type AgentSignerContext ¶ added in v0.15.0
type AgentSignerContext struct {
Claims *authn.AgentClaims
Agent *relational.Agent
Key *relational.AgentServiceAccountKey
}
type BatchItemFunc ¶ added in v0.22.0
type BatchItemFunc func(ctx context.Context, payload json.RawMessage, signer *SignerContext, onCreated func(tx *gorm.DB, evidence *relational.Evidence) error) error
BatchItemFunc stores one batch item as evidence. It must hand onCreated to EvidenceService.Create (CreateEvidenceParams.OnCreated) so the item is marked done in the transaction that stores its evidence, and return a BatchItemRejectedError for an item the submitter has to fix. Any other error is retried.
type BatchItemRejectedError ¶ added in v0.22.0
type BatchItemRejectedError struct {
Err error
}
BatchItemRejectedError marks an item the submitter has to fix (invalid evidence, an unknown subject, ...). The item fails with this message and is not retried.
func (*BatchItemRejectedError) Error ¶ added in v0.22.0
func (e *BatchItemRejectedError) Error() string
func (*BatchItemRejectedError) Unwrap ¶ added in v0.22.0
func (e *BatchItemRejectedError) Unwrap() error
type BatchItemResult ¶ added in v0.22.0
type BatchItemResult struct {
Index int
Status relational.EvidenceBatchItemStatus
EvidenceID *uuid.UUID
Error string
}
BatchItemResult is one item's outcome.
type BatchJobEnqueuer ¶ added in v0.22.0
type BatchJobEnqueuer interface {
// EvidenceBatchesAvailable reports why batches can't be processed (no worker
// service), or nil.
EvidenceBatchesAvailable() error
EnqueueEvidenceBatchChunks(ctx context.Context, batchID uuid.UUID, chunks int) error
}
BatchJobEnqueuer starts the background jobs that process a batch, one per chunk.
type BatchService ¶ added in v0.22.0
type BatchService struct {
// contains filtered or unexported fields
}
BatchService accepts evidence batches and stores their evidence in the background.
func NewBatchService ¶ added in v0.22.0
func NewBatchService(db *gorm.DB, logger *zap.SugaredLogger, enqueuer BatchJobEnqueuer, processItem BatchItemFunc, chunkSize int) *BatchService
func (*BatchService) Available ¶ added in v0.22.0
func (s *BatchService) Available() error
Available reports why batches can't be accepted right now, or nil.
func (*BatchService) Get ¶ added in v0.22.0
func (s *BatchService) Get(ctx context.Context, batchID uuid.UUID, submittedBy string) (*BatchSummary, error)
Get returns a batch submitted by submittedBy (see BatchSubmitter) with every item's outcome, or ErrBatchNotFound.
func (*BatchService) GetAny ¶ added in v0.22.0
func (s *BatchService) GetAny(ctx context.Context, batchID uuid.UUID) (*BatchSummary, error)
GetAny returns any batch with every item's outcome, whoever submitted it, or ErrBatchNotFound. Callers check the reader may inspect other submitters' batches (evidence:inspect).
func (*BatchService) ProcessChunk ¶ added in v0.22.0
func (s *BatchService) ProcessChunk(ctx context.Context, batchID uuid.UUID, chunk int, finalAttempt bool) error
ProcessChunk stores the pending items of one chunk of a batch. An item rejected by BatchItemFunc fails with its message. Any other error stops the chunk so the job is retried; on the job's final attempt the item fails instead. Each item is marked done in the transaction that stores its evidence, so a retried or duplicated job never stores an item twice.
func (*BatchService) Submit ¶ added in v0.22.0
func (s *BatchService) Submit(ctx context.Context, payloads []json.RawMessage, signer *SignerContext) (*BatchSummary, error)
Submit stores the payloads as a pending batch and starts its background jobs.
type BatchStatus ¶ added in v0.22.0
type BatchStatus string
BatchStatus is a batch's progress, derived from its items.
const ( // BatchStatusPending batches have no item processed yet. BatchStatusPending BatchStatus = "pending" // BatchStatusProcessing batches have some items processed and some pending. BatchStatusProcessing BatchStatus = "processing" // BatchStatusCompleted batches have every item succeeded or failed. BatchStatusCompleted BatchStatus = "completed" )
type BatchSummary ¶ added in v0.22.0
type BatchSummary struct {
ID uuid.UUID
// SubmittedBy is the submitter's identity (see BatchSubmitter).
SubmittedBy string
Status BatchStatus
Total int
Pending int
Succeeded int
Failed int
AcceptedAt time.Time
Items []BatchItemResult
}
BatchSummary is a batch's progress and the outcome of each item.
type ComponentDefinitionResolver ¶
type ComponentDefinitionResolver interface {
ResolveOrUpsertComponentDefinition(input templates.ResolveOrUpsertComponentDefinitionInput) (*templates.ResolveOrUpsertComponentDefinitionResult, error)
FindSystemComponentsByDefinedComponentIDs(definedComponentIDs []uuid.UUID) ([]relational.SystemComponent, error)
}
ComponentDefinitionResolver resolves or creates ComponentDefinition + DefinedComponent records from evidence labels and returns the SystemComponents linked to those DefinedComponents.
type CreateEvidenceParams ¶
type CreateEvidenceParams struct {
Evidence relational.Evidence
Components []relational.SystemComponent
InventoryItems []relational.InventoryItem
Activities []relational.Activity
Subjects []relational.AssessmentSubject
Labels []relational.Labels
Signer *SignerContext
// Origin is set by creation paths that aren't identified by their signer (workflow,
// system). Left empty, the signer decides; see EffectiveOrigin.
Origin EvidenceOrigin
// DeclaredSubjectUUIDs are subjects the submitter names explicitly: defined components,
// SSP system components, parties or users.
DeclaredSubjectUUIDs []uuid.UUID
// OnCreated, when set, runs last in the transaction that stores the evidence, so what
// it records commits or rolls back with the evidence. An error rolls both back.
OnCreated func(tx *gorm.DB, evidence *relational.Evidence) error
}
func (CreateEvidenceParams) EffectiveOrigin ¶ added in v0.21.0
func (p CreateEvidenceParams) EffectiveOrigin() EvidenceOrigin
EffectiveOrigin is the origin the evidence is treated as: the one its creation path set explicitly (workflow and system paths do), otherwise the one its signer implies.
type EvidenceOrigin ¶ added in v0.21.0
type EvidenceOrigin string
EvidenceOrigin is where a piece of evidence came from. It decides which subject rules apply to it.
const ( OriginAgent EvidenceOrigin = "agent" OriginUser EvidenceOrigin = "user" OriginWorkflow EvidenceOrigin = "workflow" OriginSystem EvidenceOrigin = "system" )
func OriginFromSigner ¶ added in v0.21.0
func OriginFromSigner(signer *SignerContext) EvidenceOrigin
OriginFromSigner derives the origin of evidence submitted through the API: a user signer means user, and an agent signer or no signer (anonymous public ingest) means agent.
type EvidenceService ¶
type EvidenceService struct {
// contains filtered or unexported fields
}
func NewEvidenceService ¶
func NewEvidenceService(db *gorm.DB, logger *zap.SugaredLogger, cfg *config.Config, riskEnqueuer RiskJobEnqueuer, opts ...EvidenceServiceOption) *EvidenceService
func (*EvidenceService) Create ¶
func (s *EvidenceService) Create(ctx context.Context, params CreateEvidenceParams) (*relational.Evidence, error)
func (*EvidenceService) GetByID ¶
func (s *EvidenceService) GetByID(id uuid.UUID) (*relational.Evidence, error)
func (*EvidenceService) GetControlByID ¶
func (s *EvidenceService) GetControlByID(id string) (*relational.Control, error)
func (*EvidenceService) GetFilterByID ¶
func (s *EvidenceService) GetFilterByID(id uuid.UUID) (*relational.Filter, error)
func (*EvidenceService) GetHistory ¶
func (s *EvidenceService) GetHistory(streamUUID uuid.UUID) ([]relational.Evidence, error)
func (*EvidenceService) GetHistoryPaginated ¶ added in v0.15.0
func (s *EvidenceService) GetHistoryPaginated(streamUUID uuid.UUID, limit, offset int) ([]relational.Evidence, int64, error)
func (*EvidenceService) GetLatestByUUID ¶
func (s *EvidenceService) GetLatestByUUID(streamUUID uuid.UUID) (*relational.Evidence, error)
func (*EvidenceService) GetLatestForFilters ¶
func (s *EvidenceService) GetLatestForFilters(filters ...labelfilter.Filter) ([]relational.Evidence, error)
func (*EvidenceService) GetSignatureByID ¶ added in v0.15.0
func (s *EvidenceService) GetSignatureByID(id uuid.UUID) (*SignatureDetail, error)
func (*EvidenceService) GetStatusCountsAtPoint ¶
func (s *EvidenceService) GetStatusCountsAtPoint(filter labelfilter.Filter, endBefore *time.Time) ([]StatusCount, error)
func (*EvidenceService) GetStatusCountsByFilters ¶
func (s *EvidenceService) GetStatusCountsByFilters(filters ...labelfilter.Filter) ([]StatusCount, error)
func (*EvidenceService) GetStatusCountsByUUIDAtPoint ¶
func (s *EvidenceService) GetStatusCountsByUUIDAtPoint(streamUUID uuid.UUID, endBefore *time.Time) ([]StatusCount, error)
func (*EvidenceService) ManualEvidenceRequiresSubject ¶ added in v0.21.0
func (s *EvidenceService) ManualEvidenceRequiresSubject() bool
ManualEvidenceRequiresSubject reports whether user-submitted evidence must name a subject (CCF_MANUAL_EVIDENCE_REQUIRE_SUBJECT).
func (*EvidenceService) Search ¶
func (s *EvidenceService) Search(filter labelfilter.Filter) ([]relational.Evidence, error)
func (*EvidenceService) SearchPaginated ¶ added in v0.15.0
func (s *EvidenceService) SearchPaginated(filter labelfilter.Filter, opts SearchOptions) ([]relational.Evidence, int64, error)
func (*EvidenceService) VerifyByID ¶ added in v0.15.0
func (s *EvidenceService) VerifyByID(id uuid.UUID) (*VerificationResult, error)
type EvidenceServiceOption ¶
type EvidenceServiceOption func(*EvidenceService)
func WithComponentDefinitionResolver ¶
func WithComponentDefinitionResolver(resolver ComponentDefinitionResolver) EvidenceServiceOption
type RiskJobEnqueuer ¶
type RiskJobEnqueuer interface {
EnqueueRiskProcessEvidence(ctx context.Context, evidenceID uuid.UUID, evidenceEnd, status string) error
}
RiskJobEnqueuer interface to avoid circular imports
type SearchOptions ¶ added in v0.15.0
type SearchOptions struct {
Limit int
Offset int
Name string
// SubjectUUID limits results to evidence with this subject among its subjects.
SubjectUUID *uuid.UUID
SortBy SearchSortBy
SortDirection SearchSortDirection
}
type SearchSortBy ¶ added in v0.15.0
type SearchSortBy string
const ( SearchSortByLastSeenAt SearchSortBy = "lastSeenAt" SearchSortByName SearchSortBy = "name" SearchSortByStatus SearchSortBy = "status" )
type SearchSortDirection ¶ added in v0.15.0
type SearchSortDirection string
const ( SearchSortDirectionAsc SearchSortDirection = "asc" SearchSortDirectionDesc SearchSortDirection = "desc" )
type SignatureDetail ¶ added in v0.15.0
type SignatureDetail struct {
Status string `json:"status"`
Signature *relational.EvidenceSignature `json:"signature,omitempty"`
}
type SignerContext ¶ added in v0.15.0
type SignerContext struct {
User *UserSignerContext
Agent *AgentSignerContext
// AcceptedAt, when set, dates the signature instead of the signing time: evidence
// accepted in a batch is signed later, in the background, but is attested as of the
// moment the API accepted it, while the submitter's token was valid.
AcceptedAt time.Time
}
func NewAgentSignerContext ¶ added in v0.15.0
func NewAgentSignerContext(claims *authn.AgentClaims, agent *relational.Agent, key *relational.AgentServiceAccountKey) *SignerContext
func NewUserSignerContextFromClaims ¶ added in v0.15.0
func NewUserSignerContextFromClaims(claims *authn.UserClaims) *SignerContext
func (*SignerContext) IsEmpty ¶ added in v0.15.0
func (s *SignerContext) IsEmpty() bool
func (*SignerContext) SubmittedByValue ¶ added in v0.15.0
func (s *SignerContext) SubmittedByValue() string
type SigningService ¶ added in v0.15.0
type SigningService struct {
// contains filtered or unexported fields
}
func NewSigningService ¶ added in v0.15.0
func NewSigningService(privateKey *rsa.PrivateKey) *SigningService
func (*SigningService) SignEvidence ¶ added in v0.15.0
func (s *SigningService) SignEvidence(params CreateEvidenceParams, signer *SignerContext) (*datatypes.JSONType[relational.EvidenceSignature], error)
type StatusCount ¶
type UserSignerContext ¶ added in v0.15.0
type UserSignerContext struct {
Claims *authn.UserClaims
}
type VerificationChecks ¶ added in v0.15.0
type VerificationResult ¶ added in v0.15.0
type VerificationResult struct {
Status string `json:"status"`
Signature *relational.EvidenceSignature `json:"signature,omitempty"`
IsValid bool `json:"is_valid"`
Checks VerificationChecks `json:"checks"`
Errors []string `json:"errors,omitempty"`
ContentHash *relational.Hash `json:"content_hash,omitempty"`
Signer *relational.EvidenceSignatureSigner `json:"signer,omitempty"`
Claims *relational.EvidenceSignatureClaims `json:"claims,omitempty"`
SignedAt *time.Time `json:"signed_at,omitempty"`
}