Name

ips — format of ips component configuration

DESCRIPTION

General syntax rules of Kernun Firewall configuration files are described in configuration(7). This man page describes types, sections and items specific for the ips component configuration.

Repeatable sections/items are marked by the '*' before section/item name.

TYPES

Configuration directives have attributes of several value-types. For the basic types description, see configuration(7).

Enumeration is a list of words (names) representing integer values. Some enumerations accept both names and direct integer values; in this case, enumeration description contains values for every name (in parenthesis next to name). For other enumerations, using of names is obligatory.

The following enumerations are used in ips configuration directives:

yes-no (see common(5))

report-mode (see common(5))

time-cond (see common(5))

zip-mode (see common(5))

ips-modes (name-usage obligatory)

IPS mode of operation.

ids

IDS mode, logs invalid packets.

ips

IPS mode, logs and/or prevents invalid packets.

ips-log-level (name-usage obligatory)

IPS agent log level

none

No messages are logged

emergency

Only emergency messages are logged

alert

Alert messages and above are logged

critical

Critical messages and above are logged

error

Error messages and above are logged

warning

Warning messages and above are logged

notice

Notice messages and above are logged

info

Informational messages and above are logged

perf

Performance messages and above are logged

config

Configuration messages and above are logged

debug

All possible messages are logged

ips-block-direction (name-usage obligatory)

IPS mode block direction

src

Block source

dst

Block destination

both

Block both source and destination

ips-protocol (name-usage obligatory)

IPS protocols

any

Scan any protocol

tcp

Scan TCP protocol

udp

Scan UDP protocol

dcerpc

Scan DCERPC protocol

dhcp

Scan DHCP protocol

dns

Scan DNS protocol

ftp

Scan FTP protocol

http

Scan HTTP protocol

icmp

Scan ICMP protocol

ikev2

Scan IKEV2 protocol

imap

Scan IMAP protocol

krb5

Scan KRB5 protocol

msn

Scan MSN protocol

nfs

Scan NFS protocol

ntp

Scan NTP protocol

smtp

Scan SMTP protocol

ssh

Scan SSH protocol

tls

Scan TLS protocol

download-type (name-usage obligatory)

IPS download-rule types

kernun-ips

Kernun IPS rules

emergingthreats-open

Emerging Threats rules - open

custom

Custom URL for downloading the rules

ips-rule-action (name-usage obligatory)

IPS rule action

alert

Generate an alert using the selected alert method, and then log the packet

log

Log the packet

pass

Ignore the packet

drop

Drop the packet and log it

reject

Drop the packet, log it, and then send a TCP reset if the protocol is TCP or an ICMP port, unreachable message if the protocol is UDP.

ips-new-rule-action (name-usage obligatory)

IPS rule new action

alert

Generate an alert using the selected alert method, and then log the packet

pass

Ignore the packet

drop

Drop the packet and log it

reject

Drop the packet, log it, and then send a TCP reset if the protocol is TCP or an ICMP port, unreachable message if the protocol is UDP.

ips-rule-refresh-frequency (name-usage obligatory)

IPS rules refresh frequency

daily

Run the task once a day.

hourly

Run the task once an hour.

every

Run the task every PERIOD minutes.

raw

Raw crontab period specification.

manually

No automatically scheduled refresh.

threshold-type (name-usage obligatory)

IPS rules track by

threshold

Sets a minimum threshold for a rule before it generates alerts.

A threshold setting of COUNT means on the COUNT-th time the rule matches an alert is generated.

limit

If set to limit COUNT, it alerts at most COUNT times.

both

Applies both thresholding and limiting.

threshold-track-by (name-usage obligatory)

IPS rules track by

src

Track the policy rule by source.

dst

Track the policy rule by destination.

rate-filter-track-by (name-usage obligatory)

IPS rules track by

src

Track the policy rule by source.

The tracking is done per IP-address.

dst

Track the policy rule by destination.

The tracking is done per IP-address.

rule

Track the policy rule globally for the rule.

both

Track the policy rule by a pair of source and destination.

