discovery

package module
v0.1.39 Latest Latest
Warning

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

 Go to latest Published: Apr 21, 2025 License: Apache-2.0 Imports: 4 Imported by: 0

README

discovery

Go Report Card Documentation license

Border0 service discovery framework and library.

Example: Discover EC2, ECS, and RDS Resources

Assume that the following variables are defined as follows:

ctx := context.Background()

cfg, err := config.LoadDefaultConfig(ctx)
if err != nil {
	// handle error
}

Then,

// initialize a new one off engine
engine := engines.NewOneOffEngine(
	engines.OneOffEngineOptionWithDiscoverers(
		discoverers.NewAwsEc2Discoverer(cfg),
		discoverers.NewAwsEcsDiscoverer(cfg),
		discoverers.NewAwsRdsDiscoverer(cfg),
		// ... LAN, docker, k8s, gcp compute, azure vms, etc ...
	),
)

// create channels for discovery results
results := make(chan *discovery.Result, 10)

// run engine
go engine.Run(ctx, results)

// process results as they come in
for result := range results {
	// ... do something ...
}
Example: Continuously Discover EC2, ECS, and RDS Resources

Assume that the following variables are defined as follows:

Assume that ctx (type context.Context) is defined by some upstream code

cfg, err := config.LoadDefaultConfig(ctx)
if err != nil {
	// handle error
}

Then,

// initialize a new continuous engine
engine := engines.NewContinuousEngine(
	engines.WithDiscoverer(
		discoverers.NewAwsEc2Discoverer(cfg),
		engines.WithInitialInterval(time.Second*2),
	),
	engines.WithDiscoverer(
		discoverers.NewAwsEcsDiscoverer(cfg),
		engines.WithInitialInterval(time.Second*2),
	),
	engines.WithDiscoverer(
		discoverers.NewAwsRdsDiscoverer(cfg),
		engines.WithInitialInterval(time.Second*2),
	),
)

// create channels for discovery results
results := make(chan *discovery.Result, 10)

// run engine
go engine.Run(ctx, results)

// process results as they come in
for result := range results {
	// ... do something ...
}
Example: Discover EC2 Instances In Multiple AWS Regions

Assume that the following variables are defined as follows:

awsRegions := []string{"us-east-1", "us-east-2", "us-west-2", "eu-west-1"}

ctx := context.Background()
cfg, err := config.LoadDefaultConfig(ctx)
if err != nil {
	// handle error
}

Then,

// define an ec2 discoverer for each region
ds := []discovery.Discoverer{}
for _, region := range regions {
	cfg.Region = region

	ds = append(ds, discoverers.NewAwsEc2Discoverer(cfg))
}

// initialize a new one off engine with the discoverers
engine := engines.NewOneOffEngine(
	engines.OneOffEngineOptionWithDiscoverers(ds...),
)

// create channels for discovery results
results := make(chan *discovery.Result, 10)

// run engine
go engine.Run(ctx, results)

// process results as they come in
for result := range results {
	// ... do something ...
}

Documentation

Index

Constants

