mapper

package
v1.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 20, 2026 License: Apache-2.0 Imports: 30 Imported by: 0

README

ServiceRadar Network Mapper

UBNT

This mapper is designed to work with UBNT (Ubiquiti Networks) devices, specifically for integrating with their UniFi network controllers. It allows you to manage and monitor multiple UniFi controllers by providing their API details.

Configuration Example:

{
  "unifi_apis": [
    {
      "name": "Main Controller",
      "base_url": "https://192.168.1.1/proxy/network/integration/v1",
      "api_key": "NYlYuZSN591uSBBGLL8t4GM8j5436cxd"
    },
    {
      "name": "Secondary Controller",
      "base_url": "https://192.168.2.1/proxy/network/integration/v1",
      "api_key": "ABcDeFgHiJkLmNoPqRsTuVwXyZ123456"
    }
  ]
}

Documentation

Overview

Package mapper pkg/discovery/discovery.go

Package mapper pkg/mapper/grpc.go

Package mapper pkg/discovery/interfaces.go

Package mapper pkg/mapper/mapper_agent_service.go

Package mapper is a generated GoMock package.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrDiscoveryStopTimeout occurs when the discovery engine fails to stop within the timeout period.
	ErrDiscoveryStopTimeout     = errors.New("discovery engine stop timed out")
	ErrDiscoveryAtCapacity      = errors.New("discovery engine at capacity, please try again later")
	ErrDiscoveryShuttingDown    = errors.New("discovery engine is shutting down")
	ErrDiscoveryWorkersBusy     = errors.New("discovery engine at capacity (workers busy), please try again later")
	ErrDiscoveryJobNotFound     = errors.New("discovery job not found")
	ErrDiscoveryJobStillActive  = errors.New("discovery job is still active")
	ErrDiscoveryJobNotCompleted = errors.New("discovery job not found or not completed")
	ErrDiscoveryJobNotActive    = errors.New("discovery job not found or not active")
	ErrConfigNil                = errors.New("config cannot be nil")
	ErrInvalidWorkers           = errors.New("workers must be greater than 0")
	ErrInvalidMaxActiveJobs     = errors.New("maxActiveJobs must be greater than 0")
	ErrUnsupportedSNMPVersion   = errors.New("unsupported SNMP version")

	ErrDatabaseServiceRequired = errors.New("database service is required")
	ErrSNMPGetFailed           = errors.New("SNMP GET failed")
	ErrSNMPError               = errors.New("SNMP error occurred")
	ErrNoSNMPDataReturned      = errors.New("no SNMP data returned")
	ErrNoLLDPNeighborsFound    = errors.New("no LLDP neighbors found")
	ErrNoCDPNeighborsFound     = errors.New("no CDP neighbors found")
	ErrNoICMPResponse          = errors.New("no ICMP response")
	ErrInt32RangeExceeded      = errors.New("value exceeds int32 range")
	ErrFoundMACStoppingWalk    = errors.New("found MAC, stopping walk")
	ErrConnectionTimeout       = errors.New("connection timeout")

	// UniFi/UBNT specific errors
	ErrUniFiSitesRequestFailed   = errors.New("UniFi sites request failed")
	ErrNoUniFiSitesFound         = errors.New("no UniFi sites found")
	ErrUniFiDevicesRequestFailed = errors.New("UniFi devices request failed")
	ErrUniFiDeviceDetailsFailed  = errors.New("UniFi device details request failed")
	ErrNoUniFiDevicesFound       = errors.New("no UniFi devices found; all API attempts failed")
	ErrSNMPQueryTimeout          = errors.New("SNMP query timeout")

	// ErrNoSeedsProvided occurs when no discovery seeds are provided for a job.
	ErrNoSeedsProvided         = errors.New("no seeds provided")
	ErrJobQueueFull            = errors.New("job queue full, cannot enqueue discovery job")
	ErrScheduledJobMissingName = errors.New("scheduled job missing name")
	ErrScheduledJobNotFound    = errors.New("scheduled job not found")
	ErrJobHasNoSeeds           = errors.New("job has no seeds")
	ErrJobMissingType          = errors.New("job missing type")
	ErrJobInvalidType          = errors.New("job has invalid type")
	ErrJobInvalidConcurrency   = errors.New("job has invalid concurrency")
	ErrJobInvalidRetries       = errors.New("job has invalid retries")
)
View Source 
var (
	// ErrNoUniFiNeighborsFound indicates that no neighboring devices were found during UniFi discovery.
	ErrNoUniFiNeighborsFound        = errors.New("no UniFi neighbors found")
	ErrUniFiPayloadDriftQuarantined = errors.New("unifi payload drift quarantined")
)

Functions

func GenerateDeviceID 

func GenerateDeviceID(mac string) string

GenerateDeviceID creates a device identifier from a MAC address.

func GenerateDeviceIDFromIP 

