alspmgr

README

Application Layer Spam Prevention (ASLP) Manager

Implementation of ALSP manager is available here: manager.go Note that this readme is primarily focusing on the ALSP manager. For more details regarding the ALSP system please refer to readme.md.

Architectural Overview

Reporting Misbehavior and Managing Node Penalties

Figure below illustrates the ALSP manager’s role in the reporting of misbehavior and the management of node penalties as well as the interactions between the ALSP manager and the LibP2PNode, ConnectionGater, and PeerManager components for the disallow listing and allow listing processes.

Reporting Misbehavior

In the event that an engine detects misbehavior within a channel, it is imperative to report this finding to the ALSP manager. This is achieved by invoking the ReportMisbehavior method on the conduit corresponding to the engine.

Managing Penalties

The ALSP manager is responsible for maintaining records of misbehavior reports associated with remote nodes and for calculating their accumulated misbehavior penalties. Should a node’s misbehavior penalty surpass a certain threshold (referred to as DisallowListingThreshold), the ALSP manager initiates the disallow listing process. When a remote node is disallow-listed, it is effectively isolated from the network by the ConnectionGater and PeerManager components, i.e., the existing connections to that remote node are closed and new connections attempts are rejected.

Disallow Listing Process

1. The ALSP manager communicates with the LibP2PNode by calling its OnDisallowListNotification method to indicate that a particular remote node has been disallow-listed.

2. In response, the LibP2PNode takes two important actions:

   a. It alerts the PeerManager, instructing it to sever the connection with the disallow-listed node. b. It notifies the ConnectionGater to block any incoming or outgoing connections to and from the disallow-listed node. This ensures that the disallow-listed node is effectively isolated from the local node's network.

Penalty Decay and Allow Listing Process

The ALSP manager also includes a penalty decay mechanism, which gradually reduces the penalties of nodes over time upon regular heartbeat intervals (default is every one second). Once a disallow-listed node's penalty decays back to zero, the node can be reintegrated into the network through the allow listing process. The allow-listing process involves allowing the ConnectionGater to lift the block on the disallow-listed node and instructing the PeerManager to initiate an outbound connection with the allow-listed node.

1. The ALSP manager calls the OnAllowListNotification method on the LibP2PNode to signify that a previously disallow-listed node is now allow-listed.

2. The LibP2PNode responds by:

   a. Instructing the ConnectionGater to lift the block, thereby permitting connections with the now allow-listed node. b. Requesting the PeerManager to initiate an outbound connection with the allow-listed node.

This series of actions allows the rehabilitated node to be reintegrated and actively participate in the network once again.

Developer Guidelines

The ALSP (Application Layer Spam Prevention) Manager handles application layer spamming misbehavior reports and penalizes misbehaving nodes. It also disallow-lists nodes whose penalties drop below a threshold.

• Misbehavior Reports: When a local engine detects a spamming misbehavior of a remote node, it sends a report to the ALSP manager, by invoking the HandleMisbehaviorReport method of the corresponding conduit on which the misbehavior was detected. The manager handles the report in a thread-safe and non-blocking manner, using worker pools.

func (m *MisbehaviorReportManager) HandleMisbehaviorReport(channel channels.Channel, report network.MisbehaviorReport) {
    // Handle the report
}

• Penalties: Misbehaving nodes are penalized by the manager. The manager keeps a cache of records with penalties for each node. The penalties are decayed over time through periodic heartbeats.

• Disallow-listing: Nodes whose penalties drop below a threshold are disallow-listed.

• Heartbeats: Periodic heartbeats allow the manager to perform recurring tasks, such as decaying the penalties of misbehaving nodes.

func (m *MisbehaviorReportManager) heartbeatLoop(ctx irrecoverable.SignalerContext, interval time.Duration) {
    // Handle heartbeats
}

• Disallow-list Notification Consumer: is the interface of the consumer of disallow-list notifications, which is responsible for taking actions when a node is disallow-listed, i.e., closing exisitng connections with the remote disallow-listed node and blocking any incoming or outgoing connections to that node. The consumer is passed to the manager when it is created. In the current implementation the consumer is the instance of the LibP2PNode component of the node.

disallowListingConsumer network.DisallowListNotificationConsumer

Configuration

The configuration includes settings like cache size, heartbeat intervals, and network type.

Documentation

Index

• Variables
• type MisbehaviorReportManager
  • func NewMisbehaviorReportManager(cfg *MisbehaviorReportManagerConfig, ...) (*MisbehaviorReportManager, error)
  • func (m *MisbehaviorReportManager) HandleMisbehaviorReport(channel channels.Channel, report network.MisbehaviorReport)
• type MisbehaviorReportManagerConfig
• type MisbehaviorReportManagerOption
  • func WithDecayFunc(f SpamRecordDecayFunc) MisbehaviorReportManagerOption
  • func WithSpamRecordsCacheFactory(f SpamRecordCacheFactory) MisbehaviorReportManagerOption
• type SpamRecordCacheFactory
• type SpamRecordDecayFunc

Variables