View Source 
const (
	// ResourceTypeAwsEc2Instance is the resource type for AWS EC2 instances.
	ResourceTypeAwsEc2Instance = "aws_ec2_instance"

	// ResourceTypeAwsEcsService is the resource type for AWS ECS services.
	ResourceTypeAwsEcsService = "aws_ecs_service"

	// ResourceTypeAwsEksCluster is the resource type for AWS EKS clusters.
	ResourceTypeAwsEksCluster = "aws_eks_cluster"

	// ResourceTypeAwsRdsInstnace is the resource type for AWS RDS instances.
	ResourceTypeAwsRdsInstance = "aws_rds_instance"

	// ResourceTypeAwsSsmTarget is the resource type for AWS SSM targets.
	ResourceTypeAwsSsmTarget = "aws_ssm_target"

	// ResourceTypeKubernetesService is the resource type for kubernetes services.
	ResourceTypeKubernetesService = "kubernetes_service"

	// ResourceTypeDockerContainer is the resource type for containers managed by a Docker daemon.
	ResourceTypeDockerContainer = "docker_container"

	// ResourceTypeNetworkHttpServer is the resource type for network-reachable HTTP servers.
	ResourceTypeNetworkHttpServer = "network_http_server"

	// ResourceTypeNetworkHttpsServer is the resource type for network-reachable HTTPS servers.
	ResourceTypeNetworkHttpsServer = "network_https_server"

	// ResourceTypeNetworkMysqlServer is the resource type for network-reachable MySQL servers.
	ResourceTypeNetworkMysqlServer = "network_mysql_server"

	// ResourceTypeNetworkPostgresqlServer is the resource type for network-reachable PostgreSQL servers.
	ResourceTypeNetworkPostgresqlServer = "network_postgresql_server"

	// ResourceTypeNetworkRdpServer is the resource type for network-reachable RDP servers.
	ResourceTypeNetworkRdpServer = "network_rdp_server"

	// ResourceTypeNetworkSshServer is the resource type for network-reachable SSH servers.
	ResourceTypeNetworkSshServer = "network_ssh_server"

	// ResourceTypeNetworkVncServer is the resource type for network-reachable VNC servers.
	ResourceTypeNetworkVncServer = "network_vnc_server"

	// Ec2InstanceSsmStatusOnline represents the SSM status of an EC2 instance that is associated and online.
	Ec2InstanceSsmStatusOnline = "online"

	// Ec2InstanceSsmStatusOffline represents the SSM status of an EC2 instance that is associated and offline.
	Ec2InstanceSsmStatusOffline = "offline"

	// Ec2InstanceSsmStatusNotChecked represents the SSM status of an EC2 instance that is not checked.
	Ec2InstanceSsmStatusNotChecked = "not_checked"

	// Ec2InstanceSsmStatusNotAssociated represents the SSM status of an EC2 instance that is not associated.
	Ec2InstanceSsmStatusNotAssociated = "not_associated"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type AwsBaseDetails 

type AwsBaseDetails struct {
	AwsAccountId string `json:"aws_account_id"`
	AwsRegion    string `json:"aws_region"`
	AwsArn       string `json:"aws_arn"`
}

AwsBaseDetails represents the details of a discovered generic AWS resource.

type AwsEc2InstanceDetails 

type AwsEc2InstanceDetails struct {
	AwsBaseDetails // extends

	Tags map[string]string `json:"tags"`

	InstanceId       string `json:"instance_id"`
	ImageId          string `json:"ami_id"`
	VpcId            string `json:"vpc_id"`
	SubnetId         string `json:"subnet_id"`
	AvailabilityZone string `json:"availability_zone"`
	PrivateDnsName   string `json:"private_dns_name"`
	PrivateIpAddress string `json:"private_ip_address"`
	PublicDnsName    string `json:"public_dns_name"`
	PublicIpAddress  string `json:"public_ip_address"`
	InstanceType     string `json:"instance_type"`
	InstanceState    string `json:"instance_state"`

	InstanceSsmStatus string `json:"ssm_status"`

	PrivateDnsNameReachable   *bool `json:"private_dns_name_reachable,omitempty"`
	PrivateIpAddressReachable *bool `json:"private_ip_address_reachable,omitempty"`
	PublicDnsNameReachable    *bool `json:"public_dns_name_reachable,omitempty"`
	PublicIpAddressReachable  *bool `json:"public_ip_address_reachable,omitempty"`
}

AwsEc2InstanceDetails represents the details of a discovered AWS EC2 instance.

type AwsEcsServiceDetails added in v0.1.16 

type AwsEcsServiceDetails struct {
	AwsBaseDetails // extends

	Tags map[string]string `json:"tags"`

	ServiceName          string `json:"service_name"`
	ClusterArn           string `json:"cluster_arn"`
	ClusterName          string `json:"cluster_name"`
	TaskDefinition       string `json:"task_definition"`
	EnableExecuteCommand bool   `json:"enable_execute_command"`
}

AwsEcsServiceDetails represents the details of a discovered AWS ECS service.

type AwsEksClusterDetails added in v0.1.29 

type AwsEksClusterDetails struct {
	AwsBaseDetails // extends

	Tags map[string]string `json:"tags"`

	ClusterName       string `json:"cluster_name"`
	KubernetesVersion string `json:"kubernetes_version"`
	Endpoint          string `json:"endpoint"`

	VpcId string `json:"vpc_id"`

	EndpointReachable *bool `json:"endpoint_reachable,omitempty"`
}

AwsEksClusterDetails represents the details of a discovered AWS EKS cluster.

type AwsRdsInstanceDetails 

type AwsRdsInstanceDetails struct {
	AwsBaseDetails // extends

	Tags map[string]string `json:"tags"`

	DbInstanceIdentifier string `json:"db_instance_identifier"`
	DbInstanceStatus     string `json:"db_instance_status"`
	Engine               string `json:"engine"`
	EngineVersion        string `json:"engine_version"`
	VpcId                string `json:"vpc_id"`
	DBSubnetGroupName    string `json:"db_subnet_group_name"`
	EndpointAddress      string `json:"endpoint_address"`
	EndpointPort         int32  `json:"endpoint_port"`
	NetworkReachable     *bool  `json:"network_reachable,omitempty"`
}

AwsRdsInstanceDetails represents the details of a discovered AWS RDS instance.

type Discoverer 

type Discoverer interface {
	Discover(context.Context) *Result
}

Discoverer represents an entity capable of discovering resources.

type DockerContainerDetails added in v0.1.17 

type DockerContainerDetails struct {
	ContainerId  string            `json:"container_id"`
	Status       string            `json:"status"`
	Image        string            `json:"image"`
	Names        []string          `json:"names"`
	PortBindings map[string]string `json:"port_bindings"`
	Labels       map[string]string `json:"labels"`
}

DockerContainerDetails represents the details of a discovered container managed by a Docker daemon.

type Engine added in v0.1.0 

type Engine interface {
	Run(context.Context, chan<- *Result)
}

Engine represents an entity capable of managing discovery jobs.

An Engine has three responsibilities: - Write zero or more results to the channel - Close the channel as soon as they are done with it - Exit gracefully upon the context being done

type KubernetesServiceDetails added in v0.1.11 

type KubernetesServiceDetails struct {
	Namespace      string                  `json:"namespace"`
	Name           string                  `json:"name"`
	Uid            string                  `json:"uid"`
	ServiceType    string                  `json:"service_type"`
	ExternalName   string                  `json:"external_name,omitempty"`
	LoadBalancerIp string                  `json:"load_balancer_ip,omitempty"`
	ClusterIp      string                  `json:"cluster_ip"`
	ClusterIps     []string                `json:"cluster_ips"`
	Ports          []KubernetesServicePort `json:"ports"`
	Labels         map[string]string       `json:"labels"`
	Annotations    map[string]string       `json:"annotations"`
}

KubernetesServiceDetails represents the details of a discovered kubernetes service.

type KubernetesServicePort added in v0.1.11 

type KubernetesServicePort struct {
	Name        string  `json:"name,omitempty"`
	Protocol    string  `json:"protocol,omitempty"`
	AppProtocol *string `json:"app_protocol,omitempty"`
	Port        int32   `json:"port"`
	TargetPort  string  `json:"target_port,omitempty"`
	NodePort    int32   `json:"node_port,omitempty"`
}

KubernetesServicePort represents the details of a port for a kubernetes service.

type Metadata added in v0.1.3 

type Metadata struct {
	DiscovererId string    `json:"discoverer_id"`
	StartedAt    time.Time `json:"started_at"`
	EndedAt      time.Time `json:"ended_at"`
}

Metadata represents metadata for a result.

type NetworkBaseDetails added in v0.1.4 

type NetworkBaseDetails struct {
	HostNames []string `json:"hostnames,omitempty"`
	IpAddress string   `json:"ip_address"`
	Port      string   `json:"port"`
}

NetworkBaseDetails represents the details of a discovered generic service on the network.

type NetworkHttpServerDetails added in v0.1.4 

type NetworkHttpServerDetails struct {
	NetworkBaseDetails // extends

}

NetworkHttpServerDetails represents the details of a discovered HTTP server on the network.

type NetworkHttpsServerDetails added in v0.1.4 

type NetworkHttpsServerDetails struct {
	NetworkBaseDetails // extends

}

NetworkHttpsServerDetails represents the details of a discovered HTTPS server on the network.

type NetworkMysqlServerDetails added in v0.1.4 

type NetworkMysqlServerDetails struct {
	NetworkBaseDetails // extends

}

NetworkMysqlServerDetails represents the details of a discovered MySQL server on the network.

type NetworkPostgresqlServerDetails added in v0.1.4 

type NetworkPostgresqlServerDetails struct {
	NetworkBaseDetails // extends

}

NetworkPostgresqlServerDetails represents the details of a discovered PostgreSQL server on the network.

type NetworkRdpServerDetails added in v0.1.22 

type NetworkRdpServerDetails struct {
	NetworkBaseDetails // extends

}

NetworkRdpServerDetails represents the details of a discovered RDP server on the network.

type NetworkSshServerDetails added in v0.1.4 

type NetworkSshServerDetails struct {
	NetworkBaseDetails // extends

}

NetworkSshServerDetails represents the details of a discovered SSH server on the network.

type NetworkVncServerDetails added in v0.1.22 

type NetworkVncServerDetails struct {
	NetworkBaseDetails // extends

}

NetworkVncServerDetails represents the details of a discovered VNC server on the network.

type Resource 

type Resource struct {
	ResourceType string `json:"resource_type"`

	AwsEc2InstanceDetails          *AwsEc2InstanceDetails          `json:"aws_ec2_instance_details,omitempty"`
	AwsEcsServiceDetails           *AwsEcsServiceDetails           `json:"aws_ecs_service_details,omitempty"`
	AwsEksClusterDetails           *AwsEksClusterDetails           `json:"aws_eks_cluster_details,omitempty"`
	AwsRdsInstanceDetails          *AwsRdsInstanceDetails          `json:"aws_rds_instance_details,omitempty"`
	KubernetesServiceDetails       *KubernetesServiceDetails       `json:"kubernetes_service_details,omitempty"`
	DockerContainerDetails         *DockerContainerDetails         `json:"docker_container_details,omitempty"`
	NetworkHttpServerDetails       *NetworkHttpServerDetails       `json:"network_http_server_details,omitempty"`
	NetworkHttpsServerDetails      *NetworkHttpsServerDetails      `json:"network_https_server_details,omitempty"`
	NetworkMysqlServerDetails      *NetworkMysqlServerDetails      `json:"network_mysql_server_details,omitempty"`
	NetworkPostgresqlServerDetails *NetworkPostgresqlServerDetails `json:"network_postgresql_server_details,omitempty"`
	NetworkRdpServerDetails        *NetworkRdpServerDetails        `json:"network_rdp_server_details,omitempty"`
	NetworkSshServerDetails        *NetworkSshServerDetails        `json:"network_ssh_server_details,omitempty"`
	NetworkVncServerDetails        *NetworkVncServerDetails        `json:"network_vnc_server_details,omitempty"`
}

Resource represents a generic discovered resource.

type Result added in v0.1.0 

type Result struct {
	sync.Mutex // inherit lock behaviour

	Resources []Resource `json:"resources"`
	Metadata  Metadata   `json:"metadata"`

	Errors   []string `json:"errors"`
	Warnings []string `json:"warnings"`
}

Result represents the result of a discoverer.

func NewResult added in v0.1.0 

func NewResult(discovererId string) *Result

NewResult returns a new Result object with the StartedAt time set to the current time.

func (*Result) AddError added in v0.1.1 

func (r *Result) AddError(err string)

AddError adds an error to a result

func (*Result) AddErrorf added in v0.1.15 

func (r *Result) AddErrorf(template string, args ...any)

AddErrorf adds a formatted error to a result

func (*Result) AddResources added in v0.1.3 

func (r *Result) AddResources(resources ...Resource)

AddResources adds resources to a result

func (*Result) AddWarning added in v0.1.15 

func (r *Result) AddWarning(warn string)

AddWarning adds an warning to a result

func (*Result) AddWarningf added in v0.1.15 

func (r *Result) AddWarningf(template string, args ...any)

AddWarningf adds a formatted warning to a result

func (*Result) Done added in v0.1.0 

func (r *Result) Done()

Done sets the EndedAt time in a Result to the current time.

Source Files

View all Source files

Directories

Path Synopsis
__examples__
aws_continuous command
aws_multiregion command
aws_oneoff command
docker_oneoff command
k8s_oneoff command
network_oneoff command

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.