models

package
v1.0.78 Latest Latest
Warning

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

 Go to latest Published: Dec 14, 2025 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package models pkg/models/api_types.go

Package models pkg/models/metrics.go

Package models provides data models for the sweeper service.

Index

Constants

View Source 
const (
	DiscoverySourceSNMP         DiscoverySource = "snmp"
	DiscoverySourceMapper       DiscoverySource = "mapper"
	DiscoverySourceIntegration  DiscoverySource = "integration"
	DiscoverySourceNetFlow      DiscoverySource = "netflow"
	DiscoverySourceManual       DiscoverySource = "manual"
	DiscoverySourceSweep        DiscoverySource = "sweep"
	DiscoverySourceSighting     DiscoverySource = "sighting"
	DiscoverySourceSelfReported DiscoverySource = "self-reported"
	DiscoverySourceArmis        DiscoverySource = "armis"
	DiscoverySourceNetbox       DiscoverySource = "netbox"
	DiscoverySourceSysmon       DiscoverySource = "sysmon"
	DiscoverySourceServiceRadar DiscoverySource = "serviceradar" // ServiceRadar infrastructure components

	// Confidence levels for discovery sources (1-10 scale)
	ConfidenceLowUnknown         = 1  // Low confidence - unknown source
	ConfidenceMediumSweep        = 5  // Medium confidence - network sweep
	ConfidenceMediumTraffic      = 6  // Medium confidence - traffic analysis
	ConfidenceMediumMonitoring   = 6  // Medium confidence - system monitoring
	ConfidenceGoodExternal       = 7  // Good confidence - external system
	ConfidenceGoodSecurity       = 7  // Good confidence - external security system
	ConfidenceGoodDocumentation  = 7  // Good confidence - network documentation system
	ConfidenceHighNetworkMapping = 8  // High confidence - network mapping
	ConfidenceHighSelfReported   = 8  // High confidence - device reported itself
	ConfidenceHighSNMP           = 9  // High confidence - active SNMP query
	ConfidenceHighestManual      = 10 // Highest confidence - human input
)
View Source 
const MetricPointSize = 32 // 8 bytes timestamp + 8 bytes response + 16 bytes name
View Source 
const ServiceDevicePartition = "serviceradar"

ServiceDevicePartition is the special partition used for service components

View Source 
const (
	// TrueString represents the string "true"
	TrueString = "true"
)

Variables

View Source 
var (
	ErrEdgeOnboardingDisabled          = errors.New("edge onboarding: service disabled")
	ErrEdgeOnboardingInvalidRequest    = errors.New("edge onboarding: invalid request")
	ErrEdgeOnboardingPollerConflict    = errors.New("edge onboarding: poller already provisioned")
	ErrEdgeOnboardingComponentConflict = errors.New("edge onboarding: component already provisioned")
	ErrEdgeOnboardingSpireUnavailable  = errors.New("edge onboarding: spire admin unavailable")
	ErrEdgeOnboardingDownloadRequired  = errors.New("edge onboarding: download token required")
	ErrEdgeOnboardingDownloadInvalid   = errors.New("edge onboarding: download token invalid")
	ErrEdgeOnboardingDownloadExpired   = errors.New("edge onboarding: download token expired")
	ErrEdgeOnboardingPackageDelivered  = errors.New("edge onboarding: package already delivered")
	ErrEdgeOnboardingPackageRevoked    = errors.New("edge onboarding: package revoked")
	ErrEdgeOnboardingDecryptFailed     = errors.New("edge onboarding: decrypt failed")
)
View Source 
var (
	// ErrInputMustBeStruct indicates that the input must be a struct or pointer to struct.
	ErrInputMustBeStruct = errors.New("input must be a struct or pointer to struct")
)

Functions

func ContainsMode 

func ContainsMode(modes []SweepMode, mode SweepMode) bool

ContainsMode checks if a mode is in a list of modes.

func ExtractSafeConfigMetadata added in v1.0.55 

func ExtractSafeConfigMetadata(config interface{}) map[string]string

ExtractSafeConfigMetadata extracts only safe, non-sensitive configuration metadata for service registration and tracking purposes.

func FilterIPsWithBlacklist 

func FilterIPsWithBlacklist(ips, blacklistCIDRs []string) ([]string, error)

FilterIPsWithBlacklist filters out IP addresses that match the given CIDR blacklist. This is a utility function to be used by sync integrations to apply network blacklisting.

func FilterSensitiveFields added in v1.0.55 

func FilterSensitiveFields(input interface{}) (map[string]interface{}, error)

FilterSensitiveFields removes fields marked with `sensitive:"true"` tag from a struct before serializing it. This ensures sensitive data like secrets and passwords are never stored in databases or sent to UIs.

func GenerateNetworkDeviceID added in v1.0.55 

func GenerateNetworkDeviceID(partition, ip string) string

GenerateNetworkDeviceID creates a device ID for a discovered network device Format: partition:ip Example: default:192.168.1.1

func GenerateServiceDeviceID added in v1.0.55 

func GenerateServiceDeviceID(serviceType ServiceType, serviceID string) string

GenerateServiceDeviceID creates a device ID for a service component Format: serviceradar:service_type:service_id Example: serviceradar:poller:k8s-poller

func GetSourceConfidence 

func GetSourceConfidence(source DiscoverySource) int

GetSourceConfidence returns the confidence level for a discovery source

func IsServiceDevice added in v1.0.55 

func IsServiceDevice(deviceID string) bool

IsServiceDevice checks if a device_id represents a service component

Types

type AgentConfig 

type AgentConfig struct {
	CheckersDir string          `json:"checkers_dir"` // e.g., /etc/serviceradar/checkers
	ListenAddr  string          `json:"listen_addr"`  // e.g., :50051
	ServiceName string          `json:"service_name"` // e.g., "agent"
	Security    *SecurityConfig `json:"security"`
	KVAddress   string          `json:"kv_address,omitempty"` // Optional KV store address
}

AgentConfig represents the configuration for an agent instance.

type AgentDefinition 

type AgentDefinition struct {
	Address string  `json:"address"` // gRPC address of the agent
	Checks  []Check `json:"checks"`  // List of checks to run on this agent
}

AgentDefinition represents a remote agent and its checks.

type AuthConfig 

type AuthConfig struct {
	// Secret key used for signing JWT tokens (SENSITIVE: never store in DB or display in UI)
	JWTSecret string `json:"jwt_secret" example:"very-secret-key-do-not-share" sensitive:"true"`
	// Optional JWT signing algorithm. Defaults to HS256. Set to RS256 to enable RSA signing.
	JWTAlgorithm string `json:"jwt_algorithm,omitempty" example:"RS256"`
	// PEM-encoded RSA private key used for RS256 signing (SENSITIVE)
	JWTPrivateKeyPEM string `json:"jwt_private_key_pem,omitempty" sensitive:"true"`
	// PEM-encoded RSA public key (optional; derived from private key if omitted)
	JWTPublicKeyPEM string `json:"jwt_public_key_pem,omitempty"`
	// Key ID placed in JWT header as `kid` for JWKS lookup
	JWTKeyID string `json:"jwt_key_id,omitempty" example:"main-2025-09"`
	// How long JWT tokens are valid
	JWTExpiration time.Duration `json:"jwt_expiration" example:"24h"`
	// OAuth callback URL
	CallbackURL string `json:"callback_url" example:"https://api.example.com/auth/callback"`
	// Map of local usernames to password hashes (SENSITIVE: never store in DB or display in UI)
	LocalUsers map[string]string `json:"local_users" sensitive:"true"`
	// Configuration for SSO providers like Google, GitHub, etc. (SENSITIVE: may contain secrets)
	SSOProviders map[string]SSOConfig `json:"sso_providers" sensitive:"true"`
	// RBAC configuration for users
	RBAC RBACConfig `json:"rbac"`
}

AuthConfig contains authentication configuration. @Description Authentication and authorization configuration settings.

func (*AuthConfig) MarshalJSON added in v1.0.55 

func (a *AuthConfig) MarshalJSON() ([]byte, error)

func (*AuthConfig) UnmarshalJSON added in v1.0.55 

func (a *AuthConfig) UnmarshalJSON(data []byte) error

type CNPGDatabase added in v1.0.55 

type CNPGDatabase struct {
	Host               string            `json:"host"`
	Port               int               `json:"port"`
	Database           string            `json:"database"`
	Username           string            `json:"username"`
	Password           string            `json:"password" sensitive:"true"`
	ApplicationName    string            `json:"application_name,omitempty"`
	SSLMode            string            `json:"ssl_mode,omitempty"`
	CertDir            string            `json:"cert_dir,omitempty"`
	TLS                *TLSConfig        `json:"tls,omitempty"`
	MaxConnections     int32             `json:"max_connections,omitempty"`
	MinConnections     int32             `json:"min_connections,omitempty"`
	MaxConnLifetime    Duration          `json:"max_conn_lifetime,omitempty"`
	HealthCheckPeriod  Duration          `json:"health_check_period,omitempty"`
	StatementTimeout   Duration          `json:"statement_timeout,omitempty"`
	ExtraRuntimeParams map[string]string `json:"runtime_params,omitempty"`
}

CNPGDatabase describes the Timescale/CloudNativePG connection.

type CORSConfig 

type CORSConfig struct {
	// List of origins allowed to access the API
	AllowedOrigins []string `json:"allowed_origins" example:"['*','https://example.com']"`
	// Whether to allow credentials (cookies, authorization headers) in CORS requests
	AllowCredentials bool `json:"allow_credentials" example:"true"`
}

CORSConfig contains Cross-Origin Resource Sharing configuration. @Description Configuration for Cross-Origin Resource Sharing (CORS) for the API.

type CPUClusterMetric added in v1.0.55 

type CPUClusterMetric struct {
	// Cluster name (e.g., ECPU, PCPU)
	Name string `json:"name" example:"ECPU"`
	// Instantaneous frequency in Hz, if available.
	FrequencyHz float64 `json:"frequency_hz" example:"1700000000"`
	// When this metric was collected
	Timestamp time.Time `json:"timestamp" example:"2025-04-24T14:15:22Z"`
	// Host identifier for the agent that collected this metric
	HostID string `json:"host_id,omitempty" example:"server-east-1"`
	// Host IP address for the agent that collected this metric
	HostIP string `json:"host_ip,omitempty" example:"192.168.1.100"`
	// ServiceRadar agent identifier
	AgentID string `json:"agent_id,omitempty" example:"agent-1234"`
}

CPUClusterMetric represents aggregated CPU cluster telemetry. @Description Aggregated metrics for a logical CPU cluster (e.g., efficiency or performance cores).

type CPUMetric 

type CPUMetric struct {
	// ID number of the CPU core
	CoreID int32 `json:"core_id" example:"0"`
	// Platform label for the CPU core (e.g., ECPU0, PCPU3)
	Label string `json:"label,omitempty" example:"ECPU0"`
	// Cluster identifier this core belongs to (e.g., ECPU, PCPU)
	Cluster string `json:"cluster,omitempty" example:"ECPU"`
	// Usage percentage (0-100)
	UsagePercent float64 `json:"usage_percent" example:"45.2"`
	// Instantaneous frequency in Hz, if available.
	FrequencyHz float64 `json:"frequency_hz" example:"2400000000"`
	// When this metric was collected
	Timestamp time.Time `json:"timestamp" example:"2025-04-24T14:15:22Z"`
	// Host identifier for the agent that collected this metric
	HostID string `json:"host_id,omitempty" example:"server-east-1"`
	// Host IP address for the agent that collected this metric
	HostIP string `json:"host_ip,omitempty" example:"192.168.1.100"`
	// ServiceRadar agent identifier
	AgentID string `json:"agent_id,omitempty" example:"agent-1234"`
}

