report

Documentation

Index

• Constants
• Variables
• func AddLocalBridge(name string) error
• func AddressIDAddresser(id string) net.IP
• func EndpointIDAddresser(id string) net.IP
• func ExtractHostID(m NodeMetadata) string
• func MakeAddressNodeID(hostID, address string) string
• func MakeAdjacencyID(srcNodeID string) string
• func MakeContainerNodeID(hostID, containerID string) string
• func MakeEdgeID(srcNodeID, dstNodeID string) string
• func MakeEndpointNodeID(hostID, address, port string) string
• func MakeHostNodeID(hostID string) string
• func MakeOverlayNodeID(peerName string) string
• func MakeProcessNodeID(hostID, pid string) string
• func ParseAdjacencyID(adjacencyID string) (string, bool)
• func ParseEdgeID(edgeID string) (srcNodeID, dstNodeID string, ok bool)
• func ParseEndpointNodeID(endpointNodeID string) (hostID, address, port string, ok bool)
• func ParseNodeID(nodeID string) (hostID string, remainder string, ok bool)
• type Adjacency
  • func (a *Adjacency) Merge(other Adjacency)
• type EdgeMetadata
  • func (m *EdgeMetadata) Flatten(other EdgeMetadata)
  • func (m *EdgeMetadata) Merge(other EdgeMetadata)
• type EdgeMetadatas
  • func (e *EdgeMetadatas) Merge(other EdgeMetadatas)
• type IDAddresser
• type IDList
  • func MakeIDList(ids ...string) IDList
  • func (a IDList) Add(ids ...string) IDList
  • func (a IDList) Contains(id string) bool
  • func (a IDList) Merge(b IDList) IDList
• type Interface
• type Networks
  • func (n Networks) Contains(ip net.IP) bool
• type NodeMetadata
  • func (nm NodeMetadata) Copy() NodeMetadata
  • func (nm NodeMetadata) Merge(other NodeMetadata) NodeMetadata
• type NodeMetadatas
  • func (m *NodeMetadatas) Merge(other NodeMetadatas)
• type Report
  • func MakeReport() Report
  • func (r *Report) Merge(other Report)
  • func (r Report) Topologies() []Topology
  • func (r Report) Validate() error
• type Topology
  • func NewTopology() Topology
  • func SelectAddress(r Report) Topology
  • func SelectContainer(r Report) Topology
  • func SelectContainerImage(r Report) Topology
  • func SelectEndpoint(r Report) Topology
  • func SelectHost(r Report) Topology
  • func SelectProcess(r Report) Topology
  • func (t *Topology) Merge(other Topology)
  • func (t Topology) Validate() error
• type TopologySelector

Constants

const (
	// ScopeDelim is a general-purpose delimiter used within node IDs to
	// separate different contextual scopes. Different topologies have
	// different key structures.
	ScopeDelim = ";"

	// EdgeDelim separates two node IDs when they need to exist in the same key.
	// Concretely, it separates node IDs in keys that represent edges.
	EdgeDelim = "|"
)

Delimiters are used to separate parts of node IDs, to guarantee uniqueness in particular contexts.

const (
	// HostNodeID is a metadata foreign key, linking a node in any topology to
	// a node in the host topology. That host node is the origin host, where
	// the node was originally detected.
	HostNodeID = "host_node_id"
)

const TheInternet = "theinternet"

TheInternet is used as a node ID to indicate a remote IP.

Variables

var (
	LocalNetworks       = Networks{}
	InterfaceByNameStub = func(name string) (Interface, error) {
		return net.InterfaceByName(name)
	}
)

Variables exposed for testing

Functions

func AddLocalBridge

func AddLocalBridge(name string) error

AddLocalBridge records the subnet address associated with the bridge name supplied, such that MakeAddressNodeID will scope addresses in this subnet as local.

func AddressIDAddresser

func AddressIDAddresser(id string) net.IP

AddressIDAddresser converts an address node ID to an IP.

func EndpointIDAddresser

func EndpointIDAddresser(id string) net.IP

EndpointIDAddresser converts an endpoint node ID to an IP.

func ExtractHostID

func ExtractHostID(m NodeMetadata) string

ExtractHostID extracts the host id from NodeMetadata

func MakeAddressNodeID

func MakeAddressNodeID(hostID, address string) string

MakeAddressNodeID produces an address node ID from its composite parts.

