lwcomponent

Documentation

Overview

A development kit for the cloud based of modular components.

A Lacework component package to help facilitate the loading and execution of components

Index

• Constants
• Variables
• func Dir() (string, error)
• func DownloadFile(filepath string, url string, timeout time.Duration) (err error)
• func IsNotFound(err error) bool
• type Artifact
• type Breadcrumbs
• type Component
  • func (c Component) ArtifactForRunningHost(version string) (*Artifact, bool)
  • func (c Component) CurrentVersion() (*semver.Version, error)
  • func (c Component) EnterDevelopmentMode() error
  • func (c Component) IsCommandType() bool
  • func (c Component) IsExecutable() bool
  • func (c Component) IsInstalled() bool
  • func (c Component) ListVersions(installed *semver.Version) string
  • func (c Component) MakeUpdateMessage(from, to semver.Version) string
  • func (c Component) MarshalJSON() ([]byte, error)
  • func (c Component) Path() (string, error)
  • func (c Component) RootPath() (string, error)
  • func (c Component) RunAndOutput(args []string, envs ...string) error
  • func (c Component) RunAndReturn(args []string, stdin io.Reader, envs ...string) (stdout string, stderr string, err error)
  • func (c Component) SignatureFromDisk() ([]byte, error)
  • func (c Component) Status() Status
  • func (c Component) UnderDevelopment() bool
  • func (c *Component) UnmarshalJSON(data []byte) error
  • func (c Component) UpdateAvailable() (bool, error)
  • func (c Component) WriteSignature(signature []byte) error
  • func (c Component) WriteVersion(installed string) error
• type Library
• type RunError
  • func (e *RunError) Error() string
  • func (e *RunError) Unwrap() error
• type State
  • func LoadState(client *api.Client) (*State, error)
  • func LocalState() (*State, error)
  • func (s State) GetComponent(name string) (*Component, bool)
  • func (s State) Install(component *Component, version string) error
  • func (s State) Verify(component *Component, version string) error
  • func (s State) WriteState() error
• type Status
  • func (cs Status) String() string
• type Type

Constants

const (
	EmptyType Type = ""

	// the component is a binary
	BinaryType = "BINARY"

	// will this component be accessible via the CLI
	CommandType = "CLI_COMMAND"

	// the component is a library, only provides content for the CLI or other components
	LibraryType = "LIBRARY"

	// the component is standalone, should be available in $PATH
	StandaloneType = "STANDALONE"
)

Variables

var (
	ErrComponentNotFound = errors.New("component not found on disk")
)

Functions

func Dir

func Dir() (string, error)

Dir returns the directory where the components will be stored

func DownloadFile

func DownloadFile(filepath string, url string, timeout time.Duration) (err error)

func IsNotFound

func IsNotFound(err error) bool

IsNotFound returns a boolean indicating whether the error is known to have determined the component is not found. It is satisfied by ErrNotApplyComment

Types

type Artifact

type Artifact struct {
	OS            string `json:"os"`
	ARCH          string `json:"arch"`
	URL           string `json:"url,omitempty"`
	Signature     string `json:"signature"`
	Version       string `json:"version"`
	UpdateMessage string `json:"updateMessage"`
}

type Breadcrumbs

type Breadcrumbs struct {
	InstallationMessage string `json:"installationMessage,omitempty"`
	UpdateMessage       string `json:"updateMessage,omitempty"`
}

Components should leave a trail/crumb after installation or update, these messages will be shown by the Lacework CLI

type Component

type Component struct {
	Name          string         `json:"name"`
	Description   string         `json:"description"`
	Type          Type           `json:"type"`
	LatestVersion semver.Version `json:"-"`
	Artifacts     []Artifact     `json:"artifacts"`
	Breadcrumbs   Breadcrumbs    `json:"breadcrumbs,omitempty"`

	// @dhazekamp command_name required when CLICommand is true?
	CommandName string `json:"command_name,omitempty"`
}

Component can be a command-line tool, a new command that extends the Lacework CLI, or a library that contains files used by another Lacework component.

func (Component) ArtifactForRunningHost

func (c Component) ArtifactForRunningHost(version string) (*Artifact, bool)

ArtifactForRunningHost returns the right component artifact for the running host,

func (Component) CurrentVersion

func (c Component) CurrentVersion() (*semver.Version, error)

