The highest tagged major version is
Documentation
¶
Overview ¶
Package kits provides tools for interacting with kit archives directly. Most users will not need to deal with this.
Index ¶
- Constants
- Variables
- func GetHash(v []byte) [sha256.Size]byte
- func GetKitItem(name string, tp ItemType, rdr io.Reader) (itm types.KitItem, err error)
- type Builder
- func (pb *Builder) Abort() error
- func (pb *Builder) Add(name string, tp ItemType, v []byte) error
- func (pb *Builder) AddFile(name string, tp ItemType, f *os.File) error
- func (pb *Builder) AddReader(name string, tp ItemType, r io.Reader) error
- func (pb *Builder) Close() (err error)
- func (pb *Builder) Description() string
- func (pb *Builder) ID() string
- func (pb *Builder) Manifest() Manifest
- func (pb *Builder) Name() string
- func (pb *Builder) SetBanner(id string) error
- func (pb *Builder) SetCover(id string) error
- func (pb *Builder) SetIcon(id string) error
- func (pb *Builder) WriteManifest(sig []byte) (err error)
- type BuilderConfig
- type CallbackFunc
- type Item
- type ItemType
- type Manifest
- func (m *Manifest) Add(item Item) error
- func (m *Manifest) CompatibleVersion(v types.CanonicalVersion) (err error)
- func (m *Manifest) Load(rdr io.Reader) error
- func (m *Manifest) Marshal() ([]byte, error)
- func (m *Manifest) SetBanner(id string) error
- func (m *Manifest) SetCover(id string) error
- func (m *Manifest) SetIcon(id string) error
- func (m *Manifest) Unmarshal(v []byte) error
- type PackedDashboard
- type PackedMacro
- type PackedResource
- type PackedScheduledSearch
- type Reader
- type SigVerificationFunc
Constants ¶
const ( Version uint = 3 ManifestName = `MANIFEST` ManifestSigName = `SIGNATURE` Resource ItemType = 1 ScheduledSearch ItemType = 2 Dashboard ItemType = 3 Extractor ItemType = 4 Pivot ItemType = 5 Template ItemType = 6 File ItemType = 7 Macro ItemType = 8 SearchLibrary ItemType = 9 License ItemType = 10 Playbook ItemType = 11 Alert ItemType = 12 External ItemType = 0xffff )
Variables ¶
var ( ErrNotActive = errors.New("Not active") ErrInvalidImageID = errors.New("Invalid image ID, must be an existing file GUID") ErrEmptyID = errors.New("Empty bundle ID") )
var ( ErrInvalidSignature = errors.New("Invalid manifest signature") ErrEmptyFileName = errors.New("Empty file name") ErrEmptyName = errors.New("Empty name") ErrEmptyContent = errors.New("Empty data") ErrInvalidType = errors.New("Invalid ItemType") ErrInvalidHash = errors.New("Invalid file hash") ErrInvalidVersion = errors.New("Invalid kit Version") ErrManifestMismatch = errors.New("Manifest does not match kit") ErrMissingManifest = errors.New("Kit is missing a manifest") ErrMissingSignature = errors.New("Kit is missing a manifest signature") )
Functions ¶
func GetKitItem ¶
GetKitItem extracts additional data about a given Item by extracting the object from the rdr and fetching metadata from it. It is typically used in conjunction with the Process method, e.g.:
kitreader.Process(func(name string, tp kits.ItemType, hash [sha256.Size]byte, rdr io.Reader) error {
if itm, err := kits.GetKitItem(name, tp, rdr); err != nil {
return err
} else {
itm.Hash = hash
kitItems = append(kitItems, itm)
}
return nil
})
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder is used to construct a kit. A typical workflow is:
• Instantiate Builder using NewBuilder or NewBuilderFile
• Add kit items by calling Add method on Builder
• Use SetCover, SetBanner, SetIcon methods if desired
• Call WriteManifest method and Close method
func NewBuilder ¶
func NewBuilder(cfg BuilderConfig, fout io.WriteCloser) (pb *Builder, err error)
NewBuilder creates a new Builder object. It takes a kit configuration (BuilderConfig) and a WriteCloser as arguments. The completed kit will be written to the WriteCloser.
func NewBuilderFile ¶
func NewBuilderFile(cfg BuilderConfig, output string) (pb *Builder, err error)
NewBuilderFile instantiates a new Builder object. It takes a kit configuration and a file path where the resulting kit should be saved.
func (*Builder) Abort ¶
Abort bails and closes the output stream. It does not properly shut down the kit archive writer; the resulting kit will likely not be valid.
func (*Builder) Add ¶
Add includes an item in the kit. The parameters are name (the name for the item), tp (the type of item), and v (the JSON-encoded item itself).
func (*Builder) AddFile ¶
AddFile includes an item in the kit, reading from an open file descriptor rather than from a slice of bytes.
func (*Builder) AddReader ¶
AddReader includes an item in the kit, reading from an io.Reader instead of a slice of bytes.
func (*Builder) Close ¶
Close attempts to properly terminate the kit archive writer and close the Builder.
func (*Builder) Description ¶
Description returns kit's description.
func (*Builder) SetBanner ¶
SetBanner sets the banner image for the kit. The parameter must be the name of an existing item already in the kit with ItemType == File.
func (*Builder) SetCover ¶
SetCover sets the cover image for the kit. The parameter must be the name of an existing item already in the kit with ItemType == File.
func (*Builder) SetIcon ¶
SetIcon sets the icon image for the kit. The parameter must be the name of an existing item already in the kit with ItemType == File.
func (*Builder) WriteManifest ¶
WriteManifest writes the current state of the kit manifest to the archive. It should be the last thing called before completing the kit, after all items have been added. The "sig" parameter is an optional manifest signature which will be added to the kit if it is not nil. Call Manifest() to get the manifest, generate the signature based on that manifest, then call WriteManifest with that signature.
type BuilderConfig ¶
type BuilderConfig struct {
Version uint
Name string
Description string // A short description of the kit
Readme string // A more detailed description of the kit
ID string
MinVersion types.CanonicalVersion
MaxVersion types.CanonicalVersion
Dependencies []types.KitDependency
ConfigMacros []types.KitConfigMacro
}
BuilderConfig sets basic options for a kit.
func (*BuilderConfig) Validate ¶
func (c *BuilderConfig) Validate() error
Validate ensures that the BuilderConfig is acceptable.
type CallbackFunc ¶
CallbackFunc is the function type which is passed to the Process method. The function will be called for each Item in the kit. The item itself can be read from the io.Reader.
type Item ¶
type Item struct {
Name string //the name given to the item (script name, dashboard name, etc...)
Type ItemType //type specifier
Hash [sha256.Size]byte //hash in the bundle
}
Item describes a single object within the kit. Note that it does not contain the actual body of the object, it just describes the item name and type, and gives a hash which can be used to verify item integrity.
func (Item) MarshalJSON ¶
MarshalJSON packs an Item into JSON encoding.
func (*Item) UnmarshalJSON ¶
UnmarshalJSON unpacks an Item from JSON encoding.
type ItemType ¶
type ItemType int
func TranslateExt ¶
TranslateExt translates a file extension (e.g. "dashboard") into an ItemType.
func TranslateType ¶
TranslateType converts a string (e.g. "scheduled search") into an ItemType.
func (ItemType) Ext ¶
Ext returns a file extension for the item type. These will not contain spaces.
type Manifest ¶
type Manifest struct {
ID string
Name string
Desc string
Readme string
Version uint
MinVersion types.CanonicalVersion
MaxVersion types.CanonicalVersion
Icon string
Banner string
Cover string
Items []Item
Dependencies []types.KitDependency
ConfigMacros []types.KitConfigMacro
}
Manifest contains information about a kit and a listing of items in the kit.
func Verify ¶
func Verify(rdr io.Reader, sigVerify SigVerificationFunc) (signed bool, manifest Manifest, sigerr error, err error)
Verify reads a kit from the rdr and checks that all items are valid. If sigVerify is not nil, it will be called to verify the manifest signature. It returns two errors, one from the signature verification function and one for all other errors.
func (*Manifest) CompatibleVersion ¶
func (m *Manifest) CompatibleVersion(v types.CanonicalVersion) (err error)
CompatibleVersion checks the given version against the minimum and maximum versions specified in the manifest. It returns an error if the version is outside the range.
func (*Manifest) Load ¶
Load reads a JSON-encoded manifest from an io.Reader and unpacks it into the current manifest.
func (*Manifest) Marshal ¶
Marshal returns a slice of bytes containing indented JSON representing the manifest.
func (*Manifest) SetBanner ¶
SetBanner sets the banner field to point at an existing File item in the manifest.
func (*Manifest) SetCover ¶
SetCover sets the cover field to point at an existing File item in the manifest.
type PackedDashboard ¶
type PackedDashboard struct {
UUID string
Name string
Description string
Data types.RawObject
Labels []string
}
PackedDashboard is a stripped-down type used for dashboards in kits.
func PackDashboard ¶
func PackDashboard(d types.Dashboard) (pd PackedDashboard)
PackDashboard converts a Dashboard into a PackedDashboard.
func (*PackedDashboard) JSONMetadata ¶
func (pd *PackedDashboard) JSONMetadata() (json.RawMessage, error)
JSONMetadata returns additional info about the PackedDashboard in JSON format.
func (*PackedDashboard) Validate ¶
func (pd *PackedDashboard) Validate() error
Validate checks the fields of the PackedDashboard.
type PackedMacro ¶
type PackedMacro struct {
Name string
Description string
Expansion string `json:",omitempty"`
Labels []string
}
PackedMacro is a stripped-down representation of a macro object for inclusion in a kit.
func PackSearchMacro ¶
func PackSearchMacro(m *types.SearchMacro) (p PackedMacro)
PackSearchMacro turns a regular SearchMacro object into a PackedMacro.
func (*PackedMacro) JSONMetadata ¶
func (pm *PackedMacro) JSONMetadata() (json.RawMessage, error)
JSONMetadata returns additional information about the macro.
func (*PackedMacro) Validate ¶
func (pm *PackedMacro) Validate() error
Validate ensures that the fields of the PackedMacro are valid.
type PackedResource ¶
type PackedResource struct {
VersionNumber int // resource version #, increment at each Write
ResourceName string
Description string
Labels []string
Size uint64
Hash []byte
Data []byte
}
PackedResource is a stripped-down representation of a resource for inclusion in a kit.
func PackResourceUpdate ¶
func PackResourceUpdate(ru types.ResourceUpdate) (p PackedResource)
PackResourceUpdate takes a ResourceUpdate (which contains a complete description of a resource, including its contents) and converts it into a PackedResource.
func (*PackedResource) JSONMetadata ¶
func (p *PackedResource) JSONMetadata() (json.RawMessage, error)
JSONMetadata returns additional information about the resource.
func (*PackedResource) Validate ¶
func (p *PackedResource) Validate() error
Validate checks the contents of a PackedResource for validity.
type PackedScheduledSearch ¶
type PackedScheduledSearch struct {
Name string // the name of this scheduled search
Description string // freeform description
Labels []string
Schedule string // when to run: a cron spec
SearchString string `json:",omitempty"` // The actual search to run
Duration int64 `json:",omitempty"` // How many seconds back to search, MUST BE NEGATIVE
Script string `json:",omitempty"` // If set, execute the contents rather than running SearchString
DefaultDeploymentRules types.ScriptDeployConfig
Flow string `json:",omitempty"`
ScheduledType string
GUID uuid.UUID // A unique ID for this scheduled search. Useful for detecting and handling upgrades.
}
PackedScheduledSearch is a stripped-down representation of a scheduled search for inclusion in a kit.
func PackScheduledSearch ¶
func PackScheduledSearch(ss *types.ScheduledSearch) (p PackedScheduledSearch)
PackScheduledSearch converts a ScheduledSearch into a PackedScheduledSearch for inclusion in a kit.
func (*PackedScheduledSearch) JSONMetadata ¶
func (pss *PackedScheduledSearch) JSONMetadata() (json.RawMessage, error)
JSONMetadata returns additional info about the PackedScheduledSearch in JSON format.
func (*PackedScheduledSearch) TypeName ¶
func (pss *PackedScheduledSearch) TypeName() string
TypeName returns either "script" or "search" depending on the type of the PackedScheduledSearch.
func (*PackedScheduledSearch) Unpackage ¶
func (pss *PackedScheduledSearch) Unpackage(uid int32, gids []int32) (ss types.ScheduledSearch)
Unpackage expands a PackedScheduledSearch into a ScheduledSearch.
func (*PackedScheduledSearch) Validate ¶
func (pss *PackedScheduledSearch) Validate() error
Validate checks the fields of the PackedScheduledSearch.
type Reader ¶
type Reader struct {
// contains filtered or unexported fields
}
Reader is used to extract kit archives for processing and installation. A typical workflow is:
• Instantiate Reader using NewReader
• Call Verify method to ensure kit file is valid
• Optionally call Signed method to ensure kit file was signed
• Call Process method with a callback function to extract items from kit.
func NewReader ¶
func NewReader(rdr utils.ReadResetCloser, sigVerify SigVerificationFunc) (rp *Reader, err error)
NewReader returns a Reader which will parse a kit from the given ReadResetCloser. Note that rdr is a ReadResetCloser; the Reset function is used to reset the reader to the beginning of the stream. The github.com/gravwell/gravwell/v4/ingesters/utils package includes several convenient ReadResetCloser implementations.
The sigVerify parameter is an optional function used to validate the kit's manifest signature. The function will be called with the manifest and signature passed as slices of bytes; it is the responsibility of the user to implement signature validation. Pass 'nil' to disable signature verification.
func (*Reader) Manifest ¶
Manifest returns the manifest object for the kit. It will return an error if the reader is not properly initialized or if the Verify function has not been called.
func (*Reader) Process ¶
func (rp *Reader) Process(cb CallbackFunc) (err error)
Process walks the contents of the kit, extracting individual items and calling the CallbackFunc for each item. If the callback returns an error, Process will terminate early.
func (*Reader) Signed ¶
Signed returns true if the kit has been signed. It will return an error if the reader has not been initialized, if the Verify method has not been previously called, or if there was a problem with the kit signature.
func (*Reader) Verify ¶
Verify validates the contents of the kit and prepares the Reader for use. It calls the Verify function to extract the kit's manifest and check the signature. Note that Verify does not return an error if the kit signature is invalid, because a kit should be able to pass basic verification and still fail the sig check; use the Signed function to check that.
type SigVerificationFunc ¶
SigVerificationFunc is the function type used to validate a manifest signature. It is passed the manifest and signature as slices of bytes. For standard public-key signature verification, use a lambda function which captures the key.
Source Files