plugin

package
v0.0.0-...-95d7268 Latest Latest
Warning

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

 Go to latest Published: Mar 19, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package plugin provides the plugin architecture for afterdark-darkd. It uses hashicorp/go-plugin for cross-platform, multi-language plugin support.

Index

Constants

View Source 
const ProtocolVersion = 1

ProtocolVersion is the plugin protocol version

Variables

View Source 
var HandshakeConfig = plugin.HandshakeConfig{
	ProtocolVersion:  ProtocolVersion,
	MagicCookieKey:   "AFTERDARK_PLUGIN",
	MagicCookieValue: "darkd-v1",
}

HandshakeConfig is used to validate plugin connections

View Source 
var PluginMap = map[string]plugin.Plugin{
	"service":    &ServicePluginImpl{},
	"datasource": &DataSourcePluginImpl{},
	"storage":    &StoragePluginImpl{},
	"reporter":   &ReporterPluginImpl{},
	"cli":        &CLIPluginImpl{},
}

PluginMap defines the available plugin types

Functions

This section is empty.

Types

type BlockedIP 

type BlockedIP struct {
	IP            string    `json:"ip"`
	Reason        string    `json:"reason"`
	SourceService string    `json:"source_service"`
	BlockedAt     time.Time `json:"blocked_at"`
	ExpiresAt     time.Time `json:"expires_at,omitempty"`
	ThreatScore   int       `json:"threat_score"`
	Categories    []string  `json:"categories"`
}

BlockedIP represents a blocked IP address

type CLICommand 

type CLICommand struct {
	Name        string       `json:"name"`
	Description string       `json:"description"`
	Usage       string       `json:"usage"`
	Flags       []CLIFlag    `json:"flags,omitempty"`
	Subcommands []CLICommand `json:"subcommands,omitempty"`
}

CLICommand represents a CLI command provided by a plugin

type CLIFlag 

type CLIFlag struct {
	Name        string `json:"name"`
	Shorthand   string `json:"shorthand,omitempty"`
	Description string `json:"description"`
	Type        string `json:"type"` // "string", "int", "bool", "stringSlice"
	Default     string `json:"default,omitempty"`
	Required    bool   `json:"required"`
}

CLIFlag represents a command-line flag

type CLIPlugin 

type CLIPlugin interface {
	// Info returns plugin metadata
	Info() PluginInfo

	// Configure sets up the CLI plugin
	Configure(config map[string]interface{}) error

	// Commands returns the list of commands provided by this plugin
	Commands() []CLICommand

	// Execute runs a command with the given arguments and flags
	Execute(ctx context.Context, command string, args []string, flags map[string]interface{}) (string, error)

	// Health returns the current health status
	Health() PluginHealth
}

CLIPlugin is the interface for CLI command plugins These add new commands to the admin and user CLIs

type CLIPluginImpl 

type CLIPluginImpl struct {
	plugin.Plugin
	Impl CLIPlugin
}

CLIPluginImpl implements plugin.GRPCPlugin for CLI plugins

func (*CLIPluginImpl) GRPCClient 

func (p *CLIPluginImpl) GRPCClient(ctx context.Context, broker *plugin.GRPCBroker, c *grpc.ClientConn) (interface{}, error)

func (*CLIPluginImpl) GRPCServer 

func (p *CLIPluginImpl) GRPCServer(broker *plugin.GRPCBroker, s *grpc.Server) error

type DataSourcePlugin 

type DataSourcePlugin interface {
	// Info returns plugin metadata
	Info() PluginInfo

	// Configure sets up the data source
	Configure(config map[string]interface{}) error

	// Connect establishes connection to the data source
	Connect(ctx context.Context) error

	// Disconnect closes the connection
	Disconnect(ctx context.Context) error

	// Query retrieves data from the source
	Query(ctx context.Context, query string, params map[string]interface{}) ([]map[string]interface{}, error)

	// Subscribe sets up real-time updates (optional)
	Subscribe(ctx context.Context, topic string, handler func(data map[string]interface{})) error

	// Health returns the current health status
	Health() PluginHealth
}

DataSourcePlugin is the interface for data source plugins These provide threat intel feeds, API integrations, etc.

type DataSourcePluginImpl 