CurrentVersion returns the current installed version of the component

func (Component) EnterDevelopmentMode

func (c Component) EnterDevelopmentMode() error

func (Component) IsCommandType

func (c Component) IsCommandType() bool

func (Component) IsExecutable

func (c Component) IsExecutable() bool

func (Component) IsInstalled

func (c Component) IsInstalled() bool

IsInstalled returns true if the component is installed on disk

func (Component) ListVersions

func (c Component) ListVersions(installed *semver.Version) string

func (Component) MakeUpdateMessage

func (c Component) MakeUpdateMessage(from, to semver.Version) string

func (Component) MarshalJSON

func (c Component) MarshalJSON() ([]byte, error)

func (Component) Path

func (c Component) Path() (string, error)

Path returns the path to the component ("RootPath()/{name}")

func (Component) RootPath

func (c Component) RootPath() (string, error)

RootPath returns the component's root path ("Dir()/{name}")

func (Component) RunAndOutput

func (c Component) RunAndOutput(args []string, envs ...string) error

RunAndOutput runs the command and outputs to os.Stdout and os.Stderr, the provided environment variables will be accessible by the component

func (Component) RunAndReturn

func (c Component) RunAndReturn(args []string, stdin io.Reader, envs ...string) (
	stdout string,
	stderr string,
	err error,
)

RunAndReturn runs the command and returns its standard output and standard error, the provided environment variables will be accessible by the component

func (Component) SignatureFromDisk

func (c Component) SignatureFromDisk() ([]byte, error)

SignatureFromDisk returns the component signature stored on disk ("RootPath()/.signature")

func (Component) Status

func (c Component) Status() Status

Status returns the component status

func (Component) UnderDevelopment

func (c Component) UnderDevelopment() bool

UnderDevelopment returns true if the component is under development that is, if the component root path has the '.dev' specs file or, if the environment variable 'LW_CDK_DEV_COMPONENT' matches the component name

func (*Component) UnmarshalJSON

func (c *Component) UnmarshalJSON(data []byte) error

func (Component) UpdateAvailable

func (c Component) UpdateAvailable() (bool, error)

UpdateAvailable returns true if there is a newer version of the component

func (Component) WriteSignature

func (c Component) WriteSignature(signature []byte) error

WriteSignature stores the component signature on disk

func (Component) WriteVersion

func (c Component) WriteVersion(installed string) error

WriteVersion stores the component version on disk

type Library

type Library interface {

	// Install downloads the library and deploys the files and index
	Install() error

	// Index returns the index of files that the library contains
	Index() []string

	// GetFile returns the content of one file from the library
	GetFile(string) ([]byte, error)
}

A library component provides one or more files that other components use

type RunError

type RunError struct {
	ExitCode int
	Message  string
	Err      error
}

RunError is a struct used to pass an error when a component tries to run and it fails, a few functions will return this error so that callers (upstream packages) can unwrap and identify that the error comes from this package

func (*RunError) Error

func (e *RunError) Error() string

func (*RunError) Unwrap

func (e *RunError) Unwrap() error

type State

type State struct {
	Version    string      `json:"version"`
	Components []Component `json:"components"`
}

State holds the components specification

You can load the state from the Lacework API server by passing an `api.Client`.

client, err := api.NewClient(account, opts...)
cState, err := lwcomponent.LoadState(client)

Or, you can load the state from the local storage.

cState, err := lwcomponent.LocalState()

func LoadState

func LoadState(client *api.Client) (*State, error)

LoadState loads the state from the Lacework API server

func LocalState

func LocalState() (*State, error)

LocalState loads the state from the local storage ("Dir()/state")

func (State) GetComponent

func (s State) GetComponent(name string) (*Component, bool)

GetComponent returns the pointer of a component, if the component is not found, this function will return a `nil` pointer and `false`

Usage:

component, found := state.GetComponent(name)

if !found {
	fmt.Println("Component %s not found", name)
}

func (State) Install

func (s State) Install(component *Component, version string) error

func (State) Verify

func (s State) Verify(component *Component, version string) error

func (State) WriteState

func (s State) WriteState() error

WriteState stores the components state to disk

type Status

type Status int

const (
	UnknownStatus Status = iota
	NotInstalled
	Installed
	UpdateAvailable
)

func (Status) String

func (cs Status) String() string

type Type

type Type string