func GenerateDeviceIDFromIP(ip string) string

GenerateDeviceIDFromIP creates a device identifier from an IP address when MAC is not available.

func NormalizeMAC 

func NormalizeMAC(mac string) string

NormalizeMAC normalizes a MAC address for consistent formatting

Types

type AgentService 

type AgentService struct {
	proto.UnimplementedAgentServiceServer
	// contains filtered or unexported fields
}

AgentService implements the proto.AgentServiceServer for the mapper's own health.

func NewAgentService 

func NewAgentService(engine *DiscoveryEngine) *AgentService

NewAgentService creates a new AgentService.

func (*AgentService) GetResults 

func (s *AgentService) GetResults(_ context.Context, req *proto.ResultsRequest) (*proto.ResultsResponse, error)

GetResults implements the AgentService GetResults method. Mapper service doesn't support GetResults, so return a "not supported" response.

func (*AgentService) GetStatus 

func (s *AgentService) GetStatus(_ context.Context, req *proto.StatusRequest) (*proto.StatusResponse, error)

GetStatus implements the monitoring.AgentServiceServer interface.

type Config 

type Config struct {
	Workers            int                        `json:"workers"`
	Timeout            time.Duration              `json:"timeout"`
	Retries            int                        `json:"retries"`
	MaxActiveJobs      int                        `json:"max_active_jobs"`
	ResultRetention    time.Duration              `json:"result_retention"`
	DefaultCredentials SNMPCredentials            `json:"default_credentials"`
	OIDs               map[DiscoveryType][]string `json:"oids"`
	StreamConfig       StreamConfig               `json:"stream_config"`
	Credentials        []SNMPCredentialConfig     `json:"credentials"`
	Seeds              []string                   `json:"seeds"`
	Security           *models.SecurityConfig     `json:"security"`
	UniFiAPIs          []UniFiAPIConfig           `json:"unifi_apis"`
	ScheduledJobs      []*ScheduledJob            `json:"scheduled_jobs"`
	Logging            *logger.Config             `json:"logging"`
}

Config defines the configuration settings for the mapper service.

func (*Config) UnmarshalJSON 

func (c *Config) UnmarshalJSON(data []byte) error

UnmarshalJSON provides custom JSON unmarshaling for Config with validation and defaults.

type DeviceInterfaceMap 

type DeviceInterfaceMap struct {
	DeviceID   string              // Primary DeviceID (based on primary MAC)
	MACs       map[string]struct{} // All MACs associated with this device
	IPs        map[string]struct{} // All IPs associated with this device
	SysName    string              // System name (from SNMP or UniFi)
	Interfaces []*DiscoveredInterface
}

DeviceInterfaceMap represents a consolidated view of a device with all its interfaces and associated network identifiers.

type DiscoveredDevice 

type DiscoveredDevice struct {
	DeviceID        string // Unique identifier for the device (agentID:gatewayID:deviceIP)
	IP              string
	MAC             string
	Hostname        string
	SysName         string
	SysDescr        string
	SysObjectID     string
	SysContact      string
	SysLocation     string
	IPForwarding    int32
	BridgeBaseMAC   string
	SNMPFingerprint *SNMPFingerprint
	Uptime          int64
	Metadata        map[string]string
	FirstSeen       time.Time
	LastSeen        time.Time
}

DiscoveredDevice represents a discovered network device.

type DiscoveredInterface 

type DiscoveredInterface struct {
	DeviceIP         string
	DeviceID         string
	IfIndex          int32
	IfName           string
	IfDescr          string
	IfAlias          string
	IfSpeed          uint64
	IfPhysAddress    string
	IPAddresses      []string
	IfAdminStatus    int32
	IfOperStatus     int32
	IfType           int32
	Metadata         map[string]string
	AvailableMetrics []InterfaceMetric // Available SNMP metrics for this interface
}

DiscoveredInterface represents a discovered network interface.

type DiscoveryContract added in v1.1.2 

type DiscoveryContract struct {
	AgentID          string
	GatewayID        string
	ScheduledJobName string
	StageTransitions []DiscoveryStageTransition
	ProbeSummary     DiscoveryProbeSummary
	TopologyContract string
	ParseDiagnostics DiscoveryParseDiagnostics
	DebugBundle      DiscoveryDebugBundle
}

DiscoveryContract captures typed, cross-service discovery metadata.

type DiscoveryDebugBundle added in v1.1.2 

type DiscoveryDebugBundle struct {
	Enabled        bool
	ExportPath     string
	ExportedAtUnix int64
	DeviceCount    int
	InterfaceCount int
	TopologyCount  int
	Error          string
}

DiscoveryDebugBundle captures debug export metadata for a discovery job.

type DiscoveryEngine 

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

DiscoveryEngine implements the Engine interface using SNMP.

func (*DiscoveryEngine) CancelDiscovery 

