plugin

Documentation

Index

• Constants
• func CacheReusable(observation Observation, resolved *Resolved, target TargetRef, ...) (bool, bool, string)
• func CurrentPlatform() string
• func FixturePath(resolved *Resolved, fixture string) (string, error)
• func Path(id string) (string, error)
• func Remove(id string) (string, error)
• func Root() (string, error)
• func SupportsPlatform(platforms []string, target string) bool
• func Test(id, fixture string) (*Resolved, Result, string, error)
• func ValidateID(id string) error
• type ActionResult
• type CachePolicy
• type CacheState
• type CapabilityRef
• type CreateOptions
• type CreateResult
  • func Create(options CreateOptions) (*CreateResult, error)
• type Evidence
• type Lock
• type LockEntry
• type Manifest
• type Observation
  • func DecodeObservation(data []byte) (Observation, error)
• type OutputContract
• type RedactionPolicy
• type Resolved
  • func Resolve(id string) (*Resolved, error)
  • func Trust(id string) (*Resolved, error)
• type Result
  • func RedactResult(result Result, policy RedactionPolicy) (Result, []string)
  • func ValidateResult(resolved *Resolved, data []byte) (Result, error)
• type ResultError
• type Runner
• type Summary
  • func BuiltinSummaries() []Summary
  • func List() ([]Summary, error)
  • func SummaryFromResolved(resolved *Resolved) Summary
• type TargetRef

Constants

const (
	ManifestFile   = "manifest.json"
	SchemaVersion  = "sshx.dev/plugin/v1"
	ObservationV1  = "sshx.observation/v1"
	LockFile       = "plugin-lock.json"
	MaxManifest    = 1 << 20
	MaxSchema      = 2 << 20
	MaxCollector   = 2 << 20
	MaxFixture     = 10 << 20
	DefaultTimeout = 30 * time.Second
)

const MaxObservation = 10 << 20

Functions

func CacheReusable

func CacheReusable(observation Observation, resolved *Resolved, target TargetRef, privilege, parameters string, now time.Time, maxAge time.Duration) (bool, bool, string)

func CurrentPlatform

func CurrentPlatform() string

func FixturePath

func FixturePath(resolved *Resolved, fixture string) (string, error)

func Path

func Path(id string) (string, error)

func Remove

func Remove(id string) (string, error)

func Root

func Root() (string, error)

func SupportsPlatform

func SupportsPlatform(platforms []string, target string) bool

func Test

func Test(id, fixture string) (*Resolved, Result, string, error)

func ValidateID

func ValidateID(id string) error

Types

type ActionResult

type ActionResult struct {
	Success     bool      `json:"success"`
	Action      string    `json:"action"`
	PluginID    string    `json:"plugin_id,omitempty"`
	Path        string    `json:"path,omitempty"`
	BackupPath  string    `json:"backup_path,omitempty"`
	Digest      string    `json:"digest,omitempty"`
	Trusted     bool      `json:"trusted,omitempty"`
	Valid       bool      `json:"valid,omitempty"`
	Files       []string  `json:"files,omitempty"`
	Plugins     []Summary `json:"plugins,omitempty"`
	Plugin      *Summary  `json:"plugin,omitempty"`
	Manifest    *Manifest `json:"manifest,omitempty"`
	TestResult  *Result   `json:"test_result,omitempty"`
	Fixture     string    `json:"fixture,omitempty"`
	NextActions []string  `json:"next_actions,omitempty"`
	ErrorKind   string    `json:"error_kind,omitempty"`
	Error       string    `json:"error,omitempty"`
}

type CachePolicy

type CachePolicy struct {
	RecommendedTTL string `json:"recommended_ttl"`
	HardMaxAge     string `json:"hard_max_age"`
}

type CacheState

type CacheState struct {
	Mode       string `json:"mode"`
	Hit        bool   `json:"hit"`
	Stale      bool   `json:"stale"`
	AgeSeconds int64  `json:"age_seconds,omitempty"`
}

type CapabilityRef

type CapabilityRef struct {
	ID      string `json:"id"`
	Version string `json:"version"`
	Digest  string `json:"digest"`
	Builtin bool   `json:"builtin"`
}

type CreateOptions

type CreateOptions struct {
	ID        string
	Runner    string
	Platform  string
	Privilege string
	Template  string
	Replace   bool
}

type CreateResult