CPUMetric represents CPU utilization for a single core. @Description CPU usage metrics for an individual processor core.

type Check 

type Check struct {
	ServiceType string          `json:"service_type"` // e.g., "grpc", "process", "port"
	ServiceName string          `json:"service_name"`
	Details     string          `json:"details,omitempty"` // Service-specific details
	Port        int32           `json:"port,omitempty"`    // For port checkers
	Config      json.RawMessage `json:"config,omitempty"`  // Checker-specific configuration
}

Check represents a generic service check configuration.

type CloudConfig 

type CloudConfig struct {
	ListenAddr     string          `json:"listen_addr"`
	GrpcAddr       string          `json:"grpc_addr,omitempty"`
	DBPath         string          `json:"db_path"`
	AlertThreshold Duration        `json:"alert_threshold"`
	KnownPollers   []string        `json:"known_pollers"`
	Webhooks       []WebhookConfig `json:"webhooks,omitempty"`
}

CloudConfig represents the configuration for the cloud service.

type CloudEvent 

type CloudEvent struct {
	SpecVersion     string      `json:"specversion"`
	ID              string      `json:"id"`
	Source          string      `json:"source"`
	Type            string      `json:"type"`
	DataContentType string      `json:"datacontenttype"`
	Subject         string      `json:"subject,omitempty"`
	Time            *time.Time  `json:"time,omitempty"`
	Data            interface{} `json:"data,omitempty"`
}

CloudEvent represents a CloudEvents v1.0 compliant event.

type CollectorCapability added in v1.0.55 

type CollectorCapability struct {
	DeviceID     string    `json:"device_id"`
	Capabilities []string  `json:"capabilities"`
	AgentID      string    `json:"agent_id,omitempty"`
	PollerID     string    `json:"poller_id,omitempty"`
	LastSeen     time.Time `json:"last_seen"`
	ServiceName  string    `json:"service_name,omitempty"`
}

CollectorCapability describes the collectors currently responsible for a device. Capabilities are explicit strings such as "icmp", "snmp", or "sysmon".

type ColumnDefinition 

type ColumnDefinition struct {
	Key       ColumnKey
	Name      string
	Type      string
	Codec     string
	Alias     string
	Default   string
	Mandatory bool
}

ColumnDefinition represents a column in the netflow_metrics stream

type ColumnKey 

type ColumnKey int

ColumnKey represents a column in the schema

type Config 

type Config struct {
	Networks      []string       `json:"networks"`
	Ports         []int          `json:"ports"`
	SweepModes    []SweepMode    `json:"sweep_modes"`
	DeviceTargets []DeviceTarget `json:"device_targets,omitempty"` // Per-device sweep configuration
	Interval      time.Duration  `json:"interval"`
	Concurrency   int            `json:"concurrency"`
	Timeout       time.Duration  `json:"timeout"`
	ICMPCount     int            `json:"icmp_count"`
	MaxIdle       int            `json:"max_idle"`
	MaxLifetime   time.Duration  `json:"max_lifetime"`
	IdleTimeout   time.Duration  `json:"idle_timeout"`
	// Agent/Partition information for proper device identification
	AgentID      string `json:"agent_id,omitempty"`
	PollerID     string `json:"poller_id,omitempty"`
	Partition    string `json:"partition,omitempty"`
	ICMPSettings struct {
		RateLimit int // Packets per second
		Timeout   time.Duration
		MaxBatch  int
	}
	TCPSettings struct {
		Concurrency        int
		Timeout            time.Duration
		MaxBatch           int
		RouteDiscoveryHost string `json:"route_discovery_host,omitempty"` // Target for local IP discovery (default: "8.8.8.8:80")

		// Ring buffer tuning for SYN scanner memory vs performance tradeoffs
		// These values will be clamped to safe limits automatically
		RingBlockSize  int `json:"ring_block_size,omitempty"`  // Block size in bytes (default: 1MB, max: 8MB)
		RingBlockCount int `json:"ring_block_count,omitempty"` // Number of blocks (default: 8, max: 32, total max: 64MB)

		// Network interface selection for multi-homed hosts
		Interface string `json:"interface,omitempty"` // Network interface (e.g., "eth0", "wlan0") - auto-detected if empty

		// Advanced NAT/firewall compatibility options
		SuppressRSTReply bool `json:"suppress_rst_reply,omitempty"` // Suppress RST packet generation (optional)

		// Global ring buffer memory cap (in MB) to be distributed across all CPU cores
		// If 0, defaults to 64MB total. This prevents excessive memory usage on high-CPU systems.
		GlobalRingMemoryMB int `json:"global_ring_memory_mb,omitempty"`

		// Ring readers and poll timeout tuning
		RingReaders       int `json:"ring_readers,omitempty"`         // number of AF_PACKET ring readers
		RingPollTimeoutMs int `json:"ring_poll_timeout_ms,omitempty"` // poll() timeout per reader in ms
	}
	EnableHighPerformanceICMP bool `json:"high_perf_icmp,omitempty"`
	ICMPRateLimit             int  `json:"icmp_rate_limit,omitempty"`
}

Config defines sweeper configuration.

type CoreServiceConfig 

type CoreServiceConfig struct {
	ListenAddr     string                 `json:"listen_addr"`
	GrpcAddr       string                 `json:"grpc_addr"`
	DBPath         string                 `json:"db_path"` // Keep for compatibility, can be optional
	AlertThreshold time.Duration          `json:"alert_threshold"`
	PollerPatterns []string               `json:"poller_patterns"`
	Webhooks       []alerts.WebhookConfig `json:"webhooks,omitempty"`
	KnownPollers   []string               `json:"known_pollers,omitempty"`
	Metrics        Metrics                `json:"metrics"`
	SNMP           SNMPConfig             `json:"snmp"`
	Security       *SecurityConfig        `json:"security"`
	KVSecurity     *SecurityConfig        `json:"kv_security,omitempty"`
	Auth           *AuthConfig            `json:"auth,omitempty"`
	CORS           CORSConfig             `json:"cors,omitempty"`
	CNPG           *CNPGDatabase          `json:"cnpg"`
	WriteBuffer    WriteBufferConfig      `json:"write_buffer,omitempty"`
	NATS           *NATSConfig            `json:"nats,omitempty"`
	Events         *EventsConfig          `json:"events,omitempty"`
	Logging        *logger.Config         `json:"logging,omitempty"`
	MCP            *MCPConfigRef          `json:"mcp,omitempty"`
	SRQL           *SRQLConfig            `json:"srql,omitempty"`
	// KV endpoints for admin config operations (hub/leaf mappings)
	KVEndpoints    []KVEndpoint                  `json:"kv_endpoints,omitempty"`
	SpireAdmin     *SpireAdminConfig             `json:"spire_admin,omitempty"`
	EdgeOnboarding *EdgeOnboardingConfig         `json:"edge_onboarding,omitempty"`
	Features       FeatureFlags                  `json:"features,omitempty"`
	Reaper         *ReaperConfig                 `json:"reaper,omitempty"`
	Identity       *IdentityReconciliationConfig `json:"identity_reconciliation,omitempty"`
}

CoreServiceConfig represents the configuration for the core service. This was previously named DBConfig but contains much more than database configuration.

func (*CoreServiceConfig) MarshalJSON 

func (c *CoreServiceConfig) MarshalJSON() ([]byte, error)

func (*CoreServiceConfig) UnmarshalJSON 

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

func (*CoreServiceConfig) Validate 

func (c *CoreServiceConfig) Validate() error

type Device 

type Device struct {
	DeviceID         string                 `json:"device_id"`
	AgentID          string                 `json:"agent_id"`
	PollerID         string                 `json:"poller_id"`
	DiscoverySources []string               `json:"discovery_sources"`
	IP               string                 `json:"ip"`
	MAC              string                 `json:"mac,omitempty"`
	Hostname         string                 `json:"hostname,omitempty"`
	FirstSeen        time.Time              `json:"first_seen"`
	LastSeen         time.Time              `json:"last_seen"`
	IsAvailable      bool                   `json:"is_available"`
	ServiceType      string                 `json:"service_type,omitempty"`
	ServiceStatus    string                 `json:"service_status,omitempty"`
	LastHeartbeat    *time.Time             `json:"last_heartbeat,omitempty"`
	DeviceType       string                 `json:"device_type,omitempty"`
	OSInfo           string                 `json:"os_info,omitempty"`
	VersionInfo      string                 `json:"version_info,omitempty"`
	Metadata         map[string]interface{} `json:"metadata,omitempty"`
}

Device represents a network device.

type DeviceCapabilityEvent added in v1.0.55 

type DeviceCapabilityEvent struct {
	EventID       string         `json:"event_id"`
	DeviceID      string         `json:"device_id"`
	ServiceID     string         `json:"service_id,omitempty"`
	ServiceType   string         `json:"service_type,omitempty"`
	Capability    string         `json:"capability"`
	State         string         `json:"state,omitempty"`
	Enabled       bool           `json:"enabled"`
	LastChecked   time.Time      `json:"last_checked"`
	LastSuccess   *time.Time     `json:"last_success,omitempty"`
	LastFailure   *time.Time     `json:"last_failure,omitempty"`
	FailureReason string         `json:"failure_reason,omitempty"`
	Metadata      map[string]any `json:"metadata,omitempty"`
	RecordedBy    string         `json:"recorded_by,omitempty"`
}

DeviceCapabilityEvent captures a single capability check result emitted by a poller/agent for audit purposes. Events land in the ClickHouse Stream `device_capabilities`.

type DeviceCapabilitySnapshot added in v1.0.55 

type DeviceCapabilitySnapshot struct {
	DeviceID      string         `json:"device_id"`
	ServiceID     string         `json:"service_id,omitempty"`
	ServiceType   string         `json:"service_type,omitempty"`
	Capability    string         `json:"capability"`
	State         string         `json:"state,omitempty"`
	Enabled       bool           `json:"enabled"`
	LastChecked   time.Time      `json:"last_checked"`
	LastSuccess   *time.Time     `json:"last_success,omitempty"`
	LastFailure   *time.Time     `json:"last_failure,omitempty"`
	FailureReason string         `json:"failure_reason,omitempty"`
	Metadata      map[string]any `json:"metadata,omitempty"`
	RecordedBy    string         `json:"recorded_by,omitempty"`
}

DeviceCapabilitySnapshot reflects the most recent state for a capability in the versioned_kv registry (`device_capability_registry`).

type DeviceIdentifier added in v1.0.59 

type DeviceIdentifier struct {
	DeviceID   string            `json:"device_id"`
	IDType     string            `json:"id_type"`
	IDValue    string            `json:"id_value"`
	Partition  string            `json:"partition,omitempty"`
	Confidence string            `json:"confidence"`
	Source     string            `json:"source,omitempty"`
	FirstSeen  time.Time         `json:"first_seen"`
	LastSeen   time.Time         `json:"last_seen"`
	Verified   bool              `json:"verified,omitempty"`
	Metadata   map[string]string `json:"metadata,omitempty"`
}

DeviceIdentifier captures a normalized identifier tied to a device.

type DeviceLifecycleEventData added in v1.0.55 

type DeviceLifecycleEventData struct {
	DeviceID   string            `json:"device_id"`
	Partition  string            `json:"partition,omitempty"`
	Action     string            `json:"action"` // e.g. deleted, restored
	Actor      string            `json:"actor,omitempty"`
	Reason     string            `json:"reason,omitempty"`
	Timestamp  time.Time         `json:"timestamp"`
	Severity   string            `json:"severity,omitempty"`
	Level      int32             `json:"level,omitempty"`
	RemoteAddr string            `json:"remote_addr,omitempty"`
	Metadata   map[string]string `json:"metadata,omitempty"`
}

