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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CategoryCounts ¶
CategoryCounts returns a map from Category to the number of registered modules in that category.
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" CategoryEvasion Category = "evasion" )
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 ByCategory ¶
ByCategory returns all registered modules in the given category, sorted by name.
type ModuleInfo ¶
type Outcome ¶ added in v0.4.0
type Outcome string
Outcome describes what happened to the action a module attempted, which is a different question from whether macnoise itself worked. A TCC probe that is refused is expected, valid telemetry rather than a fault, and recording it the same way as a broken tool leaves a consumer no way to tell the two apart short of parsing the message text.
const ( // OutcomeExecuted means the action ran and did what the module claims. OutcomeExecuted Outcome = "executed" // OutcomeDenied means the action ran and the environment refused it. OutcomeDenied Outcome = "denied" // OutcomeIndeterminate means the action ran but no conclusion can be // drawn from it: the target was absent, or the technique leaves no // evidence either way. OutcomeIndeterminate Outcome = "indeterminate" // OutcomeError means macnoise itself failed to carry the action out. OutcomeError Outcome = "error" )
Outcome values. Everything except OutcomeError describes a working macnoise.
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 Privilege ¶
type Privilege string
Privilege represents the privilege level required to run a module.
type ProcessContext ¶
type ProcessContext struct {
PID int `json:"pid"`
PPID int `json:"ppid"`
ParentName string `json:"parent_name,omitempty"`
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"`
// Outcome is left empty by NewEvent and set only by modules that need to
// say something Success cannot express. It is resolved to a concrete value
// at the output boundary, so emitted records always carry one.
Outcome Outcome `json:"outcome"`
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.
func (TelemetryEvent) ResolvedOutcome ¶ added in v0.4.0
func (ev TelemetryEvent) ResolvedOutcome() Outcome
ResolvedOutcome returns ev.Outcome, falling back to Success for the majority of events that never set one. It is the single definition of how the two fields relate, so an outcome-aware consumer and a Success-only consumer can never read the same event differently.
Source Files