puffgo: A Logic-Bomb Written in Go

An Overview of the Package

The package puffgo implements a logic-bomb using elementary golang functionalities. It makes use of goroutines to define a simple EventListener, and a type: LogicBomb, that enables users to define and control logic-bombs.

It's a really easy to use package. To use the types and functions within, simply import:

import "github.com/ARaChn3/puffgo"

Run the following command in shell to get the module for your package:

$ go get github.com/ARaChn3/puffgo

A detailed information guide about the library, including documentation, usage, reference and examples, can be found on the project's wiki

The package's event-listener is defined as follows:

type EventListener struct {
	TriggerChannel chan bool
	Interval *time.Duration
	TriggerFunction func() bool
	TerminationChannel chan bool
	PID *int
}

The TriggerChannel works as a detection mechanism that allows the event-listener to check if the specified event has occoured.

The Interval field specifies the length of the intervals between checks for the specified Event. This Event is specified using the TriggerFunction field. The function returns a boolean true that will be passed into TriggerChannel when the event is detected.

The TerminationChannel acts as a stopping mechanism. When it detects a boolean true passed into it, the EventListener stops listening for the event.

The PID field specifies the pid for the process running the eventlistener.

Similarly, the type: LogicBomb makes use of the abovementioned type.

type LogicBomb struct {
	Listener *EventListener
	ExecutionFunction func()
	BombID string
	PID *int
}

The implementation of this type is pretty simple, we just take Listener that specifies an instance of EventListener used for detecting the event that triggers the logic-bomb. ExecutionFunction specifies a function that will be executed when the bomb is triggered.

BombID and PID are used to identify the bomb if there are multiple instances running. In the current release version: v1.1.0, LogicBomb cannot yet make use of these fields, but in future patches, it will be able to locate bombs running as subprocesses and terminate them if needed.

Here's some example uses for the bomb:

Example usage

package main

import (
	"fmt"
	"time"

	"github.com/ARaChn3/puffgo"
)

func main() {
	// interval is the interval between listening cycles of the event listener
	interval := 500 * time.Millisecond

	// First we need to declare an event-listener for the logic-bomb:
	// We can do so using the NewListener() method
	el := puffgo.NewListener(&interval, triggerFunction)

	// We can now create the logic-bomb using the NewBomb method:
	lb := puffgo.NewBomb(*el, executionFunction)

	// Next, we need to arm the bomb for it to go off when it detects
	// a signal from the event-listener
	lb.Arm()
}

// This can be anything.
// For the sake of simplicity, let it be a simple function that returns true
func triggerFunction() bool {
	return true
}

// This is the function which is callled when the bomb goes off.
// For this example, we'll just make it print something
func executionFunction() {
	fmt.Println("BOOOOM!!")
}

You may change executionFunction as needed. The same goes for triggerFunction. What's the result? It's a logic bomb that can be programmed to detect and execute virtually anything upon being triggered.

---

Why Did I Make This Project?

Well, to answer the question: "Why did you create it?"; the reason why I created this project is so that students beginning with malware analysis/development have a live project with access to the full source code for different types of malware. Logic-Bombs are not as big a deal.

It's often the case that if you can look at how something is implemented, it becomes very easy to understand how it works.

I'm always open to suggestions and improvements, so feel free to contact me regarding the same on LinkedIn or by my email: [e-mail] OR [e-mail]

I hope that my projects can help students understand how malware works better.

---

❗ Warning ❗

This project is strictly for educational/research purposes, any malicious activities that involve use of this repository is not the responsibility of the owner. ⚡ Ignore at your own risk! ⚡.

---