state

README

Remote Config Go client

This package powers the Remote Config client shipped in the Go tracer and in all the agent processes (core-agent, trace-agent, system-probe, ...).

To add a new product simply add it to products.go as a constant and in the validProducts set.

Documentation

Overview

Package state provides the types and logic needed to track the current TUF repository state for a client.

Index

• Constants
• Variables
• type ASMDataConfig
• type ASMDataRuleData
• type ASMDataRuleDataEntry
• type ASMDataRulesData
• type ASMFeaturesConfig
• type ASMFeaturesData
• type AgentConfig
• type AgentConfigOrder
• type AgentConfigState
• type AgentTaskConfig
  • func ParseConfigAgentTask(data []byte, metadata Metadata) (AgentTaskConfig, error)
• type AgentTaskData
• type ApplyState
• type ApplyStatus
• type CachedFile
• type ConfigASMDD
• type ConfigContent
  • func MergeRCAgentConfig(applyStatus func(cfgPath string, status ApplyStatus), ...) (ConfigContent, error)
• type ConfigState
• type Metadata
• type RawConfig
• type Repository
  • func NewRepository(embeddedRoot []byte) (*Repository, error)
  • func NewUnverifiedRepository() (*Repository, error)
  • func (r *Repository) ASMDDConfigs() map[string]ConfigASMDD
  • func (r *Repository) ASMDataConfigs() map[string]ASMDataConfig
  • func (r *Repository) ASMFeaturesConfigs() map[string]ASMFeaturesConfig
  • func (r *Repository) AgentTaskConfigs() map[string]AgentTaskConfig
  • func (r *Repository) CurrentState() (RepositoryState, error)
  • func (r *Repository) GetConfigs(product string) map[string]RawConfig
  • func (r *Repository) Update(update Update) ([]string, error)
  • func (r *Repository) UpdateApplyStatus(cfgPath string, status ApplyStatus)
• type RepositoryState
• type Update

Constants

const (
	// ProductUpdaterCatalogDD is the product used to receive the package catalog from datadog
	ProductUpdaterCatalogDD = "UPDATER_CATALOG_DD"
	// ProductUpdaterAgent is the product used to receive defaults versions to install
	ProductUpdaterAgent = "UPDATER_AGENT"
	// ProductUpdaterTask is the product used to receive tasks to execute
	ProductUpdaterTask = "UPDATER_TASK"
	// ProductAgentConfig is to receive agent configurations, like the log level
	ProductAgentConfig = "AGENT_CONFIG"
	// ProductAgentFailover is to receive the multi-region failover configuration
	ProductAgentFailover = "AGENT_FAILOVER"
	// ProductAgentIntegrations is to receive integrations to schedule
	ProductAgentIntegrations = "AGENT_INTEGRATIONS"
	// ProductAgentTask is to receive agent task instruction, like a flare
	ProductAgentTask = "AGENT_TASK"
	// ProductAPMSampling is the apm sampling product
	ProductAPMSampling = "APM_SAMPLING"
	// ProductCWSDD is the cloud workload security product managed by datadog employees
	ProductCWSDD = "CWS_DD"
	// ProductCWSCustom is the cloud workload security product managed by datadog customers
	ProductCWSCustom = "CWS_CUSTOM"
	// ProductCWSProfiles is the cloud workload security profile product
	ProductCWSProfiles = "CWS_SECURITY_PROFILES"
	// ProductASM is the ASM product used by customers to issue rules configurations
	ProductASM = "ASM"
	// ProductASMFeatures is the ASM product used form ASM activation through remote config
	ProductASMFeatures = "ASM_FEATURES"
	// ProductASMDD is the application security monitoring product managed by datadog employees
	ProductASMDD = "ASM_DD"
	// ProductASMData is the ASM product used to configure WAF rules data
	ProductASMData = "ASM_DATA"
	// ProductAPMTracing is the apm tracing product
	ProductAPMTracing = "APM_TRACING"
	// ProductLiveDebugging is the dynamic instrumentation product
	ProductLiveDebugging = "LIVE_DEBUGGING"
	// ProductTesting1 is a product used for testing remote config
	ProductTesting1 = "TESTING1"
	// ProductTesting2 is a product used for testing remote config
	ProductTesting2 = "TESTING2"
)

Variables