The tracking is done per IP-address. Packets going to opposite directions between same addresses tracked as the same pair.

suppress-direction (name-usage obligatory)

IPS rules direction

src

Suppress the policy rule for given source addresses.

dst

Suppress the policy rule for given destination addresses.

any

Suppress the policy rule for given destination or source addresses.

rules-policy (name-usage obligatory)

Talos rules policy

connectivity

You run a lot of real time applications (VOIP, financial transactions, etc), and don't want to run any rules that could affect the current performance of your sensor. This category focuses on the high profile most likely to affect the largest number of people type of vulnerabilities.

balanced

You run normal stuff and you want normal security protections. This is the best policy to start from if you are new, old, or just plain average. If you don't have any special requirements for super high speeds or super secure networks start here.

security

You don't care about dropping your bosses email, everything in your environment is tightly regulated and you don't tolerate people stepping outside of your security policy. This policy hates on IM, P2P, vulnerabilities, malware, web apps that cause productivity loss, remote access, and just about anything not related to getting work done. If you run your network with an iron fist start here.

ITEMS AND SECTIONS

Configuration of ips library component consists of following prototypes:


  ips-from-to ... ;
* ips-rule-def name { ... }
* base-rule-policy name { ... }
* base-rate-filter name { ... }
* base-threshold name { ... }
* base-suppress name { ... }
  base-change-rule ... ;
  ips { ... }
    

Description:

ips-from-to [hosts [ports]];

hosts (type: host-set, optional, default: *)

Set of hosts to apply the rule to

ports (type: port-set, optional, default: *)

Set of ports to apply the rule to

ips-rule-def name {


  action ... ;
  protocol ... ;
  src ... ;
  dst ... ;
  options ... ;
}

        

IPS rule to be added

Constraints:

Action must be specified.

Options must be specified.

Items & subsections:

action action;

Rule action.

Note that some actions only work in the IPS mode (see SYSTEM.IPS.MODE).

action (type: ips-rule-action)

protocol [proto];

Protocol to be scanned. Defaults to any protocol if omited.

The available protocols depend on the agent configuration. The protocols that are listed here are available in the default agent configuration.

proto (type: ips-protocol, optional, default: any)

src [hosts [ports]];

Source addresses and ports. Defaults to any address and any port if omitted.

hosts (type: host-set, optional, default: *)

Set of hosts to apply the rule to

ports (type: port-set, optional, default: *)

Set of ports to apply the rule to

dst [hosts [ports]];

Destination addresses and ports. Defaults to any address and any port if omitted.

hosts (type: host-set, optional, default: *)

Set of hosts to apply the rule to

ports (type: port-set, optional, default: *)

Set of ports to apply the rule to

options options;

Rule definition (called options in the snort terminology).

See snort/suricata documentation for the options syntax.

For example: "msg:\"Testing rule\"; flow:to_server,established; content:\"TEST\"; sid:1999999; classtype:unknown;"

Note that SID numbers have to be unique, range between 1500000 and 1999999 can be used for custom rules.

options (type: str)

[End of section ips-rule-def description.]

base-rule-policy name {


* sid ... ;
}

        

Rule policy base

Items & subsections:

sid sid;

Signature identifier

sid (type: uint64)

[End of section base-rule-policy description.]

base-rate-filter name {


* sid ... ;
  track-by ... ;
  count ... ;
  seconds ... ;
  new-action ... ;
  timeout ... ;
}

        

Rate filter base

The base-rate-filter section is derived from base-rule-policy section prototype. For detail description of it, see above.

Changes to the base-rate-filter section:

Item TRACK-BY required.

Item COUNT required.

Item SECONDS required.

Item NEW-ACTION required.

Item TIMEOUT required.

Added items & subsections:

track-by src;

track-by dst;

track-by rule;

track-by both;

How to track the exception.

<branching element> (type: rate-filter-track-by)

count count;

Number of rule hits before this exception is activated

count (type: uint64)

seconds seconds;

Time period within which the COUNT needs to be reached to activate this exception

seconds (type: uint64)

new-action action;

