verify

package
v0.4.6 Latest Latest
Warning

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

 Go to latest Published: Oct 16, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package verify evaluates lightweight post-step / post-run assertions (exit code, stdout substring, file presence) used by Missions and MCP.

Index

Constants

View Source 
const EvidenceSchema = "vaultrun.verify.evidence.v1"

EvidenceSchema identifies the sealed verification export format.

View Source 
const MaxEvidenceStdoutBytes = 64 << 10

MaxEvidenceStdoutBytes caps observation text embedded in evidence exports.

View Source 
const SuiteID = "vaultrun-verify-controls-v2"

SuiteID is the frozen identity of the built-in verify control suite. Bump when control cases change (also update pinned fingerprint in tests).

Variables

View Source 
var ErrNotFound = errors.New("verification not found")

ErrNotFound is returned when a verification id does not exist.

Functions

func ComputeContentDigest added in v0.3.4 

func ComputeContentDigest(rec *EvidenceRecord) (string, error)

ComputeContentDigest returns SHA-256 hex of the canonical JSON payload with content_digest and sig cleared.

func SignEvidence added in v0.3.4 

func SignEvidence(contentDigest string, key []byte) string

SignEvidence HMAC-SHA256s the content digest hex string.

func SuiteFingerprint 

func SuiteFingerprint() string

SuiteFingerprint returns a stable digest of the frozen control definitions.

func VerifyEvidenceIntegrity added in v0.3.4 

func VerifyEvidenceIntegrity(rec *EvidenceRecord, hmacKey []byte) error

VerifyEvidenceIntegrity checks content_digest (and sig when key provided).

Types

type Check 

type Check struct {
	Name   string `json:"name"`
	Passed bool   `json:"passed"`
	Detail string `json:"detail,omitempty"`
}

Check is one assertion outcome.

type ControlCase 

type ControlCase struct {
	ID             string          `json:"id"`
	Kind           ControlKind     `json:"kind"`
	Name           string          `json:"name"`
	Description    string          `json:"description"`
	Spec           Spec            `json:"spec"`
	Observation    Observation     `json:"observation"`
	FileExistsMap  map[string]bool `json:"-"` // probe fixture; not part of public digest payload separately
	ExpectedPassed bool            `json:"expected_passed"`
}

ControlCase is one frozen evaluator control (FaultWright-style).

func ControlCasesPublic 

func ControlCasesPublic() []ControlCase

ControlCasesPublic returns the frozen cases without running them (for docs/debug).

type ControlKind 

type ControlKind string

ControlKind is positive (must pass) or negative (must fail). 

const (
	ControlPositive ControlKind = "positive"
	ControlNegative ControlKind = "negative"
)

type ControlOutcome 

type ControlOutcome struct {
	ID             string      `json:"id"`
	Kind           ControlKind `json:"kind"`
	Name           string      `json:"name"`
	Description    string      `json:"description"`
	ExpectedPassed bool        `json:"expected_passed"`
	ObservedPassed bool        `json:"observed_passed"`
	Consistent     bool        `json:"consistent"`
	Result         Result      `json:"result"`
}

ControlOutcome is the evaluation of one control against the live evaluator.

type ControlReport 

type ControlReport struct {
	SuiteID               string           `json:"suite_id"`
	Fingerprint           string           `json:"fingerprint"`
	CreatedAt             time.Time        `json:"created_at"`
	Passed                bool             `json:"passed"`
	PipelineDiscriminates bool             `json:"pipeline_discriminates"`
	Controls              []ControlOutcome `json:"controls"`
	Summary               string           `json:"summary"`
}

ControlReport is the auditable record for a control-suite run.

func RunControls 

func RunControls() ControlReport

RunControls evaluates the frozen positive/negative suite against Evaluate. PipelineDiscriminates is true only when every control is consistent with expectation and the suite contains at least one passing positive and one failing negative observation.

type EvidenceCheckpoint added in v0.3.4 

type EvidenceCheckpoint struct {
	Spec        Spec        `json:"spec"`
	Observation Observation `json:"observation"`
	Checks      []Check     `json:"checks"`
	Passed      bool        `json:"passed"`
}

EvidenceCheckpoint is one evaluated verify checkpoint inside an export.

type EvidenceInput added in v0.3.4 

type EvidenceInput struct {
	Actor           string
	SessionID       *uuid.UUID
	RunID           *uuid.UUID
	VerificationID  *uuid.UUID
	StepName        string
	Spec            Spec
	Observation     Observation
	Result          Result
	IncludeControls bool
	HasCheckpoint   bool
	HMACKey         []byte
}