type CreateResult struct {
	Resolved   *Resolved
	Files      []string
	BackupPath string
}

func Create

func Create(options CreateOptions) (*CreateResult, error)

type Evidence

type Evidence struct {
	Kind   string `json:"kind"`
	Source string `json:"source"`
}

type Lock

type Lock struct {
	Version int                  `json:"version"`
	Plugins map[string]LockEntry `json:"plugins"`
}

type LockEntry

type LockEntry struct {
	Digest    string    `json:"digest"`
	TrustedAt time.Time `json:"trusted_at"`
}

type Manifest

type Manifest struct {
	APIVersion       string          `json:"api_version"`
	ID               string          `json:"id"`
	Version          string          `json:"version"`
	Kind             string          `json:"kind"`
	Description      string          `json:"description,omitempty"`
	Platforms        []string        `json:"platforms"`
	Runner           Runner          `json:"runner"`
	RequiredCommands []string        `json:"required_commands,omitempty"`
	Privilege        string          `json:"privilege"`
	Timeout          string          `json:"timeout"`
	Effects          []string        `json:"effects"`
	Output           OutputContract  `json:"output"`
	Cache            CachePolicy     `json:"cache"`
	Redaction        RedactionPolicy `json:"redaction"`
}

type Observation

type Observation struct {
	Schema      string         `json:"schema"`
	Capability  CapabilityRef  `json:"capability"`
	Target      TargetRef      `json:"target"`
	CollectedAt time.Time      `json:"collected_at"`
	ExpiresAt   time.Time      `json:"expires_at"`
	Status      string         `json:"status"`
	Privilege   string         `json:"privilege"`
	Parameters  string         `json:"parameters_digest"`
	Cache       CacheState     `json:"cache"`
	Facts       map[string]any `json:"facts"`
	Evidence    []Evidence     `json:"evidence"`
	Errors      []ResultError  `json:"errors"`
	Redaction   []string       `json:"redacted_fields,omitempty"`
}

func DecodeObservation

func DecodeObservation(data []byte) (Observation, error)

type OutputContract

type OutputContract struct {
	Schema string `json:"schema"`
}

type RedactionPolicy

type RedactionPolicy struct {
	DenyFields []string `json:"deny_fields,omitempty"`
}

type Resolved

type Resolved struct {
	Manifest  Manifest `json:"manifest"`
	Path      string   `json:"path"`
	Digest    string   `json:"digest"`
	Trusted   bool     `json:"trusted"`
	Builtin   bool     `json:"builtin"`
	Collector []byte   `json:"-"`
	Schema    any      `json:"-"`
}

func Resolve

func Resolve(id string) (*Resolved, error)

func Trust

func Trust(id string) (*Resolved, error)

type Result

type Result struct {
	Status   string         `json:"status"`
	Facts    map[string]any `json:"facts"`
	Evidence []Evidence     `json:"evidence"`
	Errors   []ResultError  `json:"errors"`
}

func RedactResult

func RedactResult(result Result, policy RedactionPolicy) (Result, []string)

func ValidateResult

func ValidateResult(resolved *Resolved, data []byte) (Result, error)

type ResultError

type ResultError struct {
	Kind    string `json:"kind"`
	Section string `json:"section,omitempty"`
	Message string `json:"message,omitempty"`
}

type Runner

type Runner struct {
	Type       string `json:"type"`
	Entrypoint string `json:"entrypoint"`
}

type Summary

type Summary struct {
	ID          string `json:"id"`
	Version     string `json:"version,omitempty"`
	Description string `json:"description,omitempty"`
	Path        string `json:"path"`
	Digest      string `json:"digest,omitempty"`
	Trusted     bool   `json:"trusted"`
	Builtin     bool   `json:"builtin"`
	Valid       bool   `json:"valid"`
	ErrorKind   string `json:"error_kind,omitempty"`
	Error       string `json:"error,omitempty"`
}

func BuiltinSummaries

func BuiltinSummaries() []Summary

func List

func List() ([]Summary, error)

func SummaryFromResolved

func SummaryFromResolved(resolved *Resolved) Summary

type TargetRef

type TargetRef struct {
	Host               string `json:"host"`
	Port               string `json:"port"`
	User               string `json:"user"`
	UID                string `json:"uid,omitempty"`
	HostKeyFingerprint string `json:"host_key_fingerprint"`
	Platform           string `json:"platform"`
	BootID             string `json:"boot_id,omitempty"`
}