starlink

README

Starlink API Client

This package provides a Go client for interacting with Starlink Dishy terminals via their gRPC API.

Implementation Approach

The client uses native Go gRPC with reflection to interact with the Starlink gRPC API. This provides a robust, dependency-free solution without requiring external tools or pre-generated protobuf code.

Why native gRPC with reflection?

1. No external dependencies: Pure Go implementation, no need for grpcurl binary
2. Reliability: Direct gRPC connection with proper error handling
3. Maintenance: Uses reflection to dynamically discover API structure
4. Performance: Native implementation is faster than shelling out to external tools
5. Flexibility: Works with any gRPC service that supports reflection

Key Features

• Dynamic service discovery: Uses gRPC reflection to discover service methods and message types
• Proper timeout handling: Consistent 10-second timeouts with context cancellation
• Graceful error handling: Detailed error messages and fallback parsing strategies
• Connection validation: TCP connectivity test before attempting gRPC calls

How to Extract Proto Files (for reference/future changes)

If you need to understand the API structure or generate proper proto clients:

# Create output directory
mkdir -p starlink/proto

# Extract all proto definitions using grpcurl reflection
grpcurl -plaintext -proto-out-dir starlink/proto 127.0.0.1:9200 describe SpaceX.API.Device.Device

# The proto files will be saved to starlink/proto/ with proper package structure

This will generate:

• spacex_api/device/device.proto - Main service definition
• spacex_api/device/common.proto - Common message types
• spacex_api/common/status/status.proto - Status definitions
• Plus all dependencies

Generating Go Client (if needed)

If you want to generate a proper Go client from proto files:

# Install protobuf tools
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

# Generate Go code (after fixing go_package options)
cd starlink
protoc --go_out=. --go-grpc_out=. --proto_path=proto \
  proto/spacex_api/device/device.proto \
  proto/spacex_api/device/common.proto \
  proto/spacex_api/common/status/status.proto

Note: You'll need to add option go_package = "spacex.com/api/..."; to proto files that don't have it.

API Endpoints

The client currently implements:

• GetDeviceInfo() - Retrieves hardware/software information
• GetStatus() - Retrieves operational status (placeholder)
• GetConfig() - Retrieves configuration (placeholder)

Adding New Endpoints

To add support for additional Starlink API calls:

1. Identify the gRPC method using: grpcurl -plaintext 127.0.0.1:9200 describe SpaceX.API.Device.Request
2. Find the field number for your request type
3. Create a similar method to GetDeviceInfo() with the appropriate request JSON

Example for getting status:

requestData := `{"get_status":{}}`
// ... rest same as GetDeviceInfo()

Dependencies

• google.golang.org/grpc - gRPC client library
• google.golang.org/grpc/reflection/grpc_reflection_v1alpha - gRPC reflection support
• google.golang.org/protobuf - Protocol Buffers runtime

Security Considerations

The Starlink API provides access to sensitive device information including:

• Device identifiers
• Network configuration
• Performance metrics
• Operational status

Ensure this client is only used in trusted environments and consider the security implications of exposing this data.

Documentation

Index

• Constants
• func FormatStarlinkReport(info *StarLinkInfo) string
• type Client
  • func NewClient(endpoint string, out output.Output) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) GetConfig() (*DishConfig, error)
  • func (c *Client) GetDeviceInfo() (*DeviceInfo, error)
  • func (c *Client) GetStatus() (*DishStatus, error)
  • func (c *Client) IsAccessible() bool
• type DeviceInfo
• type DeviceInfoResp
• type DeviceStateResp
• type DishConfig
• type DishConfigResp
• type DishGetConfigResp
• type DishGetStatusResp
• type DishStatus
• type GRPCResponse
• type GetDeviceInfoResp
• type SecurityIssue
• type StarLinkInfo
  • func CheckStarlink(out output.Output) *StarLinkInfo

Constants

const (
	// Standard Starlink Dishy IP and port
	DefaultStarlinkIP   = "192.168.100.1"
	DefaultStarlinkPort = 9200

	// Alternative endpoints for testing
	LocalhostTestIP   = "127.0.0.1"
	LocalhostTestPort = 9200

	// Timeouts
	DialTimeout    = 5 * time.Second
	RequestTimeout = 10 * time.Second
)

Functions

func FormatStarlinkReport

func FormatStarlinkReport(info *StarLinkInfo) string

FormatStarlinkReport generates a human-readable report of Starlink findings

Types

type Client

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

Client provides access to Starlink API using native gRPC

func NewClient

func NewClient(endpoint string, out output.Output) (*Client, error)

NewClient creates a new Starlink client

func (*Client) Close

func (c *Client) Close() error

Close closes the gRPC connection

func (*Client) GetConfig

func (c *Client) GetConfig() (*DishConfig, error)

GetConfig retrieves configuration

func (*Client) GetDeviceInfo

func (c *Client) GetDeviceInfo() (*DeviceInfo, error)

GetDeviceInfo retrieves device information using native gRPC with reflection

func (*Client) GetStatus

func (c *Client) GetStatus() (*DishStatus, error)

GetStatus retrieves status information

func (*Client) IsAccessible

func (c *Client) IsAccessible() bool

IsAccessible checks if the Starlink service is accessible

type DeviceInfo

type DeviceInfo struct {
	ID              string `json:"id"`
	HardwareVersion string `json:"hardware_version"`
	SoftwareVersion string `json:"software_version"`
	CountryCode     string `json:"country_code"`
	BootCount       int    `json:"boot_count"`
	BuildID         string `json:"build_id"`
}

DeviceInfo contains basic device identification

type DeviceInfoResp