New rule action that is applied to matching traffic when this exception is applied.

Note that some actions only work in the IPS mode (see SYSTEM.IPS.MODE).

action (type: ips-new-rule-action)

timeout timeout;

Time in seconds during which this exception remains active

timeout (type: uint64)

[End of section base-rate-filter description.]

base-threshold name {


* sid ... ;
  type ... ;
  track-by ... ;
  count ... ;
  seconds ... ;
}

        

Threshold base

The base-threshold section is derived from base-rule-policy section prototype. For detail description of it, see above.

Changes to the base-threshold section:

Item TYPE required.

Item TRACK-BY required.

Item COUNT required.

Item SECONDS required.

Added items & subsections:

type threshold;

type limit;

type both;

Threshold type.

<branching element> (type: threshold-type)

track-by src;

track-by dst;

How to track the threshold.

<branching element> (type: threshold-track-by)

count count;

The COUNT as described by TYPE

count (type: uint64)

seconds seconds;

Time period within which the COUNT needs to be reached to activate this threshold

seconds (type: uint64)

[End of section base-threshold description.]

base-suppress name {


* sid ... ;
  direction ... ;
  address ... ;
}

        

Exception base

The base-suppress section is derived from base-rule-policy section prototype. For detail description of it, see above.

Added items & subsections:

direction src;

direction dst;

direction [any];

Direction of the suppression.

<branching element> (type: suppress-direction, optional, default: any)

address [address];

The addresses and ports to base the suppression on.

address (type: host-set, optional, default: *)

Set of hosts to apply the rule to

[End of section base-suppress description.]

base-change-rule sid;

Change rule base

sid (type: uint64-list)

Constraints:

SID list must not be empty.

ips {


  phase ... ;
* tag ... ;
  mode ... ;
* iface ... ;
  rules { ... }
  agent { ... }
  feedback-upload { ... }
  rules-download { ... }
  rotate-log ... ;
  stats-daily { ... }
  stats-weekly { ... }
  stats-monthly { ... }
}

        

Intrusion prevention/detection system.

Constraints:

At least one interface must be specified.

Item RULES.MODIFY-RULES requires item RULES-DOWNLOAD to be enabled.

Item RULES.ENABLE-RULES requires item RULES-DOWNLOAD to be enabled.

Item RULES.DISABLE-RULES requires item RULES-DOWNLOAD to be enabled.

Item RULES.CHANGE-RULES-TO-DROP requires item RULES-DOWNLOAD to be enabled.

Item RULES.CHANGE-RULES-TO-REJECT requires item RULES-DOWNLOAD to be enabled.

Items & subsections:

phase [number];

Application Startup Phase.

number (type: uint8, optional, default: 50)

Phase number; the lower one, the earlier start.

tag value;

Configuration factorization tag.

This feature allows admin to create groups of Kernun applications (specially proxies and servers) according to various aspects (belonging to one customer, applications of particular network traffic etc.).

Each application can have several tag attributes and the KAT tool can run some commands (like 'ps', 'start' atc.) for applications with or without given tag.

value (type: str)

Constraints:

Tag must contain letters, digits, hyphens and dots, only.

mode [mode];

Selection between IDS and IPS mode. The rules action can be modified by the RULES items.

mode (type: ips-modes, optional, default: ids)

iface name;

Network interfaces watched by IPS.

name (type: name of interface, see interface(5))

rules {


  rules-policy ... ;
* add-rule name { ... }
* include-rules ... ;
* modify-rules ... ;
  enable-rules ... ;
  disable-rules ... ;
  change-rules-to-drop ... ;
  change-rules-to-reject ... ;
* rule-rate-filter name { ... }
* global-rate-filter name { ... }
* rule-threshold name { ... }
* global-threshold name { ... }
* rule-suppress name { ... }
* global-suppress name { ... }
}

            

IPS rules configuration and modification

Items & subsections:

rules-policy rules-policy;

Policy to use for Talos rules (formerly VRT rules).

Use only if you are using rules that support policy as this causes all rules that don't have the selected policy to be disabled.

rules-policy (type: rules-policy)