func (e *DiscoveryEngine) CancelDiscovery(_ context.Context, discoveryID string) error

CancelDiscovery cancels an in-progress discovery operation

func (*DiscoveryEngine) GetDiscoveryResults 

func (e *DiscoveryEngine) GetDiscoveryResults(
	_ context.Context, discoveryID string, includeRawData bool) (*DiscoveryResults, error)

GetDiscoveryResults retrieves the results of a completed discovery operation

func (*DiscoveryEngine) GetDiscoveryStatus 

func (e *DiscoveryEngine) GetDiscoveryStatus(_ context.Context, discoveryID string) (*DiscoveryStatus, error)

GetDiscoveryStatus retrieves the status of a discovery operation

func (*DiscoveryEngine) RunScheduledJob added in v1.0.91 

func (e *DiscoveryEngine) RunScheduledJob(ctx context.Context, name string) (string, error)

RunScheduledJob triggers a named scheduled job immediately.

func (*DiscoveryEngine) Start 

func (e *DiscoveryEngine) Start(ctx context.Context) error

Start initializes and starts the discovery engine

func (*DiscoveryEngine) StartDiscovery 

func (e *DiscoveryEngine) StartDiscovery(ctx context.Context, params *DiscoveryParams) (string, error)

StartDiscovery initiates a discovery operation with the given parameters.

func (*DiscoveryEngine) Stop 

func (e *DiscoveryEngine) Stop(ctx context.Context) error

Stop gracefully shuts down the discovery engine

type DiscoveryJob 

type DiscoveryJob struct {
	ID      string
	Params  *DiscoveryParams
	Status  *DiscoveryStatus
	Results *DiscoveryResults
	// contains filtered or unexported fields
}

DiscoveryJob represents a running discovery operation.

type DiscoveryParams 

type DiscoveryParams struct {
	Seeds       []string          // IP addresses or CIDR ranges to scan
	Type        DiscoveryType     // Type of discovery to perform
	Mode        string            // Discovery mode (e.g., "snmp", "hybrid")
	Credentials *SNMPCredentials  // SNMP credentials to use
	Options     map[string]string // Additional discovery options
	Concurrency int               // Maximum number of concurrent operations
	Timeout     time.Duration     // Timeout for each operation
	Retries     int               // Number of retries for failed operations
	AgentID     string            // ID of the agent performing discovery
	GatewayID   string            // ID of the gateway initiating discovery
}

DiscoveryParams contains parameters for a discovery operation.

type DiscoveryParseDiagnostics added in v1.1.2 

type DiscoveryParseDiagnostics struct {
	ParseFailures     map[string]int
	UnknownTopLevel   map[string]int
	ParserMismatches  map[string]int
	LastFailureByType map[string]string
}

DiscoveryParseDiagnostics tracks source-shape drift and parser quality signals.

type DiscoveryProbeSummary added in v1.1.2 

type DiscoveryProbeSummary struct {
	Attempts int
	Failures int
}

DiscoveryProbeSummary tracks host probe behavior with typed counters.

type DiscoveryResults 

type DiscoveryResults struct {
	DiscoveryID   string
	Status        *DiscoveryStatus
	Devices       []*DiscoveredDevice
	Interfaces    []*DiscoveredInterface
	TopologyLinks []*TopologyLink
	Contract      DiscoveryContract
}

DiscoveryResults contains the results of a discovery operation.

type DiscoveryStage added in v1.1.2 

type DiscoveryStage string

DiscoveryStage identifies the current phase of the staged discovery pipeline. 

const (
	DiscoveryStagePrepare  DiscoveryStage = "prepare"
	DiscoveryStageIdentity DiscoveryStage = "identity"
	DiscoveryStageEnrich   DiscoveryStage = "enrichment"
	DiscoveryStageTopology DiscoveryStage = "topology"
	DiscoveryStageFinalize DiscoveryStage = "finalize"
)

type DiscoveryStageStatus added in v1.1.2 

type DiscoveryStageStatus string

DiscoveryStageStatus describes lifecycle state for a stage transition record. 

const (
	DiscoveryStageStatusStarted   DiscoveryStageStatus = "started"
	DiscoveryStageStatusCompleted DiscoveryStageStatus = "completed"
	DiscoveryStageStatusFailed    DiscoveryStageStatus = "failed"
	DiscoveryStageStatusCanceled  DiscoveryStageStatus = "canceled"
)

type DiscoveryStageTransition added in v1.1.2 

type DiscoveryStageTransition struct {
	Stage     DiscoveryStage
	Status    DiscoveryStageStatus
	Timestamp time.Time
	Message   string
}

DiscoveryStageTransition captures a typed stage transition event.

type DiscoveryStatus 

