modules

Documentation

Overview

This package implements interfaces to write modules for MIG.

For a guide on how to write modules, head over to http://mig.mozilla.org/doc/modules.rst.html

Index

• Variables
• func DefaultPersistHandlers(in ModuleReader, out ModuleWriter, logch chan string, errch chan error, ...)
• func GetPersistListener(modname string) (l net.Listener, specname string, err error)
• func HandlePersistRequest(l net.Listener, f func(interface{}) string, errch chan error)
• func MakeMessage(class MessageClass, params interface{}, comp bool) (rawMsg []byte, err error)
• func MakeMessageAlert(f string, args ...interface{}) (rawMsg []byte, err error)
• func MakeMessageConfig(cfgdata interface{}, hostname string, env interface{}, tags map[string]string) (rawMsg []byte, err error)
• func MakeMessageLog(f string, args ...interface{}) (rawMsg []byte, err error)
• func MakeMessageRegister(spec string) (rawMsg []byte, err error)
• func ReadInputParameters(r ModuleReader, p interface{}) (err error)
• func ReadPersistInputParameters(r ModuleReader, p interface{}) (spath string, err error)
• func Register(name string, mod Moduler)
• func RegisterDispatchFunction(f func(string))
• func SendPersistRequest(p interface{}, sockspec string) (res string)
• func WatchForStop(r ModuleReader, stopChan *chan bool) error
• func WriteOutput(buf []byte, w ModuleWriter) (err error)
• type AlertParams
• type ConfigParams
• type HasEnhancedPrivacy
• type HasParamsCreator
• type HasParamsParser
• type HasResultsPrinter
• type LogParams
• type Message
  • func ReadInput(r ModuleReader) (msg Message, err error)
• type MessageClass
• type ModuleReader
  • func NewModuleReader(r io.Reader) (ret ModuleReader)
• type ModuleWriter
  • func NewModuleWriter(w io.Writer) (ret ModuleWriter)
• type Moduler
• type PersistRunner
• type RegParams
• type Result
  • func (r Result) GetElements(el interface{}) (err error)
  • func (r Result) GetStatistics(stats interface{}) (err error)
• type Runner

Variables

var Available = make(map[string]Moduler)

The set of registered modules

var ModuleRunDir string

Functions

func DefaultPersistHandlers

func DefaultPersistHandlers(in ModuleReader, out ModuleWriter, logch chan string,
	errch chan error, regch chan string, alertch chan string, confch chan ConfigParams)

A general management function that can be called by persistent modules from the RunPersist function. Looks after replying to ping messages, writing logs, and other communication between the agent and the running persistent module.

func GetPersistListener

func GetPersistListener(modname string) (l net.Listener, specname string, err error)

Get a listener for a persistent module that is appropriate for the platform type, returns the listener itself in addition to the socket specification that should be registered.

func HandlePersistRequest

func HandlePersistRequest(l net.Listener, f func(interface{}) string, errch chan error)

Request handler that can be called from RunPersist in a persistent module. Looks after accepting incoming requests to listener l, and routing the requests to the registered incoming request handler f.

func MakeMessage

func MakeMessage(class MessageClass, params interface{}, comp bool) (rawMsg []byte, err error)

MakeMessage creates a new modules.Message with a given class and parameters and return the byte slice of the json marshalled message

func MakeMessageAlert

func MakeMessageAlert(f string, args ...interface{}) (rawMsg []byte, err error)

MakeMessageAlert creates a new message of class alert

func MakeMessageConfig

func MakeMessageConfig(cfgdata interface{}, hostname string, env interface{},
	tags map[string]string) (rawMsg []byte, err error)

Creates a new message of class config.

func MakeMessageLog

func MakeMessageLog(f string, args ...interface{}) (rawMsg []byte, err error)

MakeMessageLog creates a new message of class log.

func MakeMessageRegister

func MakeMessageRegister(spec string) (rawMsg []byte, err error)

Creates a new message of class register.

func ReadInputParameters

func ReadInputParameters(r ModuleReader, p interface{}) (err error)

ReadInputParameters reads the first line from ModuleReader r and expects to find a modules.Message of class `parameters`. This function uses ReadInput and will block waiting for data on stdin

func ReadPersistInputParameters

func ReadPersistInputParameters(r ModuleReader, p interface{}) (spath string, err error)

ReadPersistInputParameters performs the same function as ReadInputParameters however it also validates a socket path has been specified to query the persistent module, returning an error if this is not present. Populates p and also returns the socket path.

func Register

func Register(name string, mod Moduler)

Register a new module as available

func RegisterDispatchFunction

func RegisterDispatchFunction(f func(string))

RegisterDispatchFunction can be called by a module to register a function that will be used to process incoming alert messages from the master agent process. It is primarily used by the dispatch module.

func SendPersistRequest

func SendPersistRequest(p interface{}, sockspec string) (res string)

Sends the parameters in p as a request to a persistent module listening at socket specification sockspec; would typically be used in the Run() function of a persistent module.

func WatchForStop

func WatchForStop(r ModuleReader, stopChan *chan bool) error