type DeviceInfoResp struct {
	ID              string `json:"id"`
	HardwareVersion string `json:"hardwareVersion"`
	SoftwareVersion string `json:"softwareVersion"`
	CountryCode     string `json:"countryCode"`
	BootCount       int    `json:"bootcount"`
	BuildID         string `json:"buildId"`
}

type DeviceStateResp

type DeviceStateResp struct {
	UptimeS string `json:"uptimeS"`
}

type DishConfig

type DishConfig struct {
	SwupdateRebootHour                   int  `json:"swupdate_reboot_hour"`
	ApplySnowMeltMode                    bool `json:"apply_snow_melt_mode"`
	ApplyLocationRequestMode             bool `json:"apply_location_request_mode"`
	ApplyLevelDishMode                   bool `json:"apply_level_dish_mode"`
	ApplyPowerSaveStartMinutes           bool `json:"apply_power_save_start_minutes"`
	ApplyPowerSaveDurationMinutes        bool `json:"apply_power_save_duration_minutes"`
	ApplyPowerSaveMode                   bool `json:"apply_power_save_mode"`
	ApplySwupdateThreeDayDeferralEnabled bool `json:"apply_swupdate_three_day_deferral_enabled"`
	ApplyAssetClass                      bool `json:"apply_asset_class"`
	ApplySwupdateRebootHour              bool `json:"apply_swupdate_reboot_hour"`
}

DishConfig contains configuration settings

type DishConfigResp

type DishConfigResp struct {
	SwupdateRebootHour                   int  `json:"swupdateRebootHour"`
	ApplySnowMeltMode                    bool `json:"applySnowMeltMode"`
	ApplyLocationRequestMode             bool `json:"applyLocationRequestMode"`
	ApplyLevelDishMode                   bool `json:"applyLevelDishMode"`
	ApplyPowerSaveStartMinutes           bool `json:"applyPowerSaveStartMinutes"`
	ApplyPowerSaveDurationMinutes        bool `json:"applyPowerSaveDurationMinutes"`
	ApplyPowerSaveMode                   bool `json:"applyPowerSaveMode"`
	ApplySwupdateThreeDayDeferralEnabled bool `json:"applySwupdateThreeDayDeferralEnabled"`
	ApplyAssetClass                      bool `json:"applyAssetClass"`
	ApplySwupdateRebootHour              bool `json:"applySwupdateRebootHour"`
}

type DishGetConfigResp

type DishGetConfigResp struct {
	DishConfig DishConfigResp `json:"dishConfig"`
}

type DishGetStatusResp

type DishGetStatusResp struct {
	DeviceInfo            DeviceInfoResp  `json:"deviceInfo"`
	DeviceState           DeviceStateResp `json:"deviceState"`
	DownlinkThroughputBps float64         `json:"downlinkThroughputBps"`
	UplinkThroughputBps   float64         `json:"uplinkThroughputBps"`
	PopPingLatencyMs      float64         `json:"popPingLatencyMs"`
	BoresightAzimuthDeg   float64         `json:"boresightAzimuthDeg"`
	BoresightElevationDeg float64         `json:"boresightElevationDeg"`
	EthSpeedMbps          int             `json:"ethSpeedMbps"`
	ConnectedRouters      []string        `json:"connectedRouters"`
	HasActuators          string          `json:"hasActuators"`
	DisablementCode       string          `json:"disablementCode"`
	SoftwareUpdateState   string          `json:"softwareUpdateState"`
}

type DishStatus

type DishStatus struct {
	UptimeS               int64    `json:"uptime_s"`
	DownlinkThroughputBps float64  `json:"downlink_throughput_bps"`
	UplinkThroughputBps   float64  `json:"uplink_throughput_bps"`
	PopPingLatencyMs      float64  `json:"pop_ping_latency_ms"`
	BoresightAzimuthDeg   float64  `json:"boresight_azimuth_deg"`
	BoresightElevationDeg float64  `json:"boresight_elevation_deg"`
	EthSpeedMbps          int      `json:"eth_speed_mbps"`
	ConnectedRouters      []string `json:"connected_routers"`
	HasActuators          string   `json:"has_actuators"`
	DisablementCode       string   `json:"disablement_code"`
	SoftwareUpdateState   string   `json:"software_update_state"`
}

DishStatus contains operational status information

type GRPCResponse

type GRPCResponse struct {
	APIVersion    string             `json:"apiVersion"`
	DishGetStatus *DishGetStatusResp `json:"dishGetStatus,omitempty"`
	GetDeviceInfo *GetDeviceInfoResp `json:"getDeviceInfo,omitempty"`
	DishGetConfig *DishGetConfigResp `json:"dishGetConfig,omitempty"`
}

gRPC response structures for parsing JSON responses

type GetDeviceInfoResp

type GetDeviceInfoResp struct {
	DeviceInfo DeviceInfoResp `json:"deviceInfo"`
}

type SecurityIssue

type SecurityIssue struct {
	Severity    string `json:"severity"`
	Category    string `json:"category"`
	Title       string `json:"title"`
	Description string `json:"description"`
	Impact      string `json:"impact"`
	Remediation string `json:"remediation"`
}

SecurityIssue represents a security finding related to Starlink

type StarLinkInfo

type StarLinkInfo struct {
	Accessible     bool            `json:"accessible"`
	DeviceInfo     *DeviceInfo     `json:"device_info,omitempty"`
	Status         *DishStatus     `json:"status,omitempty"`
	Config         *DishConfig     `json:"config,omitempty"`
	SecurityIssues []SecurityIssue `json:"security_issues"`
}

StarLinkInfo represents information gathered from a Starlink Dishy

func CheckStarlink

func CheckStarlink(out output.Output) *StarLinkInfo

CheckStarlink attempts to detect and analyze a Starlink Dishy on the network