type DiscoveryStatus struct {
	DiscoveryID      string              // Unique ID for this discovery job
	Status           DiscoveryStatusType // Current status
	Progress         float64             // Progress percentage (0-100)
	StartTime        time.Time           // When the discovery started
	EndTime          time.Time           // When the discovery completed (if finished)
	Error            string              // Error message (if any)
	DevicesFound     int                 // Number of devices found
	InterfacesFound  int                 // Number of interfaces found
	TopologyLinks    int                 // Number of topology links found
	EstimatedSeconds int                 // Estimated remaining seconds
}

DiscoveryStatus contains the current status of a discovery operation

type DiscoveryStatusType 

type DiscoveryStatusType string

DiscoveryStatusType describes the current state of a discovery job. 

const (
	// DiscoveryStatusUnknown indicates the discovery status is not determined.
	DiscoveryStatusUnknown DiscoveryStatusType = "unknown"
	// DiscoveryStatusPending indicates the discovery job is queued but not started.
	DiscoveryStatusPending DiscoveryStatusType = "pending"
	// DiscoveryStatusRunning indicates the discovery job is currently executing.
	DiscoveryStatusRunning DiscoveryStatusType = "running"
	// DiscoveryStatusCompleted indicates the discovery job finished successfully.
	DiscoveryStatusCompleted DiscoveryStatusType = "completed"
	// DiscoveryStatusFailed indicates the discovery job encountered an error.
	DiscoveryStatusFailed DiscoveryStatusType = "failed"
	// DiscoverStatusCanceled indicates the discovery job was canceled.
	DiscoverStatusCanceled DiscoveryStatusType = "canceled"
)

type DiscoveryType 

type DiscoveryType string

DiscoveryType identifies the type of discovery to perform. 

const (
	// DiscoveryTypeFull performs comprehensive device discovery including all data.
	DiscoveryTypeFull DiscoveryType = "full"
	// DiscoveryTypeBasic performs basic device discovery without detailed topology.
	DiscoveryTypeBasic DiscoveryType = "basic"
	// DiscoveryTypeInterfaces discovers network interfaces for devices.
	DiscoveryTypeInterfaces DiscoveryType = "interfaces"
	// DiscoveryTypeTopology discovers network topology relationships between devices.
	DiscoveryTypeTopology DiscoveryType = "topology"
)

type GRPCDiscoveryService 

type GRPCDiscoveryService struct {
	proto.UnimplementedDiscoveryServiceServer
	// contains filtered or unexported fields
}

GRPCDiscoveryService implements the gRPC interface for the discovery service

func NewGRPCDiscoveryService 

func NewGRPCDiscoveryService(engine Mapper, log logger.Logger) *GRPCDiscoveryService

NewGRPCDiscoveryService creates a new gRPC discovery service

func (*GRPCDiscoveryService) GetDiscoveryResults 

func (s *GRPCDiscoveryService) GetDiscoveryResults(ctx context.Context, req *proto.ResultsRequest) (*proto.ResultsResponse, error)

GetDiscoveryResults implements the DiscoveryService interface

func (*GRPCDiscoveryService) GetLatestCachedResults 

func (s *GRPCDiscoveryService) GetLatestCachedResults(
	_ context.Context, req *proto.GetLatestCachedResultsRequest) (*proto.ResultsResponse, error)

GetLatestCachedResults implements the DiscoveryService interface

func (*GRPCDiscoveryService) GetStatus 

func (s *GRPCDiscoveryService) GetStatus(ctx context.Context, req *proto.StatusRequest) (*proto.StatusResponse, error)

GetStatus implements the DiscoveryService interface

func (*GRPCDiscoveryService) StartDiscovery 

func (s *GRPCDiscoveryService) StartDiscovery(ctx context.Context, req *proto.DiscoveryRequest) (*proto.DiscoveryResponse, error)

StartDiscovery implements the DiscoveryService interface

type HostProber added in v1.1.2 

type HostProber interface {
	Probe(ctx context.Context, host string) error
	Close() error
}

HostProber provides advisory host reachability checks for worker scheduling.

type InterfaceMetric added in v1.0.83 

type InterfaceMetric struct {
	Name          string `json:"name"`           // Human-readable metric name (e.g., "ifInOctets")
	OID           string `json:"oid"`            // SNMP OID in dotted notation
	DataType      string `json:"data_type"`      // Data type: "counter" or "gauge"
	Supports64Bit bool   `json:"supports_64bit"` // Whether 64-bit (HC) counter is available
	OID64Bit      string `json:"oid_64bit"`      // 64-bit OID if supports_64bit is true
	Category      string `json:"category"`       // Category for visualization: "traffic", "errors", "packets", "environmental", "status"
	Unit          string `json:"unit"`           // Unit of measurement: "bytes", "packets", "errors", "celsius", "rpm", "percent", "watts"
}

InterfaceMetric represents an available SNMP metric for an interface.

type Mapper 

