notify

Documentation

Overview

Package notify sends findings to somewhere outside this machine.

It is the only part of LAN Sheriff that does so, and the only part that can ever cause information about a network to reach a third party. Everything here is shaped by that:

• **Off unless configured.** No target has a default. An unset target is not a disabled feature, it is an absent one.
• **The payload is deliberately thin.** A notification says which rule fired and what it fired about, and nothing else. It does not carry the organization, the address, the interval, or the counts, those live in the dashboard, behind the user's own authentication. A push notification travels through somebody else's server and often ends up on a lock screen.
• **It cannot delay observation.** Sending happens on its own goroutine with a short timeout; a webhook that hangs must never slow down capture.
• **It fails quietly and does not retry.** A missed notification is a small loss. A retry storm against somebody's server, from a tool that is supposed to be unobtrusive, is a much larger one.

Index

• func Message(f Finding) string
• type Discord
  • func NewDiscord(raw string) (*Discord, error)
  • func (Discord) Name() string
  • func (d Discord) Send(ctx context.Context, f Finding) error
• type Finding
• type Notifier
  • func (n *Notifier) Enabled() bool
  • func (n *Notifier) Notify(ctx context.Context, f Finding)
• type Ntfy
  • func NewNtfy(raw string) (*Ntfy, error)
  • func (Ntfy) Name() string
  • func (n Ntfy) Send(ctx context.Context, f Finding) error
• type Slack
  • func NewSlack(raw string) (*Slack, error)
  • func (Slack) Name() string
  • func (s Slack) Send(ctx context.Context, f Finding) error
• type Target
• type Webhook
  • func NewWebhook(raw string) (*Webhook, error)
  • func (Webhook) Name() string
  • func (w Webhook) Send(ctx context.Context, f Finding) error

Functions

func Message

func Message(f Finding) string

Message is the human-readable line a target sends.

One sentence, naming the rule and the subject. Any more would be putting network detail on somebody's lock screen.

Types

type Discord

type Discord struct{ URL string }

Discord posts to an incoming webhook.

func NewDiscord

func NewDiscord(raw string) (*Discord, error)

func (Discord) Name

func (Discord) Name() string

func (Discord) Send

func (d Discord) Send(ctx context.Context, f Finding) error

type Finding

type Finding struct {
	// Rule is the stable code, such as "beaconing".
	Rule string
	// Subject is the device's display name, or its address if it has no name.
	Subject string
	// Score is the finding's weight, so a recipient can filter.
	Score float64
	At    time.Time
}

Finding is the thin shape a notification carries.

Deliberately not the store's Finding: this is what leaves the machine, and it should be obvious from the type alone exactly how much that is.

type Notifier

type Notifier struct {
	Targets []Target
	// MinScore suppresses notifications below a threshold, so a channel can be
	// set to carry only what matters.
	MinScore float64
	// contains filtered or unexported fields
}

Notifier fans a finding out to every configured target.

func (*Notifier) Enabled

func (n *Notifier) Enabled() bool

Enabled reports whether anything is configured. Used to avoid doing work when nothing would come of it.

func (*Notifier) Notify

func (n *Notifier) Notify(ctx context.Context, f Finding)

Notify sends a finding to every target, subject to the rate limit.

Returns immediately: delivery happens in the background, because nothing about observing a network should wait on somebody else's server.

type Ntfy

type Ntfy struct{ URL string }

Ntfy posts a plain-text line to an ntfy topic.

func NewNtfy

func NewNtfy(raw string) (*Ntfy, error)

func (Ntfy) Name

func (Ntfy) Name() string

func (Ntfy) Send

func (n Ntfy) Send(ctx context.Context, f Finding) error

type Slack

type Slack struct{ URL string }

Slack posts to an incoming webhook.

func NewSlack

func NewSlack(raw string) (*Slack, error)

func (Slack) Name

func (Slack) Name() string

func (Slack) Send

func (s Slack) Send(ctx context.Context, f Finding) error

type Target

type Target interface {
	Name() string
	Send(ctx context.Context, f Finding) error
}

Target is somewhere notifications go.

type Webhook

type Webhook struct{ URL string }

Webhook posts a small JSON object to any endpoint.

The general case, and the one to prefer: it goes wherever the user chooses rather than through a third party's infrastructure.

func NewWebhook

func NewWebhook(raw string) (*Webhook, error)

func (Webhook) Name

func (Webhook) Name() string

func (Webhook) Send

func (w Webhook) Send(ctx context.Context, f Finding) error