labchecks

package
v1.10.0 Latest Latest
Warning

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

Go to latest
Published: Nov 21, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package labchecks is the contract of device bootstrap and lab checks: the secret documents the management agent writes (Secret <device>-bootstrap, key bootstrap.json; Secret <lab>-checks, key checks.json), the limits on them and the validation the agent applies before anything is written. The launcher and the checker read the same types.

Index

Constants

View Source
const (
	BootstrapSecretSuffix = "-bootstrap"
	ChecksSecretSuffix    = "-checks"
	// BootstrapKey and ChecksKey hold one JSON document each (Bootstrap and []Check wrapped in ChecksDoc).
	BootstrapKey = "bootstrap.json"
	ChecksKey    = "checks.json"
)

Secret names and keys. The device Secret is named after the Device object (as the -env Secret is), the lab Secret after the Lab.

View Source
const (
	DefaultInterpreter = "/bin/sh"
	// DefaultCustomUser: a command of a check runs as nobody unless the author names a user (root included: an explicit choice).
	DefaultCustomUser         = "nobody"
	DefaultBootstrapTimeLimit = 300
	DefaultCheckTimeLimit     = 30
)

Defaults filled in by Normalize, so a consumer never guesses them.

View Source
const (
	// BootstrapMaxAttempts is the number of attempts before a device stays in "failed" (three, with growing pauses).
	BootstrapMaxAttempts = 3
	// MaxBootstrapTimeLimit and MaxCheckTimeLimit are in seconds.
	MaxBootstrapTimeLimit = 3600
	MaxCheckTimeLimit     = 600
	// MaxScheduleSeconds is the longest interval of a scheduled check (one day).
	MaxScheduleSeconds = 86400

	MaxScriptBytes       = 64 << 10
	MaxBootstrapFiles    = 32
	MaxFileBytes         = 256 << 10
	MaxBootstrapBytes    = 512 << 10 // script and all file contents of one device together; a Secret holds 1 MiB and JSON adds a third to bytes
	MaxChecksPerLab      = 64
	MaxPartsPerCheck     = 8
	MaxChecksBytes       = 512 << 10 // the whole checks document of a lab
	MaxPathBytes         = 4096
	MaxPatternBytes      = 1024
	MaxExpectBytes       = 4096
	MaxCommandItems      = 64
	MaxCommandItemBytes  = 4096
	MaxIDBytes           = 64
	MaxNameBytes         = 128
	MaxResultDetailBytes = 2048
	MaxResultValueBytes  = 256

	// The built-in observations.
	MaxEntryNames     = 64        // names in has_entries / lacks_entries
	MaxEntryNameBytes = 255       // one name
	MaxProcessName    = 128       // a process name or a user to match
	MaxHostBytes      = 253       // the host of a request
	MaxRequestPath    = 2048      // the path of an HTTP request
	MaxFileRead       = 256 << 10 // the part of a file that is read; a larger file is an error where the content matters
)

Limits. Each is a platform ceiling: the agent refuses a request over it, and GetFeatures reports them.

Variables

View Source
var Observations = []string{"file", "directory", "process", "port", "kernel_param", "request", "permission", "custom"}

The kinds of observation a laboratory's checker runs. File and custom are the first two; the rest read the state of the device themselves and execute nothing of it.

Functions

func BootstrapPause

func BootstrapPause(failedAttempts int) time.Duration

BootstrapPause is how long a device waits after the given number of failed bootstrap attempts before it tries again (10 s after the first, 30 s after the second). After BootstrapMaxAttempts failures there is no next attempt.

func MarshalBootstrap

func MarshalBootstrap(b *Bootstrap) ([]byte, error)

MarshalBootstrap and MarshalChecks produce the Secret documents (after Normalize and Validate).

func MarshalChecks

func MarshalChecks(checks []Check) ([]byte, error)

MarshalChecks encodes the checks document and refuses one over MaxChecksBytes.

func NormalizeBootstrap

func NormalizeBootstrap(b *Bootstrap)

NormalizeBootstrap fills the defaults of a bootstrap list.

func NormalizeChecks

func NormalizeChecks(checks []Check)

NormalizeChecks fills the defaults of every check.

func TruncateDetail

func TruncateDetail(s string) string

TruncateDetail cuts a result detail to MaxResultDetailBytes on a UTF-8 boundary.

func TruncateValue

func TruncateValue(s string) string

TruncateValue cuts a result value to MaxResultValueBytes on a UTF-8 boundary.

func ValidateBootstrap

func ValidateBootstrap(b *Bootstrap) error

ValidateBootstrap checks the bootstrap list of one device. It must be called after NormalizeBootstrap.

func ValidateChecks

func ValidateChecks(checks []Check, devices map[string]bool) error

ValidateChecks checks the checks of a lab against the names of its devices (the devices that can be observed). It must be called after NormalizeChecks.

Types

type Bootstrap

type Bootstrap struct {
	Script           string `json:"script,omitempty"`
	Interpreter      string `json:"interpreter,omitempty"`
	Files            []File `json:"files,omitempty"`
	TimeLimitSeconds int32  `json:"timeLimitSeconds"`
}

Bootstrap is the list of one device with the values already filled in: an optional script and files, and a time limit.

func (*Bootstrap) Empty

func (b *Bootstrap) Empty() bool

Empty reports a list that does nothing: no script and no files (it removes the Secret).

type Check

