module

Documentation

Overview

Package module defines the core Generator interface and supporting types used by all MacNoise telemetry modules. Every module implements Generator and self-registers via init() so the runner can discover and execute it.

Index

• func CategoryCounts() map[Category]int
• func Register(g Generator)
• type Category
  • func AllCategories() []Category
• type EventEmitter
• type Generator
  • func All() []Generator
  • func ByCategory(cat Category) []Generator
  • func ByTag(tag string) []Generator
  • func Get(name string) (Generator, bool)
• type MITRE
• type ModuleInfo
• type ParamSpec
• type Params
  • func (p Params) Get(key, defaultVal string) string
• type Privilege
• type ProcessContext
• type TelemetryEvent

Functions

func CategoryCounts

func CategoryCounts() map[Category]int

CategoryCounts returns a map from Category to the number of registered modules in that category.

func Register

func Register(g Generator)

Register adds g to the global module registry. It panics on duplicate names.

Types

type Category

type Category string

Category is the telemetry domain that a module belongs to.

const (
	CategoryNetwork          Category = "network"
	CategoryProcess          Category = "process"
	CategoryFile             Category = "file"
	CategoryTCC              Category = "tcc"
	CategoryEndpointSecurity Category = "endpoint_security"
	CategoryService          Category = "service"
	CategoryPlist            Category = "plist"
	CategoryXPC              Category = "xpc"
)

Category constants for each supported telemetry domain.

func AllCategories

func AllCategories() []Category

AllCategories returns a slice containing every known Category value.

type EventEmitter

type EventEmitter func(TelemetryEvent)

EventEmitter is a callback that receives a telemetry event from a module.

type Generator

type Generator interface {
	Info() ModuleInfo
	ParamSpecs() []ParamSpec
	CheckPrereqs() error
	Generate(ctx context.Context, params Params, emit EventEmitter) error
	DryRun(params Params) []string
	Cleanup() error
}

Generator is implemented by every MacNoise module and drives the runner lifecycle.

func All

func All() []Generator

All returns every registered module sorted by name.

func ByCategory

func ByCategory(cat Category) []Generator

ByCategory returns all registered modules in the given category, sorted by name.

func ByTag

func ByTag(tag string) []Generator

ByTag returns all registered modules that carry the given tag, sorted by name.

func Get

func Get(name string) (Generator, bool)

Get looks up a module by name, returning it and a found boolean.

type MITRE

type MITRE struct {
	Technique string
	SubTech   string
	Name      string
}

MITRE holds a single ATT&CK technique reference associated with a module.

type ModuleInfo

type ModuleInfo struct {
	Name        string
	Description string
	Category    Category
	Tags        []string
	Privileges  Privilege
	MITRE       []MITRE
	Author      string
	MinMacOS    string
}

type ParamSpec

type ParamSpec struct {
	Name         string
	Description  string
	Required     bool
	DefaultValue string
	Example      string
}

ParamSpec describes a single named parameter accepted by a module.

type Params

type Params map[string]string

Params is the key-value map of runtime parameters passed to a module.

func (Params) Get

func (p Params) Get(key, defaultVal string) string

Get returns the value for key, or defaultVal if key is absent or empty.

type Privilege

type Privilege string

Privilege represents the privilege level required to run a module.

const (
	PrivilegeNone  Privilege = "none"
	PrivilegeRoot  Privilege = "root"
	PrivilegeTCC   Privilege = "tcc"
	PrivilegeAdmin Privilege = "admin"
)

Privilege level constants used in ModuleInfo.

type ProcessContext

type ProcessContext struct {
	PID        int    `json:"pid"`
	PPID       int    `json:"ppid"`
	Executable string `json:"executable"`
	Username   string `json:"username"`
}

ProcessContext captures identifying information about the MacNoise process itself.

type TelemetryEvent

type TelemetryEvent struct {
	SchemaVersion  string         `json:"schema_version"`
	Timestamp      time.Time      `json:"timestamp"`
	Module         string         `json:"module"`
	Category       string         `json:"category"`
	EventType      string         `json:"event_type"`
	Success        bool           `json:"success"`
	Message        string         `json:"message"`
	Details        map[string]any `json:"details,omitempty"`
	Error          string         `json:"error,omitempty"`
	MITRE          []MITRE        `json:"mitre,omitempty"`
	ProcessContext ProcessContext `json:"process_context"`
}

TelemetryEvent is the structured record emitted by a module for each action it performs.