Documentation

Overview

Package puffgo implements a logic-bomb using elementary golang functionalities. The package breaks the implementation of this into 2 parts.

The first part is the type EventListener defined in EventListener.go. It uses a network of channels that help run a subprocess concurrently to detect an arbitrary system event and trigger the logic bomb.

The second part is the type LogicBomb defined in LogicBomb.go. The type defines several methods to control the function of the logic bomb.

The documentation and definition of each of the types in the package can be found below. See the included examples for more detail.

Index

Overview
type EventListener
 func NewListener(interval *time.Duration, tfunc func() bool) *EventListener
 func (e *EventListener) Mainloop()
 func (e *EventListener) Terminate()
type LogicBomb
 func NewBomb(listener EventListener, execFunc func()) *LogicBomb
 func (lb *LogicBomb) Arm()
 func (lb *LogicBomb) Disarm()

type EventListener

type EventListener struct {

	// TriggerChannel is used to detect if the specified event has occurred.
	// When the event does occur, a boolean true is passed into it.
	TriggerChannel chan bool

	// Interval specifies the delay between each check performed for the event.
	Interval *time.Duration

	// TriggerFunction specifies the function which will be
	// used to check for the event's occurence.
	//
	// The function will return a boolean, and will be executed
	// on intervals of Interval (type: *time.Duration).
	// If Interval is nil, it performs checks every 500ms.
	//
	// When the event occurs, true is passed into TriggerChannel,
	// which can be used as a detection mechanism.
	TriggerFunction func() bool

	// TerminationChannel acts as a stopping mechanism for the EventListener's mainloop.
	// If a boolean true is passed into it, the mainloop is terminated and
	// the EventListener no longer will detect the specified event.
	TerminationChannel chan bool

	// PID specifies the process-id of the EventListener's persistent mainloop.
	// It holds nil until the mainloop is started.
	PID *int
}

As the name suggests, EventListener type defines an event listener that performs background checks for a specific event. The checks are performed on the basis of the function: TriggerFunction in the fields of the EventListener struct.

An EventListener will constantly perform checks using TriggerFunction, and will sleep for Interval during each iteration of the mainloop. The mainloop can be started using the Mainloop() function.

func NewListener

func NewListener(interval *time.Duration, tfunc func() bool) *EventListener

NewListener returns a pointer of type *EventListener. It takes in the following arguments:

• interval Type: *time.Duration
  
  Specifies the delay between checks for the occurrence of the specified event. If interval is nil, the delay is taken to be 500ms by default.

• tfunc Type: func() bool
  
  Specifies the TriggerFunction for the new event-listener. As stated in the definition of the EventListener type, the TriggerFunction is used to perform checks for the occurrence of the specified event.

func (e *EventListener) Mainloop()

func (e *EventListener) Mainloop()

Mainloop starts the mainloop for the event listener. It makes use of TriggerChannel and TerminationChannel defined in the type definition of EventListener.

When the function is executed, it starts the "listening" process of the event-listener. Every iteration of the process, it passes the boolean return value obtained by TriggerFunction. If the value passed into this channel is true, the Bomb goes off and the function: ExecutionFunction defined in the type: LogicBomb is executed.

NOTE: Mainloop starts an infinite loop for the listening process, and not a subprocess.

func (e *EventListener) Terminate()

func (e *EventListener) Terminate() 

Terminate() terminates the mainloop checking for the event by passing true into the TerminationChannel. It can be used for specific termination of the event-listener's mainloop, i.e. as an "Emergency Stop" for the program.

type LogicBomb

type LogicBomb struct {

	// Listener represents an event-listner defined in this library.
	Listener *EventListener

	// ExecutionFunction specifies the function
	// which will be executed when the bomb is triggered and it goes off
	ExecutionFunction func()

	// BombID specifies a random hex string used to identify the bomb.
	BombID string

	// PID specifies the process-id of the persistent logic-bomb program running.
	// It holds nil until the mainloop of the event-listner is started.
	PID *int
}

LogicBomb is a type implementing a logic-bomb.

It makes use of concurrent processes via EventListener to detect the occurrence of an event that triggers the bomb. When the bomb is triggered, ExecutionFunction is executed.

func NewBomb(listener EventListener, execFunc func()) *LogicBomb

func NewBomb(listener EventListener, execFunc func()) *LogicBomb

NewBomb() returns a pointer of type: *LogicBomb. It takes in the following arguments:

• listener Type: EventListener

Specifies the event-listener for the logic bomb to listen for the triggering event.

• execFunc Type: func()

Specifies a function that will be executed when the bomb is triggered.

func (lb *LogicBomb) Arm()

func (lb *LogicBomb) Arm()

Arm() allows the activation of the bomb. If a bomb is not armed, it won't be triggered even if the event defined in Listener occurs.

It makes use of the TriggerChannel and TerminationChannel from EventListener

func (lb *LogicBomb) Disarm()

func (lb *LogicBomb) Disarm()

Disarm() allows the deactivation of the bomb. It passes a true into the TerminationChannel of Listener, thereby terminating the listener's mainloop.