DeviceLifecycleEventData represents lifecycle changes for a device (manual delete, restore, etc).

type DeviceStatsMeta added in v1.0.55 

type DeviceStatsMeta struct {
	RawRecords                int `json:"raw_records"`
	ProcessedRecords          int `json:"processed_records"`
	SkippedNilRecords         int `json:"skipped_nil_records"`
	SkippedTombstonedRecords  int `json:"skipped_tombstoned_records"`
	SkippedServiceComponents  int `json:"skipped_service_components"`
	SkippedNonCanonical       int `json:"skipped_non_canonical_records"`
	InferredCanonicalFallback int `json:"inferred_canonical_records"`
	SkippedSweepOnlyRecords   int `json:"skipped_sweep_only_records"`
}

DeviceStatsMeta captures bookkeeping details for debugging the stats snapshot pipeline.

type DeviceStatsSnapshot added in v1.0.55 

type DeviceStatsSnapshot struct {
	Timestamp             time.Time        `json:"timestamp"`
	TotalDevices          int              `json:"total_devices"`
	AvailableDevices      int              `json:"available_devices"`
	UnavailableDevices    int              `json:"unavailable_devices"`
	ActiveDevices         int              `json:"active_devices"`
	DevicesWithCollectors int              `json:"devices_with_collectors"`
	DevicesWithICMP       int              `json:"devices_with_icmp"`
	DevicesWithSNMP       int              `json:"devices_with_snmp"`
	DevicesWithSysmon     int              `json:"devices_with_sysmon"`
	Partitions            []PartitionStats `json:"partitions"`
}

DeviceStatsSnapshot aggregates system-wide device metrics that are expensive to compute directly from the warehouse. The core Service publishes updates at a fixed cadence.

type DeviceTarget added in v1.0.54 

type DeviceTarget struct {
	Network    string            `json:"network"`               // CIDR or IP address
	SweepModes []SweepMode       `json:"sweep_modes,omitempty"` // Specific sweep modes for this device
	QueryLabel string            `json:"query_label,omitempty"` // Source query label
	Source     string            `json:"source,omitempty"`      // Discovery source (armis, netbox, etc.)
	Metadata   map[string]string `json:"metadata,omitempty"`    // Additional metadata from discovery
}

DeviceTarget represents a single device/network with its specific sweep configuration

type DeviceUpdate 

type DeviceUpdate struct {
	DeviceID    string            `json:"device_id"`
	IP          string            `json:"ip"`
	Source      DiscoverySource   `json:"source"`
	AgentID     string            `json:"agent_id"`
	PollerID    string            `json:"poller_id"`
	Partition   string            `json:"partition,omitempty"`    // Optional partition for multi-tenant systems
	ServiceType *ServiceType      `json:"service_type,omitempty"` // Type of service component (poller/agent/checker)
	ServiceID   string            `json:"service_id,omitempty"`   // ID of the service component
	Timestamp   time.Time         `json:"timestamp"`
	Hostname    *string           `json:"hostname,omitempty"`
	MAC         *string           `json:"mac,omitempty"`
	Metadata    map[string]string `json:"metadata,omitempty"`
	IsAvailable bool              `json:"is_available"`
	Confidence  int               `json:"confidence"`
}

DeviceUpdate represents an update to a device from a discovery source

func CreateAgentDeviceUpdate added in v1.0.55 

func CreateAgentDeviceUpdate(agentID, pollerID, hostIP, partition string, metadata map[string]string) *DeviceUpdate

CreateAgentDeviceUpdate creates a DeviceUpdate for an agent to register itself as a device

func CreateCheckerDeviceUpdate added in v1.0.55 

func CreateCheckerDeviceUpdate(checkerID, checkerKind, agentID, pollerID, hostIP, partition string, metadata map[string]string) *DeviceUpdate

CreateCheckerDeviceUpdate creates a DeviceUpdate for a checker to register itself as a device

func CreateCoreServiceDeviceUpdate added in v1.0.61 

func CreateCoreServiceDeviceUpdate(serviceType ServiceType, serviceID, hostIP, partition string, metadata map[string]string) *DeviceUpdate

CreateCoreServiceDeviceUpdate creates a DeviceUpdate for a core service (datasvc, sync, mapper, otel, zen, core) to register itself as a device with a stable service device ID that survives IP changes.

func CreatePollerDeviceUpdate added in v1.0.55 

func CreatePollerDeviceUpdate(pollerID, hostIP, partition string, metadata map[string]string) *DeviceUpdate

CreatePollerDeviceUpdate creates a DeviceUpdate for a poller to register itself as a device

type DictionaryConfig 

type DictionaryConfig struct {
	Name       string   `json:"name"`       // e.g., "asn_dictionary"
	Source     string   `json:"source"`     // e.g., "/path/to/asn.csv"
	Keys       []string `json:"keys"`       // e.g., ["ip"]
	Attributes []string `json:"attributes"` // e.g., ["asn", "name"]
	Layout     string   `json:"layout"`     // e.g., "hashed"
}

DictionaryConfig represents a custom dictionary for enrichment

type DiscoveredField 

type DiscoveredField[T any] struct {
	Value       T               `json:"value"`
	Source      DiscoverySource `json:"source"`
	LastUpdated time.Time       `json:"last_updated"`
	Confidence  int             `json:"confidence"` // 1-10 scale for source priority
	AgentID     string          `json:"agent_id"`
	PollerID    string          `json:"poller_id"`
}

DiscoveredField represents a field value with its discovery source and metadata

type DiscoveredInterface 

type DiscoveredInterface struct {
	Timestamp     time.Time       `json:"timestamp"`
	AgentID       string          `json:"agent_id"`
	PollerID      string          `json:"poller_id"`
	DeviceIP      string          `json:"device_ip"`
	DeviceID      string          `json:"device_id"`
	IfIndex       int32           `json:"ifIndex"`
	IfName        string          `json:"ifName"`
	IfDescr       string          `json:"ifDescr"`
	IfAlias       string          `json:"ifAlias"`
	IfSpeed       uint64          `json:"ifSpeed"`
	IfPhysAddress string          `json:"ifPhysAddress"`
	IPAddresses   []string        `json:"ip_addresses"`
	IfAdminStatus int32           `json:"ifAdminStatus"`
	IfOperStatus  int32           `json:"ifOperStatus"`
	Metadata      json.RawMessage `json:"metadata"`
}

DiscoveredInterface represents a network interface discovered by the system

type DiscoverySource 

type DiscoverySource string

DiscoverySource represents the different ways devices can be discovered

type DiscoverySourceInfo 

type DiscoverySourceInfo struct {
	Source     DiscoverySource `json:"source"`
	AgentID    string          `json:"agent_id"`
	PollerID   string          `json:"poller_id"`
	FirstSeen  time.Time       `json:"first_seen"`
	LastSeen   time.Time       `json:"last_seen"`
	Confidence int             `json:"confidence"`
}

DiscoverySourceInfo tracks when and how a device was discovered by each source

type DiskMetric 

type DiskMetric struct {
	// Mount point path
	MountPoint string `json:"mount_point" example:"/var"`
	// Bytes currently in use
	UsedBytes uint64 `json:"used_bytes" example:"10737418240"`
	// Total capacity in bytes
	TotalBytes uint64 `json:"total_bytes" example:"107374182400"`
	// When this metric was collected
	Timestamp time.Time `json:"timestamp" example:"2025-04-24T14:15:22Z"`
	// Host identifier for the agent that collected this metric
	HostID string `json:"host_id,omitempty" example:"server-east-1"`
	// Host IP address for the agent that collected this metric
	HostIP string `json:"host_ip,omitempty" example:"192.168.1.100"`
	// ServiceRadar agent identifier
	AgentID string `json:"agent_id,omitempty" example:"agent-1234"`
}

DiskMetric represents disk usage for a single mount point. @Description Storage usage metrics for a disk partition.

type Duration 

type Duration time.Duration

func (Duration) MarshalJSON added in v1.0.55 

func (d Duration) MarshalJSON() ([]byte, error)

func (*Duration) UnmarshalJSON 

func (d *Duration) UnmarshalJSON(b []byte) error

type EdgeOnboardingComponentType added in v1.0.55 

type EdgeOnboardingComponentType string

EdgeOnboardingComponentType identifies the resource represented by a package. 

const (
	EdgeOnboardingComponentTypePoller  EdgeOnboardingComponentType = "poller"
	EdgeOnboardingComponentTypeAgent   EdgeOnboardingComponentType = "agent"
	EdgeOnboardingComponentTypeChecker EdgeOnboardingComponentType = "checker"
	EdgeOnboardingComponentTypeNone    EdgeOnboardingComponentType = ""
)

type EdgeOnboardingConfig added in v1.0.55 

type EdgeOnboardingConfig struct {
	Enabled                bool                         `json:"enabled"`
	EncryptionKey          string                       `json:"encryption_key" sensitive:"true"`
	DefaultSelectors       []string                     `json:"default_selectors,omitempty"`
	DefaultMetadata        map[string]map[string]string `json:"default_metadata,omitempty"`
	DownstreamPathTemplate string                       `json:"downstream_path_template,omitempty"`
	JoinTokenTTL           Duration                     `json:"join_token_ttl,omitempty"`
	DownloadTokenTTL       Duration                     `json:"download_token_ttl,omitempty"`
	PollerIDPrefix         string                       `json:"poller_id_prefix,omitempty"`
}

EdgeOnboardingConfig configures secure edge poller enrollment.

type EdgeOnboardingCreateRequest added in v1.0.55 

type EdgeOnboardingCreateRequest struct {
	Label              string
	ComponentID        string
	ComponentType      EdgeOnboardingComponentType
	ParentType         EdgeOnboardingComponentType
	SecurityMode       string
	ParentID           string
	PollerID           string
	Site               string
	Selectors          []string
	MetadataJSON       string
	CheckerKind        string
	CheckerConfigJSON  string
	Notes              string
	CreatedBy          string
	JoinTokenTTL       time.Duration
	DownloadTokenTTL   time.Duration
	DownstreamSPIFFEID string
	DataSvcEndpoint    string // DataSvc gRPC endpoint (e.g., "23.138.124.23:50057")
}

EdgeOnboardingCreateRequest drives package provisioning.

type EdgeOnboardingCreateResult added in v1.0.55 

type EdgeOnboardingCreateResult struct {
	Package           *EdgeOnboardingPackage
	JoinToken         string
	DownloadToken     string
	BundlePEM         []byte
	MTLSBundle        []byte
	DownstreamEntryID string
}

EdgeOnboardingCreateResult bundles the stored package and sensitive artifacts.

type EdgeOnboardingDeliverRequest added in v1.0.55 

type EdgeOnboardingDeliverRequest struct {
	PackageID     string
	DownloadToken string
	Actor         string
	SourceIP      string
}

EdgeOnboardingDeliverRequest captures download token verification.

type EdgeOnboardingDeliverResult added in v1.0.55 

type EdgeOnboardingDeliverResult struct {
	Package    *EdgeOnboardingPackage
	JoinToken  string
	BundlePEM  []byte
	MTLSBundle []byte
}

EdgeOnboardingDeliverResult contains decrypted artifacts for installers.

type EdgeOnboardingEvent added in v1.0.55 

