types

type Capabilities struct {
	Mode string `json:"mode"` // "deputy" | "patrol"

	// Available reports whether the source can run at all right now.
	Available bool `json:"available"`

	HostEgress         bool `json:"host_egress"`
	OtherDevices       bool `json:"other_devices"`
	ProcessAttribution bool `json:"process_attribution"`
	ByteCounts         bool `json:"byte_counts"`
	DNSFeed            bool `json:"dns_feed"`
	DeviceInventory    bool `json:"device_inventory"`

	// Topology is how much of the network graph this source can draw:
	// "none", "host" (this host and its peers) or "lan" (everything).
	Topology string `json:"topology"`

	// Hint is the single sentence explaining what is missing and what enabling
	// more would add. Empty when nothing is missing.
	//
	// This is English prose, for API consumers reading the JSON directly. The
	// dashboard does not display it: it displays the translation of HintCode.
	Hint string `json:"hint,omitempty"`

	// HintCode identifies the hint so the UI can translate it.
	//
	// Backend-generated prose cannot be localized, the server has no idea what
	// language the viewer reads, so anything destined for a human travels as a
	// stable code and is rendered on the client.
	HintCode string `json:"hint_code,omitempty"`

	// EnableCmd is the one command that would unlock this source, when it is
	// unavailable for want of privilege.
	EnableCmd string `json:"enable_cmd,omitempty"`
}

type Conn struct {
	Src   netip.AddrPort
	Dst   netip.AddrPort
	Proto Proto

	// State is the transport state where the source exposes one ("ESTABLISHED",
	// "SYN_SENT", ...). Empty for connectionless observations.
	State string

	// DeviceID is the device this connection originated from. In Deputy Mode
	// that is always the local host.
	DeviceID string

	PID         int32
	Process     string // short name, e.g. "Google Chrome"
	ProcessPath string // full executable path, when the OS will tell us

	BytesOut uint64
	BytesIn  uint64

	// Listening marks a socket that is accepting connections rather than being
	// one. These are not flows, but they tell the normalizer which local ports
	// are servers, which is how inbound connections are recognized.
	Listening bool
}

type DNSEvent struct {
	ID       int64     `json:"id"`
	TS       time.Time `json:"ts"`
	DeviceID string    `json:"device_id,omitempty"`
	Process  string    `json:"process,omitempty"`
	QName    string    `json:"qname"`
	QType    string    `json:"qtype,omitempty"`
	Answers  []string  `json:"answers,omitempty"`
	RespMS   int       `json:"resp_ms,omitempty"`
	Flagged  string    `json:"flagged,omitempty"`
}

type Device struct {
	ID         string    `json:"id"`
	MAC        string    `json:"mac,omitempty"`
	IP         string    `json:"ip,omitempty"`
	Hostname   string    `json:"hostname,omitempty"`
	Vendor     string    `json:"vendor,omitempty"`
	DeviceType string    `json:"device_type,omitempty"`
	Label      string    `json:"label,omitempty"`
	Trust      string    `json:"trust"`
	FirstSeen  time.Time `json:"first_seen"`
	LastSeen   time.Time `json:"last_seen"`
	Online     bool      `json:"online"`
	Suspicion  float64   `json:"suspicion"`
	IsSelf     bool      `json:"is_self"`
	// Name is what the device calls itself; Label is what the user called it.
	// Kept apart so discovery can never overwrite a name a person chose.
	Name  string `json:"name,omitempty"`
	Model string `json:"model,omitempty"`
	// MACRandomized marks a device whose hardware address is generated. It is
	// still a usable identity on this network, but it can rotate, so the UI says
	// so rather than presenting it as a permanent address.
	MACRandomized bool            `json:"mac_randomized,omitempty"`
	Addresses     []DeviceAddress `json:"addresses,omitempty"`
	Services      []DeviceService `json:"services,omitempty"`
	Notes         string          `json:"notes,omitempty"`
	// TypeReason names the evidence behind DeviceType, as a stable code the
	// dashboard translates. Carried so the UI can explain a classification
	// instead of asking the user to trust it.
	TypeReason string `json:"type_reason,omitempty"`
	// TypeLocked marks a type the user set by hand. Re-inference skips these.
	TypeLocked bool `json:"type_locked,omitempty"`
}

type DeviceAddress struct {
	IP        string    `json:"ip"`
	FirstSeen time.Time `json:"first_seen"`
	LastSeen  time.Time `json:"last_seen"`
}