var (
	// ErrMalformedEmbeddedRoot occurs when the TUF root provided is invalid
	ErrMalformedEmbeddedRoot = errors.New("malformed embedded TUF root file provided")
)

var ErrNoConfigVersion = errors.New("version missing in custom file meta")

ErrNoConfigVersion occurs when a target file's custom meta is missing the config version

Types

type ASMDataConfig

type ASMDataConfig struct {
	Config   ASMDataRulesData
	Metadata Metadata
}

ASMDataConfig is a deserialized configuration file that holds rules data that can be used by the ASM WAF for specific features (example: ip blocking).

type ASMDataRuleData

type ASMDataRuleData struct {
	ID   string                 `json:"id"`
	Type string                 `json:"type"`
	Data []ASMDataRuleDataEntry `json:"data"`
}

ASMDataRuleData is an entry in the rules data list held by an ASMData configuration

type ASMDataRuleDataEntry

type ASMDataRuleDataEntry struct {
	Expiration int64  `json:"expiration,omitempty"`
	Value      string `json:"value"`
}

ASMDataRuleDataEntry represents a data entry in a rule data file

type ASMDataRulesData

type ASMDataRulesData struct {
	RulesData []ASMDataRuleData `json:"rules_data"`
}

ASMDataRulesData is a serializable array of rules data entries

type ASMFeaturesConfig

type ASMFeaturesConfig struct {
	Config   ASMFeaturesData
	Metadata Metadata
}

ASMFeaturesConfig is a deserialized configuration file that indicates whether ASM should be enabled within a tracer, along with its associated remote config metadata.

type ASMFeaturesData

type ASMFeaturesData struct {
	ASM struct {
		Enabled bool `json:"enabled"`
	} `json:"asm"`
	APISecurity struct {
		RequestSampleRate float64 `json:"request_sample_rate"`
	} `json:"api_security"`
}

ASMFeaturesData describes the state of ASM and some of its features

type AgentConfig

type AgentConfig struct {
	Config   agentConfigData
	Metadata Metadata
}

AgentConfig is a deserialized agent configuration file along with the associated metadata

type AgentConfigOrder

type AgentConfigOrder struct {
	Config   agentConfigOrderData
	Metadata Metadata
}

AgentConfigOrder is a deserialized agent configuration file along with the associated metadata

type AgentConfigState

type AgentConfigState struct {
	FallbackLogLevel string
	LatestLogLevel   string
}

AgentConfigState contains the state of the config in case of fallback or override

type AgentTaskConfig

type AgentTaskConfig struct {
	Config   AgentTaskData
	Metadata Metadata
}

AgentTaskConfig is a deserialized agent task configuration file along with the associated metadata

func ParseConfigAgentTask

func ParseConfigAgentTask(data []byte, metadata Metadata) (AgentTaskConfig, error)

ParseConfigAgentTask parses an agent task config

type AgentTaskData

type AgentTaskData struct {
	TaskType string            `json:"task_type"`
	UUID     string            `json:"uuid"`
	TaskArgs map[string]string `json:"args"`
}

AgentTaskData is the content of a agent task configuration file

type ApplyState

type ApplyState uint64

ApplyState represents the status of a configuration application by a remote configuration client Clients need to either ack the correct application of received configurations, or communicate that they haven't applied it yet, or communicate any error that may have happened while doing so

const (
	//ApplyStateUnknown indicates that a client does not support the ApplyState feature
	ApplyStateUnknown ApplyState = iota
	// ApplyStateUnacknowledged indicates a client has received the config but has not specified success or failure
	ApplyStateUnacknowledged
	// ApplyStateAcknowledged indicates a client has successfully applied the config
	ApplyStateAcknowledged
	// ApplyStateError indicates that a client has failed to apply the config
	ApplyStateError
)

type ApplyStatus

type ApplyStatus struct {
	State ApplyState
	Error string
}

ApplyStatus is the processing status for a given configuration. It basically represents whether a config was successfully processed and apply, or if an error occurred

type CachedFile

type CachedFile struct {
	Path   string
	Length uint64
	Hashes map[string][]byte
}

CachedFile describes a cached file stored by the agent client

Note: You may be wondering why this exists when `ConfigState` exists as well. The API for requesting updates does not mandate that a client cache config files. This implementation just happens to do so.

type ConfigASMDD

