firewall

package
v0.17.3-alpha Latest Latest
Warning

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

 Go to latest Published: Aug 27, 2026 License: MIT Imports: 34 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// RuleEnforcerCaveat is the name of the custom caveat that contains all
	// the rules that need to be enforced in the firewall.
	RuleEnforcerCaveat = "lit-mac-fw"

	// MetaInfoValuePrefix is the static prefix a macaroon caveat value has
	// to mark the beginning of the meta information JSON data.
	MetaInfoValuePrefix = "meta"

	// MetaRulesValuePrefix is the static prefix a macaroon caveat value has
	// to mark the beginning of the rules list JSON data.
	MetaRulesValuePrefix = "rules"

	// CondPrivacy is the name of the custom caveat that will
	// instruct lnd to send all requests with this caveat to this
	// interceptor.
	CondPrivacy = "privacy"
)
View Source 
const (
	// MWRequestTypeStreamAuth represents the type name for a stream
	// authentication interception message.
	MWRequestTypeStreamAuth = "stream_auth"

	// MWRequestTypeRequest represents the type name for a request
	// interception message.
	MWRequestTypeRequest = "request"

	// MWRequestTypeResponse represents the type name for a response
	// interception message.
	MWRequestTypeResponse = "response"
)
View Source 
const (
	RequestLoggerLevelInterceptor = "interceptor"
	RequestLoggerLevelAll         = "all"
	RequestLoggerLevelFull        = "full"
)
View Source 
const (

	// DefaultTimeVariation is the default timestamp obfuscation variation
	// space. Timestamps are randomly shifted by ±DefaultTimeVariation.
	DefaultTimeVariation = time.Duration(10) * time.Minute
)
View Source 
const (
	// RequestLoggerName is the name of the RequestLogger interceptor.
	RequestLoggerName = "lit-macaroon-firewall-logger"
)
View Source 
const (
	// RuleEnforcerName is the name of the RuleEnforcer interceptor.
	RuleEnforcerName = "lit-macaroon-firewall"
)
View Source 
const Subsystem = "FIRE"

Variables

View Source 
var (
	// MetaInfoFullCaveatPrefix is the full prefix a caveat needs to have to
	// be recognized as a meta information caveat.
	MetaInfoFullCaveatPrefix = fmt.Sprintf("%s %s %s",
		macaroons.CondLndCustom, RuleEnforcerCaveat,
		MetaInfoValuePrefix)

	// MetaRulesFullCaveatPrefix is the full prefix a caveat needs to have
	// to be recognized as a rules list caveat.
	MetaRulesFullCaveatPrefix = fmt.Sprintf("%s %s %s",
		macaroons.CondLndCustom, RuleEnforcerCaveat,
		MetaRulesValuePrefix)

	// MetaPrivacyCaveatPrefix is the caveat prefix that will be used to
	// identify the privacy mapper caveat.
	MetaPrivacyCaveatPrefix = fmt.Sprintf("%s %s", macaroons.CondLndCustom,
		CondPrivacy)

	// MetaPrivacyCaveat is the caveat required to ensure that the
	// privacy mapper is activated as an interceptor for a request.
	MetaPrivacyCaveat = macaroon.Caveat{Id: []byte(MetaPrivacyCaveatPrefix)}

	// ErrNoMetaInfoCaveat is the error that is returned if a caveat doesn't
	// have the prefix to be recognized as a meta information caveat.
	ErrNoMetaInfoCaveat = fmt.Errorf("not a meta info caveat")

	// ErrNoRulesCaveat is the error that is returned if a caveat doesn't
	// have the prefix to be recognized as a rules list caveat.
	ErrNoRulesCaveat = fmt.Errorf("not a rules list caveat")
)
View Source 
var (
	// ErrNotSupportedByPrivacyMapper indicates that the invoked RPC method
	// is not supported by the privacy mapper.
	ErrNotSupportedByPrivacyMapper = errors.New("this RPC call is not " +
		"supported by the privacy mapper interceptor")
)

Functions

func CryptoRandIntn 

func CryptoRandIntn(n int64) (int64, error)

CryptoRandIntn generates a random number between [0, n).

func IsPrivacyCaveat 

func IsPrivacyCaveat(caveat string) bool

IsPrivacyCaveat returns true if the given caveat string is a privacy mapper caveat.

func ObfuscateConfig 

func ObfuscateConfig(db firewalldb.PrivacyMapReader, configB []byte,
	flags session.PrivacyFlags) ([]byte, map[string]string, error)

ObfuscateConfig alters the config string by replacing sensitive data with random values and returns new replacement pairs. We only substitute items in strings, numbers are left unchanged.

func RulesToCaveat 

func RulesToCaveat(rules *InterceptRules) (string, error)

RulesToCaveat encodes a list of rules as a full custom caveat string representation in this format: 

lnd-custom lit-mac-fw rules:[<array_of_JSON_encoded_rules>]

func UseLogger 

func UseLogger(logger btclog.Logger)

UseLogger uses a specified Logger to output package logging info. This should be used in preference to SetLogWriter if the caller is also using btclog.

