evidence

package
v0.22.0 Latest Latest
Warning

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

Go to latest
Published: Oct 28, 2026 License: AGPL-3.0 Imports: 24 Imported by: 0

Documentation

Index

Constants

View Source
const (
	SignatureStatusSigned   = "signed"
	SignatureStatusUnsigned = "unsigned"
)

Variables

View Source
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")
)
View Source
var ErrSubjectRequired = errors.New("evidence has no subject")

ErrSubjectRequired is returned when evidence that must have a subject has none.

View Source
var ErrTooManySubjects = errors.New("too many subjects")

ErrTooManySubjects is returned when evidence names more subjects than one lookup allows.

View Source
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

func PruneBatches(ctx context.Context, db *gorm.DB, acceptedBefore time.Time) (int64, error)

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

func RejectBatchItem(err error) error

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 (*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

type StatusCount

type StatusCount struct {
	Count  int64  `json:"count"`
	Status string `json:"status"`
}

type UserSignerContext added in v0.15.0

type UserSignerContext struct {
	Claims *authn.UserClaims
}

type VerificationChecks added in v0.15.0

type VerificationChecks struct {
	HashMatch            bool `json:"hash_match"`
	SignatureValid       bool `json:"signature_valid"`
	TemporalValid        bool `json:"temporal_valid"`
	SignedContentMatches bool `json:"signed_content_matches"`
}

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"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL