audit

Documentation

Overview

Package audit provides a tamper-evident, hash-chained audit log.

Verification detects mutation, removal, sequence gaps, invalid signatures, and duplicate operation IDs. The log is tamper-evident, not tamper-proof.

Index

• Variables
• func ComputeHash(r *Record) error
• func ExportJSON(recs []Record) ([]byte, error)
• type Actor
• type Finding
• type Option
  • func WithFile(path string) Option
  • func WithKeyRing(ring *signing.KeyRing) Option
  • func WithSigner(key signing.PrivateKey, ring *signing.KeyRing) Option
• type Record
  • func LoadNDJSON(path string) ([]Record, error)
• type Report
  • func VerifyRecords(recs []Record, keys *signing.KeyRing) Report
• type Store
  • func New(opts ...Option) *Store
  • func (s *Store) Append(actor Actor, action, resource, result, operationID string, ...) (Record, error)
  • func (s *Store) Checkpoint(actor Actor) (Record, error)
  • func (s *Store) Records() []Record
  • func (s *Store) Verify() Report

Variables

var (
	ErrEmptyStore   = errors.New("audit: empty store")
	ErrChainBroken  = errors.New("audit: hash chain broken")
	ErrSequenceGap  = errors.New("audit: sequence gap")
	ErrDuplicateOp  = errors.New("audit: duplicate operation id")
	ErrInvalidSig   = errors.New("audit: invalid signature")
	ErrMutation     = errors.New("audit: record mutated")
	ErrRemoval      = errors.New("audit: record removed")
	ErrBadTimestamp = errors.New("audit: invalid timestamp")
	ErrUnknownKey   = errors.New("audit: unknown signing key")
)

Functions

func ComputeHash

func ComputeHash(r *Record) error

ComputeHash fills RecordHash from chain fields.

func ExportJSON

func ExportJSON(recs []Record) ([]byte, error)

ExportJSON writes records as pretty JSON.

Types

type Actor

type Actor struct {
	ID   string `json:"id"`
	Type string `json:"type,omitempty"`
}

Actor identifies who performed an action.

type Finding

type Finding struct {
	Code     string `json:"code"`
	Sequence uint64 `json:"sequence,omitempty"`
	Message  string `json:"message"`
}

Finding is one verification problem.

type Option

type Option func(*Store)

Option configures Store.

func WithFile

func WithFile(path string) Option

WithFile mirrors records as NDJSON to path.

func WithKeyRing

func WithKeyRing(ring *signing.KeyRing) Option

WithKeyRing sets verification keys without requiring a local signer.

func WithSigner

func WithSigner(key signing.PrivateKey, ring *signing.KeyRing) Option

WithSigner enables record signatures.

type Record

type Record struct {
	Sequence     uint64            `json:"sequence"`
	PreviousHash [32]byte          `json:"previous_hash"`
	RecordHash   [32]byte          `json:"record_hash"`
	Time         time.Time         `json:"time"`
	Actor        Actor             `json:"actor"`
	Action       string            `json:"action"`
	Resource     string            `json:"resource,omitempty"`
	Result       string            `json:"result,omitempty"`
	OperationID  string            `json:"operation_id,omitempty"`
	Metadata     map[string]string `json:"metadata,omitempty"`
	Signature    []byte            `json:"signature,omitempty"`
	KeyID        string            `json:"key_id,omitempty"`
}

Record is one append-only audit entry with hash chaining.

func LoadNDJSON

func LoadNDJSON(path string) ([]Record, error)

LoadNDJSON loads records from an NDJSON file.

type Report

type Report struct {
	OK       bool      `json:"ok"`
	Records  int       `json:"records"`
	Findings []Finding `json:"findings,omitempty"`
}

Report summarizes verification.

func VerifyRecords

func VerifyRecords(recs []Record, keys *signing.KeyRing) Report

VerifyRecords validates an exported chain.

type Store

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

Store is an append-only in-memory audit log with optional file mirror.

func New

func New(opts ...Option) *Store

New creates an empty store.

func (*Store) Append

func (s *Store) Append(actor Actor, action, resource, result, operationID string, metadata map[string]string) (Record, error)

Append adds a record, computing sequence and hashes.

func (*Store) Checkpoint

func (s *Store) Checkpoint(actor Actor) (Record, error)

Checkpoint appends a signed checkpoint over the current tip.

func (*Store) Records

func (s *Store) Records() []Record

Records returns a copy of all records.

func (*Store) Verify

func (s *Store) Verify() Report

Verify checks the in-memory chain.