func MakeAdjacencyID

func MakeAdjacencyID(srcNodeID string) string

MakeAdjacencyID produces an adjacency ID from a node id.

func MakeContainerNodeID

func MakeContainerNodeID(hostID, containerID string) string

MakeContainerNodeID produces a container node ID from its composite parts.

func MakeEdgeID

func MakeEdgeID(srcNodeID, dstNodeID string) string

MakeEdgeID produces an edge ID from composite parts.

func MakeEndpointNodeID

func MakeEndpointNodeID(hostID, address, port string) string

MakeEndpointNodeID produces an endpoint node ID from its composite parts.

func MakeHostNodeID

func MakeHostNodeID(hostID string) string

MakeHostNodeID produces a host node ID from its composite parts.

func MakeOverlayNodeID

func MakeOverlayNodeID(peerName string) string

MakeOverlayNodeID produces an overlay topology node ID from a router peer's name, which is assumed to be globally unique.

func MakeProcessNodeID

func MakeProcessNodeID(hostID, pid string) string

MakeProcessNodeID produces a process node ID from its composite parts.

func ParseAdjacencyID

func ParseAdjacencyID(adjacencyID string) (string, bool)

ParseAdjacencyID produces a node ID from an adjancency ID.

func ParseEdgeID

func ParseEdgeID(edgeID string) (srcNodeID, dstNodeID string, ok bool)

ParseEdgeID splits an edge ID to its composite parts.

func ParseEndpointNodeID

func ParseEndpointNodeID(endpointNodeID string) (hostID, address, port string, ok bool)

ParseEndpointNodeID produces the host ID, address, and port and remainder (typically an address) from an endpoint node ID. Note that hostID may be blank.

func ParseNodeID

func ParseNodeID(nodeID string) (hostID string, remainder string, ok bool)

ParseNodeID produces the host ID and remainder (typically an address) from a node ID. Note that hostID may be blank.

Types

type Adjacency

type Adjacency map[string]IDList

Adjacency is an adjacency-list encoding of the topology. Keys are node IDs, as produced by the relevant MappingFunc for the topology.

func (*Adjacency) Merge

func (a *Adjacency) Merge(other Adjacency)

Merge merges another Adjacency list into the receiver.

type EdgeMetadata

type EdgeMetadata struct {
	WithBytes    bool `json:"with_bytes,omitempty"`
	BytesIngress uint `json:"bytes_ingress,omitempty"` // dst -> src
	BytesEgress  uint `json:"bytes_egress,omitempty"`  // src -> dst

	WithConnCountTCP bool `json:"with_conn_count_tcp,omitempty"`
	MaxConnCountTCP  uint `json:"max_conn_count_tcp,omitempty"`
}

EdgeMetadata describes a superset of the metadata that probes can conceivably (and usefully) collect about an edge between two nodes in any topology.

func (*EdgeMetadata) Flatten

func (m *EdgeMetadata) Flatten(other EdgeMetadata)

Flatten sums two EdgeMetadatas. Their windows should be the same duration; they should represent different edges at the same time.

func (*EdgeMetadata) Merge

func (m *EdgeMetadata) Merge(other EdgeMetadata)

Merge merges another EdgeMetadata into the receiver. The two edge metadatas should represent the same edge on different times.

type EdgeMetadatas

type EdgeMetadatas map[string]EdgeMetadata

EdgeMetadatas collect metadata about each edge in a topology. Keys are a concatenation of node IDs.

func (*EdgeMetadatas) Merge

func (e *EdgeMetadatas) Merge(other EdgeMetadatas)

Merge merges another EdgeMetadatas into the receiver. If other is from another probe this is the union of both metadatas. Keys present in both are summed.

type IDAddresser

type IDAddresser func(string) net.IP

IDAddresser tries to convert a node ID to a net.IP, if possible.

type IDList

type IDList []string

IDList is a list of string IDs, which are always sorted and unique.

func MakeIDList

func MakeIDList(ids ...string) IDList

MakeIDList makes a new IDList.

func (IDList) Add

func (a IDList) Add(ids ...string) IDList

Add is the only correct way to add ids to an IDList.

func (IDList) Contains

func (a IDList) Contains(id string) bool

Contains returns true if id is in the list.

func (IDList) Merge

func (a IDList) Merge(b IDList) IDList

Merge all elements from a and b into a new list

type Interface

