detect

type Beacon struct {
	// contains filtered or unexported fields
}

type BeaconConfig struct {
	// MinConnections is how many connections must be observed before a verdict
	// is possible. Too low and ordinary repeated requests look periodic; the
	// default of 8 is roughly where random traffic stops producing low
	// dispersion by chance.
	MinConnections int
	// MinInterval and MaxInterval bound the beacon periods considered. Below
	// MinInterval we are looking at a chatty application, above MaxInterval
	// there is not enough evidence in a capture to call it.
	MinInterval time.Duration
	MaxInterval time.Duration
	// Threshold is the score in [0,1] at or above which an alert fires.
	Threshold float64
	// History is how far back connection times are retained.
	History time.Duration
	// MaxTracked bounds the number of (src,dst,port) triples tracked.
	MaxTracked int
}

type Config struct {
	// HomeNets defines which addresses count as "inside". Direction matters
	// enormously for detection: 500 MB leaving the network is exfiltration,
	// 500 MB arriving is a software update.
	HomeNets []netip.Prefix

	// MaxSuppressionEntries bounds how many distinct findings the engine
	// remembers for duplicate suppression. Zero selects the default.
	MaxSuppressionEntries int
	// AlertCooldown is the minimum gap between two identical alerts. Without
	// it a host beaconing every 30 seconds would produce an alert on every
	// tick forever, and the analyst would mute the tool by the end of the day.
	AlertCooldown time.Duration

	// Policy is consulted for every alert before it is emitted. Returning
	// false drops the alert; the alert may also be modified in place.
	//
	// This is the seam the YAML rule pack plugs into — disabling a rule,
	// exempting a known-good host, overriding a severity, or attaching extra
	// ATT&CK techniques. The engine deliberately knows nothing about rule
	// files: detection logic and deployment policy are different concerns with
	// different rates of change, and a detector that had to parse YAML would
	// be markedly harder to test.
	//
	// Nil means allow everything.
	Policy func(*model.Alert) bool
}

type Context struct {
	Cfg Config
	Now time.Time
	// contains filtered or unexported fields
}

type DNSTunnel struct {
	// contains filtered or unexported fields
}

type DNSTunnelConfig struct {
	MinQueries     int           // evidence required before scoring
	Threshold      float64       // score in [0,1] at which an alert fires
	History        time.Duration // how long a domain's evidence is retained
	MaxTracked     int           // bound on tracked (client, domain) pairs
	MaxUniqueNames int           // bound on the per-domain unique-name set
}

type Detector interface {
	// Name is the stable identifier used in alerts and configuration.
	Name() string
}

type Engine struct {
	// contains filtered or unexported fields
}

type Exfil struct {
	// contains filtered or unexported fields
}

type ExfilConfig struct {
	// MinBytesOut is the floor below which a transfer is not worth reporting
	// regardless of how lopsided it is.
	MinBytesOut uint64
	// MinRatio is how many times more data must leave than arrive. Normal
	// client traffic is heavily inbound — you download far more than you
	// upload — so inverting that ratio is the signal.
	MinRatio float64
}

type FlowDetector interface {
	Detector
	OnFlowClosed(c *Context, f *model.Flow)
}

type Inventory struct {
	// contains filtered or unexported fields
}

type InventoryConfig struct {
	// MinHostsForRarity is how many internal hosts must be known before a
	// "only one host uses this TLS stack" claim is meaningful. On a network of
	// three machines, every fingerprint is rare.
	MinHostsForRarity int
	// MinFingerprintsForRarity is the equivalent baseline for fingerprints.
	MinFingerprintsForRarity int
	// MinSharedFingerprints is how many fingerprints must be in use by two or
	// more hosts before any fingerprint may be called rare.
	//
	// This is the guard that makes the detector honest. Early in a capture
	// every host has contributed exactly one fingerprint, so *everything* looks
	// unique and the detector would indict the entire network. Requiring
	// evidence that some stacks are genuinely shared proves a baseline exists
	// before anything is measured against it.
	MinSharedFingerprints int
	// MinObservations is how many flows a fingerprint must appear on before its
	// rarity counts. One connection from one host is not evidence of anything.
	MinObservations int
	// MinAge is how long a fingerprint must have been known before it may be
	// called rare.
	//
	// Without this the detector reports the first host to use any new stack.
	// A browser that prefers HTTP/3 produces a fingerprint nobody has yet, and
	// for the few minutes before a second machine happens to use it, it is
	// indistinguishable from an implant. Rarity is a claim about the network
	// over time, so it needs time to be true.
	MinAge time.Duration
	// MaxDevices bounds the inventory.
	MaxDevices int
	// MaxFingerprints bounds the set of distinct JA4s tracked.
	//
	// Sibling to MaxDevices, and it was missing. The device map was capped
	// while the fingerprint map beside it grew without limit, which is the
	// wrong way round for a daemon: a network can only hold so many hosts,
	// but a host that varies its TLS stack, or an attacker who chooses to,
	// can mint fingerprints indefinitely.
	MaxFingerprints int
	// MaxJA4sPerDevice bounds the per-device fingerprint list.
	//
	// The list is display detail, and it is scanned linearly on the packet
	// path, so an unbounded one costs time as well as memory.
	MaxJA4sPerDevice int
	// SilenceNewDevice suppresses the informational new-host alert. Phrased as
	// an opt-out so the zero value behaves like the documented default.
	SilenceNewDevice bool
}

type PacketDetector interface {
	Detector
	OnPacket(c *Context, p *model.Packet, f *model.Flow, isNew bool)
}

type Scan struct {
	// contains filtered or unexported fields
}

type ScanConfig struct {
	// VerticalPorts is how many distinct ports on one target constitute a
	// vertical scan ("what is this host running?").
	VerticalPorts int
	// HorizontalHosts is how many distinct targets on one port constitute a
	// horizontal sweep ("who else runs SMB?").
	HorizontalHosts int
	// Window is the sliding period over which evidence accumulates. An
	// observation older than this stops counting towards either threshold.
	Window time.Duration
	// MaxAnsweredRatio is the largest fraction of probes that may have been
	// answered for the source to still be called a scanner.
	//
	// This is what separates a scanner from a busy client, and without it the
	// cardinality thresholds alone accuse any host that talks to enough peers.
	// A browser knows the port it wants and nearly everything it opens
	// succeeds; a scanner is asking a question and most of the answers are no.
	MaxAnsweredRatio float64
	// MaxTracked bounds the number of source hosts tracked at once.
	MaxTracked int
	// MaxPortsPerTarget and MaxTargetsPerPort bound per-source memory. A scan
	// is by definition high-cardinality, so these caps are what stop the
	// detector from becoming the denial of service it is meant to detect.
	MaxPortsPerTarget int
	MaxTargetsPerPort int
}

type Stats struct {
	Emitted    uint64 `json:"emitted"`
	Suppressed uint64 `json:"suppressed"`
	// Filtered counts alerts dropped by rule policy: a disabled rule or a
	// matching exception. Reported separately from Suppressed so an operator
	// can tell "the tool is quiet" from "I told the tool to be quiet".
	Filtered  uint64 `json:"filtered"`
	Detectors int    `json:"detectors"`
}

type TickDetector interface {
	Detector
	OnTick(c *Context, now time.Time)
}