EvidenceInput configures BuildEvidence.

type EvidenceKind added in v0.3.4 

type EvidenceKind string

EvidenceKind classifies what the record contains. 

const (
	EvidenceKindCheckpoint EvidenceKind = "checkpoint"
	EvidenceKindControls   EvidenceKind = "controls"
	EvidenceKindCombined   EvidenceKind = "combined"
)

type EvidenceRecord added in v0.3.4 

type EvidenceRecord struct {
	Schema        string              `json:"schema"`
	ID            string              `json:"id"`
	CreatedAt     time.Time           `json:"created_at"`
	Kind          EvidenceKind        `json:"kind"`
	Passed        bool                `json:"passed"`
	Subject       EvidenceSubject     `json:"subject"`
	Checkpoint    *EvidenceCheckpoint `json:"checkpoint,omitempty"`
	Controls      *ControlReport      `json:"controls,omitempty"`
	ContentDigest string              `json:"content_digest"`
	Sig           string              `json:"sig,omitempty"`
}

EvidenceRecord is a digests-and-optional-HMAC sealed verification export (FaultWright-style evidence packaging for VaultRun verify).

func BuildEvidence added in v0.3.4 

func BuildEvidence(in EvidenceInput) (*EvidenceRecord, error)

BuildEvidence seals a verification export with content digest and optional HMAC.

type EvidenceSubject added in v0.3.4 

type EvidenceSubject struct {
	SessionID      string `json:"session_id,omitempty"`
	RunID          string `json:"run_id,omitempty"`
	VerificationID string `json:"verification_id,omitempty"`
	StepName       string `json:"step_name,omitempty"`
	Actor          string `json:"actor,omitempty"`
}

EvidenceSubject binds the record to optional VaultRun entities.

type FileProbe 

type FileProbe func(path string) (exists bool, err error)

FileProbe reports whether a workspace-relative path exists. May be nil when Spec.FileExists is empty.

type Observation 

type Observation struct {
	ExitCode *int   `json:"exit_code,omitempty"`
	Stdout   string `json:"stdout,omitempty"`
	Stderr   string `json:"stderr,omitempty"`
}

Observation is the measured outcome to check against Spec.

type Record 

type Record struct {
	ID           uuid.UUID       `db:"id" json:"id"`
	SessionID    *uuid.UUID      `db:"session_id" json:"session_id,omitempty"`
	RunID        *uuid.UUID      `db:"run_id" json:"run_id,omitempty"`
	MissionRunID *uuid.UUID      `db:"mission_run_id" json:"mission_run_id,omitempty"`
	StepName     string          `db:"step_name" json:"step_name,omitempty"`
	Spec         json.RawMessage `db:"spec" json:"spec"`
	Observation  json.RawMessage `db:"observation" json:"observation"`
	Passed       bool            `db:"passed" json:"passed"`
	Checks       json.RawMessage `db:"checks" json:"checks"`
	CreatedAt    time.Time       `db:"created_at" json:"created_at"`
}

Record is a persisted verification outcome.

type Result 

type Result struct {
	Passed bool    `json:"passed"`
	Checks []Check `json:"checks"`
}

Result aggregates all checks.

func Evaluate 

func Evaluate(spec Spec, obs Observation, probe FileProbe) Result

Evaluate runs Spec against Observation (and optional FileProbe).

type Spec 

type Spec struct {
	ExitCodeZero   *bool  `json:"exit_code_zero,omitempty"`
	StdoutContains string `json:"stdout_contains,omitempty"`
	FileExists     string `json:"file_exists,omitempty"`
}

Spec is a set of optional assertions. Empty fields are skipped.

func (Spec) Empty 

func (s Spec) Empty() bool

Empty reports whether the spec asks for no checks.

type Store 

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

Store persists verification results.

func NewStore 

func NewStore(db *sqlx.DB) *Store

NewStore creates a Store.

func (*Store) Get added in v0.3.4 

func (s *Store) Get(ctx context.Context, id uuid.UUID) (*Record, error)

Get returns one verification by id.

func (*Store) ListBySession 

func (s *Store) ListBySession(ctx context.Context, sessionID uuid.UUID, limit int) ([]Record, error)

ListBySession returns recent verifications for a session.

func (*Store) Save 

func (s *Store) Save(ctx context.Context, rec *Record) error

Save inserts a verification record.

Source Files

View all Source files

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.