type DataSourcePluginImpl struct {
	plugin.Plugin
	Impl DataSourcePlugin
}

DataSourcePluginImpl implements plugin.GRPCPlugin for data source plugins

func (*DataSourcePluginImpl) GRPCClient 

func (p *DataSourcePluginImpl) GRPCClient(ctx context.Context, broker *plugin.GRPCBroker, c *grpc.ClientConn) (interface{}, error)

func (*DataSourcePluginImpl) GRPCServer 

func (p *DataSourcePluginImpl) GRPCServer(broker *plugin.GRPCBroker, s *grpc.Server) error

type FirewallPlugin 

type FirewallPlugin interface {
	// Info returns plugin metadata
	Info() PluginInfo

	// Configure sets up the firewall plugin
	Configure(config map[string]interface{}) error

	// Health returns the current health status
	Health() PluginHealth

	// Firewall control
	Enable(ctx context.Context, enable bool, defaultDenyInbound bool, defaultDenyOutbound bool) (*FirewallStatus, error)
	Status(ctx context.Context) (*FirewallStatus, error)

	// IP blocking
	BlockIP(ctx context.Context, ip string, reason string, sourceService string, durationSeconds int64, threatScore int, categories []string) (*BlockedIP, error)
	UnblockIP(ctx context.Context, ip string) error
	ListBlockedIPs(ctx context.Context, limit int, offset int, sourceService string) ([]BlockedIP, int, error)
	IsIPBlocked(ctx context.Context, ip string) (bool, *BlockedIP, error)

	// Rule management
	AddRule(ctx context.Context, rule *FirewallRule) (*FirewallRule, error)
	RemoveRule(ctx context.Context, ruleID string) error
	UpdateRule(ctx context.Context, rule *FirewallRule) (*FirewallRule, error)
	ListRules(ctx context.Context, limit int, offset int, direction string, enabledOnly bool) ([]FirewallRule, int, error)
	GetRule(ctx context.Context, ruleID string) (*FirewallRule, error)

	// Bulk operations
	SyncBlocklist(ctx context.Context, blockedIPs []BlockedIP, replace bool) (added int, removed int, unchanged int, err error)
	FlushRules(ctx context.Context, flushBlocks bool, flushRules bool, keepEssential bool) (rulesFlushed int, blocksFlushed int, err error)

	// Port management (convenience)
	OpenPort(ctx context.Context, port int, protocol string, direction string, sourceIP string, description string) (*FirewallRule, error)
	ClosePort(ctx context.Context, port int, protocol string, direction string) error
}

FirewallPlugin is the interface for firewall plugins These provide OS-specific firewall control (iptables, pf, Windows Firewall)

type FirewallRule 

type FirewallRule struct {
	ID            string    `json:"id"`
	Name          string    `json:"name"`
	Description   string    `json:"description"`
	Direction     string    `json:"direction"`   // "inbound", "outbound", "both"
	Action        string    `json:"action"`      // "allow", "deny", "drop", "reject"
	Protocol      string    `json:"protocol"`    // "tcp", "udp", "icmp", "any"
	SourceIP      string    `json:"source_ip"`   // CIDR notation
	SourcePort    string    `json:"source_port"` // Port or range
	DestIP        string    `json:"dest_ip"`
	DestPort      string    `json:"dest_port"`
	Interface     string    `json:"interface"`
	Priority      int       `json:"priority"`
	Enabled       bool      `json:"enabled"`
	CreatedAt     time.Time `json:"created_at"`
	ExpiresAt     time.Time `json:"expires_at,omitempty"`
	Reason        string    `json:"reason"`
	SourceService string    `json:"source_service"`
	HitCount      int64     `json:"hit_count"`
	LastHitAt     time.Time `json:"last_hit_at,omitempty"`
}

FirewallRule represents a firewall rule

type FirewallStatus 

type FirewallStatus struct {
	Enabled             bool              `json:"enabled"`
	Backend             string            `json:"backend"`
	Version             string            `json:"version"`
	TotalRules          int               `json:"total_rules"`
	ActiveRules         int               `json:"active_rules"`
	BlockedIPs          int               `json:"blocked_ips"`
	DefaultDenyInbound  bool              `json:"default_deny_inbound"`
	DefaultDenyOutbound bool              `json:"default_deny_outbound"`
	LastUpdated         time.Time         `json:"last_updated"`
	Capabilities        map[string]string `json:"capabilities"`
}