type Mapper interface {
	// Start initializes and starts the discovery engine
	Start(ctx context.Context) error

	// Stop gracefully shuts down the discovery engine
	Stop(ctx context.Context) error

	// StartDiscovery initiates a discovery operation with the given parameters
	StartDiscovery(ctx context.Context, params *DiscoveryParams) (string, error)

	// GetDiscoveryStatus retrieves the status of a discovery operation
	GetDiscoveryStatus(ctx context.Context, discoveryID string) (*DiscoveryStatus, error)

	// GetDiscoveryResults retrieves the results of a completed discovery operation
	GetDiscoveryResults(ctx context.Context, discoveryID string, includeRawData bool) (*DiscoveryResults, error)

	// CancelDiscovery cancels an in-progress discovery operation
	CancelDiscovery(ctx context.Context, discoveryID string) error
}

Mapper is the main interface for network discovery operations

func NewDiscoveryEngine 

func NewDiscoveryEngine(config *Config, publisher Publisher, log logger.Logger) (Mapper, error)

NewDiscoveryEngine creates a new discovery engine with the given configuration

type MockMapper 

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

MockMapper is a mock of Mapper interface.

func NewMockMapper 

func NewMockMapper(ctrl *gomock.Controller) *MockMapper

NewMockMapper creates a new mock instance.

func (*MockMapper) CancelDiscovery 

func (m *MockMapper) CancelDiscovery(ctx context.Context, discoveryID string) error

CancelDiscovery mocks base method.

func (*MockMapper) EXPECT 

func (m *MockMapper) EXPECT() *MockMapperMockRecorder

EXPECT returns an object that allows the caller to indicate expected use.

func (*MockMapper) GetDiscoveryResults 

func (m *MockMapper) GetDiscoveryResults(ctx context.Context, discoveryID string, includeRawData bool) (*DiscoveryResults, error)

GetDiscoveryResults mocks base method.

func (*MockMapper) GetDiscoveryStatus 

func (m *MockMapper) GetDiscoveryStatus(ctx context.Context, discoveryID string) (*DiscoveryStatus, error)

GetDiscoveryStatus mocks base method.

func (*MockMapper) Start 

func (m *MockMapper) Start(ctx context.Context) error

Start mocks base method.

func (*MockMapper) StartDiscovery 

func (m *MockMapper) StartDiscovery(ctx context.Context, params *DiscoveryParams) (string, error)

StartDiscovery mocks base method.

func (*MockMapper) Stop 

func (m *MockMapper) Stop(ctx context.Context) error

Stop mocks base method.

type MockMapperMockRecorder 

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

MockMapperMockRecorder is the mock recorder for MockMapper.

func (*MockMapperMockRecorder) CancelDiscovery 

func (mr *MockMapperMockRecorder) CancelDiscovery(ctx, discoveryID any) *gomock.Call

CancelDiscovery indicates an expected call of CancelDiscovery.

func (*MockMapperMockRecorder) GetDiscoveryResults 

func (mr *MockMapperMockRecorder) GetDiscoveryResults(ctx, discoveryID, includeRawData any) *gomock.Call

GetDiscoveryResults indicates an expected call of GetDiscoveryResults.

func (*MockMapperMockRecorder) GetDiscoveryStatus 

func (mr *MockMapperMockRecorder) GetDiscoveryStatus(ctx, discoveryID any) *gomock.Call

GetDiscoveryStatus indicates an expected call of GetDiscoveryStatus.

func (*MockMapperMockRecorder) Start 

func (mr *MockMapperMockRecorder) Start(ctx any) *gomock.Call

Start indicates an expected call of Start.

func (*MockMapperMockRecorder) StartDiscovery 

func (mr *MockMapperMockRecorder) StartDiscovery(ctx, params any) *gomock.Call

StartDiscovery indicates an expected call of StartDiscovery.

func (*MockMapperMockRecorder) Stop 

func (mr *MockMapperMockRecorder) Stop(ctx any) *gomock.Call

Stop indicates an expected call of Stop.

type MockPublisher 

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

MockPublisher is a mock of Publisher interface.

func NewMockPublisher 

func NewMockPublisher(ctrl *gomock.Controller) *MockPublisher

NewMockPublisher creates a new mock instance.

func (*MockPublisher) EXPECT 

func (m *MockPublisher) EXPECT() *MockPublisherMockRecorder

EXPECT returns an object that allows the caller to indicate expected use.

func (*MockPublisher) PublishDevice 

func (m *MockPublisher) PublishDevice(ctx context.Context, device *DiscoveredDevice) error

PublishDevice mocks base method.

func (*MockPublisher) PublishInterface 

func (m *MockPublisher) PublishInterface(ctx context.Context, iface *DiscoveredInterface) error

PublishInterface mocks base method. 

func (m *MockPublisher) PublishTopologyLink(ctx context.Context, link *TopologyLink) error

PublishTopologyLink mocks base method.

type MockPublisherMockRecorder 

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

MockPublisherMockRecorder is the mock recorder for MockPublisher.