type EdgeOnboardingEvent struct {
	PackageID   string    `json:"package_id"`
	EventTime   time.Time `json:"event_time"`
	EventType   string    `json:"event_type"`
	Actor       string    `json:"actor"`
	SourceIP    string    `json:"source_ip,omitempty"`
	DetailsJSON string    `json:"details_json,omitempty"`
}

EdgeOnboardingEvent captures audit trail entries for onboarding packages.

type EdgeOnboardingListFilter added in v1.0.55 

type EdgeOnboardingListFilter struct {
	PollerID    string
	ComponentID string
	ParentID    string
	Statuses    []EdgeOnboardingStatus
	Limit       int
	Types       []EdgeOnboardingComponentType
}

EdgeOnboardingListFilter allows filtering onboarding packages.

type EdgeOnboardingPackage added in v1.0.55 

type EdgeOnboardingPackage struct {
	PackageID              string                      `json:"package_id"`
	Label                  string                      `json:"label"`
	ComponentID            string                      `json:"component_id"`
	ComponentType          EdgeOnboardingComponentType `json:"component_type"`
	ParentType             EdgeOnboardingComponentType `json:"parent_type,omitempty"`
	ParentID               string                      `json:"parent_id,omitempty"`
	PollerID               string                      `json:"poller_id"`
	Site                   string                      `json:"site,omitempty"`
	Status                 EdgeOnboardingStatus        `json:"status"`
	SecurityMode           string                      `json:"security_mode,omitempty"`
	DownstreamEntryID      string                      `json:"downstream_entry_id,omitempty"`
	DownstreamSPIFFEID     string                      `json:"downstream_spiffe_id"`
	Selectors              []string                    `json:"selectors,omitempty"`
	JoinTokenCiphertext    string                      `json:"join_token_ciphertext"`
	JoinTokenExpiresAt     time.Time                   `json:"join_token_expires_at"`
	BundleCiphertext       string                      `json:"bundle_ciphertext"`
	DownloadTokenHash      string                      `json:"download_token_hash"`
	DownloadTokenExpiresAt time.Time                   `json:"download_token_expires_at"`
	CreatedBy              string                      `json:"created_by"`
	CreatedAt              time.Time                   `json:"created_at"`
	UpdatedAt              time.Time                   `json:"updated_at"`
	DeliveredAt            *time.Time                  `json:"delivered_at,omitempty"`
	ActivatedAt            *time.Time                  `json:"activated_at,omitempty"`
	ActivatedFromIP        *string                     `json:"activated_from_ip,omitempty"`
	LastSeenSPIFFEID       *string                     `json:"last_seen_spiffe_id,omitempty"`
	RevokedAt              *time.Time                  `json:"revoked_at,omitempty"`
	DeletedAt              *time.Time                  `json:"deleted_at,omitempty"`
	DeletedBy              string                      `json:"deleted_by,omitempty"`
	DeletedReason          string                      `json:"deleted_reason,omitempty"`
	MetadataJSON           string                      `json:"metadata_json,omitempty"`
	CheckerKind            string                      `json:"checker_kind,omitempty"`
	CheckerConfigJSON      string                      `json:"checker_config_json,omitempty"`
	KVRevision             uint64                      `json:"kv_revision,omitempty"`
	Notes                  string                      `json:"notes,omitempty"`
}

EdgeOnboardingPackage models the material tracked for an edge poller bootstrap.

type EdgeOnboardingRevokeRequest added in v1.0.55 

type EdgeOnboardingRevokeRequest struct {
	PackageID string
	Actor     string
	Reason    string
	SourceIP  string
}

EdgeOnboardingRevokeRequest describes a package revocation.

type EdgeOnboardingRevokeResult added in v1.0.55 

type EdgeOnboardingRevokeResult struct {
	Package *EdgeOnboardingPackage
}

EdgeOnboardingRevokeResult returns the updated package after revocation.

type EdgeOnboardingStatus added in v1.0.55 

type EdgeOnboardingStatus string

EdgeOnboardingStatus represents the lifecycle state of an onboarding package. 

const (
	EdgeOnboardingStatusIssued    EdgeOnboardingStatus = "issued"
	EdgeOnboardingStatusDelivered EdgeOnboardingStatus = "delivered"
	EdgeOnboardingStatusActivated EdgeOnboardingStatus = "activated"
	EdgeOnboardingStatusRevoked   EdgeOnboardingStatus = "revoked"
	EdgeOnboardingStatusExpired   EdgeOnboardingStatus = "expired"
	EdgeOnboardingStatusDeleted   EdgeOnboardingStatus = "deleted"
)

type EdgeTemplate added in v1.0.69 

type EdgeTemplate struct {
	ComponentType EdgeOnboardingComponentType `json:"component_type"` // Component type (e.g., "checker")
	Kind          string                      `json:"kind"`           // Component kind (e.g., "sysmon", "snmp", "rperf")
	SecurityMode  string                      `json:"security_mode"`  // Security mode for the template (e.g., "mtls", "spire")
	TemplateKey   string                      `json:"template_key"`   // Full KV key path (e.g., "templates/checkers/mtls/sysmon.json")
}

EdgeTemplate represents an available component template in KV.

type ErrorResponse 

type ErrorResponse struct {
	// Error message
	Message string `json:"message" example:"Invalid request parameters"`
	// HTTP status code
	Status int `json:"status" example:"400"`
}

ErrorResponse represents an API error response. @Description Error information returned from the API.

type EventRow 

type EventRow struct {
	SpecVersion     string
	ID              string
	Source          string
	Type            string
	DataContentType string
	Subject         string
	RemoteAddr      string
	Host            string
	Level           int32
	Severity        string
	ShortMessage    string
	EventTimestamp  time.Time
	Version         string
	RawData         string
}

EventRow represents a single row in the events database table.

type EventsConfig 

type EventsConfig struct {
	Enabled    bool     `json:"enabled"`
	StreamName string   `json:"stream_name"`
	Subjects   []string `json:"subjects"`
}

EventsConfig configures the event publishing system

func (*EventsConfig) Validate 

func (c *EventsConfig) Validate() error

Validate ensures the events configuration is valid

type FeatureFlags added in v1.0.55 

type FeatureFlags struct {
	UseLogDigest           *bool `json:"use_log_digest,omitempty"`
	UseStatsCache          *bool `json:"use_stats_cache,omitempty"`
	UseDeviceSearchPlanner *bool `json:"use_device_search_planner,omitempty"`
	RequireDeviceRegistry  *bool `json:"require_device_registry,omitempty"`
}

FeatureFlags captures optional feature toggles for the core service.

type FingerprintingConfig added in v1.0.59 

type FingerprintingConfig struct {
	Enabled    bool     `json:"enabled"`
	PortBudget int      `json:"port_budget,omitempty"`
	Timeout    Duration `json:"timeout,omitempty"`
}

FingerprintingConfig configures lightweight fingerprinting probes. 

type Header struct {
	Key   string `json:"key"`
	Value string `json:"value"`
}

Header represents a custom HTTP header.

type HostResult 

type HostResult struct {
	Host         string              `json:"host"`
	Available    bool                `json:"available"`
	FirstSeen    time.Time           `json:"first_seen"`
	LastSeen     time.Time           `json:"last_seen"`
	PortResults  []*PortResult       `json:"port_results,omitempty"`
	PortMap      map[int]*PortResult `json:"-"` // O(1) port lookup, excluded from JSON
	ICMPStatus   *ICMPStatus         `json:"icmp_status,omitempty"`
	ResponseTime time.Duration       `json:"response_time"`
}

HostResult represents all results for a single host.

type ICMPStatus 

type ICMPStatus struct {
	Available  bool          `json:"available"`
	RoundTrip  time.Duration `json:"round_trip"`
	PacketLoss float64       `json:"packet_loss"`
}

ICMPStatus represents ICMP ping results.

type IdentityDriftConfig added in v1.0.59 

type IdentityDriftConfig struct {
	BaselineDevices  int  `json:"baseline_devices,omitempty"`
	TolerancePercent int  `json:"tolerance_percent,omitempty"`
	PauseOnDrift     bool `json:"pause_on_drift,omitempty"`
	AlertOnDrift     bool `json:"alert_on_drift,omitempty"`
}

IdentityDriftConfig configures gating based on device cardinality drift.

type IdentityReaperConfig added in v1.0.59 

type IdentityReaperConfig struct {
	Interval Duration                         `json:"interval,omitempty"`
	Profiles map[string]IdentityReaperProfile `json:"profiles,omitempty"`
}

IdentityReaperConfig configures the sightings/low-confidence reaper.

type IdentityReaperProfile added in v1.0.59 

type IdentityReaperProfile struct {
	TTL         Duration `json:"ttl"`
	AllowIPAsID bool     `json:"allow_ip_as_id,omitempty"`
}

IdentityReaperProfile configures TTL and policy toggles for a subnet class.

type IdentityReconciliationConfig added in v1.0.59 

type IdentityReconciliationConfig struct {
	Enabled        bool                 `json:"enabled"`
	SightingsOnly  bool                 `json:"sightings_only_mode,omitempty"`
	Promotion      PromotionConfig      `json:"promotion,omitempty"`
	Fingerprinting FingerprintingConfig `json:"fingerprinting,omitempty"`
	Reaper         IdentityReaperConfig `json:"reaper,omitempty"`
	Drift          IdentityDriftConfig  `json:"drift,omitempty"`
}

IdentityReconciliationConfig gates the new IRE pipeline.

type KVEndpoint added in v1.0.55 

type KVEndpoint struct {
	ID      string `json:"id"`
	Name    string `json:"name"`
	Address string `json:"address"`
	Domain  string `json:"domain"`
	Type    string `json:"type,omitempty"` // hub | leaf | other

}

KVEndpoint describes a reachable KV gRPC endpoint and its JetStream domain.

type LogCounters added in v1.0.55 

type LogCounters struct {
	UpdatedAt time.Time            `json:"updated_at"`
	Window1H  SeverityWindowCounts `json:"window_1h"`
	Window24H SeverityWindowCounts `json:"window_24h"`
}

LogCounters tracks rolling window statistics for recent high-severity logs.

type LogDigestSnapshot added in v1.0.55 

type LogDigestSnapshot struct {
	Entries  []LogSummary `json:"entries"`
	Counters LogCounters  `json:"counters"`
}

LogDigestSnapshot represents a pre-computed digest of critical logs and counters.

type LogSummary added in v1.0.55 

type LogSummary struct {
	Timestamp   time.Time `json:"timestamp"`
	Severity    string    `json:"severity"`
	ServiceName string    `json:"service_name,omitempty"`
	Body        string    `json:"body,omitempty"`
	TraceID     string    `json:"trace_id,omitempty"`
	SpanID      string    `json:"span_id,omitempty"`
}

LogSummary provides a compact view of high-severity log entries that are surfaced on dashboards.

type LoginRequest 

type LoginRequest struct {
	// Username for authentication
	Username string `json:"username" example:"admin"`
	// Password for authentication
	Password string `json:"password" example:"p@ssw0rd"`
}

LoginRequest represents a login request. @Description Authentication request with username and password.

type MCPConfigRef 

type MCPConfigRef struct {
	Enabled bool   `json:"enabled"`
	APIKey  string `json:"api_key" sensitive:"true"`
}

MCPConfigRef represents MCP configuration to avoid circular imports

type MemoryMetric 

type MemoryMetric struct {
	// Bytes currently in use
	UsedBytes uint64 `json:"used_bytes" example:"4294967296"`
	// Total memory capacity in bytes
	TotalBytes uint64 `json:"total_bytes" example:"17179869184"`
	// When this metric was collected
	Timestamp time.Time `json:"timestamp" example:"2025-04-24T14:15:22Z"`
	// Host identifier for the agent that collected this metric
	HostID string `json:"host_id,omitempty" example:"server-east-1"`
	// Host IP address for the agent that collected this metric
	HostIP string `json:"host_ip,omitempty" example:"192.168.1.100"`
	// ServiceRadar agent identifier
	AgentID string `json:"agent_id,omitempty" example:"agent-1234"`
}