Types

type Config 

type Config struct {
	RequestLogger *RequestLoggerConfig `group:"request-logger" namespace:"request-logger" description:"request logger settings"`
}

Config holds all config options for the firewall.

func DefaultConfig 

func DefaultConfig() *Config

DefaultConfig constructs the default firewall Config struct.

type InterceptMetaInfo 

type InterceptMetaInfo struct {
	// ActorName is the name of the actor service (=management software)
	// that is issuing this request.
	ActorName string `json:"actor_name"`

	// Feature is the feature that caused the actor to execute this action.
	Feature string `json:"feature"`

	// Trigger is the action or condition that triggered this intercepted
	// request to be made.
	Trigger string `json:"trigger"`

	// Intent is the desired outcome or end condition this request aims to
	// arrive at.
	Intent string `json:"intent"`

	// StructuredJsonData is extra, structured, info that the Autopilot can
	// send to Lit. It is a json serialised string.
	StructuredJsonData string `json:"structured_json_data"`
}

InterceptMetaInfo is the JSON serializable struct containing meta information about a request made by an automated node management software against LiT. The meta information is added as a macaroon caveat.

func ParseMetaInfoCaveat 

func ParseMetaInfoCaveat(caveat string) (*InterceptMetaInfo, error)

ParseMetaInfoCaveat tries to parse the given caveat string as a meta information struct.

func (*InterceptMetaInfo) ToCaveat 

func (i *InterceptMetaInfo) ToCaveat() (string, error)

ToCaveat returns the full custom caveat string representation of the interception meta information in this format: 

lnd-custom lit-mac-fw meta:<JSON_encoded_meta_information>

type InterceptRules 

type InterceptRules struct {
	// SessionRules are rules that apply session wide. The map is rule
	// name to rule value.
	SessionRules map[string]string `json:"session_rules"`

	// Feature rules are rules that apply to a specific feature. The map is
	// feature name to a map of rule name to rule value.
	FeatureRules map[string]map[string]string `json:"feature_rules"`
}

InterceptRules is the JSON serializable struct containing all the rules and their limits/settings that need to be enforced on a request made by an automated node management software against LiT. The rule information is added as a custom macaroon caveat.

func ParseRuleCaveat 

func ParseRuleCaveat(caveat string) (*InterceptRules, error)

ParseRuleCaveat tries to parse the given caveat string as a rule struct.

type PermissionsManager 

type PermissionsManager interface {
	// IsSubServerURI returns true if the given URI belongs to the RPC of
	// the named sub-server.
	IsSubServerURI(subServer string, uri string) bool
}

PermissionsManager defines the interface for checking if a URI belongs to a specific sub-server.

type PrivacyMapper 

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

PrivacyMapper is a RequestInterceptor that maps any pseudo names in certain requests to their real values and vice versa for responses.

func NewPrivacyMapper 

func NewPrivacyMapper(newDB firewalldb.PrivacyMapper,
	randIntn func(int64) (int64, error),
	sessionDB firewalldb.SessionDB, permsMgr PermissionsManager,
	timeVariation time.Duration) *PrivacyMapper

NewPrivacyMapper returns a new instance of PrivacyMapper. The time variation parameter specifies the variation space for timestamp obfuscation. If zero, DefaultTimeVariation is used. The randIntn function is used to draw randomness for request field obfuscation.

func (*PrivacyMapper) CustomCaveatName 

func (p *PrivacyMapper) CustomCaveatName() string

CustomCaveatName returns the name of the custom caveat that is expected to be handled by this interceptor. Cannot be specified in read-only mode.

func (*PrivacyMapper) Intercept 

func (p *PrivacyMapper) Intercept(ctx context.Context,
	req *lnrpc.RPCMiddlewareRequest) (*lnrpc.RPCMiddlewareResponse, error)

Intercept processes an RPC middleware interception request and returns the interception result which either accepts or rejects the intercepted message.

func (*PrivacyMapper) Name 

func (p *PrivacyMapper) Name() string

Name returns the name of the interceptor.

func (*PrivacyMapper) ReadOnly 

func (p *PrivacyMapper) ReadOnly() bool

ReadOnly returns true if this interceptor should be registered in read-only mode. In read-only mode no custom caveat name can be specified.

func (*PrivacyMapper) StreamServerInterceptor 

func (p *PrivacyMapper) StreamServerInterceptor() grpc.StreamServerInterceptor