add-rule name {


  action ... ;
  protocol ... ;
  src ... ;
  dst ... ;
  options ... ;
}

                

Custom IPS rule

The add-rule section is derived from ips-rule-def section prototype. For detail description of it, see above.

include-rules file;

Include raw-defined rules from a file

file (type: name of shared-file, see common(5))

File to include raw-defined rules from

modify-rules sid replace-regex replace-with;

IPS rule modification

sid (type: uint64-list)

replace-regex (type: regexp)

replace-with (type: str)

Constraints:

SID list must not be empty.

enable-rules sid;

Enable IPS rules

sid (type: uint64-list)

Constraints:

SID list must not be empty.

disable-rules sid;

Disable IPS rules.

A disabled rule is not passed to the agent.

sid (type: uint64-list)

Constraints:

SID list must not be empty.

change-rules-to-drop sid;

Change the action of IPS rules to drop

sid (type: uint64-list)

Constraints:

SID list must not be empty.

change-rules-to-reject sid;

Change the action of IPS rules to reject

sid (type: uint64-list)

Constraints:

SID list must not be empty.

rule-rate-filter name {


* sid ... ;
  track-by ... ;
  count ... ;
  seconds ... ;
  new-action ... ;
  timeout ... ;
}

                

Conditionally change the action of selected IPS rules

The rule-rate-filter section is derived from base-rate-filter section prototype. For detail description of it, see above.

Changes to the rule-rate-filter section:

Atleast one SID must be entered.

global-rate-filter name {


  track-by ... ;
  count ... ;
  seconds ... ;
  new-action ... ;
  timeout ... ;
}

                

Conditionally change the action of all IPS rules

The global-rate-filter section is derived from base-rate-filter section prototype. For detail description of it, see above.

Changes to the global-rate-filter section:

Item sid is not valid.

rule-threshold name {


* sid ... ;
  type ... ;
  track-by ... ;
  count ... ;
  seconds ... ;
}

                

Conditionally limit the selected IPS rules

The rule-threshold section is derived from base-threshold section prototype. For detail description of it, see above.

Changes to the rule-threshold section:

Atleast one SID must be entered.

global-threshold name {


  type ... ;
  track-by ... ;
  count ... ;
  seconds ... ;
}

                

Conditionally limit all IPS rules

The global-threshold section is derived from base-threshold section prototype. For detail description of it, see above.

Changes to the global-threshold section:

Item sid is not valid.

rule-suppress name {


* sid ... ;
  direction ... ;
  address ... ;
}

                

Conditionally suppress selected IPS rules.

A suppressed rule acts the same as a rule with action "pass", which means:

- it doesn't generate an alert,

- it prevents other rules from matching on that packet.

The rule-suppress section is derived from base-suppress section prototype. For detail description of it, see above.

Changes to the rule-suppress section:

Atleast one SID must be entered.

Item ADDRESS requires item DIRECTION to be specified..

Item DIRECTION requires atleast one item ADDRESS to be specified..

global-suppress name {


  direction ... ;
  address ... ;
}

                

Conditionally suppress all IPS rules.

A suppressed rule acts the same as a rule with action "pass", which means:

- it doesn't generate an alert,

- it prevents other rules from matching on that packet.

The global-suppress section is derived from base-suppress section prototype. For detail description of it, see above.

Changes to the global-suppress section:

Item sid is not valid.

Atleast one address must be specified..

[End of section ips.rules description.]

agent {


  engine-flags ... ;
  engine-cfg-file ... ;
  block-direction ... ;
  block-alerts ... ;
  log-level ... ;
  log-blocks ... ;
  address-groups { ... }
  port-groups { ... }
}

            

IPS agent configuration

Items & subsections:

engine-flags flags;

Flags to be passed to the engine upon start.

flags (type: str)

engine-cfg-file file;

The configuration file for the agent.

Default value is "samples/shared/kernun-ips.yaml" from distribution. CML modifies this file according to its purpose, i.e:

- CML overwrites variable definitions according to ADDRESS-GROUPS and PORT-GROUPS