FirewallStatus represents the current firewall state

type Host 

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

Host manages plugin lifecycle

func NewHost 

func NewHost(pluginDir string, logger *zap.Logger) *Host

NewHost creates a new plugin host

func (*Host) DiscoverPlugins 

func (h *Host) DiscoverPlugins() ([]string, error)

DiscoverPlugins scans the plugin directory for available plugins

func (*Host) GetCLIPlugins 

func (h *Host) GetCLIPlugins() []CLIPlugin

GetCLIPlugins returns all loaded CLI plugins

func (*Host) GetDataSourcePlugins 

func (h *Host) GetDataSourcePlugins() []DataSourcePlugin

GetDataSourcePlugins returns all loaded data source plugins

func (*Host) GetPlugin 

func (h *Host) GetPlugin(path string) (*LoadedPlugin, bool)

GetPlugin returns a loaded plugin by path

func (*Host) GetPluginByName 

func (h *Host) GetPluginByName(name string) (*LoadedPlugin, bool)

GetPluginByName returns a loaded plugin by name

func (*Host) GetReporterPlugins 

func (h *Host) GetReporterPlugins() []ReporterPlugin

GetReporterPlugins returns all loaded reporter plugins

func (*Host) GetServicePlugins 

func (h *Host) GetServicePlugins() []ServicePlugin

GetServicePlugins returns all loaded service plugins

func (*Host) GetStoragePlugins 

func (h *Host) GetStoragePlugins() []StoragePlugin

GetStoragePlugins returns all loaded storage plugins

func (*Host) HealthCheck 

func (h *Host) HealthCheck() map[string]PluginHealth

HealthCheck performs health check on all plugins

func (*Host) ListPlugins 

func (h *Host) ListPlugins() []*LoadedPlugin

ListPlugins returns all loaded plugins

func (*Host) LoadAllPlugins 

func (h *Host) LoadAllPlugins() error

LoadAllPlugins discovers and loads all plugins

func (*Host) LoadPlugin 

func (h *Host) LoadPlugin(path string) (*LoadedPlugin, error)

LoadPlugin loads a single plugin from the given path

func (*Host) UnloadAllPlugins 

func (h *Host) UnloadAllPlugins()

UnloadAllPlugins stops all loaded plugins

func (*Host) UnloadPlugin 

func (h *Host) UnloadPlugin(path string) error

UnloadPlugin stops and removes a plugin

type LoadedPlugin 

type LoadedPlugin struct {
	Info       PluginInfo
	Path       string
	Client     *plugin.Client
	Raw        interface{}
	State      PluginState
	LoadedAt   time.Time
	LastHealth PluginHealth
	// contains filtered or unexported fields
}

LoadedPlugin represents a loaded and running plugin

type PluginHealth 

type PluginHealth struct {
	State     PluginState            `json:"state"`
	Message   string                 `json:"message,omitempty"`
	LastCheck time.Time              `json:"last_check"`
	Metrics   map[string]interface{} `json:"metrics,omitempty"`
}

PluginHealth represents health status of a plugin

type PluginInfo 

type PluginInfo struct {
	Name         string     `json:"name"`
	Version      string     `json:"version"`
	Type         PluginType `json:"type"`
	Description  string     `json:"description"`
	Author       string     `json:"author"`
	License      string     `json:"license"`
	Capabilities []string   `json:"capabilities,omitempty"`
}

PluginInfo contains metadata about a plugin

type PluginState 

type PluginState int

PluginState represents the current state of a plugin 

const (
	PluginStateUnknown PluginState = iota
	PluginStateLoading
	PluginStateReady
	PluginStateRunning
	PluginStateStopping
	PluginStateStopped
	PluginStateError
)

func (PluginState) String 

func (s PluginState) String() string

type PluginType 

type PluginType string

PluginType identifies the kind of plugin 

const (
	PluginTypeService    PluginType = "service"
	PluginTypeDataSource PluginType = "datasource"
	PluginTypeStorage    PluginType = "storage"
	PluginTypeReporter   PluginType = "reporter"
	PluginTypeCLI        PluginType = "cli"
	PluginTypeFirewall   PluginType = "firewall"
)