MemoryMetric represents system memory usage. @Description System memory utilization metrics.

type MergeAuditEvent added in v1.0.59 

type MergeAuditEvent struct {
	EventID         string            `json:"event_id"`
	FromDeviceID    string            `json:"from_device_id"`
	ToDeviceID      string            `json:"to_device_id"`
	Reason          string            `json:"reason,omitempty"`
	ConfidenceScore *float64          `json:"confidence_score,omitempty"`
	Source          string            `json:"source,omitempty"`
	Details         map[string]string `json:"details,omitempty"`
	CreatedAt       time.Time         `json:"created_at"`
}

MergeAuditEvent records merges between devices for auditability.

type MetricPoint 

type MetricPoint struct {
	// The time when this metric was collected
	Timestamp time.Time `json:"timestamp" example:"2025-04-24T14:15:22Z"`
	// The response time in milliseconds
	ResponseTime int64 `json:"response_time" example:"42"`
	// The name of the service this metric is for
	ServiceName string `json:"service_name" example:"postgres"`
	// The device ID this metric is associated with (partition:ip)
	DeviceID string `json:"device_id,omitempty" example:"default:192.168.1.100"`
	// The partition this metric belongs to
	Partition string `json:"partition,omitempty" example:"default"`
	// The agent ID that collected this metric
	AgentID string `json:"agent_id,omitempty" example:"agent-1234"`
	// The poller ID that requested this metric
	PollerID string `json:"poller_id,omitempty" example:"demo-staging"`
}

MetricPoint represents a single performance metric measurement. @Description A single point of performance metric data with timestamp information.

type Metrics 

type Metrics struct {
	Enabled             bool  `json:"enabled"`
	Retention           int32 `json:"retention"`
	MaxPollers          int32 `json:"max_pollers"`
	DeviceRetentionDays int32 `json:"device_retention_days,omitempty"` // Days to keep devices in unified_devices (default: 3)
}

type MetricsConfig 

type MetricsConfig struct {
	// Whether metrics collection is enabled
	Enabled bool `json:"metrics_enabled" example:"true"`
	// How long metrics are kept before being purged (in days)
	Retention int32 `json:"metrics_retention" example:"30"`
	// Maximum number of pollers to track metrics for
	MaxPollers int32 `json:"max_pollers" example:"1000"`
}

MetricsConfig contains configuration for metrics collection. @Description Configuration settings for metrics collection and storage.

type NATSConfig 

type NATSConfig struct {
	URL      string          `json:"url"`
	Domain   string          `json:"domain,omitempty"`
	Security *SecurityConfig `json:"security,omitempty"`
}

NATSConfig configures NATS connectivity

func (*NATSConfig) Validate 

func (c *NATSConfig) Validate() error

Validate ensures the NATS configuration is valid

type NetflowConfig 

type NetflowConfig struct {
	ListenAddr     string             `json:"listen_addr"`
	NATSURL        string             `json:"nats_url"`
	StreamName     string             `json:"stream_name"`
	ConsumerName   string             `json:"consumer_name"`
	Security       *SecurityConfig    `json:"security"`
	EnabledFields  []ColumnKey        `json:"enabled_fields"`
	DisabledFields []ColumnKey        `json:"disabled_fields"`
	Dictionaries   []DictionaryConfig `json:"dictionaries"`
	CNPG           *CNPGDatabase      `json:"cnpg"`
}

NetflowConfig holds the configuration for the NetFlow consumer service.

type NetflowMetric 

type NetflowMetric struct {
	Timestamp        time.Time `json:"timestamp"`
	SrcAddr          string    `json:"src_addr"`
	DstAddr          string    `json:"dst_addr"`
	SrcPort          uint32    `json:"src_port"`
	DstPort          uint32    `json:"dst_port"`
	Protocol         uint32    `json:"protocol"`
	Bytes            uint64    `json:"bytes"`
	Packets          uint64    `json:"packets"`
	ForwardingStatus uint32    `json:"forwarding_status"`
	NextHop          string    `json:"next_hop"`
	SamplerAddress   string    `json:"sampler_address"`
	SrcAs            uint32    `json:"src_as"`
	DstAs            uint32    `json:"dst_as"`
	IPTos            uint32    `json:"ip_tos"`
	VlanID           uint32    `json:"vlan_id"`
	BgpNextHop       string    `json:"bgp_next_hop"`
	Metadata         string    `json:"metadata"`
}

NetflowMetric represents a NetFlow datapoint for the netflow_metrics stream.

type NetworkSighting added in v1.0.59 

type NetworkSighting struct {
	SightingID    string                   `json:"sighting_id,omitempty"`
	Partition     string                   `json:"partition"`
	IP            string                   `json:"ip"`
	SubnetID      *string                  `json:"subnet_id,omitempty"`
	Source        DiscoverySource          `json:"source"`
	Status        NetworkSightingStatus    `json:"status"`
	FirstSeen     time.Time                `json:"first_seen"`
	LastSeen      time.Time                `json:"last_seen"`
	TTLExpiresAt  *time.Time               `json:"ttl_expires_at,omitempty"`
	FingerprintID *string                  `json:"fingerprint_id,omitempty"`
	Metadata      map[string]string        `json:"metadata,omitempty"`
	Promotion     *SightingPromotionStatus `json:"promotion,omitempty"`
}

NetworkSighting captures a low-confidence observation prior to promotion.

type NetworkSightingStatus added in v1.0.59 

type NetworkSightingStatus string

NetworkSightingStatus represents the lifecycle state for a sighting. 

const (
	SightingStatusActive    NetworkSightingStatus = "active"
	SightingStatusPromoted  NetworkSightingStatus = "promoted"
	SightingStatusExpired   NetworkSightingStatus = "expired"
	SightingStatusDismissed NetworkSightingStatus = "dismissed"
)

type OTELLogRow added in v1.0.55 

type OTELLogRow struct {
	Timestamp          time.Time
	TraceID            string
	SpanID             string
	SeverityText       string
	SeverityNumber     int32
	Body               string
	ServiceName        string
	ServiceVersion     string
	ServiceInstance    string
	ScopeName          string
	ScopeVersion       string
	Attributes         string
	ResourceAttributes string
}

OTELLogRow represents a normalized log entry emitted by OTEL collectors.

type OTELMetricRow added in v1.0.55 

type OTELMetricRow struct {
	Timestamp       time.Time
	TraceID         string
	SpanID          string
	ServiceName     string
	SpanName        string
	SpanKind        string
	DurationMs      float64
	DurationSeconds float64
	MetricType      string
	HTTPMethod      string
	HTTPRoute       string
	HTTPStatusCode  string
	GRPCService     string
	GRPCMethod      string
	GRPCStatusCode  string
	IsSlow          bool
	Component       string
	Level           string
}

OTELMetricRow captures a single OTEL performance metric sample.

type OTELTraceRow added in v1.0.55 

type OTELTraceRow struct {
	Timestamp          time.Time
	TraceID            string
	SpanID             string
	ParentSpanID       string
	Name               string
	Kind               int32
	StartTimeUnixNano  int64
	EndTimeUnixNano    int64
	ServiceName        string
	ServiceVersion     string
	ServiceInstance    string
	ScopeName          string
	ScopeVersion       string
	StatusCode         int32
	StatusMessage      string
	Attributes         string
	ResourceAttributes string
	Events             string
	Links              string
}

OTELTraceRow stores a single OTEL trace span row.

type PartitionStats added in v1.0.55 

type PartitionStats struct {
	PartitionID    string `json:"partition_id"`
	DeviceCount    int    `json:"device_count"`
	ActiveCount    int    `json:"active_count"`
	AvailableCount int    `json:"available_count"`
}

PartitionStats captures per-partition device counts for dashboard consumption.

type PollerConfig 

type PollerConfig struct {
	Agents       map[string]AgentDefinition `json:"agents"`        // Map of agent ID to agent definition
	CloudAddress string                     `json:"cloud_address"` // Address of cloud service
	PollInterval Duration                   `json:"poll_interval"` // How often to poll agents
	PollerID     string                     `json:"poller_id"`     // Unique identifier for this poller
}

PollerConfig represents the configuration for a poller instance.

type PollerHealthEventData 

type PollerHealthEventData struct {
	PollerID       string    `json:"poller_id"`
	PreviousState  string    `json:"previous_state"`
	CurrentState   string    `json:"current_state"`
	Timestamp      time.Time `json:"timestamp"`
	LastSeen       time.Time `json:"last_seen"`
	Host           string    `json:"host,omitempty"`
	RemoteAddr     string    `json:"remote_addr,omitempty"`
	SourceIP       string    `json:"source_ip,omitempty"`
	Partition      string    `json:"partition,omitempty"`
	AlertSent      bool      `json:"alert_sent"`
	RecoveryReason string    `json:"recovery_reason,omitempty"`
}

PollerHealthEventData represents the data payload for poller health events.

type PollerHistory 

type PollerHistory struct {
	// Unique identifier for the poller
	PollerID string `json:"poller_id" example:"poller-prod-east-01"`
	// When this status was recorded
	Timestamp time.Time `json:"timestamp" example:"2025-04-24T14:15:22Z"`
	// Whether the poller was healthy at this time
	IsHealthy bool `json:"is_healthy" example:"true"`
	// Services status at this time
	Services []ServiceStatus `json:"services"`
}

PollerHistory represents historical status of a poller. @Description Historical status information for a poller.

type PollerHistoryPoint 

type PollerHistoryPoint struct {
	// When this status was recorded
	Timestamp time.Time `json:"timestamp" example:"2025-04-24T14:15:22Z"`
	// Whether the poller was healthy at this time
	IsHealthy bool `json:"is_healthy" example:"true"`
}

PollerHistoryPoint represents a simplified historical health state. @Description Simplified historical health state for a poller.

type PollerStatus 

type PollerStatus struct {
	// Unique identifier for the poller
	PollerID string `json:"poller_id" example:"poller-prod-east-01"`
	// Whether the poller is currently healthy
	IsHealthy bool `json:"is_healthy" example:"true"`
	// List of services monitored by this poller
	Services []ServiceStatus `json:"services"`
	// How long the poller has been running
	UpTime string `json:"uptime" example:"3d 2h 15m"`
	// When the poller was first seen by the system
	FirstSeen time.Time `json:"first_seen" example:"2025-04-20T10:00:00Z"`
	// Last time the poller reported its status
	LastSeen time.Time `json:"last_seen" example:"2025-04-24T14:15:22Z"`
	// IP address of the host where the poller is running
	HostIP string `json:"host_ip,omitempty" example:"192.168.1.100"`
	// Optional metrics data points
	Metrics []MetricPoint `json:"metrics,omitempty"`
	// Metadata about the poller
	LastEvaluated time.Time `json:"last_evaluated" example:"2025-04-24T14:15:22Z"`
	// AlertSent indicates if an alert has been sent for this poller
	AlertSent bool `json:"alert_sent" example:"false"`
}

PollerStatus represents the status of a poller. @Description Status information about a service poller.

type PortCount 

type PortCount struct {
	Port      int `json:"port"`
	Available int `json:"available"`
}

type PortResult 

type PortResult struct {
	Port      int           `json:"port"`
	Available bool          `json:"available"`
	RespTime  time.Duration `json:"response_time"`
	Service   string        `json:"service,omitempty"` // Optional service identification
}