type ConfigASMDD struct {
	Config   []byte
	Metadata Metadata
}

ConfigASMDD is a deserialized ASM DD configuration file along with its associated remote config metadata

type ConfigContent

type ConfigContent struct {
	LogLevel string `json:"log_level"`
}

ConfigContent contains the configurations set by remote-config

func MergeRCAgentConfig

func MergeRCAgentConfig(applyStatus func(cfgPath string, status ApplyStatus), updates map[string]RawConfig) (ConfigContent, error)

MergeRCAgentConfig is the callback function called when there is an AGENT_CONFIG config update The RCClient can directly call back listeners, because there would be no way to send back RCTE2 configuration applied state to RC backend.

type ConfigState

type ConfigState struct {
	Product     string
	ID          string
	Version     uint64
	ApplyStatus ApplyStatus
}

ConfigState describes an applied config by the agent client.

type Metadata

type Metadata struct {
	Product     string
	ID          string
	Name        string
	Version     uint64
	RawLength   uint64
	Hashes      map[string][]byte
	ApplyStatus ApplyStatus
}

Metadata stores remote config metadata for a given configuration

type RawConfig

type RawConfig struct {
	Config   []byte
	Metadata Metadata
}

RawConfig holds a config that will be parsed separately

type Repository

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

Repository is a remote config client used in a downstream process to retrieve remote config updates from an Agent.

func NewRepository

func NewRepository(embeddedRoot []byte) (*Repository, error)

NewRepository creates a new remote config repository that will track both TUF metadata and raw config files for a client.

func NewUnverifiedRepository

func NewUnverifiedRepository() (*Repository, error)

NewUnverifiedRepository creates a new remote config repository that will track config files for a client WITHOUT verifying any TUF related metadata.

When creating this we pretend we have a root version of 1, as the backend expects to not have to send the initial "embedded" root.

func (*Repository) ASMDDConfigs

func (r *Repository) ASMDDConfigs() map[string]ConfigASMDD

ASMDDConfigs returns the currently active ASMDD configs

func (*Repository) ASMDataConfigs

func (r *Repository) ASMDataConfigs() map[string]ASMDataConfig

ASMDataConfigs returns the currently active ASMData configs

func (*Repository) ASMFeaturesConfigs

func (r *Repository) ASMFeaturesConfigs() map[string]ASMFeaturesConfig

ASMFeaturesConfigs returns the currently active ASMFeatures configs

func (*Repository) AgentTaskConfigs

func (r *Repository) AgentTaskConfigs() map[string]AgentTaskConfig

AgentTaskConfigs returns the currently active AGENT_TASK configs

func (*Repository) CurrentState

func (r *Repository) CurrentState() (RepositoryState, error)

CurrentState returns all of the information needed to make an update for new configurations.

func (*Repository) GetConfigs

func (r *Repository) GetConfigs(product string) map[string]RawConfig

GetConfigs returns the current configs of a given product

func (*Repository) Update

func (r *Repository) Update(update Update) ([]string, error)

Update processes the ClientGetConfigsResponse from the Agent and updates the configuration state

func (*Repository) UpdateApplyStatus

func (r *Repository) UpdateApplyStatus(cfgPath string, status ApplyStatus)

UpdateApplyStatus updates the config's metadata to reflect its processing state Can be used after a call to Update() in order to tell the repository which config was acked, which wasn't and which errors occurred while processing. Note: it is the responsibility of the caller to ensure that no new Update() call was made between the first Update() call and the call to UpdateApplyStatus() so as to keep the repository state accurate.

type RepositoryState

type RepositoryState struct {
	Configs            []ConfigState
	CachedFiles        []CachedFile
	TargetsVersion     int64
	RootsVersion       int64
	OpaqueBackendState []byte
}

RepositoryState contains all of the information about the current config files stored by the client to be able to make an update request to an Agent

type Update

type Update struct {
	// TUFRoots contains, in order, updated roots that this repository needs to keep up with TUF validation
	TUFRoots [][]byte
	// TUFTargets is the latest TUF Targets file and is used to validate raw config files
	TUFTargets []byte
	// TargetFiles stores the raw config files by their full TUF path
	TargetFiles map[string][]byte
	// ClientcConfigs is a list of TUF path's corresponding to config files designated for this repository
	ClientConfigs []string
}

An Update contains all the data needed to update a client's remote config repository state