mellaris

README

Mellaris

Mellaris is a Go library for network stream analysis and filtering.

Usage

package main

import (
	"context"

	"git.difuse.io/Difuse/Mellaris"
)

func main() {
	cfg := mellaris.Config{
		IO: mellaris.IOConfig{
			// QueueSize, ReadBuffer, WriteBuffer, Local, RST
		},
		Workers: mellaris.WorkersConfig{
			// Count, QueueSize, TCPMaxBufferedPagesTotal, TCPMaxBufferedPagesPerConn, UDPMaxStreams
		},
		Ruleset: mellaris.RulesetConfig{
			GeoIp:   "/path/to/geoip.dat",
			GeoSite: "/path/to/geosite.dat",
		},
	}

	app, err := mellaris.New(cfg, mellaris.Options{
		RulesFile: "rules.yaml",
		Analyzers: mellaris.DefaultAnalyzers(),
		Modifiers: mellaris.DefaultModifiers(),
	})
	if err != nil {
		panic(err)
	}
	defer app.Close()

	_ = app.Run(context.Background())
}

Testing

Run all tests:

go test ./...

Run tests with coverage:

go test -cover ./...                              # per-package summary
go test -coverprofile=coverage.out ./...          # full profile
go tool cover -html=coverage.out -o coverage.html # HTML report

Run tests for a specific package:

go test -v ./analyzer/tcp/
go test -v -run TestSSH ./analyzer/tcp/

Based on OpenGFW by apernet: https://github.com/apernet/OpenGFW

LICENSE

MPL-2.0

Documentation

Index

• func DefaultAnalyzers() []analyzer.Analyzer
• func DefaultModifiers() []modifier.Modifier
• type App
  • func New(cfg Config, opts Options) (*App, error)
  • func (a *App) Close() error
  • func (a *App) Engine() engine.Engine
  • func (a *App) ReloadRules() error
  • func (a *App) Run(ctx context.Context) error
  • func (a *App) Stats() Stats
  • func (a *App) UpdateRules(rules []ruleset.ExprRule) error
• type Config
• type ConfigError
  • func (e ConfigError) Error() string
  • func (e ConfigError) Unwrap() error
• type IOConfig
• type Options
• type RulesetConfig
• type Stats
• type WorkersConfig

Functions

func DefaultAnalyzers

func DefaultAnalyzers() []analyzer.Analyzer

DefaultAnalyzers returns the built-in analyzer set.

func DefaultModifiers

func DefaultModifiers() []modifier.Modifier

DefaultModifiers returns the built-in modifier set.

Types

type App

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

App owns the Mellaris engine and ruleset lifecycle.

func New

func New(cfg Config, opts Options) (*App, error)

New builds an App from config and options.

func (*App) Close

func (a *App) Close() error

Close releases the underlying PacketIO.

func (*App) Engine

func (a *App) Engine() engine.Engine

Engine returns the underlying engine instance.

func (*App) ReloadRules

func (a *App) ReloadRules() error

ReloadRules reloads rules from the configured rules file.

func (*App) Run

func (a *App) Run(ctx context.Context) error

Run starts the engine and blocks until it exits or ctx is cancelled.

func (*App) Stats

func (a *App) Stats() Stats

func (*App) UpdateRules

func (a *App) UpdateRules(rules []ruleset.ExprRule) error

UpdateRules compiles the provided rules and updates the running engine.

type Config

type Config struct {
	IO      IOConfig      `mapstructure:"io" yaml:"io"`
	Workers WorkersConfig `mapstructure:"workers" yaml:"workers"`
	Ruleset RulesetConfig `mapstructure:"ruleset" yaml:"ruleset"`
}

Config defines IO, worker, and ruleset settings for the engine.

type ConfigError

type ConfigError struct {
	Field string
	Err   error
}

ConfigError indicates a configuration issue.

func (ConfigError) Error

func (e ConfigError) Error() string

func (ConfigError) Unwrap

func (e ConfigError) Unwrap() error

type IOConfig

type IOConfig struct {
	QueueSize    uint32 `mapstructure:"queueSize" yaml:"queueSize"`
	ReadBuffer   int    `mapstructure:"rcvBuf" yaml:"rcvBuf"`
	WriteBuffer  int    `mapstructure:"sndBuf" yaml:"sndBuf"`
	Local        bool   `mapstructure:"local" yaml:"local"`
	RST          bool   `mapstructure:"rst" yaml:"rst"`
	NumQueues    int    `mapstructure:"numQueues" yaml:"numQueues"`
	MaxPacketLen uint32 `mapstructure:"maxPacketLen" yaml:"maxPacketLen"`

	// PacketIO overrides NFQueue creation when set.
	// When provided, App.Close will call PacketIO.Close.
	PacketIO gfwio.PacketIO `mapstructure:"-" yaml:"-"`
}

IOConfig configures packet IO.

type Options

type Options struct {
	// RulesFile is a YAML rules file on disk. Mutually exclusive with Rules.
	RulesFile string
	// Rules provides inline expression rules. Mutually exclusive with RulesFile.
	Rules []ruleset.ExprRule

	// Analyzers and Modifiers default to built-ins when nil.
	Analyzers []analyzer.Analyzer
	Modifiers []modifier.Modifier

	// EngineLogger and RulesetLogger default to no-op loggers when nil.
	EngineLogger  engine.Logger
	RulesetLogger ruleset.Logger
}

Options configures rules, analyzers, modifiers, and logging.

type RulesetConfig

type RulesetConfig struct {
	GeoIp   string `mapstructure:"geoip" yaml:"geoip"`
	GeoSite string `mapstructure:"geosite" yaml:"geosite"`
}

RulesetConfig configures built-in rule helpers.

type Stats

type Stats struct {
	Engine  engine.Stats
	Ruleset ruleset.Stats
}

type WorkersConfig

type WorkersConfig struct {
	Count                      int                          `mapstructure:"count" yaml:"count"`
	QueueSize                  int                          `mapstructure:"queueSize" yaml:"queueSize"`
	TCPMaxBufferedPagesTotal   int                          `mapstructure:"tcpMaxBufferedPagesTotal" yaml:"tcpMaxBufferedPagesTotal"`
	TCPMaxBufferedPagesPerConn int                          `mapstructure:"tcpMaxBufferedPagesPerConn" yaml:"tcpMaxBufferedPagesPerConn"`
	UDPMaxStreams              int                          `mapstructure:"udpMaxStreams" yaml:"udpMaxStreams"`
	OverflowPolicy             engine.OverflowPolicy        `mapstructure:"overflowPolicy" yaml:"overflowPolicy"`
	AnalyzerSelectionMode      engine.AnalyzerSelectionMode `mapstructure:"analyzerSelectionMode" yaml:"analyzerSelectionMode"`
}

WorkersConfig configures engine worker behavior.