type ReporterPlugin 

type ReporterPlugin interface {
	// Info returns plugin metadata
	Info() PluginInfo

	// Configure sets up the reporter
	Configure(config map[string]interface{}) error

	// SupportedFormats returns list of output formats (e.g., "pdf", "html", "csv")
	SupportedFormats() []string

	// Generate creates a report from the provided data
	Generate(ctx context.Context, format string, data map[string]interface{}) ([]byte, error)

	// Health returns the current health status
	Health() PluginHealth
}

ReporterPlugin is the interface for report generator plugins These generate reports in various formats (PDF, HTML, etc.)

type ReporterPluginImpl 

type ReporterPluginImpl struct {
	plugin.Plugin
	Impl ReporterPlugin
}

ReporterPluginImpl implements plugin.GRPCPlugin for reporter plugins

func (*ReporterPluginImpl) GRPCClient 

func (p *ReporterPluginImpl) GRPCClient(ctx context.Context, broker *plugin.GRPCBroker, c *grpc.ClientConn) (interface{}, error)

func (*ReporterPluginImpl) GRPCServer 

func (p *ReporterPluginImpl) GRPCServer(broker *plugin.GRPCBroker, s *grpc.Server) error

type ServicePlugin 

type ServicePlugin interface {
	// Info returns plugin metadata
	Info() PluginInfo

	// Configure sets up the plugin with the provided configuration
	Configure(config map[string]interface{}) error

	// Start initializes and starts the service
	Start(ctx context.Context) error

	// Stop gracefully shuts down the service
	Stop(ctx context.Context) error

	// Health returns the current health status
	Health() PluginHealth

	// Execute runs a specific action and returns results
	Execute(ctx context.Context, action string, params map[string]interface{}) (map[string]interface{}, error)
}

ServicePlugin is the interface for service-type plugins These add new monitoring/security services to the daemon

type ServicePluginImpl 

type ServicePluginImpl struct {
	plugin.Plugin
	Impl ServicePlugin
}

ServicePluginImpl implements plugin.GRPCPlugin for service plugins

func (*ServicePluginImpl) GRPCClient 

func (p *ServicePluginImpl) GRPCClient(ctx context.Context, broker *plugin.GRPCBroker, c *grpc.ClientConn) (interface{}, error)

func (*ServicePluginImpl) GRPCServer 

func (p *ServicePluginImpl) GRPCServer(broker *plugin.GRPCBroker, s *grpc.Server) error

type StoragePlugin 

type StoragePlugin interface {
	// Info returns plugin metadata
	Info() PluginInfo

	// Configure sets up the storage backend
	Configure(config map[string]interface{}) error

	// Connect establishes connection to storage
	Connect(ctx context.Context) error

	// Disconnect closes the connection
	Disconnect(ctx context.Context) error

	// Get retrieves a value by key from a collection
	Get(ctx context.Context, collection, key string) ([]byte, error)

	// Set stores a value by key in a collection
	Set(ctx context.Context, collection, key string, value []byte) error

	// Delete removes a key from a collection
	Delete(ctx context.Context, collection, key string) error

	// List returns all keys in a collection matching a prefix
	List(ctx context.Context, collection, prefix string) ([]string, error)

	// Query performs a query on the storage (implementation-specific)
	Query(ctx context.Context, collection string, query map[string]interface{}) ([][]byte, error)

	// Health returns the current health status
	Health() PluginHealth
}

StoragePlugin is the interface for storage backend plugins These provide alternative storage mechanisms (databases, cloud, etc.)

type StoragePluginImpl 

type StoragePluginImpl struct {
	plugin.Plugin
	Impl StoragePlugin
}

StoragePluginImpl implements plugin.GRPCPlugin for storage plugins

func (*StoragePluginImpl) GRPCClient 

func (p *StoragePluginImpl) GRPCClient(ctx context.Context, broker *plugin.GRPCBroker, c *grpc.ClientConn) (interface{}, error)

func (*StoragePluginImpl) GRPCServer 

func (p *StoragePluginImpl) GRPCServer(broker *plugin.GRPCBroker, s *grpc.Server) error

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.