ripcord

README

ripcord

A damage-limitation monitoring library to protect your infrastructure during a DOS attack.

What's the point?

Here's a scenario. Totally plucked from the air but scary enough that I decided to implement ripcord:

• You run a server that's exposed on the internet.
• You've opted for a price bracket that suits you and enjoy up to 500GB of transfer between you and your users.
• You get DDOS'd, which takes your bandwidth way beyond your allowance.
• It's OK! You've configured an early-warning system, which emails you if your monthly expenditure exceeds a configured maximum.
• You're in a meeting and you feel an email come through. You obviously don't open it because that would bring about shame upon you and your kin.
• You leave your meeting to find that your monthly expenditure is currently £78,041 and your cloud provider want blood.

What it does

Ripcord sits on your web servers and monitors the traffic on any number of configured network interfaces. If the number of bytes sent or received exceeds a configured maximum, you can perform a task, which might include killing your web server entirely as damage limitation.

Todo

• Allow the user to configure command against each network interface
• Test in-process usage
• Test out-of-process usage
• Runner should take Options, allowing for default stats collector to be used
• Ability to run different stats collectors per interface config

Documentation

Index

• func NewLogger(out io.Writer, level log.Level) (logger *log.Logger)
• type CommandExecutor
• type ConfigDuration
  • func (d *ConfigDuration) UnmarshalJSON(b []byte) (err error)
• type ErrBytesRecv
  • func NewErrBytesRecv(interfaceName string, amount uint64, config InterfaceConfig) (err *ErrBytesRecv)
  • func (err *ErrBytesRecv) Error() string
  • func (err *ErrBytesRecv) Execute() error
• type ErrBytesSent
  • func NewErrBytesSent(interfaceName string, amount uint64, config InterfaceConfig) (err *ErrBytesSent)
  • func (err *ErrBytesSent) Error() string
  • func (err *ErrBytesSent) Execute() error
• type IOStat
• type IOStats
  • func (stats IOStats) Filter(names ...string) (filtered IOStats)
  • func (stats IOStats) Find(name string) (stat IOStat)
• type InterfaceConfig
  • func (config InterfaceConfig) CompareStat(prev IOStat, curr IOStat) (err error)
• type InterfaceConfigs
  • func NewConfigsFromReader(reader io.Reader) (configs InterfaceConfigs, err error)
  • func (configs InterfaceConfigs) CompareStats(prev IOStats, curr IOStats) (err error)
• type Runner
  • func NewRunner(statsCollector StatsCollector, configs InterfaceConfigs, logger *log.Logger) (runner *Runner)
  • func (runner *Runner) Start() (err error)
  • func (runner *Runner) Stop()
• type StatsCollector
• type UTCFormatter
  • func (u UTCFormatter) Format(e *log.Entry) ([]byte, error)

Functions

func NewLogger

func NewLogger(out io.Writer, level log.Level) (logger *log.Logger)

NewLogger returns a pointer to a new logrus logger with all sensible defaults configured.

Types

type CommandExecutor

type CommandExecutor interface {
	Execute() error
}

CommandExecutor describes the behaviour of something capable of executing a command.

type ConfigDuration

type ConfigDuration struct {
	time.Duration
}

ConfigDuration allows for the configuration of durations in the form of "5m30s", as opposed to the default Unix epoch timestamp.

func (*ConfigDuration) UnmarshalJSON

func (d *ConfigDuration) UnmarshalJSON(b []byte) (err error)

UnmarshalJSON unmarshals a ConfigDuration from JSON.

type ErrBytesRecv

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

ErrBytesRecv is raised when the number of bytes received on an interface exceeds the number of allowed bytes.

func NewErrBytesRecv

func NewErrBytesRecv(interfaceName string, amount uint64, config InterfaceConfig) (err *ErrBytesRecv)

NewErrBytesRecv returns a pointer to a new instance of a ErrBytesRecv error.