type Interface interface {
	Addrs() ([]net.Addr, error)
}

Interface is exported for testing.

type Networks

type Networks []*net.IPNet

Networks represent a set of subnets

func (Networks) Contains

func (n Networks) Contains(ip net.IP) bool

Contains returns true if IP is in Networks.

type NodeMetadata

type NodeMetadata map[string]string

NodeMetadata describes a superset of the metadata that probes can collect about a given node in a given topology. Right now it's a weakly-typed map, which should probably change (see comment on type MapFunc).

func (NodeMetadata) Copy

func (nm NodeMetadata) Copy() NodeMetadata

Copy returns a value copy, useful for tests.

func (NodeMetadata) Merge

func (nm NodeMetadata) Merge(other NodeMetadata) NodeMetadata

Merge merges two node metadata maps together. In case of conflict, the other (right-hand) side wins. Always reassign the result of merge to the destination. Merge is defined on the value-type, but node metadata map is itself a reference type, so if you want to maintain immutability, use copy.

type NodeMetadatas

type NodeMetadatas map[string]NodeMetadata

NodeMetadatas collect metadata about each node in a topology. Keys are node IDs.

func (*NodeMetadatas) Merge

func (m *NodeMetadatas) Merge(other NodeMetadatas)

Merge merges another NodeMetadatas into the receiver.

type Report

type Report struct {
	// Endpoint nodes are individual (address, port) tuples on each host.
	// They come from inspecting active connections and can (theoretically)
	// be traced back to a process. Edges are present.
	Endpoint Topology

	// Address nodes are addresses (e.g. ifconfig) on each host. Certain
	// information may be present in this topology that can't be mapped to
	// endpoints (e.g. ICMP). Edges are present.
	Address Topology

	// Process nodes are processes on each host. Edges are not present.
	Process Topology

	// Container nodes represent all Docker containers on hosts running probes.
	// Metadata includes things like containter id, name, image id etc.
	// Edges are not present.
	Container Topology

	// ContainerImages nodes represent all Docker containers images on
	// hosts running probes. Metadata includes things like image id, name etc.
	// Edges are not present.
	ContainerImage Topology

	// Host nodes are physical hosts that run probes. Metadata includes things
	// like operating system, load, etc. The information is scraped by the
	// probes with each published report. Edges are not present.
	Host Topology

	// Overlay nodes are active peers in any software-defined network that's
	// overlaid on the infrastructure. The information is scraped by polling
	// their status endpoints. Edges could be present, but aren't currently.
	Overlay Topology
}

Report is the core data type. It's produced by probes, and consumed and stored by apps. It's composed of multiple topologies, each representing a different (related, but not equivalent) view of the network.

func MakeReport

func MakeReport() Report

MakeReport makes a clean report, ready to Merge() other reports into.

func (*Report) Merge

func (r *Report) Merge(other Report)

Merge merges another Report into the receiver.

func (Report) Topologies

func (r Report) Topologies() []Topology

Topologies returns a slice of Topologies in this report

func (Report) Validate

func (r Report) Validate() error

Validate checks the report for various inconsistencies.

type Topology

type Topology struct {
	Adjacency
	EdgeMetadatas
	NodeMetadatas
}

Topology describes a specific view of a network. It consists of nodes and edges, represented by Adjacency, and metadata about those nodes and edges, represented by EdgeMetadatas and NodeMetadatas respectively.

func NewTopology

func NewTopology() Topology

NewTopology gives you a Topology.

func SelectAddress

func SelectAddress(r Report) Topology

SelectAddress selects the address topology.

func SelectContainer

func SelectContainer(r Report) Topology

SelectContainer selects the container topology.

func SelectContainerImage

func SelectContainerImage(r Report) Topology

SelectContainerImage selects the container image topology.

func SelectEndpoint

func SelectEndpoint(r Report) Topology

SelectEndpoint selects the endpoint topology.

func SelectHost

func SelectHost(r Report) Topology

SelectHost selects the address topology.

func SelectProcess

func SelectProcess(r Report) Topology

SelectProcess selects the process topology.

func (*Topology) Merge

func (t *Topology) Merge(other Topology)

Merge merges another Topology into the receiver.

func (Topology) Validate

func (t Topology) Validate() error

Validate checks the topology for various inconsistencies.

type TopologySelector

type TopologySelector func(r Report) Topology

TopologySelector selects a single topology from a report.