PortResult represents a single port scan result.

type PortStatus 

type PortStatus struct {
	Port      int32 `json:"port"`
	Available int32 `json:"available"`
}

PortStatus represents port availability information.

type ProcessMetric 

type ProcessMetric struct {
	// Process ID
	PID uint32 `json:"pid" example:"1234"`
	// Process name
	Name string `json:"name" example:"nginx"`
	// CPU usage percentage
	CPUUsage float32 `json:"cpu_usage" example:"2.5"`
	// Memory usage in bytes
	MemoryUsage uint64 `json:"memory_usage" example:"104857600"`
	// Process status
	Status string `json:"status" example:"Running"`
	// Process start time
	StartTime string `json:"start_time" example:"2025-04-24T14:15:22Z"`
	// When this metric was collected
	Timestamp time.Time `json:"timestamp" example:"2025-04-24T14:15:22Z"`
	// Host identifier for the agent that collected this metric
	HostID string `json:"host_id,omitempty" example:"server-east-1"`
	// Host IP address for the agent that collected this metric
	HostIP string `json:"host_ip,omitempty" example:"192.168.1.100"`
	// ServiceRadar agent identifier
	AgentID string `json:"agent_id,omitempty" example:"agent-1234"`
}

ProcessMetric represents system process metrics. @Description Process utilization metrics for running processes.

type PromotionConfig added in v1.0.59 

type PromotionConfig struct {
	Enabled            bool     `json:"enabled"`
	ShadowMode         bool     `json:"shadow_mode,omitempty"`
	MinPersistence     Duration `json:"min_persistence,omitempty"`
	RequireHostname    bool     `json:"require_hostname,omitempty"`
	RequireFingerprint bool     `json:"require_fingerprint,omitempty"`
}

PromotionConfig configures automated promotion thresholds.

type QueryConfig 

type QueryConfig struct {
	Label      string      `json:"label"`       // Name or description of the query
	Query      string      `json:"query"`       // The query string
	SweepModes []SweepMode `json:"sweep_modes"` // Sweep modes to apply to devices from this query
}

QueryConfig represents a single labeled query.

type RBACConfig added in v1.0.55 

type RBACConfig struct {
	// Map of identities to roles. Keys can be one of:
	// - "provider:subject" (preferred, e.g., "google:1122334455")
	// - "provider:email" (lowercased, e.g., "github:admin@company.com")
	// - legacy "username-or-email" (lowercased)
	// Example: {"local:admin":["admin"], "google:1122334455":["admin"], "user1":["user"]}
	UserRoles map[string][]string `json:"user_roles"`
	// Map of roles to their permissions
	RolePermissions map[string][]string `json:"role_permissions" example:"admin:[config:read,config:write,config:delete],user:[config:read]"`
	// Map of routes to required roles (can be string array or map of methods to roles)
	RouteProtection map[string]interface{} `json:"route_protection"`
}

RBACConfig contains role-based access control configuration.

type ReaperConfig added in v1.0.59 

type ReaperConfig struct {
	Interval Duration `json:"interval"`
	TTL      Duration `json:"ttl"`
}

ReaperConfig configures the stale device reaper.

type RefreshTokenRequest 

type RefreshTokenRequest struct {
	// JWT refresh token
	RefreshToken string `json:"refresh_token" example:"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."`
}

RefreshTokenRequest represents a token refresh request. @Description Request to refresh an expired access token.

type Result 

type Result struct {
	Target     Target
	Available  bool
	FirstSeen  time.Time
	LastSeen   time.Time
	RespTime   time.Duration
	PacketLoss float64
	Error      error
	Metadata   map[string]interface{}
}

Result represents the outcome of a sweep against a target.

type ResultFilter 

type ResultFilter struct {
	Host      string
	Port      int
	StartTime time.Time
	EndTime   time.Time
	Available *bool
}

ResultFilter defines criteria for retrieving results.

type RperfMetric 

type RperfMetric struct {
	// When the test was performed
	Timestamp time.Time `json:"timestamp" example:"2025-04-24T14:15:22Z"`
	// Test name or identifier
	Name string `json:"name" example:"rperf_tcp_test"`
	// Network throughput in bits per second
	BitsPerSec float64 `json:"bits_per_second" example:"943215000"`
	// Total bytes received during the test
	BytesReceived int64 `json:"bytes_received" example:"12582912"`
	// Total bytes sent during the test
	BytesSent int64 `json:"bytes_sent" example:"12582912"`
	// Test duration in seconds
	Duration float64 `json:"duration" example:"10.05"`
	// Network jitter in milliseconds
	JitterMs float64 `json:"jitter_ms" example:"0.85"`
	// Percentage of packets lost during the test
	LossPercent float64 `json:"loss_percent" example:"0.02"`
	// Number of packets lost during the test
	PacketsLost int64 `json:"packets_lost" example:"2"`
	// Number of packets received during the test
	PacketsReceived int64 `json:"packets_received" example:"9998"`
	// Number of packets sent during the test
	PacketsSent int64 `json:"packets_sent" example:"10000"`
	// Whether the test was successful
	Success bool `json:"success" example:"true"`
	// Target hostname or IP address
	Target string `json:"target" example:"192.168.1.1"`
	// ResponseTime in milliseconds
	ResponseTime int64 `json:"response_time" example:"15"`
	// Error message if test failed (null if successful)
	Error *string `json:"error,omitempty" example:"connection refused"`
	// AgentID of the agent that performed the test
	AgentID string `json:"agent_id"`
	// ServiceName of the service that performed the test
	ServiceName string `json:"service_name"`
	// ServiceType of the service that performed the test
	ServiceType string `json:"service_type"`
	// Version of the rperf service used for the test
	Version string `json:"version"`
}

RperfMetric represents a single network performance test result. @Description Single network performance test result for a specific target.

type RperfMetricData 

type RperfMetricData struct {
	// Array of test results for different targets
	Results []struct {
		// Target hostname or IP address
		Target string `json:"target" example:"192.168.1.1"`
		// Whether the test was successful
		Success bool `json:"success" example:"true"`
		// Error message if test failed
		Error *string `json:"error" example:"connection refused"`
		// Performance test summary results
		Summary struct {
			// Network throughput in bits per second
			BitsPerSecond float64 `json:"bits_per_second" example:"943215000"`
			// Total bytes received during the test
			BytesReceived int64 `json:"bytes_received" example:"12582912"`
			// Total bytes sent during the test
			BytesSent int64 `json:"bytes_sent" example:"12582912"`
			// Test duration in seconds
			Duration float64 `json:"duration" example:"10.05"`
			// Network jitter in milliseconds
			JitterMs float64 `json:"jitter_ms" example:"0.85"`
			// Percentage of packets lost during the test
			LossPercent float64 `json:"loss_percent" example:"0.02"`
			// Number of packets lost during the test
			PacketsLost int64 `json:"packets_lost" example:"2"`
			// Number of packets received during the test
			PacketsReceived int64 `json:"packets_received" example:"9998"`
			// Number of packets sent during the test
			PacketsSent int64 `json:"packets_sent" example:"10000"`
		} `json:"summary"`
	} `json:"results"`
	// ISO8601 timestamp when data was collected
	Timestamp string `json:"timestamp" example:"2025-04-24T14:15:22Z"`
}

RperfMetricData represents raw data received from the rperf service. @Description Raw network performance test data received from the rperf service.

type RperfMetricResponse 

type RperfMetricResponse struct {
	// Array of performance metrics
	Metrics []RperfMetric `json:"metrics"`
	// Error information if retrieval failed (not serialized)
	Err error `json:"-"`
}

RperfMetricResponse represents the API response for rperf metrics. @Description API response containing rperf metrics data.

type RperfMetrics 

type RperfMetrics struct {
	// Array of performance metrics for different targets
	Results []RperfMetric `json:"results"`
}

RperfMetrics represents processed network performance metrics. @Description Processed network performance metrics from rperf tests.

type SNMPConfig 

type SNMPConfig struct {
	NodeAddress string          `json:"node_address"`
	Timeout     Duration        `json:"timeout"`
	ListenAddr  string          `json:"listen_addr"`
	Security    *SecurityConfig `json:"security"`
	Targets     []Target        `json:"targets"`
}

SNMPConfig represents SNMP checker configuration.

type SNMPDiscoveryDataPayload 

type SNMPDiscoveryDataPayload struct {
	Devices    []*discoverypb.DiscoveredDevice    `json:"devices"`
	Interfaces []*discoverypb.DiscoveredInterface `json:"interfaces"`
	Topology   []*discoverypb.TopologyLink        `json:"topology"`
	AgentID    string                             `json:"agent_id"`  // Agent that ran the discovery engine
	PollerID   string                             `json:"poller_id"` // Poller that initiated the discovery
}

type SNMPMetric 

type SNMPMetric struct {
	// The name of the OID (Object Identifier)
	// @example "sysUpTime"
	OIDName string `json:"oid_name"`

	// The value of the metric
	// @example 12345
	Value interface{} `json:"value"`

	// The type of the value (e.g., integer, string)
	// @example "integer"
	ValueType string `json:"value_type"`

	// The time when the metric was collected
	// @example "2025-04-24T14:15:22Z"
	Timestamp time.Time `json:"timestamp"`

	// The scale factor applied to the value
	// @example 1.0
	Scale float64 `json:"scale"`

	// Whether the metric represents a delta value
	// @example false
	IsDelta bool `json:"is_delta"`
}

SNMPMetric represents an SNMP metric. @Description A metric collected via SNMP, including its value, type, and timestamp.

type SNMPMetricsPayload 

type SNMPMetricsPayload struct {
	PollerID  string          `json:"poller_id"` // Poller that collected the metrics
	AgentID   string          `json:"agent_id"`  // Agent that the poller belongs to
	Partition string          `json:"partition"` // Partition from SNMP checker config
	Targets   json.RawMessage `json:"targets"`   // Target statuses and metrics (map[string]snmp.TargetStatus)
}

SNMPMetricsPayload is the enhanced payload structure for SNMP metrics reports. It includes metadata about the collector infrastructure along with the target data. Deprecated: Use ServiceMetricsPayload instead

type SRQLConfig added in v1.0.55 

type SRQLConfig struct {
	Enabled bool     `json:"enabled"`
	BaseURL string   `json:"base_url"`
	APIKey  string   `json:"api_key,omitempty" sensitive:"true"`
	Timeout Duration `json:"timeout,omitempty"`
	Path    string   `json:"path,omitempty"`
}

SRQLConfig configures the external SRQL microservice integration.

type SSOConfig 

type SSOConfig struct {
	// OAuth client ID
	ClientID string `json:"client_id" example:"oauth-client-id"`
	// OAuth client secret
	ClientSecret string `json:"client_secret" example:"oauth-client-secret"`
	// OAuth scopes requested
	Scopes []string `json:"scopes" example:"profile,email"`
}

SSOConfig contains configuration for a single SSO provider. @Description Configuration for a single Single Sign-On provider.

type SecurityConfig 

type SecurityConfig struct {
	Mode           SecurityMode `json:"mode"`
	CertDir        string       `json:"cert_dir"`
	ServerName     string       `json:"server_name,omitempty"`
	Role           ServiceRole  `json:"role"`
	TLS            TLSConfig    `json:"tls"`
	TrustDomain    string       `json:"trust_domain,omitempty"`     // For SPIFFE
	ServerSPIFFEID string       `json:"server_spiffe_id,omitempty"` // Expected SPIFFE ID when acting as client
	WorkloadSocket string       `json:"workload_socket,omitempty"`  // For SPIFFE
}

