filter

Documentation

Overview

Copyright © 2022 Stamus Networks oss@stamus-networks.com

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.

Copyright © 2022 Stamus Networks oss@stamus-networks.com

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.

Copyright © 2022 Stamus Networks oss@stamus-networks.com

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.

Copyright © 2022 Stamus Networks oss@stamus-networks.com

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.

Copyright © 2022 Stamus Networks oss@stamus-networks.com

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.

Index

• Variables
• func DecapGREandERSPAN(pkt gopacket.Packet, maxdepth int) (gopacket.Packet, error)
• func ExtractBaseName(filename string) string
• type CombinedConfig
• type CombinedMatcher
  • func NewCombinedMatcher(c MatcherConfig) (*CombinedMatcher, error)
  • func (cm CombinedMatcher) Match(pkt gopacket.Packet) bool
• type ConditionASN
  • func NewConditionASN(path string, asn []string) (*ConditionASN, error)
  • func (ca ConditionASN) Match(pkt gopacket.Packet) bool
• type ConditionEndpoint
  • func NewPortMatcher(p []string) (ConditionEndpoint, error)
  • func (cs ConditionEndpoint) Match(pkt gopacket.Packet) bool
• type ConditionSubnet
  • func NewConditionalSubnet(nets []string) (ConditionSubnet, error)
  • func (cs ConditionSubnet) Match(pkt gopacket.Packet) bool
• type Config
• type DummyMatcher
  • func (d DummyMatcher) Match(pkt gopacket.Packet) bool
• type ErrEarlyExit
  • func (e ErrEarlyExit) Error() string
• type FilterItem
• type FilterKind
  • func NewFilterKind(raw string) FilterKind
  • func (k FilterKind) String() string
• type FilterResult
  • func ReadAndFilter(c *Config) (*FilterResult, error)
  • func (fr FilterResult) Map() map[string]any
• type Matcher
• type MatcherConfig
• type NegateMatcher
  • func (nm NegateMatcher) Match(pkt gopacket.Packet) bool
• type Task
• type YAMLConfig
  • func Generate(pth string, parseErrFunc func(error) bool) (YAMLConfig, error)

Variables

var FilterKinds = []string{
	FilterKindSubnet.String(),
	FilterKindPort.String(),
	FilterKindASN.String(),
	FilterKindRaw.String(),
}

Functions

func DecapGREandERSPAN

func DecapGREandERSPAN(pkt gopacket.Packet, maxdepth int) (gopacket.Packet, error)

func ExtractBaseName

func ExtractBaseName(filename string) string

Types

type CombinedConfig

type CombinedConfig struct {
	Conditions []FilterItem `yaml:"conditions,omitempty"`
}

type CombinedMatcher

type CombinedMatcher struct {
	Conditions []Matcher
}

CombinedMatcher allows us to use multiple match criteria

func NewCombinedMatcher

func NewCombinedMatcher(c MatcherConfig) (*CombinedMatcher, error)

func (CombinedMatcher) Match

func (cm CombinedMatcher) Match(pkt gopacket.Packet) bool

type ConditionASN

type ConditionASN struct {
	Values      map[uint]bool
	DB          *geoip2.Reader
	LookupErrs  int
	IPParseErrs int
}

func NewConditionASN

func NewConditionASN(path string, asn []string) (*ConditionASN, error)

func (ConditionASN) Match

func (ca ConditionASN) Match(pkt gopacket.Packet) bool

type ConditionEndpoint

type ConditionEndpoint map[gopacket.Endpoint]bool

func NewPortMatcher

func NewPortMatcher(p []string) (ConditionEndpoint, error)

func (ConditionEndpoint) Match

func (cs ConditionEndpoint) Match(pkt gopacket.Packet) bool

type ConditionSubnet

type ConditionSubnet []net.IPNet

func NewConditionalSubnet

func NewConditionalSubnet(nets []string) (ConditionSubnet, error)

NewConditionalSubnet parses a list of textual network addrs into a Matcher

func (ConditionSubnet) Match

func (cs ConditionSubnet) Match(pkt gopacket.Packet) bool

type Config

type Config struct {
	ID int
	// Full path for input and otput PCAP files
	File struct {
		Input  string
		Output string
	}
	// BPF filter object, only packets matching network list will be written to OutFile
	Filter Matcher
	// Enable GRE and ERSPAN packet decapsulation
	Decapsulate bool
	// How many layers should be checked for decapsulation
	DecapMaxDepth int

	Compress bool

	StatFunc func(map[string]any)

	Ctx context.Context

	Dedup dedup.Dedupper
}

Config holds params needed by ReadAndFilterNetworks

type DummyMatcher

type DummyMatcher struct{}

func (DummyMatcher) Match

func (d DummyMatcher) Match(pkt gopacket.Packet) bool

type ErrEarlyExit

type ErrEarlyExit struct{}

func (ErrEarlyExit) Error

func (e ErrEarlyExit) Error() string

type FilterItem

type FilterItem struct {
	Kind   string   `yaml:"kind,omitempty"`
	Negate bool     `yaml:"negate,omitempty"`
	Match  []string `yaml:"match,omitempty"`
}

type FilterKind

type FilterKind int

const (
	FilterKindUndefined FilterKind = iota
	FilterKindSubnet
	FilterKindPort
	FilterKindASN
	FilterKindRaw
)

func NewFilterKind

func NewFilterKind(raw string) FilterKind

func (FilterKind) String

func (k FilterKind) String() string

type FilterResult

type FilterResult struct {
	Count        int
	Matched      int
	Errors       int
	DecapErrors  int
	Skipped      int
	Start        time.Time
	Took         time.Duration
	Rate         string
	Deduplicated int
	DedupRatio   float64
}

func ReadAndFilter

func ReadAndFilter(c *Config) (*FilterResult, error)

ReadAndFilter processes a PCAP file, storing packets that match filtering criteria in output file

func (FilterResult) Map

func (fr FilterResult) Map() map[string]any

type Matcher

type Matcher interface {
	// Match should indicate if packet matches criteria
	Match(gopacket.Packet) bool
}

Matcher is for filtering packets

type MatcherConfig

type MatcherConfig struct {
	CombinedConfig
	MaxMindASN string
}

type NegateMatcher

type NegateMatcher struct {
	M Matcher
}

NegateMatcher implements logical NOT

func (NegateMatcher) Match

func (nm NegateMatcher) Match(pkt gopacket.Packet) bool

type Task

type Task struct {
	Input, Output string

	Filter      Matcher
	Description string
}

Task is input file to be fed to filter reader, along with BPF filter used to extract packets

type YAMLConfig

type YAMLConfig map[string]CombinedConfig

func Generate

func Generate(pth string, parseErrFunc func(error) bool) (YAMLConfig, error)

Generate produces a filter YAML configurations from suricata alerts.