func (*MockPublisherMockRecorder) PublishDevice 

func (mr *MockPublisherMockRecorder) PublishDevice(ctx, device any) *gomock.Call

PublishDevice indicates an expected call of PublishDevice.

func (*MockPublisherMockRecorder) PublishInterface 

func (mr *MockPublisherMockRecorder) PublishInterface(ctx, iface any) *gomock.Call

PublishInterface indicates an expected call of PublishInterface. 

func (mr *MockPublisherMockRecorder) PublishTopologyLink(ctx, link any) *gomock.Call

PublishTopologyLink indicates an expected call of PublishTopologyLink.

type Publisher 

type Publisher interface {
	// PublishDevice publishes a discovered device to the appropriate stream
	PublishDevice(ctx context.Context, device *DiscoveredDevice) error

	// PublishInterface publishes a discovered interface to the appropriate stream
	PublishInterface(ctx context.Context, iface *DiscoveredInterface) error

	// PublishTopologyLink publishes a discovered topology link to the appropriate stream
	PublishTopologyLink(ctx context.Context, link *TopologyLink) error
}

Publisher defines the interface for publishing discovered data to streams

type SNMPBridgeFingerprint added in v1.1.1 

type SNMPBridgeFingerprint struct {
	BridgeBaseMAC          string
	BridgePortCount        int32
	STPForwardingPortCount int32
}

SNMPBridgeFingerprint stores bridge-level identity fields.

type SNMPCredentialConfig 

type SNMPCredentialConfig struct {
	Targets         []string    `json:"targets"`                           // IP addresses or CIDR ranges
	Version         SNMPVersion `json:"version"`                           // SNMP version (v1, v2c, v3)
	Community       string      `json:"community" sensitive:"true"`        // Community string for v1/v2c
	Username        string      `json:"username"`                          // Username for v3
	AuthProtocol    string      `json:"auth_protocol"`                     // Auth protocol for v3 (MD5/SHA)
	AuthPassword    string      `json:"auth_password" sensitive:"true"`    // Auth password for v3
	PrivacyProtocol string      `json:"privacy_protocol"`                  // Privacy protocol for v3 (DES/AES)
	PrivacyPassword string      `json:"privacy_password" sensitive:"true"` // Privacy password for v3
}

SNMPCredentialConfig represents SNMP credentials for specific target IP ranges.

type SNMPCredentials 

type SNMPCredentials struct {
	Version         SNMPVersion                 // SNMP protocol version
	Community       string                      `sensitive:"true"` // Community string for v1/v2c
	Username        string                      // Username for v3
	AuthProtocol    string                      // Auth protocol for v3 (MD5/SHA)
	AuthPassword    string                      `sensitive:"true"` // Auth password for v3
	PrivacyProtocol string                      // Privacy protocol for v3 (DES/AES)
	PrivacyPassword string                      `sensitive:"true"` // Privacy password for v3
	TargetSpecific  map[string]*SNMPCredentials // Credentials for specific targets
}

SNMPCredentials contains information needed to authenticate with SNMP devices.

type SNMPFingerprint added in v1.1.1 

type SNMPFingerprint struct {
	System           *SNMPSystemFingerprint
	Bridge           *SNMPBridgeFingerprint
	VLAN             *SNMPVLANFingerprint
	InterfaceSummary *SNMPInterfaceSummaryFingerprint
	ExtractionErrors map[string]string
}

SNMPFingerprint captures normalized SNMP evidence for enrichment and identity processing.

type SNMPInterfaceSummaryFingerprint added in v1.1.1 

type SNMPInterfaceSummaryFingerprint struct {
	InterfaceCount        int32
	IfTypeCounts          []SNMPInterfaceTypeCount
	BridgeLikeNameCount   int32
	WirelessLikeNameCount int32
}

SNMPInterfaceSummaryFingerprint stores interface-level summary signals.

type SNMPInterfaceTypeCount added in v1.1.1 

type SNMPInterfaceTypeCount struct {
	IfType int32
	Count  int32
}

SNMPInterfaceTypeCount stores a count for one ifType value.

type SNMPPVIDCount added in v1.1.1 

type SNMPPVIDCount struct {
	PVID  int32
	Count int32
}

SNMPPVIDCount stores a single PVID histogram entry.

type SNMPSystemFingerprint added in v1.1.1 

type SNMPSystemFingerprint struct {
	SysName      string
	SysDescr     string
	SysObjectID  string
	SysContact   string
	SysLocation  string
	IPForwarding int32
}

SNMPSystemFingerprint stores standard system-level identity fields.

type SNMPVLANFingerprint added in v1.1.1 

type SNMPVLANFingerprint struct {
	VLANIDsSeen      []int32
	PVIDDistribution []SNMPPVIDCount
	PortEvidence     []SNMPVLANPortEvidence
}

