Border filter rule (borderrule)

Description

Static filtering rule for incoming SIP requests. Used for attack protection by SIP roles located at the border of the deployed «Incoplax» system.
Other SIP roles forcibly filter by sender address, allowing only packets from other internal servers.

The system applies the highest-priority matching rule.

The IP address value can be an IP address (e.g. 192.168.0.10), a subnet mask (e.g. 192.168.0.0/24), or an IP address range (e.g. 172.25.0.50+10).

Incoming messages pass through two verification cycles. First, rules with only a remote-side IP address/mask filter are selected. This check does not require significant resources. Rules with other filters automatically pass messages from the first stage to the second. If a message is not filtered at the first stage, it is allowed into the system, and after parsing, all rules with their filters are applied to the parsed message, including rules with filters on the From header domain, From header username, User-Agent, and so on. This must be considered when forming whitelists where the last-priority rule is to deny all.

Rules with only an IP address/mask filter prohibit placing addresses in the dynamic ban list (exceeding the number of authorization attempts with different credentials within a short interval).

Limitations

  • The collection is available only in the master domain.

Fields

Entity structure
{
  "id": uuid,
  "priority": str,
  "enabled": int,
  "site": str,
  "domain": str,
  "username": str,
  "useragent": str,
  "remoteipmask": str,
  "action": str,
  "opts": {
    "title": str,
    "comment": str
  },
  "ext": {
    "ct": date,
    "lwt": date
  }
}
Table 1. Fields
Specification Description

Field: id
Mode: inout
Type: uuid
Default: generated

Identifier. Can be specified at creation, otherwise generated by the system.

Field: enabled
Mode: in
Type: intbool
Default: 1

Rule switch

Field: priority
Mode: in
Type: int
Default: required

Priority. A lower value means higher priority.

Field: site
Mode: in
Type: str
Default: "*"

Site where the rule is applied.
"*" – applied on all sites.

Field: service
Mode: in
Type: str
Default: "*"

Service where the rule is applied.
Service types

Field: domain
Mode: in
Type: str
Default: empty

Sender domain or regular expression.

Field: username
Mode: in
Type: str
Default: empty

Username or regular expression.

Field: useragent
Mode: in
Type: str
Default: empty

UserAgent field value in the SIP request or a regular expression.

Field: remoteipmask
Mode: in
Type: str
Default: "0.0.0.0/0"

Sender IP address mask.
The IP address value can be:

  • an IP address (e.g. '192.168.0.10'),

  • a subnet mask (e.g. '192.168.0.0/24'),

  • an IP address range (e.g. '172.25.0.50+10').

Rules matching the corresponding service and specifying only an IP address filter are used by the system in a special way.
Deny rules among them form an IP address blacklist: requests from them are dropped without further parsing and processing.
Allow rules among them form an IP address whitelist for which the dynamic ban list is not applied.

Whitelist
An IP address is whitelisted if all of the following are true:

  • a border filter allow rule exists whose mask/range covers the IP address under consideration;

  • this rule has no other filters on header values;

  • this rule targets the corresponding service;

  • this rule is an allow rule;

  • no other rules with lower 'priority' values also cover the IP address with a mask/range and target the corresponding service.

Thus, for the dynamic ban list to apply to arbitrary addresses, either:

  • there must be no allow rule for 0.0.0.0/0 targeting the corresponding service and containing no other request-field filters;

  • or among lower-priority rules there must be a rule for 0.0.0.0/0 targeting the corresponding service and containing some additional request-field filter.

By default, if none of the existing rules matches, the packet received from the IP address is passed for processing. Further levels of filters then apply, in particular dropping failed responses and the dynamic ban list.

Field: action
Mode: in
Type: str
Default: required

Field: opts
Mode: in
Type: object
Compound field

Field: opts.title
Mode: in
Type: str
Default: empty

Arbitrary title

Field: opts.comment
Mode: in
Type: str
Default: empty

Arbitrary comment

Field: opts.mps_limit
Mode: in
Type: int | "default"
Default: "default"

Value of the maximum allowable message density (messages per second) arriving from a specific IP address covered by the rule with the lowest possible priority.

A value of 0 disables the counter and blocking function. A value of -1 or "default" takes, for IP addresses matching the rule filter, the default value from master domain settings.

When the anti-spam function is enabled (a non-zero maximum allowable message density is set for the address in relation to the protocol): if the number of messages from the address within a few seconds exceeds the specified density, the address automatically enters a managed ban list for some time, so that further messages from it are ignored.

Applicable to facade microservices:

  • web server (ws). HTTP API requests, WebSocket connection events, and all WebSocket messages before authorization are counted.

  • internal SIP gate (sg) and external SIP gate (esg). All kinds of SIP requests and responses, as well as non-protocol packets arriving at SIP interfaces, are counted.

  • autoprovision service (ap). All requests arriving at TFTP and PNP interfaces are counted.

If a rule applies to different service types and sets a maximum density, it makes sense to split the rule by service type so that a different maximum density can be set for different service types.

To enable the counter and anti-spam function:

  • identify microservice instances for which the anti-spam function is disabled in the configuration. For example:

    • receiving webhooks in unlimited volumes;

    • located in an isolated environment;

    • allocated to separate servers and carrying a DoS risk.

  • create high-priority border filter allow rules for the following address/range/subnet types:

    • used by SIP telephony providers, and set individual limits proportional to the number of trunks.

    • being NAT facades of subscriber subnets, and set individual limits proportional to the maximum possible number of devices, assuming 2-3 simultaneous conversations from each.

    • being system phones using state subscription, voicemail, and other services. Based on the average message count with a multiple reserve.

    • being addresses of systems integrated over HTTP(S), including those sending webhooks en masse, for example services of some messengers.

  • in the default value in master domain settings, place a value with reserve suitable for most single devices, for example 20 for SIP rules (incoming SIP messages per second, that is, all kinds of requests and responses, including retries).

Cluster internal addresses mentioned in server configuration options are excluded from anti-spam tracking regardless of how border filter rules are configured.

To soften the blocking trigger criterion, averaging over an interval of several seconds is used.

The blocking decision is recorded in the main log of the microservice node.

Field: ext
Mode: inout
Type: object
Compound field

Allows extending the compound with arbitrary keys and values

Field: ext.ct
Mode: out
Type: date
Default: generated

Object creation time

Field: ext.lwt
Mode: out
Type: date
Default: generated

Time of last modification of the object

Actions when receiving incoming requests

Table 2. Actions when receiving incoming requests
Value Description

"allow"

Allowed

"drop"

Denied. Request is ignored without sending a response.

"deny"

Denied. A rejection response is returned.

Service types

Table 3. Service types
Value Description

"ws"

Applied only on the web server for HTTP(S) and WS(S) API requests.

"sg"

Applied only on sg (TCP, UDP, TLS, WS, WSS).

"esg"

Applied only on esg (TCP, UDP, TLS).

"ap"

Applied only on autoprovision (TFTP).

"sip"

Applied on all border SIP services: sg, esg, ap.

"*"

Applied on all services listed above.

See also

Logical roles

  • sg implements SBC (Session Border Controller) at the border with devices.

  • esg implements SBC (Session Border Controller) at the border with uplinks.