store

Documentation

Overview

Package store provides the persistence layer for MulVAL analyses.

It owns all SQL and acts as the single point of contact between the application code (API handlers, executor) and the PostgreSQL manager. Neither the API layer nor the executor import pkg/services/pgsql directly.

Page token format: base64url(create_time_rfc3339 + "," + operation_name). This gives stable cursor pagination even when new rows are inserted between pages, which is required for drift detection by downstream consumers.

Index

• func AnalysisNameFromOperation(opName string) string
• func HashInputs(edb, idb string) string
• func NewOperationName() string
• func OperationNameFromAnalysis(analysisName string) string
• func UUIDFromName(name string) string
• type ListResult
  • func ListAnalyses(ctx context.Context, mgr *pgsql.Manager, pageSize int, pageToken string) (*ListResult, error)
• type Operation
  • func CreateAnalysis(ctx context.Context, mgr *pgsql.Manager, opName, edb, idb string) (*Operation, bool, error)
  • func GetByHash(ctx context.Context, mgr *pgsql.Manager, hash string) (*Operation, error)
  • func GetByName(ctx context.Context, mgr *pgsql.Manager, opName string) (*Operation, error)
  • func MarkCancelled(ctx context.Context, mgr *pgsql.Manager, op *Operation) (*Operation, error)
  • func MarkFailed(ctx context.Context, mgr *pgsql.Manager, op *Operation, errMsg string) (*Operation, error)
  • func MarkSucceeded(ctx context.Context, mgr *pgsql.Manager, op *Operation, ...) (*Operation, error)
• type OperationOutput
• type State
  • func (s State) IsTerminal() bool

Functions

func AnalysisNameFromOperation

func AnalysisNameFromOperation(opName string) string

AnalysisNameFromOperation converts "operations/{uuid}" → "analyses/{uuid}".

func HashInputs

func HashInputs(edb, idb string) string

HashInputs produces a deterministic SHA-256 fingerprint of edb+idb.

func NewOperationName

func NewOperationName() string

NewOperationName generates a new AIP-151 operation name.

func OperationNameFromAnalysis

func OperationNameFromAnalysis(analysisName string) string

OperationNameFromAnalysis converts "analyses/{uuid}" → "operations/{uuid}".

func UUIDFromName

func UUIDFromName(name string) string

UUIDFromName extracts the UUID from either "operations/{uuid}" or "analyses/{uuid}".

Types

type ListResult

type ListResult struct {
	Operations    []*Operation
	NextPageToken string // empty when no further pages exist
}

ListResult is the return value of ListAnalyses.

func ListAnalyses

func ListAnalyses(
	ctx context.Context,
	mgr *pgsql.Manager,
	pageSize int,
	pageToken string,
) (*ListResult, error)

ListAnalyses returns a page of analyses ordered by (create_time DESC, operation_name). Pagination uses an opaque cursor token.

pageSize must be between 1 and 1000; it is clamped by the caller. pageToken is empty for the first page.

type Operation

type Operation struct {
	// OperationName is the AIP-151 LRO name: "operations/{uuid}".
	// It doubles as the analysis resource name: "analyses/{uuid}".
	OperationName string

	// InputHash is the SHA-256 fingerprint of EDB+IDB.
	InputHash string

	// EDBFacts and IDBRules are the raw Prolog inputs, newline-joined.
	EDBFacts string
	IDBRules string

	// State is the current lifecycle state.
	State State

	// CreateTime is when the row was first inserted.
	CreateTime time.Time

	// EndTime is set when the operation reaches a terminal state.
	EndTime *time.Time

	// Error holds the failure message when State == StateFailed.
	Error *string

	// Output is nil until State == StateSucceeded.
	Output *OperationOutput
}

Operation is the in-memory representation of one MulVAL analysis. Passed between API handlers and the executor to avoid context stuffing.

func CreateAnalysis

func CreateAnalysis(
	ctx context.Context,
	mgr *pgsql.Manager,
	opName, edb, idb string,
) (*Operation, bool, error)

CreateAnalysis inserts a new analysis row with state=RUNNING.

If the operation name already exists (idempotent retry) the existing row is returned unchanged — callers can inspect op.State to determine whether a new run was started or an existing one was found.

Returns (op, true, nil) when a new row was created. Returns (op, false, nil) when the row already existed.

func GetByHash

func GetByHash(
	ctx context.Context,
	mgr *pgsql.Manager,
	hash string,
) (*Operation, error)

GetByHash looks up a SUCCEEDED analysis by its input content hash. Returns nil, nil when none found. Used for cache lookup.

func GetByName

func GetByName(
	ctx context.Context,
	mgr *pgsql.Manager,
	opName string,
) (*Operation, error)

GetByName retrieves an analysis by its operation name. Returns nil, nil when not found.

func MarkCancelled

func MarkCancelled(
	ctx context.Context,
	mgr *pgsql.Manager,
	op *Operation,
) (*Operation, error)

MarkCancelled transitions op to StateCancelled. Called by the CancelOperation RPC handler — not the executor.

func MarkFailed

func MarkFailed(
	ctx context.Context,
	mgr *pgsql.Manager,
	op *Operation,
	errMsg string,
) (*Operation, error)

MarkFailed transitions op to StateFailed with the given error message.

func MarkSucceeded

func MarkSucceeded(
	ctx context.Context,
	mgr *pgsql.Manager,
	op *Operation,
	output *OperationOutput,
) (*Operation, error)

MarkSucceeded transitions op to StateSucceeded and stores the raw outputs. Pass rc.Store (never-cancelled context) to survive request teardown.

type OperationOutput

type OperationOutput struct {
	VerticesCSV string
	ArcsCSV     string
	// Summary is the content of AttackGraph.txt. May be empty.
	Summary string
}

OperationOutput holds the raw MulVAL output files.

type State

type State string

State enumerates the lifecycle states of an Analysis.

const (
	StateRunning   State = "RUNNING"
	StateSucceeded State = "SUCCEEDED"
	StateFailed    State = "FAILED"
	StateCancelled State = "CANCELLED"
)

func (State) IsTerminal

func (s State) IsTerminal() bool

IsTerminal reports whether s is a terminal state.