- CML overwrites the path and generates the content of threshold file if atleast one item GLOBAL-RATE-FILTER, RULE-RATE-FILTER, GLOBAL-THRESHOLD, RULE-THRESHOLD, GLOBAL-SUPPRESS or RULE-SUPPRESS is specified

- CML overwrites the pcap section according to IFACE item

- CML appends the path to the downloaded rules to the rule-files list when item RULES-DOWNLOAD is specified

file (type: name of shared-file, see common(5))

block-direction src;

block-direction dst;

block-direction [both];

Which addresses to block when running in IPS mode

<branching element> (type: ips-block-direction, optional, default: both)

block-alerts;

By default, only rules with action drop are blocked. This item makes also rules with action alert be blocked.

log-level none;

log-level emergency;

log-level alert;

log-level critical;

log-level error;

log-level warning;

log-level [notice];

log-level info;

log-level perf;

log-level config;

log-level debug;

Agent log level

<branching element> (type: ips-log-level, optional, default: notice)

log-blocks [val];

Whether to log IPS blocks to /var/log/kernun-ips-block

val (type: yes-no, optional, default: yes)

address-groups {


  disable-home-net-whitelist ... ;
  home-net ... ;
  dns-servers ... ;
}

                

Agent address variables.

Defining these according to your network will increase the accuracy of rules.

Items & subsections:

disable-home-net-whitelist;

By default, the addresses specified in home-net are put on a whitelist in order to not be blocked when running in IPS mode. This item disables it, meaning addresses in your network can be blocked by IPS.

home-net home-net;

Set of addresses used in your network.

Defaults to { [192.168.0.0/16], [10.0.0.0/8], [172.16.0.0/12] } when uspecified.

Note that when running IPS on external interface, it is necessary to include the external address in this set because otherwise the traffic will not get matched by most rules.

home-net (type: net-list)

dns-servers dns-servers;

Set of DNS servers used in your network.

Defaults to HOME-NET when unspecified.

dns-servers (type: net-list)

[End of section ips.agent.address-groups description.]

port-groups {


  http-ports ... ;
  ssh-ports ... ;
}

                

Agent port variables.

Defining these according to your network will increase the accuracy of rules.

Items & subsections:

http-ports http-ports;

Set of HTTP ports used in your network.

Defaults to { 80, 8080 } when unspecified.

http-ports (type: port-set)

ssh-ports ssh-ports;

Set of SSH ports used in your network.

Defaults to { 22 } when unspecified.

ssh-ports (type: port-set)

[End of section ips.agent.port-groups description.]

[End of section ips.agent description.]

feedback-upload {


  upload ... ;
}

            

Items & subsections:

upload [freq];

Upload feedback to Kernun.

This feedback is necessary for achieving high success rate of IPS.

freq (type: uint32, optional, default: 15m)

Default upload frequence in seconds

[End of section ips.feedback-upload description.]

rules-download {


  disabled ... ;
  source ... ;
  ignore ... ;
  schedule ... ;
  downloader-extra-flags ... ;
* downloader-conf-raw ... ;
}

            

Specifies, how the rules are obtained.

By the default, the rules are downloaded from kernun server.

Items & subsections:

disabled;

The rules are not downloaded when this item is specified.

source [kernun-ips];

source emergingthreats-open;

source custom rule_url;

Where to download the IPS rules from.

<branching element> (type: download-type, optional, default: kernun-ips)

rule_url (type: str)

The custom URL to download the rules from.

You can specify one URL or multiple URLs separated by commas, each URL must appear as http://what.site.com/|rulesfile.tar.gz|1234567. The parts separated with pipes are URL prefix, rule file and oinkcode.

ignore [ignore];

Rule categories to ignore from the downloaded rules.

ignore (type: str, optional, default: "deleted.rules,experimental.rules,local.rules")

schedule daily [time time] [report report];

schedule hourly [minute minute] [report report];

schedule [every] [period period] [at at] [report report];

schedule raw raw raw [report report];

schedule manually;

Schedule the rules update.

If omitted, it defaults to every 15 minutes schedule.

