ips — format of ips component configuration
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.
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.
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 { ... }
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
Action must be specified.
Options must be specified.
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
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
base-rate-filter
section is derived from
base-rule-policy
section prototype.
For detail description of it, see above.
base-rate-filter
section:Item TRACK-BY required.
Item COUNT required.
Item SECONDS required.
Item NEW-ACTION required.
Item TIMEOUT required.
track-by
src
;track-by
dst
;track-by
rule
;track-by
both
;How to track the exception.
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
base-threshold
section is derived from
base-rule-policy
section prototype.
For detail description of it, see above.
base-threshold
section:Item TYPE required.
Item TRACK-BY required.
Item COUNT required.
Item SECONDS required.
type
threshold
;type
limit
;type
both
;Threshold type.
threshold-type
)track-by
src
;track-by
dst
;How to track the threshold.
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
base-suppress
section is derived from
base-rule-policy
section prototype.
For detail description of it, see above.
direction
src
;direction
dst
;direction
[any
];Direction of the suppression.
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
)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.
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.
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
)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
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
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
)SID list must not be empty.
enable-rules
sid
;Enable IPS rules
sid
(type: uint64-list
)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
)SID list must not be empty.
change-rules-to-drop
sid
;Change the action of IPS rules to drop
sid
(type: uint64-list
)SID list must not be empty.
change-rules-to-reject
sid
;Change the action of IPS rules to reject
sid
(type: uint64-list
)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
rule-rate-filter
section is derived from
base-rate-filter
section prototype.
For detail description of it, see above.
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
global-rate-filter
section is derived from
base-rate-filter
section prototype.
For detail description of it, see above.
global-rate-filter
section:Item sid
is not valid.
rule-threshold
name
{
* sid ... ;
type ... ;
track-by ... ;
count ... ;
seconds ... ;
}
Conditionally limit the selected IPS rules
rule-threshold
section is derived from
base-threshold
section prototype.
For detail description of it, see above.
rule-threshold
section:Atleast one SID must be entered.
global-threshold
name
{
type ... ;
track-by ... ;
count ... ;
seconds ... ;
}
Conditionally limit all IPS rules
global-threshold
section is derived from
base-threshold
section prototype.
For detail description of it, see above.
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.
rule-suppress
section is derived from
base-suppress
section prototype.
For detail description of it, see above.
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.
global-suppress
section is derived from
base-suppress
section prototype.
For detail description of it, see above.
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
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
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
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.
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.
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 ... ;
}
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.
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.
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.
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.
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 ... ;
}
stats-daily
section is derived from
summary
section prototype.
For detail description of it, see application(5).
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 ... ;
}
stats-weekly
section is derived from
summary
section prototype.
For detail description of it, see application(5).
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 ... ;
}
stats-monthly
section is derived from
summary
section prototype.
For detail description of it, see application(5).
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.]