type DeviceService struct {
	Service string `json:"service"`
	// Source names how it was learned: "mdns", "ssdp" or "scan".
	Source    string    `json:"source"`
	FirstSeen time.Time `json:"first_seen"`
	LastSeen  time.Time `json:"last_seen"`
}

type Direction string

type Endpoint struct {
	IP          string     `json:"ip"`
	RDNS        string     `json:"rdns,omitempty"`
	ASN         int        `json:"asn,omitempty"`
	Org         string     `json:"org,omitempty"`
	Country     string     `json:"country,omitempty"` // ISO 3166-1 alpha-2
	CountryName string     `json:"country_name,omitempty"`
	City        string     `json:"city,omitempty"`
	Lat         float64    `json:"lat,omitempty"`
	Lon         float64    `json:"lon,omitempty"`
	IsInternal  bool       `json:"is_internal"`
	FirstSeen   time.Time  `json:"first_seen"`
	LastSeen    time.Time  `json:"last_seen"`
	EnrichedAt  *time.Time `json:"enriched_at,omitempty"`
}

type EventKind string

type Flow struct {
	ID       int64     `json:"id"`
	Key      FlowKey   `json:"-"`
	TSStart  time.Time `json:"ts_start"`
	TSLast   time.Time `json:"ts_last"`
	DeviceID string    `json:"device_id,omitempty"`
	Process  string    `json:"process,omitempty"`
	PID      int32     `json:"pid,omitempty"`

	SrcIP   string `json:"src_ip"`
	SrcPort uint16 `json:"src_port"`
	DstIP   string `json:"dst_ip"`
	DstPort uint16 `json:"dst_port"`
	Proto   Proto  `json:"proto"`

	BytesOut  uint64    `json:"bytes_out"`
	BytesIn   uint64    `json:"bytes_in"`
	Direction Direction `json:"direction"`
	Suspicion float64   `json:"suspicion"`

	// Active reports whether the flow was still open at TSLast.
	Active bool `json:"active"`
	// Established reports whether this connection ever reached a state in which
	// data could flow.
	//
	// A socket still connecting, or one that was refused, is not evidence that
	// anything is listening on the other end, a distinction that matters
	// because the on-demand port check knocks on doors that do not open, and
	// those knocks are visible to the socket sampler like any other connection.
	Established bool `json:"established,omitempty"`
}

type FlowKey struct {
	Src      netip.AddrPort
	Dst      netip.AddrPort
	Proto    Proto
	DeviceID string
}

type Platform struct {
	OS      string `json:"os"`   // runtime.GOOS
	Arch    string `json:"arch"` // runtime.GOARCH
	Version string `json:"version"`
	Build   string `json:"build"` // commits reachable from this build

	// CaptureBuilt reports whether packet capture is compiled in. This is the
	// difference between the standard and portable downloads, and it is not
	// inferable from the platform: both are published for most of them.
	CaptureBuilt bool `json:"capture_built"`

	// CapturePublished reports whether a capture build exists for this
	// platform at all. False for FreeBSD, 32-bit ARM and Windows on ARM, where
	// telling somebody to download the standard build would name a file that
	// was never built.
	CapturePublished bool `json:"capture_published"`

	// Distributed reports whether this binary was released rather than built
	// from a source tree. It decides whether advice may name `make`.
	Distributed bool `json:"distributed"`

	DataDir string `json:"data_dir"`
	DBPath  string `json:"db_path"`
}

type Proto string

type RawEvent struct {
	Kind   EventKind
	Source string
	TS     time.Time

	Snapshot []Conn    // KindConnSnapshot
	Conn     *Conn     // KindConnDelta
	DNS      *DNSEvent // KindDNS
	Device   *Device   // KindDevice
	// Sighting carries identity a capture source learned about a device, as
	// distinct from traffic it observed. DHCP is the source of these: a device
	// asking for an address states its own name and often its vendor.
	Sighting *Sighting // KindSighting
}

type Sighting struct {
	MAC      string
	IP       string
	Hostname string
	// Name is a friendly name the device advertised, kept apart from the user's
	// own label so discovery can never overwrite a name a person chose.
	Name     string
	Model    string
	Vendor   string
	Services []string
	IsSelf   bool
	// Source names the discovery mechanism, recorded against services so the UI
	// can say how something was learned.
	Source string
	SeenAt time.Time
	// PreferredID is used as the device ID if this sighting creates a new
	// device, and ignored if it matches an existing one.
	//
	// It exists for this machine. The capture pipeline tags every flow with a
	// device ID derived from the local hardware address, and it must be able to
	// compute that ID before the database is open. Letting the sighting carry it
	// means discovery and capture agree on one record instead of each creating
	// their own.
	PreferredID string
}