SNMPVLANFingerprint stores VLAN-related evidence.

type SNMPVLANPortEvidence added in v1.1.1 

type SNMPVLANPortEvidence struct {
	VLANID           int32
	EgressPortsHex   string
	UntaggedPortsHex string
}

SNMPVLANPortEvidence stores per-VLAN port membership evidence.

type SNMPVersion 

type SNMPVersion string

SNMPVersion represents the SNMP protocol version. 

const (
	// SNMPVersion1 represents SNMP protocol version 1.
	SNMPVersion1 SNMPVersion = "v1"
	// SNMPVersion2c represents SNMP protocol version 2c.
	SNMPVersion2c SNMPVersion = "v2c"
	// SNMPVersion3 represents SNMP protocol version 3.
	SNMPVersion3 SNMPVersion = "v3"
)

type ScheduledJob 

type ScheduledJob struct {
	Name          string            `json:"name"`
	Interval      string            `json:"interval"`
	Enabled       bool              `json:"enabled"`
	Seeds         []string          `json:"seeds"`
	Type          string            `json:"type"`
	DiscoveryMode string            `json:"discovery_mode,omitempty"`
	Credentials   SNMPCredentials   `json:"credentials"`
	Concurrency   int               `json:"concurrency"`
	Timeout       string            `json:"timeout"`
	Retries       int               `json:"retries"`
	Options       map[string]string `json:"options"`
}

ScheduledJob represents a scheduled discovery job configuration

type StreamConfig 

type StreamConfig struct {
	DeviceStream         string
	InterfaceStream      string
	TopologyStream       string
	AgentID              string
	GatewayID            string
	Partition            string
	PublishBatchSize     int
	PublishRetries       int
	PublishRetryInterval time.Duration
}

StreamConfig contains configuration for data publishing streams 

type TopologyLink struct {
	Protocol           string
	LocalDeviceIP      string
	LocalDeviceID      string
	LocalIfIndex       int32
	LocalIfName        string
	NeighborChassisID  string
	NeighborPortID     string
	NeighborPortDescr  string
	NeighborSystemName string
	NeighborMgmtAddr   string
	NeighborIdentity   *TopologyNeighborIdentity
	Metadata           map[string]string
	Observation        *TopologyObservationV2
}

TopologyLink represents a discovered link between two devices

func (*TopologyLink) MetadataValue added in v1.1.2 

func (t *TopologyLink) MetadataValue(key string) string

type TopologyNeighborIdentity added in v1.1.2 

type TopologyNeighborIdentity struct {
	ManagementIP string
	DeviceID     string
	ChassisID    string
	PortID       string
	PortDescr    string
	SystemName   string
}

TopologyNeighborIdentity stores canonical neighbor identity evidence.

func NormalizeTopologyLinkNeighborIdentity added in v1.1.2 

func NormalizeTopologyLinkNeighborIdentity(link *TopologyLink) *TopologyNeighborIdentity

NormalizeTopologyLinkNeighborIdentity builds a canonical neighbor identity from explicit topology fields and metadata fallback keys.

type TopologyObservationEndpointV2 added in v1.1.2 

type TopologyObservationEndpointV2 struct {
	UID      string `json:"uid,omitempty"`
	DeviceID string `json:"device_id,omitempty"`
	IP       string `json:"ip,omitempty"`
	IfIndex  int32  `json:"if_index,omitempty"`
	IfName   string `json:"if_name,omitempty"`
	MAC      string `json:"mac,omitempty"`
	PortID   string `json:"port_id,omitempty"`
	SysName  string `json:"sys_name,omitempty"`
}

TopologyObservationEndpointV2 captures immutable endpoint identity fields.

type TopologyObservationV2 added in v1.1.2 

type TopologyObservationV2 struct {
	ContractVersion string                        `json:"contract_version"`
	ObservationType string                        `json:"observation_type"`
	SourceProtocol  string                        `json:"source_protocol"`
	SourceAdapter   string                        `json:"source_adapter"`
	EvidenceClass   string                        `json:"evidence_class"`
	ConfidenceTier  string                        `json:"confidence_tier"`
	ObservedAtUnix  int64                         `json:"observed_at_unix"`
	DiscoveryID     string                        `json:"discovery_id"`
	SourceEndpoint  TopologyObservationEndpointV2 `json:"source_endpoint"`
	TargetEndpoint  TopologyObservationEndpointV2 `json:"target_endpoint"`
	RawAttributes   map[string]string             `json:"raw_attributes,omitempty"`
}

TopologyObservationV2 is the typed mapper evidence envelope for topology.

type UniFiAPIConfig 

type UniFiAPIConfig struct {
	BaseURL            string `json:"base_url"`
	APIKey             string `json:"api_key" sensitive:"true"`
	Name               string `json:"name"`                           // Optional name for identifying the controller
	InsecureSkipVerify bool   `json:"insecure_skip_verify,omitempty"` // Skip TLS verification
}