func (*ErrBytesRecv) Error

func (err *ErrBytesRecv) Error() string

func (*ErrBytesRecv) Execute

func (err *ErrBytesRecv) Execute() error

Execute uses information contained within the error to execute a command.

type ErrBytesSent

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

ErrBytesSent is raised when the number of bytes sent on an interface exceeds the number of allowed bytes.

func NewErrBytesSent

func NewErrBytesSent(interfaceName string, amount uint64, config InterfaceConfig) (err *ErrBytesSent)

NewErrBytesSent returns a pointer to a new instance of a ErrBytesSent error.

func (*ErrBytesSent) Error

func (err *ErrBytesSent) Error() string

func (*ErrBytesSent) Execute

func (err *ErrBytesSent) Execute() error

Execute uses information contained within the error to execute a command.

type IOStat

type IOStat struct {
	Name      string
	BytesSent uint64
	BytesRecv uint64
}

IOStat is represents a snapshot for a network interface.

type IOStats

type IOStats []IOStat

IOStats is a slice of IOStat structs.

func (IOStats) Filter

func (stats IOStats) Filter(names ...string) (filtered IOStats)

Filter filters a given IOStats agains a set of interface names, returning only those whose names match.

func (IOStats) Find

func (stats IOStats) Find(name string) (stat IOStat)

Find returns the first net.IOCounterStat whose name matches the given value.

type InterfaceConfig

type InterfaceConfig struct {
	Name         string   `json:"name"`
	MaxBytesRecv uint64   `json:"maxBytesRecv"`
	MaxBytesSent uint64   `json:"maxBytesSent"`
	Instructions []string `json:"instructions"`
}

InterfaceConfig holds the configurable thresholds for a network interface.

func (InterfaceConfig) CompareStat

func (config InterfaceConfig) CompareStat(prev IOStat, curr IOStat) (err error)

CompareStat compares the last snapshot of an individual IOStat against the current snapshot of the same IOStats and returns an error if any of the thresholds have been breached.

type InterfaceConfigs

type InterfaceConfigs struct {
	CheckInterval ConfigDuration    `json:"checkInterval"`
	Interfaces    []InterfaceConfig `json:"interfaces"`
}

InterfaceConfigs defines a set of InterfaceConfig settings, allowing you to react to different thresholds per network interface.

func NewConfigsFromReader

func NewConfigsFromReader(reader io.Reader) (configs InterfaceConfigs, err error)

NewConfigsFromReader returns a pointer to a new instance of an InterfaceConfigs struct from a reader.

func (InterfaceConfigs) CompareStats

func (configs InterfaceConfigs) CompareStats(prev IOStats, curr IOStats) (err error)

CompareStats compares the last snapshot of IOStats against the current snapshot of IOStats and returns an error if any of the thresholds have been breached.

type Runner

type Runner struct {
	StatsCollector StatsCollector
	// contains filtered or unexported fields
}

Runner contains all of the properties necessary for running an instance of Ripcord, standalone or otherwise.

func NewRunner

func NewRunner(statsCollector StatsCollector, configs InterfaceConfigs, logger *log.Logger) (runner *Runner)

NewRunner returns the pointer to a new instance of a Ripcord struct.

func (*Runner) Start

func (runner *Runner) Start() (err error)

Start kicks everything off. It blocks, so launch in separate goroutine.

func (*Runner) Stop

func (runner *Runner) Stop()

Stop sents a signal to the Runner to stop it's execution loop.

type StatsCollector

type StatsCollector interface {
	CollectStats() (IOStats, error)
}

StatsCollector defines the behaviour of something which can collect stats.

type UTCFormatter

type UTCFormatter struct {
	log.Formatter
}

UTCFormatter formats logrus timestamps in UTC format rather than the default local format.

func (UTCFormatter) Format

func (u UTCFormatter) Format(e *log.Entry) ([]byte, error)

Format takes a local timestamp and converts it to UTC.