var (
	// ErrSpamRecordCacheSizeNotSet is returned when the spam record cache size is not set, it is a fatal irrecoverable error,
	// and the ALSP module cannot be initialized.
	ErrSpamRecordCacheSizeNotSet = errors.New("spam record cache size is not set")
	// ErrSpamReportQueueSizeNotSet is returned when the spam report queue size is not set, it is a fatal irrecoverable error,
	// and the ALSP module cannot be initialized.
	ErrSpamReportQueueSizeNotSet = errors.New("spam report queue size is not set")
	// ErrHeartBeatIntervalNotSet is returned when the heartbeat interval is not set, it is a fatal irrecoverable error,
	// and the ALSP module cannot be initialized.
	ErrHeartBeatIntervalNotSet = errors.New("heartbeat interval is not set")
)

Types

type MisbehaviorReportManager

type MisbehaviorReportManager struct {
	component.Component
	// contains filtered or unexported fields
}

MisbehaviorReportManager is responsible for handling misbehavior reports, i.e., penalizing the misbehaving node and report the node to be disallow-listed if the overall penalty of the misbehaving node drops below the disallow-listing threshold.

func NewMisbehaviorReportManager

func NewMisbehaviorReportManager(cfg *MisbehaviorReportManagerConfig, consumer network.DisallowListNotificationConsumer) (*MisbehaviorReportManager, error)

NewMisbehaviorReportManager creates a new instance of the MisbehaviorReportManager. Args: cfg: the configuration for the MisbehaviorReportManager. consumer: the consumer for the disallow-listing notifications. When the manager decides to disallow-list a node, it notifies the consumer to perform the lower-level disallow-listing action at the networking layer. All connections to the disallow-listed node are closed and the node is removed from the overlay, and no further connections are established to the disallow-listed node, either inbound or outbound.

Returns:

	A new instance of the MisbehaviorReportManager.
 An error if the config is invalid. The error is considered irrecoverable.

func (*MisbehaviorReportManager) HandleMisbehaviorReport

func (m *MisbehaviorReportManager) HandleMisbehaviorReport(channel channels.Channel, report network.MisbehaviorReport)

HandleMisbehaviorReport is called upon a new misbehavior is reported. The implementation of this function should be thread-safe and non-blocking. Args:

channel: the channel on which the misbehavior is reported.
report: the misbehavior report.

Returns:

none.

type MisbehaviorReportManagerConfig

type MisbehaviorReportManagerConfig struct {
	Logger zerolog.Logger
	// SpamRecordCacheSize is the size of the spam record cache that stores the spam records for the authorized nodes.
	// It should be as big as the number of authorized nodes in Flow network.
	// Recommendation: for small network sizes 10 * number of authorized nodes to ensure that the cache can hold all the spam records of the authorized nodes.
	SpamRecordCacheSize uint32
	// SpamReportQueueSize is the size of the queue that stores the spam records to be processed by the worker pool.
	SpamReportQueueSize uint32
	// AlspMetrics is the metrics instance for the alsp module (collecting spam reports).
	AlspMetrics module.AlspMetrics
	// HeroCacheMetricsFactory is the metrics factory for the HeroCache-related metrics.
	// Having factory as part of the config allows to create the metrics locally in the module.
	HeroCacheMetricsFactory metrics.HeroCacheMetricsFactory
	// DisablePenalty indicates whether applying the penalty to the misbehaving node is disabled.
	// When disabled, the ALSP module logs the misbehavior reports and updates the metrics, but does not apply the penalty.
	// This is useful for managing production incidents.
	// Note: under normal circumstances, the ALSP module should not be disabled.
	DisablePenalty bool
	// NetworkType is the type of the network it is used to determine whether the ALSP module is utilized in the
	// public (unstaked) or private (staked) network.
	NetworkType network.NetworkingType
	// HeartBeatInterval is the interval between the heartbeats. Heartbeat is a recurring event that is used to
	// apply recurring actions, e.g., decay the penalty of the misbehaving nodes.
	HeartBeatInterval time.Duration
	Opts              []MisbehaviorReportManagerOption
}

type MisbehaviorReportManagerOption

type MisbehaviorReportManagerOption func(*MisbehaviorReportManager)

func WithDecayFunc

func WithDecayFunc(f SpamRecordDecayFunc) MisbehaviorReportManagerOption

WithDecayFunc sets the decay function for the MisbehaviorReportManager. Useful for testing purposes to simulate the decay of the penalty without waiting for the actual decay. Args:

f: the decay function.

Returns:

a MisbehaviorReportManagerOption that sets the decay function for the MisbehaviorReportManager.

Note: this option is useful primarily for testing purposes. The default decay function should be used for production.

func WithSpamRecordsCacheFactory

func WithSpamRecordsCacheFactory(f SpamRecordCacheFactory) MisbehaviorReportManagerOption

WithSpamRecordsCacheFactory sets the spam record cache factory for the MisbehaviorReportManager. Args:

f: the spam record cache factory.

Returns:

a MisbehaviorReportManagerOption that sets the spam record cache for the MisbehaviorReportManager.

Note: this option is useful primarily for testing purposes. The default factory should be sufficient for production.

type SpamRecordCacheFactory

type SpamRecordCacheFactory func(zerolog.Logger, uint32, module.HeroCacheMetrics) alsp.SpamRecordCache

type SpamRecordDecayFunc

type SpamRecordDecayFunc func(model.ProtocolSpamRecord) float64

SpamRecordDecayFunc is the function that calculates the decay of the spam record.