SecurityConfig holds common security configuration.

type SecurityMode 

type SecurityMode string

SecurityMode defines the type of security to use. 

const (
	SecurityModeMTLS   SecurityMode = "mtls"
	SecurityModeSPIFFE SecurityMode = "spiffe"
	SecurityModeNone   SecurityMode = "none"
)

type Service 

type Service struct {
	PollerID    string            `json:"poller_id"`
	ServiceName string            `json:"service_name"`
	ServiceType string            `json:"service_type"`
	AgentID     string            `json:"agent_id"`
	DeviceID    string            `json:"device_id,omitempty"`
	Partition   string            `json:"partition,omitempty"`
	Timestamp   time.Time         `json:"timestamp"`
	Config      map[string]string `json:"config,omitempty"` // Service configuration including KV store info
}

Service represents a monitored service associated with a poller.

type ServiceMetricsPayload 

type ServiceMetricsPayload struct {
	PollerID    string          `json:"poller_id"`    // Poller that collected the metrics
	AgentID     string          `json:"agent_id"`     // Agent that the poller belongs to
	Partition   string          `json:"partition"`    // Partition for the collection
	ServiceType string          `json:"service_type"` // Type of service (snmp, sysmon, icmp, etc.)
	ServiceName string          `json:"service_name"` // Name of the service instance
	Data        json.RawMessage `json:"data"`         // Service-specific data payload
}

ServiceMetricsPayload is the enhanced payload structure for ALL service metrics reports. It includes metadata about the collector infrastructure along with the service-specific data.

type ServiceRole 

type ServiceRole string
const (
	RolePoller      ServiceRole = "poller"  // Client and Server
	RoleAgent       ServiceRole = "agent"   // Server only
	RoleCore        ServiceRole = "core"    // Server only
	RoleKVStore     ServiceRole = "kv"      // Server only
	RoleDataService ServiceRole = "datasvc" // Client and Server (NATS + gRPC)
	RoleChecker     ServiceRole = "checker" // Server only (for SNMP, Dusk checkers)
)

type ServiceStatus 

type ServiceStatus struct {
	// Name of the service
	Name string `json:"name" example:"postgres"`
	// Whether the service is currently available
	Available bool `json:"available" example:"true"`
	// Status message from the service
	Message string `json:"message" example:"Service is running normally"`
	// Type of service (e.g., "process", "port", "database", etc.)
	Type string `json:"type" example:"database"`
	// Detailed service-specific information as a JSON object
	Details     json.RawMessage `json:"details,omitempty"`
	PollerID    string          `json:"poller_id" example:"poller-prod-east-01"`
	AgentID     string          `json:"agent_id" example:"agent-prod-east-01"`
	ServiceName string          `json:"service_name" example:"postgres"`
	ServiceType string          `json:"service_type" example:"database"`
	DeviceID    string          `json:"device_id,omitempty" example:"default:192.168.1.100"`
	Partition   string          `json:"partition,omitempty" example:"default"`
	Timestamp   time.Time       `json:"timestamp" example:"2020-11-10T23:00:00+09:00"`
}

ServiceStatus represents the status of a monitored service. @Description Status information about a service monitored by a poller.

type ServiceType added in v1.0.55 

type ServiceType string

ServiceType represents the type of service component 

const (
	// ServiceTypePoller represents a poller service
	ServiceTypePoller ServiceType = "poller"
	// ServiceTypeAgent represents an agent service
	ServiceTypeAgent ServiceType = "agent"
	// ServiceTypeChecker represents a checker service
	ServiceTypeChecker ServiceType = "checker"
	// ServiceTypeNetworkDevice represents a discovered network device (not a service component)
	ServiceTypeNetworkDevice ServiceType = "network"
	// ServiceTypeDatasvc represents the datasvc/KV service
	ServiceTypeDatasvc ServiceType = "datasvc"
	// ServiceTypeKV is an alias for datasvc (legacy name)
	ServiceTypeKV ServiceType = "kv"
	// ServiceTypeSync represents the sync service
	ServiceTypeSync ServiceType = "sync"
	// ServiceTypeMapper represents the mapper service
	ServiceTypeMapper ServiceType = "mapper"
	// ServiceTypeOtel represents the OpenTelemetry collector service
	ServiceTypeOtel ServiceType = "otel"
	// ServiceTypeZen represents the zen service
	ServiceTypeZen ServiceType = "zen"
	// ServiceTypeCore represents the core service
	ServiceTypeCore ServiceType = "core"
)

type SeverityWindowCounts added in v1.0.55 

type SeverityWindowCounts struct {
	Total   int `json:"total"`
	Fatal   int `json:"fatal"`
	Error   int `json:"error"`
	Warning int `json:"warning"`
	Info    int `json:"info"`
	Debug   int `json:"debug"`
	Other   int `json:"other"`
}

SeverityWindowCounts captures per-severity totals for a specific rolling window.

type SightingEvent added in v1.0.59 

type SightingEvent struct {
	EventID    string            `json:"event_id,omitempty"`
	SightingID string            `json:"sighting_id"`
	DeviceID   string            `json:"device_id,omitempty"`
	EventType  string            `json:"event_type"`
	Actor      string            `json:"actor"`
	Details    map[string]string `json:"details,omitempty"`
	CreatedAt  time.Time         `json:"created_at"`
}

SightingEvent tracks lifecycle events for sightings.

type SightingPromotionStatus added in v1.0.59 

type SightingPromotionStatus struct {
	MeetsPolicy    bool       `json:"meets_policy"`
	Eligible       bool       `json:"eligible"`
	ShadowMode     bool       `json:"shadow_mode,omitempty"`
	Blockers       []string   `json:"blockers,omitempty"`
	Satisfied      []string   `json:"satisfied,omitempty"`
	NextEligibleAt *time.Time `json:"next_eligible_at,omitempty"`
}

SightingPromotionStatus captures promotion eligibility and blockers for a sighting.

type SourceConfig 

type SourceConfig struct {
	Type               string            `json:"type"`                   // "armis", "netbox", etc.
	Endpoint           string            `json:"endpoint"`               // API endpoint
	Credentials        map[string]string `json:"credentials"`            // e.g., {"api_key": "xyz"}
	Prefix             string            `json:"prefix"`                 // KV key prefix, e.g., "armis/"
	InsecureSkipVerify bool              `json:"insecure_skip_verify"`   // For TLS connections
	Queries            []QueryConfig     `json:"queries"`                // List of queries
	CustomField        string            `json:"custom_field,omitempty"` // Custom field for additional metadata

	// AgentID and PollerID allow assigning discovered devices to specific
	// agents and pollers. When set, they override any global defaults for
	// the Sync service.
	AgentID   string `json:"agent_id,omitempty"`
	PollerID  string `json:"poller_id,omitempty"`
	Partition string `json:"partition,omitempty"`

	// SweepInterval allows configuring how often agents should sweep the
	// networks discovered by this source. If empty, a sensible default is
	// used by each integration.
	SweepInterval string `json:"sweep_interval,omitempty"`

	// PollInterval allows configuring how often this specific source should be polled.
	// If empty, uses the global PollInterval from the sync config.
	PollInterval Duration `json:"poll_interval,omitempty"`

	// NetworkBlacklist contains CIDR ranges to filter out from this specific source
	NetworkBlacklist []string `json:"network_blacklist,omitempty"`

	// BatchSize configures the number of items to process in each batch
	// for bulk operations. If not specified, a default will be used.
	BatchSize int `json:"batch_size,omitempty"`
}

type SpireAdminConfig added in v1.0.55 

type SpireAdminConfig struct {
	Enabled        bool     `json:"enabled"`
	ServerAddress  string   `json:"server_address"`
	ServerSPIFFEID string   `json:"server_spiffe_id"`
	WorkloadSocket string   `json:"workload_socket,omitempty"`
	BundlePath     string   `json:"bundle_path,omitempty"`
	JoinTokenTTL   Duration `json:"join_token_ttl,omitempty"`
}

SpireAdminConfig captures SPIRE server access for administrative APIs.

type SubnetPolicy added in v1.0.59 

type SubnetPolicy struct {
	SubnetID       string                 `json:"subnet_id"`
	CIDR           string                 `json:"cidr"`
	Classification string                 `json:"classification"`
	PromotionRules map[string]interface{} `json:"promotion_rules,omitempty"`
	ReaperProfile  string                 `json:"reaper_profile"`
	AllowIPAsID    bool                   `json:"allow_ip_as_id"`
	CreatedAt      time.Time              `json:"created_at"`
	UpdatedAt      time.Time              `json:"updated_at"`
}

SubnetPolicy captures promotion/reaper behavior for a subnet.

type SweepConfig 

type SweepConfig struct {
	Networks      []string       `json:"networks,omitempty"`
	Ports         []int          `json:"ports,omitempty"`
	SweepModes    []string       `json:"sweep_modes,omitempty"`
	Interval      string         `json:"interval,omitempty"`
	Concurrency   int            `json:"concurrency,omitempty"`
	Timeout       string         `json:"timeout,omitempty"`
	ICMPCount     int            `json:"icmp_count,omitempty"`
	HighPerfICMP  bool           `json:"high_perf_icmp,omitempty"`
	ICMPRateLimit int            `json:"icmp_rate_limit,omitempty"`
	DeviceTargets []DeviceTarget `json:"device_targets,omitempty"` // Per-device sweep configuration
}

SweepConfig defines the network sweep tool configuration.

type SweepData 

type SweepData struct {
	Network        string       `json:"network"`
	TotalHosts     int32        `json:"total_hosts"`
	AvailableHosts int32        `json:"available_hosts"`
	LastSweep      int64        `json:"last_sweep"`
	Ports          []PortStatus `json:"ports"`
}

SweepData represents network sweep results.

type SweepHostState 

type SweepHostState struct {
	HostIP           string            `json:"host_ip"`
	PollerID         string            `json:"poller_id"`
	AgentID          string            `json:"agent_id"`
	Partition        string            `json:"partition"`
	NetworkCIDR      *string           `json:"network_cidr,omitempty"`
	Hostname         *string           `json:"hostname,omitempty"`
	MAC              *string           `json:"mac,omitempty"`
	ICMPAvailable    bool              `json:"icmp_available"`
	ICMPResponseTime *int64            `json:"icmp_response_time_ns,omitempty"` // nanoseconds
	ICMPPacketLoss   *float64          `json:"icmp_packet_loss,omitempty"`
	TCPPortsScanned  []int             `json:"tcp_ports_scanned,omitempty"`
	TCPPortsOpen     []int             `json:"tcp_ports_open,omitempty"`
	PortScanResults  []PortResult      `json:"port_scan_results,omitempty"`
	LastSweepTime    time.Time         `json:"last_sweep_time"`
	FirstSeen        time.Time         `json:"first_seen"`
	Metadata         map[string]string `json:"metadata,omitempty"`
}

SweepHostState represents the latest sweep state for a host in the versioned KV store.

type SweepMode 

type SweepMode string
const (
	ModeTCP        SweepMode = "tcp"         // SYN scanning (fast but breaks conntrack)
	ModeTCPConnect SweepMode = "tcp_connect" // TCP connect scanning (safe for conntrack)
	ModeICMP       SweepMode = "icmp"
)

type SweepResult 

type SweepResult struct {
	AgentID         string            `json:"agent_id"`
	PollerID        string            `json:"poller_id"`
	Partition       string            `json:"partition"`
	DeviceID        string            `json:"device_id"`
	DiscoverySource string            `json:"discovery_source"`
	IP              string            `json:"ip"`
	MAC             *string           `json:"mac,omitempty"`
	Hostname        *string           `json:"hostname,omitempty"`
	Timestamp       time.Time         `json:"timestamp"`
	Available       bool              `json:"available,omitempty"`
	Metadata        map[string]string `json:"metadata,omitempty"`
}