<branching element> (type: ips-rule-refresh-frequency, optional, default: every)

raw raw (type: str)

Raw line to be placed into crontab. First 5 columns (the time specification) must be specified.

minute minute (type: time, optional, default: 0)

Starting time of task (mm, hour ignored).

time time (type: time, optional, default: 415)

Starting time of task (hhmm).

period period (type: uint8, optional, default: 15)

Run the task every PERIOD minutes (mm, hours ignored).

at at (type: uint8, optional, default: 0)

Starting time of task (mm, hours ignored)

report report (type: report-mode, optional, default: nothing=0)

Task output (stdout and stderr) delivery.

downloader-extra-flags flags;

Extra flags to be used for starting the rules downloader.

flags (type: str)

downloader-conf-raw row;

Raw line to be placed into the rules downloader as is.

row (type: str)

[End of section ips.rules-download description.]

rotate-log [user user] [group group] [mode mode] [count count] [size size] [when [zip]];

Log file rotation description.

Use the SIZE elem if log file size criterion required. Use the WHEN elem if periodical rotation required. If used both SIZE and WHEN elems, the log file is rotated at a proper time only if size limit is reached.

user user (type: str, optional, default: <NULL>)

Log file owner - user.

group group (type: str, optional, default: "wheel")

Log file owner - group.

mode mode (type: uint16, optional, default: 640)

Log file permissions.

count count (type: uint16, optional, default: 31)

Number of days being archived.

size size (type: uint16, optional, default: 0)

Size limit for rotation in KB (ignore log file size if omitted).

when (type: time-cond, optional, default: anytime)

Rotation periodicity (use SIZE condition if omitted).

zip (type: zip-mode, optional, default: bzip2)

Zipping mode.

Constraints:

Use either size criterion or defined periodicity.

stats-daily {


  top-clients ... ;
  top-servers ... ;
  top-sids ... ;
  top-server-ports ... ;
  top-src-ips ... ;
  top-dst-ips ... ;
  top-rules ... ;
}

            

The stats-daily section is derived from summary section prototype. For detail description of it, see application(5).

Changes to the stats-daily section:

Item top-users is not valid.

Item top-groups is not valid.

Item top-categories is not valid.

Item top-senders is not valid.

Item top-recipients is not valid.

Item top-mime-types is not valid.

Item top-qnames is not valid.

Item top-qtypes is not valid.

Item top-callers is not valid.

Item top-receivers is not valid.

Item spam-threshold is not valid.

Section activity-report is not valid.

stats-weekly {


  top-clients ... ;
  top-servers ... ;
  top-sids ... ;
  top-server-ports ... ;
  top-src-ips ... ;
  top-dst-ips ... ;
  top-rules ... ;
}

            

The stats-weekly section is derived from summary section prototype. For detail description of it, see application(5).

Changes to the stats-weekly section:

Item top-users is not valid.

Item top-groups is not valid.

Item top-categories is not valid.

Item top-senders is not valid.

Item top-recipients is not valid.

Item top-mime-types is not valid.

Item top-qnames is not valid.

Item top-qtypes is not valid.

Item top-callers is not valid.

Item top-receivers is not valid.

Item spam-threshold is not valid.

Section activity-report is not valid.

stats-monthly {


  top-clients ... ;
  top-servers ... ;
  top-sids ... ;
  top-server-ports ... ;
  top-src-ips ... ;
  top-dst-ips ... ;
  top-rules ... ;
}

            

The stats-monthly section is derived from summary section prototype. For detail description of it, see application(5).

Changes to the stats-monthly section:

Item top-users is not valid.

Item top-groups is not valid.

Item top-categories is not valid.

Item top-senders is not valid.

Item top-recipients is not valid.

Item top-mime-types is not valid.

Item top-qnames is not valid.

Item top-qtypes is not valid.

Item top-callers is not valid.

Item top-receivers is not valid.

Item spam-threshold is not valid.

Section activity-report is not valid.

[End of section ips description.]

SEE ALSO

configuration(7), suricata(1), application(5), common(5), interface(5)