type Check struct {
	ID               string `json:"id"`
	Device           string `json:"device"`
	Mode             string `json:"mode"` // once | continuous
	ScheduleSeconds  int32  `json:"scheduleSeconds,omitempty"`
	ManualRun        bool   `json:"manualRun,omitempty"`
	TimeLimitSeconds int32  `json:"timeLimitSeconds"`
	// Parts must all hold in the same run.
	Parts []Part `json:"parts"`
}

Check is one check of a lab.

type ChecksDoc

type ChecksDoc struct {
	Checks []Check `json:"checks"`
}

ChecksDoc is the document in the lab's checks Secret.

type CustomPart

type CustomPart struct {
	Command     []string `json:"command,omitempty"`
	Script      string   `json:"script,omitempty"`
	Interpreter string   `json:"interpreter,omitempty"`
	User        string   `json:"user,omitempty"`
	// OutputContains and OutputMatches are optional additional expectations on the output.
	OutputContains *string `json:"outputContains,omitempty"`
	OutputMatches  *string `json:"outputMatches,omitempty"`
}

CustomPart runs a command (or a script) in the device. Exit code 0 means passed.

type DirectoryPart

type DirectoryPart struct {
	Path         string   `json:"path"`
	Exists       *bool    `json:"exists,omitempty"`
	Mode         *uint32  `json:"mode,omitempty"`
	Owner        *string  `json:"owner,omitempty"`
	Group        *string  `json:"group,omitempty"`
	HasEntries   []string `json:"hasEntries,omitempty"`
	LacksEntries []string `json:"lacksEntries,omitempty"`
}

DirectoryPart: exists (default true), mode, owner, group, names that must be directly in the directory and names that must not.

type File

type File struct {
	Path    string `json:"path"`
	Content []byte `json:"content,omitempty"`
	Owner   string `json:"owner,omitempty"`
	Group   string `json:"group,omitempty"`
	// Mode is the permission bits (for example 0o644); 0 means the default 0o644.
	Mode uint32 `json:"mode,omitempty"`
}

File is a file to place on a device.

type FilePart

type FilePart struct {
	Path string `json:"path"`
	// Exists true: the file exists; false: it is absent (and no other expectation may be set).
	Exists          *bool   `json:"exists,omitempty"`
	ContentContains *string `json:"contentContains,omitempty"`
	ContentMatches  *string `json:"contentMatches,omitempty"`
	Mode            *uint32 `json:"mode,omitempty"`
	Owner           *string `json:"owner,omitempty"`
	Group           *string `json:"group,omitempty"`
	// Type is what the path itself is (it is not followed): file, directory or symlink. Checksum is the sha256 of the content in
	// lower-case hex. Both need the file to exist; the checksum needs a regular file of at most MaxFileRead bytes.
	Type     *string `json:"type,omitempty"`
	Checksum *string `json:"checksum,omitempty"`
}

FilePart reads a file of the device and compares. Every expectation is optional, at least one is required.

type KernelParamPart

type KernelParamPart struct {
	Name    string  `json:"name"`
	Equals  *string `json:"equals,omitempty"`
	Matches *string `json:"matches,omitempty"`
}

KernelParamPart: the value of a sysctl; at least one of Equals and Matches.

type Part

type Part struct {
	File        *FilePart        `json:"file,omitempty"`
	Custom      *CustomPart      `json:"custom,omitempty"`
	Directory   *DirectoryPart   `json:"directory,omitempty"`
	Process     *ProcessPart     `json:"process,omitempty"`
	Port        *PortPart        `json:"port,omitempty"`
	KernelParam *KernelParamPart `json:"kernelParam,omitempty"`
	Request     *RequestPart     `json:"request,omitempty"`
	Permission  *PermissionPart  `json:"permission,omitempty"`
}

Part is one observation: exactly one member is set.

type PermissionPart

type PermissionPart struct {
	User    string `json:"user"`
	Path    string `json:"path"`
	Read    *bool  `json:"read,omitempty"`
	Write   *bool  `json:"write,omitempty"`
	Execute *bool  `json:"execute,omitempty"`
}

PermissionPart: whether a user may read, write or execute a path, tested without changing anything. Each given boolean must equal the real answer; at least one is required.

type PortPart

type PortPart struct {
	Port      int32   `json:"port"`
	Protocol  string  `json:"protocol,omitempty"`
	Listening *bool   `json:"listening,omitempty"`
	Address   *string `json:"address,omitempty"`
	Process   *string `json:"process,omitempty"`
}

PortPart: whether something listens on a port. Protocol defaults to tcp, Listening to true. A listener on the wildcard address counts for Address.

type ProcessPart

type ProcessPart struct {
	Name    *string `json:"name,omitempty"`
	Matches *string `json:"matches,omitempty"`
	User    *string `json:"user,omitempty"`
	Running *bool   `json:"running,omitempty"`
}

ProcessPart: a process by Name (the command without its directory) or by a regular expression on the command line; at least one. Running defaults to true (false: no such process may run).

type RequestPart

type RequestPart struct {
	Protocol     string  `json:"protocol"`
	Host         string  `json:"host,omitempty"`
	Port         int32   `json:"port"`
	Method       string  `json:"method,omitempty"`
	Path         string  `json:"path,omitempty"`
	Status       *int32  `json:"status,omitempty"`
	BodyContains *string `json:"bodyContains,omitempty"`
	BodyMatches  *string `json:"bodyMatches,omitempty"`
}

RequestPart: a connection from inside the device. Protocol is tcp, http or https; Host defaults to 127.0.0.1. For http and https: Method (GET by default, or HEAD), Path (/ by default), Status (200 by default), and rules on the body (GET only).

Jump to

Keyboard shortcuts

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