libwraith

Documentation

Index

• Constants
• type Config
• type Wraith
  • func (w *Wraith) GetInitTime() time.Time
  • func (w *Wraith) GetStrainId() string
  • func (w *Wraith) IsAlive() bool
  • func (w *Wraith) ModsGet() []string
  • func (w *Wraith) ModsReg(mods ...mod)
  • func (w *Wraith) SHMDump() map[string]any
  • func (w *Wraith) SHMGet(cellname string) any
  • func (w *Wraith) SHMPrune() int
  • func (w *Wraith) SHMSet(cellname string, value any)
  • func (w *Wraith) SHMUnwatch(cellname string, watchId int)
  • func (w *Wraith) SHMWatch(cellname string) (chan any, int)
  • func (w *Wraith) Spawn(pctx context.Context, conf Config, mods ...mod)

Constants

const (
	// The size of watcher channels. Making this bigger makes update
	// delivery more reliable and ordered but increases memory usage
	// if a watcher isn't reading its updates.
	SHMCONF_WATCHER_CHAN_SIZE = 255

	// Timeout in seconds after which notifications for watchers are
	// dropped if writing to the channel blocks.
	SHMCONF_WATCHER_NOTIF_TIMEOUT = 1
)

Configuration options for shared memory.

const (
	// This cell holds the latest error which occurred, be it in a module
	// or Wraith itself. Can be used to send error logs to C2.
	SHM_ERRS = "err"
)

Reserved locations in the shared memory with special purposes. All other locations should be namespaced.

Types

type Config

type Config struct {
	// A string representing the family ID or strain ID of Wraith.
	// This can be useful to check what different versions of
	// Wraith are out there, or to target only one specific
	// strain with commands/payloads. This should be changed
	// whenever a significant change is made to Wraith before building.
	StrainId string

	// A function used to generate the fingerprint for this instance
	// of Wraith. That is, a unique string identifying specifically this
	// binary, on this host, in this process. It can be a UUID, for
	// instance, meaning that it serves only the purpose of identifiaction
	// and changes on every Wraith restart, or a string based on some
	// information such as MAC Address+Wraith PID.
	FingerprintGenerator func() string

	// The max time to wait for a heartbeat from Wraith's mainloop before
	// assuming that this instance is dead. Around 1 second is recommended.
	// Note that setting this too high can cause significant slowdowns when
	// Wraith does die.
	HeartbeatTimeout time.Duration

	// How many times modules should be allowed to crash within a time
	// specified in ModuleCrashLoopDetectTime before they are no longer
	// restarted. It is recommended to keep this relatively low to prevent
	// buggy modules from using up resources. The lower the value the more
	// strict the crashloop detection.
	ModuleCrashloopDetectCount int

	// After this time, module crashes are forgotten when evaluating whether
	// a module is crashlooping. It is recommended to keep this value relatively
	// high to ensure that crashlooped or buggy modules are always caught. The
	// higher the value the more strict the crashloop detection.
	ModuleCrashloopDetectTime time.Duration
}

A struct providing configuration options for Wraith to allow for altering behaviour without altering the code.

type Wraith

type Wraith struct {
	// contains filtered or unexported fields
}

func (*Wraith) GetInitTime

func (w *Wraith) GetInitTime() time.Time

Return the time at which Wraith started initialisation (recorded as soon as Wraith confirms that it is the only running instance). This will be the time.Time zero value if Wraith has not yet started initialisation.

func (*Wraith) GetStrainId

func (w *Wraith) GetStrainId() string

Get the strain ID of this Wraith.

func (*Wraith) IsAlive

func (w *Wraith) IsAlive() bool

Check whether Wraith's mainloop is running by issuing a heartbeat request and awaiting a response with a configured timeout.

func (*Wraith) ModsGet

func (w *Wraith) ModsGet() []string

Get a list of modules available to Wraith.

func (*Wraith) ModsReg

func (w *Wraith) ModsReg(mods ...mod)

Add a module to Wraith. These are started straight away automatically.

Panics if Wraith is not running by the time this method is called.

func (*Wraith) SHMDump

func (w *Wraith) SHMDump() map[string]any

Proxy to shm.Dump()

func (*Wraith) SHMGet

func (w *Wraith) SHMGet(cellname string) any

Proxy to shm.Get().

Disallows reading from protected cells.

func (*Wraith) SHMPrune

func (w *Wraith) SHMPrune() int

Proxy to shm.Prune()

func (*Wraith) SHMSet

func (w *Wraith) SHMSet(cellname string, value any)

Proxy to shm.Set().

Disallows writing to protected cells.

func (*Wraith) SHMUnwatch

func (w *Wraith) SHMUnwatch(cellname string, watchId int)

Proxy to shm.Unwatch()

Disallows unwatching protected cells.

func (*Wraith) SHMWatch

func (w *Wraith) SHMWatch(cellname string) (chan any, int)

Proxy to shm.Watch().

Disallows watching protected cells.

func (*Wraith) Spawn

func (w *Wraith) Spawn(pctx context.Context, conf Config, mods ...mod)

Spawn an instance of Wraith running synchronously. If you would like Wraith to run asynchronously, start this function in a goroutine. It can then be stopped by cancelling its context.

The first argument is a context instance used to control Wraith's lifetime. The second is an instance of WraithConf containing the configuration for this instance of Wraith. It should be fully initialised and filled out. An uninitialised config can lead to undefined behaviour. The following arguments are modules which should be available to Wraith. In case of a name conflict, the first module in the list with the name will be used, the others will be discarded.

Modules are initialised and started in the order they are given. It is highly recommended to pass the comms manager module first (possibly preceded by modules it depends on) to make sure module communications are not lost.