SweepResult represents a single sweep result to be stored.

type SweepSummary 

type SweepSummary struct {
	Network        string       `json:"network"`
	TotalHosts     int          `json:"total_hosts"`
	AvailableHosts int          `json:"available_hosts"`
	LastSweep      int64        `json:"last_sweep"` // Unix timestamp
	Ports          []PortCount  `json:"ports"`
	Hosts          []HostResult `json:"hosts"`
}

SweepSummary provides aggregated sweep results.

type SysmonCPUResponse 

type SysmonCPUResponse struct {
	Cpus      []CPUMetric        `json:"cpus"`
	Clusters  []CPUClusterMetric `json:"clusters,omitempty"`
	Timestamp time.Time          `json:"timestamp"`
}

SysmonCPUResponse represents a CPU metrics response grouped by timestamp.

type SysmonDiskResponse 

type SysmonDiskResponse struct {
	Disks     []DiskMetric `json:"disks"`
	Timestamp time.Time    `json:"timestamp"`
}

SysmonDiskResponse represents a disk metrics response grouped by timestamp.

type SysmonMemoryResponse 

type SysmonMemoryResponse struct {
	Memory    MemoryMetric `json:"memory"`
	Timestamp time.Time    `json:"timestamp"`
}

SysmonMemoryResponse represents a memory metrics response.

type SysmonMetricData 

type SysmonMetricData struct {
	// ISO8601 timestamp when data was collected
	Timestamp string `json:"timestamp" example:"2025-04-24T14:15:22Z"`
	// Unique identifier for the host
	HostID string `json:"host_id" example:"server-east-1"`
	// IP address of the host
	HostIP string `json:"host_ip" example:"192.168.1.100"`
	// Partition identifier for device-centric model (optional)
	Partition *string `json:"partition,omitempty" example:"demo-staging"`
	// CPU metrics for each core
	CPUs []struct {
		// ID number of the CPU core
		CoreID int32 `json:"core_id" example:"0"`
		// Usage percentage (0-100)
		UsagePercent float32 `json:"usage_percent" example:"45.2"`
	} `json:"cpus"`
	// Disk usage metrics for each mount point
	Disks []struct {
		// Mount point path
		MountPoint string `json:"mount_point" example:"/var"`
		// Bytes currently in use
		UsedBytes uint64 `json:"used_bytes" example:"10737418240"`
		// Total capacity in bytes
		TotalBytes uint64 `json:"total_bytes" example:"107374182400"`
	} `json:"disks"`
	// Memory usage metrics
	Memory struct {
		// Bytes currently in use
		UsedBytes uint64 `json:"used_bytes" example:"4294967296"`
		// Total memory capacity in bytes
		TotalBytes uint64 `json:"total_bytes" example:"17179869184"`
	} `json:"memory"`
	// Process usage metrics for running processes
	Processes []struct {
		// Process ID
		PID uint32 `json:"pid" example:"1234"`
		// Process name
		Name string `json:"name" example:"nginx"`
		// CPU usage percentage
		CPUUsage float32 `json:"cpu_usage" example:"2.5"`
		// Memory usage in bytes
		MemoryUsage uint64 `json:"memory_usage" example:"104857600"`
		// Process status
		Status string `json:"status" example:"Running"`
		// Process start time
		StartTime string `json:"start_time" example:"2025-04-24T14:15:22Z"`
	} `json:"processes"`
}

SysmonMetricData represents the raw data received from the sysmon service. @Description Raw system monitoring data received from the monitoring agent.

type SysmonMetrics 

type SysmonMetrics struct {
	// CPU usage metrics for individual cores
	CPUs []CPUMetric `json:"cpus"`
	// Aggregate CPU cluster metrics (e.g., big.LITTLE clusters)
	Clusters []CPUClusterMetric `json:"clusters,omitempty"`
	// Disk usage metrics for various mount points
	Disks []DiskMetric `json:"disks"`
	// Memory usage metrics
	Memory *MemoryMetric `json:"memory"`
	// Process usage metrics for running processes
	Processes []ProcessMetric `json:"processes"`
}

SysmonMetrics represents system monitoring metrics. @Description System monitoring metrics including CPU, disk, memory, and process usage.

type SysmonProcessResponse 

type SysmonProcessResponse struct {
	Processes []ProcessMetric `json:"processes"`
	Timestamp time.Time       `json:"timestamp"`
}

SysmonProcessResponse represents a process metrics response grouped by timestamp.

type SystemStatus 

type SystemStatus struct {
	// Total number of pollers in the system
	TotalPollers int `json:"total_pollers" example:"15"`
	// Number of pollers that are currently healthy
	HealthyPollers int `json:"healthy_pollers" example:"12"`
	// Last time the system status was updated
	LastUpdate time.Time `json:"last_update" example:"2025-04-24T14:15:22Z"`
}

SystemStatus represents the overall system status. @Description Overall system status information.

type TLSConfig 

type TLSConfig struct {
	CertFile     string `json:"cert_file"`
	KeyFile      string `json:"key_file"`
	CAFile       string `json:"ca_file"`
	ClientCAFile string `json:"client_ca_file"`
}

type Target 

type Target struct {
	Host     string
	Port     int
	Mode     SweepMode
	Metadata map[string]interface{} // Additional metadata about the scan

}

Target represents a network target to be scanned.

type TimeseriesMetric 

type TimeseriesMetric struct {
	PollerID       string    `json:"poller_id"` // Unique identifier for the poller that collected this metric
	Name           string    `json:"name"`
	TargetDeviceIP string    `json:"target_device_ip"` // IP address of the device this metric is for
	DeviceID       string    `json:"device_id"`        // Device identifier in format "partition:ip"
	Partition      string    `json:"partition"`        // Partition identifier for this device
	IfIndex        int32     `json:"if_index"`
	Value          string    `json:"value"` // Store as string for flexibility
	Type           string    `json:"type"`  // Metric type identifier
	Timestamp      time.Time `json:"timestamp"`
	Metadata       string    `json:"metadata"`
}

TimeseriesMetric represents a generic timeseries datapoint.

type Token 

type Token struct {
	// JWT access token used for API authorization
	AccessToken string `json:"access_token" example:"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."`
	// JWT refresh token used to obtain new access tokens
	RefreshToken string `json:"refresh_token" example:"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."`
	// When the access token expires
	ExpiresAt time.Time `json:"expires_at" example:"2025-04-25T12:00:00Z"`
}

Token represents authentication tokens for API access. @Description Authentication tokens for API access.

type TopologyDiscoveryEvent 

type TopologyDiscoveryEvent struct {
	Timestamp              time.Time `json:"timestamp"`
	AgentID                string    `json:"agent_id"`
	PollerID               string    `json:"poller_id"`
	LocalDeviceIP          string    `json:"local_device_ip"`
	LocalDeviceID          string    `json:"local_device_id"`
	LocalIfIndex           int32     `json:"local_ifIndex"` // DB schema is int32; Postgres driver should handle
	LocalIfName            string    `json:"local_ifName"`
	ProtocolType           string    `json:"protocol_type"` // "LLDP" or "CDP"
	NeighborChassisID      string    `json:"neighbor_chassis_id"`
	NeighborPortID         string    `json:"neighbor_port_id"`
	NeighborPortDescr      string    `json:"neighbor_port_descr"`
	NeighborSystemName     string    `json:"neighbor_system_name"`
	NeighborManagementAddr string    `json:"neighbor_management_address"`
	// BGP specific fields - added
	NeighborBGPRouterID string          `json:"neighbor_bgp_router_id,omitempty"`
	NeighborIPAddress   string          `json:"neighbor_ip_address,omitempty"` // For BGP peer IP
	NeighborAS          uint32          `json:"neighbor_as,omitempty"`
	BGPSessionState     string          `json:"bgp_session_state,omitempty"`
	Metadata            json.RawMessage `json:"metadata"`
}

TopologyDiscoveryEvent represents a topology discovery event

type UnifiedDevice 

type UnifiedDevice struct {
	DeviceID string `json:"device_id" db:"device_id"`
	IP       string `json:"ip" db:"ip"`

	// Fields with discovery source attribution
	Hostname *DiscoveredField[string]            `json:"hostname,omitempty" db:"hostname"`
	MAC      *DiscoveredField[string]            `json:"mac,omitempty" db:"mac"`
	Metadata *DiscoveredField[map[string]string] `json:"metadata,omitempty" db:"metadata"`

	// Discovery tracking
	DiscoverySources []DiscoverySourceInfo `json:"discovery_sources" db:"discovery_sources"`
	FirstSeen        time.Time             `json:"first_seen" db:"first_seen"`
	LastSeen         time.Time             `json:"last_seen" db:"last_seen"`
	IsAvailable      bool                  `json:"is_available" db:"is_available"`

	// Device classification
	DeviceType    string `json:"device_type,omitempty" db:"device_type"`
	ServiceType   string `json:"service_type,omitempty" db:"service_type"`
	ServiceStatus string `json:"service_status,omitempty" db:"service_status"`

	// Additional fields
	LastHeartbeat *time.Time `json:"last_heartbeat,omitempty" db:"last_heartbeat"`
	OSInfo        string     `json:"os_info,omitempty" db:"os_info"`
	VersionInfo   string     `json:"version_info,omitempty" db:"version_info"`
}

UnifiedDevice represents a device with tracked discovery sources for each field

func NewUnifiedDeviceFromUpdate 

func NewUnifiedDeviceFromUpdate(update *DeviceUpdate) *UnifiedDevice

NewUnifiedDeviceFromUpdate creates a new UnifiedDevice from a DeviceUpdate

func (*UnifiedDevice) ToLegacyDevice 

func (ud *UnifiedDevice) ToLegacyDevice() *Device

ToLegacyDevice converts a UnifiedDevice to the legacy Device format for compatibility

type User 

type User struct {
	// Unique identifier for the user
	ID string `json:"id" example:"u-1234567890"`
	// Email address of the user
	Email string `json:"email" example:"user@example.com"`
	// Display name of the user
	Name string `json:"name" example:"John Doe"`
	// Authentication provider (e.g., "local", "google", "github")
	Provider string `json:"provider" example:"google"`
	// User roles for RBAC
	Roles []string `json:"roles" example:"admin,user"`
	// User permissions for fine-grained access control
	Permissions []string `json:"permissions" example:"config:read,config:write"`
	// When the user account was created
	CreatedAt time.Time `json:"created_at" example:"2025-01-01T00:00:00Z"`
	// When the user account was last updated
	UpdatedAt time.Time `json:"updated_at" example:"2025-04-01T00:00:00Z"`
}

User contains information about an authenticated user. @Description Information about an authenticated user.

type WebhookConfig 

type WebhookConfig struct {
	Enabled  bool     `json:"enabled"`
	URL      string   `json:"url"`
	Cooldown Duration `json:"cooldown"`
	Template string   `json:"template"`
	Headers  []Header `json:"headers,omitempty"` // Optional custom headers
}

WebhookConfig represents a webhook notification configuration.

type WriteBufferConfig 

type WriteBufferConfig struct {
	MaxSize       int      `json:"max_size"`       // Maximum buffer size before forced flush (default: 500)
	FlushInterval Duration `json:"flush_interval"` // Maximum time to wait before flushing (default: 30s)
	Enabled       bool     `json:"enabled"`        // Whether buffering is enabled (default: true)
}

WriteBufferConfig configures the database write buffer for performance optimization

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.