StreamServerInterceptor returns a gRPC stream server interceptor that enforces fail-close privacy for non-LND services. LND streaming RPCs are passed through (they use LND's own middleware chain). Non-LND streams are passed through for sessions without privacy mapping, and blocked for privacy-enabled sessions because the privacy mapper does not yet support stream-level request/response rewriting.

func (*PrivacyMapper) UnaryInterceptor 

func (p *PrivacyMapper) UnaryInterceptor() grpc.UnaryServerInterceptor

UnaryInterceptor returns a gRPC unary server interceptor that applies privacy mapping to LNC session requests for non-LND services. This interceptor enforces fail-close behavior: blocks requests if dependencies aren't ready, returns errors if no privacy checker exists for the URI.

type RequestInfo 

type RequestInfo struct {
	SessionID       fn.Option[session.ID]
	AccountID       fn.Option[accounts.AccountID]
	MsgID           uint64
	RequestID       uint64
	MWRequestType   string
	URI             string
	GRPCMessageType string
	IsError         bool
	Serialized      []byte
	Streaming       bool
	Macaroon        *macaroon.Macaroon
	Caveats         []string
	MetaInfo        *InterceptMetaInfo
	Rules           *InterceptRules
	WithPrivacy     bool
	RulesCaveat     string
}

RequestInfo stores the parsed representation of an incoming RPC middleware request.

func NewInfoFromRequest 

func NewInfoFromRequest(req *lnrpc.RPCMiddlewareRequest) (*RequestInfo, error)

NewInfoFromRequest parses the given RPC middleware interception request and returns a RequestInfo struct.

func (*RequestInfo) String 

func (ri *RequestInfo) String() string

String returns the string representation of the request info struct.

type RequestLogger 

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

RequestLogger is a RequestInterceptor that just logs incoming RPC requests.

func NewRequestLogger 

func NewRequestLogger(cfg *RequestLoggerConfig,
	actionsDB firewalldb.ActionsWriteDB) (*RequestLogger, error)

NewRequestLogger creates a new RequestLogger.

func (*RequestLogger) CustomCaveatName 

func (r *RequestLogger) CustomCaveatName() string

CustomCaveatName returns the name of the custom caveat that is expected to be handled by this interceptor. Cannot be specified in read-only mode.

func (*RequestLogger) Intercept 

func (r *RequestLogger) Intercept(ctx context.Context,
	req *lnrpc.RPCMiddlewareRequest) (*lnrpc.RPCMiddlewareResponse, error)

Intercept processes an RPC middleware interception request and returns the interception result which either accepts or rejects the intercepted message.

func (*RequestLogger) MarkAction 

func (r *RequestLogger) MarkAction(ctx context.Context, reqID uint64,
	state firewalldb.ActionState, errReason string) error

MarkAction can be used to set the state of an action identified by the given requestID.

func (*RequestLogger) Name 

func (r *RequestLogger) Name() string

Name returns the name of the interceptor.

func (*RequestLogger) ReadOnly 

func (r *RequestLogger) ReadOnly() bool

ReadOnly returns true if this interceptor should be registered in read-only mode. In read-only mode no custom caveat name can be specified.

type RequestLoggerConfig 

type RequestLoggerConfig struct {
	// Disable completely disables request logging. This option exists as a
	// separate flag rather than a log level because there are scenarios
	// where logging should be entirely skipped (no interceptor, no
	// database writes) rather than just filtered. Disabling improves
	// performance by avoiding all logging overhead, whereas a log level
	// would still process and filter each request.
	Disable            bool               `long:"disable" description:"Disable request logging completely. If set, autopilot.disable must also be set"`
	RequestLoggerLevel RequestLoggerLevel `long:"level" description:"Set the request logger level. Options include 'all', 'full' and 'interceptor''"`
}

RequestLoggerConfig holds all the config options for the request logger.

type RequestLoggerLevel 

type RequestLoggerLevel string

type RuleEnforcer 

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

RuleEnforcer is a RequestInterceptor that makes sure all firewall related custom caveats in a macaroon are properly enforced.

func NewRuleEnforcer 

func NewRuleEnforcer(ruleDB firewalldb.RulesDB,
	actionsDB firewalldb.ActionReadDBGetter,
	sessionIDIndex firewalldb.SessionDB,
	getFeaturePerms featurePerms, permsMgr *perms.Manager, nodeID [33]byte,
	routerClient lndclient.RouterClient,
	lndClient lndclient.LightningClient, lndConnID string,
	ruleMgrs rules.ManagerSet,
	markActionErrored func(ctx context.Context, reqID uint64,
		reason string) error,
	privMap firewalldb.PrivacyMapper) *RuleEnforcer

NewRuleEnforcer constructs a new RuleEnforcer instance.

func (*RuleEnforcer) CustomCaveatName 

func (r *RuleEnforcer) CustomCaveatName() string

CustomCaveatName returns the name of the custom caveat that is expected to be handled by this interceptor. Cannot be specified in read-only mode.

func (*RuleEnforcer) Intercept 

func (r *RuleEnforcer) Intercept(ctx context.Context,
	req *lnrpc.RPCMiddlewareRequest) (*lnrpc.RPCMiddlewareResponse, error)

Intercept processes an RPC middleware interception request and returns the interception result which either accepts or rejects the intercepted message.

func (*RuleEnforcer) Name 

func (r *RuleEnforcer) Name() string

Name returns the name of the interceptor.

func (*RuleEnforcer) ReadOnly 

func (r *RuleEnforcer) ReadOnly() bool

ReadOnly returns true if this interceptor should be registered in read-only mode. In read-only mode no custom caveat name can be specified.

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.