Documentation
¶
Overview ¶
Package gonids implements a basic parser of IDS rules.
For now the parser is very basic and it only parses a subset of fields. We intentionally omit http_encode as it doesn't seem to be used in practice.
Index ¶
- func Format(r io.Reader, w io.Writer) error
- func FuzzParseRule(data []byte) int
- type Absent
- type ByteMatch
- type Content
- type ContentOption
- type DataPos
- type DataRep
- type Dataset
- type DetectionFilter
- type FastPattern
- type Flowbit
- type Flowint
- type LenMatch
- type Matchers
- type Metadata
- type Metadatas
- type Network
- type PCRE
- type Reference
- type Requires
- type Rule
- func (r *Rule) Absents() []*Absent
- func (r *Rule) ByteMatchers() []*ByteMatch
- func (r *Rule) CVE() string
- func (r *Rule) Contents() []*Content
- func (r *Rule) DataReps() []*DataRep
- func (r *Rule) Datasets() []*Dataset
- func (r *Rule) ExpensivePCRE() bool
- func (r *Rule) GetSidMsg() string
- func (r *Rule) HasVar(s string) bool
- func (r *Rule) InsertMatcher(m orderedMatcher, pos int) error
- func (r *Rule) LastContent() *Content
- func (r *Rule) LenMatchers() []*LenMatch
- func (r *Rule) NoReferences() bool
- func (r *Rule) OnlyShortContents() bool
- func (r *Rule) OptimizeHTTP() bool
- func (r *Rule) PCREs() []*PCRE
- func (r *Rule) RE() string
- func (r *Rule) ShouldBeHTTP() bool
- func (r *Rule) SnortHTTPHeader() bool
- func (r *Rule) SnortHTTPHeaderFix() bool
- func (r *Rule) SnortURILenFix() bool
- func (r Rule) String() string
- func (r *Rule) UpgradeToSuri5() bool
- type RuleScanner
- type StreamCmp
- type TLSTag
- type Threshold
- type Transform
- type Transforms
- type UnsupportedOptionError
- type VersionConstraint
- type Xbit
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Format ¶
Format reads an IDS rule file or stream from r and writes canonically formatted output to w. Non-rule lines (such as comments and blank lines) are preserved as-is. Active and disabled rules (including multi-line rules) are formatted using Rule.String().
func FuzzParseRule ¶
FuzzParseRule is used by OSS-Fuzz to fuzz the library.
Types ¶
type Absent ¶
type Absent struct {
DataPosition DataPos
FrameName string
DataDirection string
Transforms Transforms
OrElse bool
}
Absent describes a Suricata absent sticky-buffer rule option (e.g. "absent;" or "absent:or_else;").
type ByteMatch ¶
type ByteMatch struct {
// DataPosition defaults to pkt_data state, can be modified to apply to file_data, base64_data locations.
// This value will apply to all following contents, to reset to default you must reset DataPosition during processing.
DataPosition DataPos
FrameName string
DataDirection string
// Kind is a specific operation type we're taking.
Kind byteMatchType
// Negate indicates negation of a value, currently only used for isdataat.
Negate bool
// A variable name being extracted by byte_extract.
Variable string
// Number of bytes to operate on. "bytes to convert" in Snort Manual. This can be an int, or a var from byte_extract.
NumBytes string
// Operator for comparison in byte_test.
Operator string
// Value to compare against using byte_test.
Value string
// Offset within given buffer to operate on.
Offset string
// Other specifics required for jump/test here. This might make sense to pull out into a "ByteMatchOption" later.
Options []string
}
ByteMatch describes a byte matching operation, similar to a Content.
type Content ¶
type Content struct {
// DataPosition defaults to pkt_data state, can be modified to apply to file_data, base64_data locations.
// This value will apply to all following contents, to reset to default you must reset DataPosition during processing.
DataPosition DataPos
// FrameName holds the frame name when DataPosition is framePos (e.g. "dns.pdu" for frame:dns.pdu;).
FrameName string
// DataDirection holds an optional sticky buffer direction modifier ("to_server" or "to_client").
DataDirection string
// FastPattern settings for the content.
FastPattern FastPattern
// Pattern is the pattern match of a content (e.g. HTTP in content:"HTTP").
Pattern []byte
// Negate is true for negated content match.
Negate bool
// Options are the option associated to the content (e.g. http_header).
Options []*ContentOption
// Transforms is the list of transforms attached to this content (sticky buffer).
Transforms Transforms
}
Content describes a rule content. A content is composed of a pattern followed by options.
func (*Content) FormatPattern ¶
FormatPattern returns a string for a Pattern in a content
func (Content) SnortHTTPHeader ¶
SnortHTTPHeader returns true if a specific content contains double CRLF at the end.
type ContentOption ¶
type ContentOption struct {
// Name is the name of the option (e.g. offset).
Name string
// Value is the value associated to the option, default to "" for option without value.
Value string
}
ContentOption describes an option set on a rule content.
func (ContentOption) String ¶
func (co ContentOption) String() string
String returns a string for a ContentOption.
type DataPos ¶
type DataPos int
DataPos indicates the data position for content matches. These should be referenced for creation by using their Suricata keywords and the StickyBuffer() function.
func StickyBuffer ¶
StickyBuffer returns the data position value for the string representation of a sticky buffer name (e.g. "file_data")
type DataRep ¶
type DataRep struct {
DataPosition DataPos
FrameName string
DataDirection string
Transforms Transforms
Name string
Operator string
Value int
Options []string
}
DataRep describes a Suricata datarep rule option.
type Dataset ¶
type Dataset struct {
DataPosition DataPos
FrameName string
DataDirection string
Transforms Transforms
Cmd string
Name string
Options []string
}
Dataset describes a Suricata dataset rule option.
type DetectionFilter ¶
DetectionFilter describes a rule detection_filter option.
func (*DetectionFilter) String ¶
func (d *DetectionFilter) String() string
String returns a string for a DetectionFilter.
type FastPattern ¶
FastPattern describes various properties of a fast_pattern value for a content.
func (FastPattern) String ¶
func (f FastPattern) String() string
String returns a string for a FastPattern.
type LenMatch ¶
type LenMatch struct {
// DataPosition defaults to pkt_data state, can be modified to apply to file_data, base64_data locations.
// This value will apply to all following contents, to reset to default you must reset DataPosition during processing.
DataPosition DataPos
FrameName string
DataDirection string
Kind lenMatchType
Min int
Max int
Num int
Operator string
Options []string
}
LenMatch holds the values to represent an Length Match.
type Metadata ¶
Metadata describes metadata tags in key-value struct.
func MetadataModifier ¶
MetadataModifier returns a metadata that identifies a given modification.
type Network ¶
type Network struct {
NegateNets bool // Negate the full set of Networks.
Nets []string // Currently just []string because these can be variables $HOME_NET, not a valid IPNet.
NegatePorts bool // Negate the full set of ports.
Ports []string // Currently just []string because these can be variables $HTTP_PORTS, not just ints.
}
Network describes the IP addresses and port numbers used in a rule. TODO: Ensure all values either begin with $ (variable) or they are valid IPNet/int. TODO: Refactor Nets and Ports into structs, each with their own bool for negation.
type PCRE ¶
type PCRE struct {
// DataPosition defaults to pkt_data state, can be modified to apply to file_data, base64_data locations.
// This value will apply to all following contents, to reset to default you must reset DataPosition during processing.
DataPosition DataPos
FrameName string
DataDirection string
Pattern []byte
Negate bool
Options []byte
Transforms Transforms
}
PCRE describes a PCRE item of a rule.
type Reference ¶
type Reference struct {
// Type is the system name for the reference: (url, cve, md5, etc.)
Type string
// Value is the identifier in the system: (address, cvd-id, hash)
Value string
}
Reference describes a gonids reference in a rule.
type Requires ¶
type Requires struct {
Version [][]VersionConstraint
Features []string
Keywords []string
}
Requires describes a Suricata requires rule option. Version is a slice of OR-separated branches, where each branch is a slice of AND-combined VersionConstraints (e.g. "version >= 7.0.4 < 8 | >= 8.0.3").
type Rule ¶
type Rule struct {
// Disbled identifies if the rule is disabled/commented out.
Disabled bool
// Action is the action the rule will take (alert, pass, drop, etc.).
Action string
// Protocol is the protocol the rule looks at.
Protocol string
// Source is the address and ports for the source of the traffic.
Source Network
// Destination is the address and ports for the source of the traffic.
Destination Network
// Bidirectional indicates the directionality of a rule (-> or <>).
Bidirectional bool
// Transactional indicates the rule uses the transactional direction operator (=>).
Transactional bool
// SID is the identifier of the rule.
SID int
// Revision is the revision of the rule.
Revision int
// Description is the msg field of the rule.
Description string
// Target specifies the attack target (src_ip or dest_ip).
Target string
// References contains references associated to the rule (e.g. CVE number).
References []*Reference
// Contents are all the decoded content matches.
Tags map[string]string
// Statements is a slice of string. These items are similar to Tags, but have no value. (e.g. 'sameip;')
Statements []string
// TLSTags is a slice of TLS related matches.
TLSTags []*TLSTag
// StreamMatch holds stream_size parameters.
StreamMatch *StreamCmp
// Threshold holds threshold parameters.
Threshold *Threshold
// DetectionFilter holds detection_filter parameters.
DetectionFilter *DetectionFilter
// Requires holds Suricata engine/feature/keyword requirements.
Requires *Requires
// Metas is a slice of Metadata.
Metas Metadatas
// Flowbits is a slice of Flowbit.
Flowbits []*Flowbit
// Xbits is a slice of Xbit
Xbits []*Xbit
// Flowints is a slice of Flowint
Flowints []*Flowint
// Matchers are internally used to ensure relative matches are printed correctly.
// Make this private before checkin?
Matchers Matchers
}
Rule describes an IDS rule.
func ParseRules ¶
ParseRules reads from an io.Reader and returns all rules parsed from the stream.
func (*Rule) ByteMatchers ¶
ByteMatchers returns all *ByteMatch for a rule.
func (*Rule) ExpensivePCRE ¶
ExpensivePCRE returns true if a rule appears to use a PCRE without conditions that make it expensive to compute.
func (*Rule) InsertMatcher ¶
InsertMatcher will insert an ordered matcher at a position specified.
func (*Rule) LastContent ¶
LastContent returns the last *Content from Matchers
func (*Rule) LenMatchers ¶
LenMatchers returns all *LenMatch for a rule.
func (*Rule) NoReferences ¶
NoReferences returns true if there are no references in the rule.
func (*Rule) OnlyShortContents ¶
OnlyShortContents returns true if all Matchers are Contents and all matches are very short.
func (*Rule) OptimizeHTTP ¶
OptimizeHTTP tunes an old style rule to leverage port independent HTTP detection.
func (*Rule) ShouldBeHTTP ¶
ShouldBeHTTP returns true if a rule looks like the protocol should be http, but is not.
func (*Rule) SnortHTTPHeader ¶
SnortHTTPHeader returns true if any content contains double CRLF at the end.
func (*Rule) SnortHTTPHeaderFix ¶
SnortHTTPHeaderFix will fix broken http_header matches.
func (*Rule) SnortURILenFix ¶
SnortURILenFix will optimize a urilen keyword from a Snort rule for Suricata.
func (*Rule) UpgradeToSuri5 ¶
UpgradeToSuri5 optimizes a Suricata 4.x rule to Suricata 5.x features.
type RuleScanner ¶
type RuleScanner struct {
IncludeComments bool
// contains filtered or unexported fields
}
RuleScanner provides a convenient interface for reading IDS rules sequentially from an io.Reader. It transparently handles multi-line rules ending with backslash (\), blank lines, and comments.
func NewRuleScanner ¶
func NewRuleScanner(r io.Reader) *RuleScanner
NewRuleScanner returns a new RuleScanner to read from r.
func (*RuleScanner) Err ¶
func (s *RuleScanner) Err() error
Err returns the first non-EOF error that was encountered by the scanner.
func (*RuleScanner) LineNumber ¶
func (s *RuleScanner) LineNumber() int
LineNumber returns the starting line number of the most recent rule.
func (*RuleScanner) Raw ¶
func (s *RuleScanner) Raw() string
Raw returns the unparsed raw rule string for the most recent rule.
func (*RuleScanner) Rule ¶
func (s *RuleScanner) Rule() *Rule
Rule returns the most recent rule generated by a call to Scan.
func (*RuleScanner) Scan ¶
func (s *RuleScanner) Scan() bool
Scan advances the scanner to the next rule in the input stream. It returns false when the scan stops, either by reaching the end of the input or encountering an error.
type StreamCmp ¶
type StreamCmp struct {
// Direction of traffic to inspect: server, client, both, either.
Direction string
// Operator is the comparison operator to apply >, <, !=, etc.
Operator string
// TODO: Can this number be a variable, if yes s/int/string.
// Number is the size to compare against
Number int
}
StreamCmp represents a stream comparison (stream_size:>20).
type TLSTag ¶
type TLSTag struct {
// Is the match negated (!).
Negate bool
// Key holds the thing we're inspecting (tls.version, tls.fingerprint, etc.).
Key string
// TODO: Consider string -> []byte and handle hex input.
// TODO: Consider supporting []struct if we can support things like: tls.version:!1.2,!1.3
// Value holds the value for the match.
Value string
}
TLSTag describes a TLS specific match (non-sticky buffer based).
type Transform ¶
Transform describes a sticky buffer transformation (e.g. dotprefix, to_lowercase, xor, pcrexform).
type Transforms ¶
type Transforms []*Transform
Transforms allows for a Stringer on []*Transform.
func (Transforms) String ¶
func (ts Transforms) String() string
String returns a space-separated string for all transforms.
type UnsupportedOptionError ¶
UnsupportedOptionError contains a partially parsed rule, and the options that aren't supported for parsing.
func (*UnsupportedOptionError) Error ¶
func (uoe *UnsupportedOptionError) Error() string
Error returns a string for UnsupportedOptionError
type VersionConstraint ¶
VersionConstraint describes a single version comparison within a Suricata requires option (e.g. ">= 8" or "< 8.0.3").
func (VersionConstraint) String ¶
func (vc VersionConstraint) String() string
String returns the string representation of a single VersionConstraint.
type Xbit ¶
type Xbit struct {
Action string
Name string
Track string
// Expire should be an int, default 0 value makes stringer difficult because this is an
// optional parameter. If we can confirm that this must be > 0 we can convert to int.
Expire string
}
Xbit describes an Xbit. TODO: Consider adding more structure to Track and Expire.