UniFiAPIConfig contains configuration for connecting to a UniFi controller API.

type UniFiDevice 

type UniFiDevice struct {
	ID         string          `json:"id"`
	IPAddress  string          `json:"ipAddress"`
	Name       string          `json:"name"`
	MAC        string          `json:"macAddress"`
	Features   []string        `json:"features"`
	Uplink     UniFiUplink     `json:"uplink"`
	Interfaces json.RawMessage `json:"interfaces"` // Use RawMessage to handle varying structures
}

UniFiDevice represents a network device managed by a UniFi controller.

type UniFiDeviceDetails 

type UniFiDeviceDetails struct {
	LLDPTable      []UniFiLLDPEntry `json:"lldp_table"`
	LLDPTableCamel []UniFiLLDPEntry `json:"lldpTable"`

	PortTable      []UniFiPortEntry `json:"port_table"`
	PortTableCamel []UniFiPortEntry `json:"portTable"`

	Uplink UniFiUplink `json:"uplink"`

	AdapterVersion string `json:"-"`
	AdapterShape   string `json:"-"`
}

UniFiDeviceDetails represents detailed device information

type UniFiInterfaces 

type UniFiInterfaces struct {
	Ports []struct {
		Idx          int    `json:"idx"`
		State        string `json:"state"`
		Connector    string `json:"connector"`
		MaxSpeedMbps int    `json:"maxSpeedMbps"`
		SpeedMbps    int    `json:"speedMbps"`
		PoE          struct {
			Standard string `json:"standard"`
			Type     int    `json:"type"`
			Enabled  bool   `json:"enabled"`
			State    string `json:"state"`
		} `json:"poe,omitempty"`
	} `json:"ports"`
}

UniFiInterfaces represents the interfaces object for devices with ports

type UniFiLLDPEntry added in v1.1.2 

type UniFiLLDPEntry struct {
	LocalPortIdx        int32  `json:"local_port_idx"`
	LocalPortIdxCamel   int32  `json:"localPortIdx"`
	LocalPortName       string `json:"local_port_name"`
	LocalPortNameCamel  string `json:"localPortName"`
	ChassisID           string `json:"chassis_id"`
	ChassisIDCamel      string `json:"chassisId"`
	PortID              string `json:"port_id"`
	PortIDCamel         string `json:"portId"`
	PortDescription     string `json:"port_description"`
	PortDescrCamel      string `json:"portDescription"`
	SystemName          string `json:"system_name"`
	SystemNameCamel     string `json:"systemName"`
	ManagementAddr      string `json:"management_address"`
	ManagementAddrCamel string `json:"managementAddr"`
}

type UniFiPortConnectedPeer added in v1.1.2 

type UniFiPortConnectedPeer struct {
	MAC      string `json:"mac"`
	MACCamel string `json:"macAddress"`
	Name     string `json:"name"`
	IP       string `json:"ip"`
	IPCamel  string `json:"ipAddress"`

	DeviceID      string `json:"deviceId"`
	DeviceIDSnake string `json:"device_id"`
	RemoteID      string `json:"remoteDeviceId"`
	RemoteIDSnake string `json:"remote_device_id"`
	ID            string `json:"id"`
}

type UniFiPortEntry added in v1.1.2 

type UniFiPortEntry struct {
	PortIdx        int32                  `json:"port_idx"`
	PortIdxCamel   int32                  `json:"portIdx"`
	Name           string                 `json:"name"`
	Connected      UniFiPortConnectedPeer `json:"connected_device"`
	ConnectedCamel UniFiPortConnectedPeer `json:"connectedDevice"`
}

type UniFiSite 

type UniFiSite struct {
	ID                string `json:"id"`
	InternalReference string `json:"internalReference"`
	Name              string `json:"name"`
}

UniFiSite represents a site from the UniFi API 

type UniFiUplink struct {
	DeviceID      string `json:"deviceId"`
	DeviceIDSnake string `json:"device_id"`
	UpstreamID    string `json:"upstreamDeviceId"`
	UpstreamSnake string `json:"upstream_device_id"`

	LocalPortIdx      int32 `json:"localPortIdx"`
	LocalPortIdxSnake int32 `json:"local_port_idx"`
	PortIdx           int32 `json:"portIdx"`
	PortIdxSnake      int32 `json:"port_idx"`
	ParentPortIdx     int32 `json:"parentPortIdx"`
	ParentPortSnake   int32 `json:"parent_port_idx"`

	LocalPortName      string `json:"localPortName"`
	LocalPortNameSnake string `json:"local_port_name"`
	PortName           string `json:"portName"`
	PortNameSnake      string `json:"port_name"`
	ParentPortName     string `json:"parentPortName"`
	ParentPortNameSnk  string `json:"parent_port_name"`
}

UniFiUplink captures multiple schema variants for uplink metadata.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.