WatchForStop continuously reads stdin for a stop message. When one is received, `true` is sent into the stop channel.

func WriteOutput

func WriteOutput(buf []byte, w ModuleWriter) (err error)

Write output in buf to writer w. buf is expected to contain a single line of data, and a line feed is appended to terminate the line as module IO is line delimited.

Types

type AlertParams

type AlertParams struct {
	Message string `json:"message"`
}

AlertParams describes the parameters used in an alert message

type ConfigParams

type ConfigParams struct {
	Config   interface{}       `json:"config"`
	Hostname string            `json:"hostname"`
	Env      interface{}       `json:"environment"`
	Tags     map[string]string `json:"tags"`
}

type HasEnhancedPrivacy

type HasEnhancedPrivacy interface {
	EnhancePrivacy(Result) (Result, error)
}

type HasParamsCreator

type HasParamsCreator interface {
	ParamsCreator() (interface{}, error)
}

HasParamsCreator implements a function that creates module parameters

type HasParamsParser

type HasParamsParser interface {
	ParamsParser([]string) (interface{}, error)
}

HasParamsParser implements a function that parses command line parameters

type HasResultsPrinter

type HasResultsPrinter interface {
	PrintResults(Result, bool) ([]string, error)
}

HasResultsPrinter implements functions used by module to print information

type LogParams

type LogParams struct {
	Message string `json:"message"`
}

Parameter format expected for a log message

type Message

type Message struct {
	Class       MessageClass `json:"class"`                 // represent the type of message being passed to the module
	Parameters  interface{}  `json:"parameters,omitempty"`  // for `parameters` class, this interface contains the module parameters
	PersistSock string       `json:"persistsock,omitempty"` // Persistent module socket path if required
}

Message defines the input messages received by modules.

All messages will have Class and Parameters set. PersistSock is used in a case where a parameters message is being sent for a persistent module. In this case, PersistSock will contain the socket specification the module has registered as listening on.

func ReadInput

func ReadInput(r ModuleReader) (msg Message, err error)

ReadInput reads one line of input from ModuleReader r, unmarshal it into a modules.Message and returns the message to the caller

type MessageClass

type MessageClass string

const (
	MsgClassParameters MessageClass = "parameters"
	MsgClassStop       MessageClass = "stop"
	MsgClassPing       MessageClass = "ping"
	MsgClassLog        MessageClass = "log"
	MsgClassRegister   MessageClass = "register"
	MsgClassConfig     MessageClass = "config"
	MsgClassAlert      MessageClass = "alert"
)

type ModuleReader

type ModuleReader struct {
	Reader       io.Reader
	BufferReader *bufio.Reader
}

ModuleReader is used to read module communications. It's intent is to wrap the initial reader (e.g., stdin) with a buffered reader that will exist for the lifetime of execution of the module. When the module reads input, it will read from BufferReader inside ModuleReader since our communication is line delimited, so we want to make sure we allocate this buffer only once.

func NewModuleReader

func NewModuleReader(r io.Reader) (ret ModuleReader)

Create a new ModuleReader wrapping reader r.

type ModuleWriter

type ModuleWriter struct {
	Writer io.Writer
}

ModuleWriter is used to write module communications. We don't require bufio on writes, but this type exists just to provide consistency with ModuleReader.

func NewModuleWriter

func NewModuleWriter(w io.Writer) (ret ModuleWriter)

Create a new ModuleWriter wrapping writer w.

type Moduler

type Moduler interface {
	NewRun() Runner
}

A mig module implements this interface

type PersistRunner

type PersistRunner interface {
	RunPersist(ModuleReader, ModuleWriter)
	PersistModConfig() interface{}
}

PersistRunner provides the interface to execution of a persistent module. All modules will satisfy Runner. Persistent modules will satisfy both Runner and PersistRunner.

type RegParams

type RegParams struct {
	SockPath string `json:"sockpath"`
}

Parameter format expected for a register message

type Result

type Result struct {
	FoundAnything bool        `json:"foundanything"`
	Success       bool        `json:"success"`
	Elements      interface{} `json:"elements"`
	Statistics    interface{} `json:"statistics"`
	Errors        []string    `json:"errors"`
}

Result implement the base type for results returned by modules. All modules must return this type of result. The fields are:

• FoundAnything: a boolean that must be set to true if the module ran a search that returned at least one positive result

• Success: a boolean that must be set to true if the module ran without fatal errors. soft errors are reported in Errors

• Elements: an undefined type that can be customized by the module to contain the detailled results

• Statistics: an undefined type that can be customized by the module to contain some information about how it ran

• Errors: an array of strings that contain non-fatal errors encountered by the module

func (Result) GetElements

func (r Result) GetElements(el interface{}) (err error)

GetElements reads the elements from a struct of results into the el interface

func (Result) GetStatistics

func (r Result) GetStatistics(stats interface{}) (err error)

GetStatistics reads the statistics from a struct of results into the stats interface

type Runner

type Runner interface {
	Run(ModuleReader) string
	ValidateParameters() error
}

Runner provides the interface to an execution of a module