Border SIP message modification rule (sipmodrule)

Description

Rule for modifying incoming and outgoing SIP messages at the system borders with the outside world. Used for deep, fine-grained adaptation of SIP messages at borders. In particular, as a result of applying a rule with full-text processing, the received packet can be dropped.

Messages are passed for modification in text, unparsed form. Because applying modification rules is quite resource-intensive, rule application is bound to specific instances of facade SIP message processing microservices (sg and esg). For each of them, a list of codes for filtering rules is specified in the configuration parameters.

Several rules can exist with one code. Rules found by codes are applied in descending priority order (increasing priority field value). Rules are processed up to the last matching one, or the process stops if the next matching rule specifies the apply_last action.

Normal mode uses regular expressions and filters. To speed up processing, a function from a custom Erlang module loaded via a patch can be used. For even deeper customization and going beyond the message, the modification mode using a service script can be used (significantly less performant).

Limitations

  • The collection is available only in the master domain.

Fields

Entity structure
{
  "id": uuid,
  "priority": str,
  "enabled": intbool,
  "code": str,
  "dir": str,

  "mode": str,
  "mode_extension": str,

  "extractors": array of str,
  "filter": array,
  "modifiers": array of str,

  "action": str,
  "repair_contentlen": intbool,

  "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 during traversal.

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

Rule group code specified in the configuration parameters of facade microservices sg and esg.
Can be the same for several rules.

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

SIP message direction
Value variants:

  • incoming - Applied only to incoming SIP messages.

  • outgoing - Applied only to outgoing SIP messages.

Field: mode
Mode: in
Type: str
Default: "mask"

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

Module or service script name for the module and svcscript modes respectively.

Field: extractors
Mode: in
Type: array of str
Default: []

List of extractor strings. Each string is a regular expression command.
Applied only in 'mask' mode.

Format: /reg/PATTERN or /reg/PATTERN/OPTS.
For complex cases where the '/' character must be used within PATTERN together with OPTS, a more complex pattern can be used:
/reg{separator}/PATTERN_separator_OPTS, for example: '/reg{!}/PATTERN!REPLACEMENT!OPTS'

Option variants (listed in arbitrary order in concatenation):

  • i — case-insensitive search (caseless);

  • f — search only in the first line (firstline);

  • u — Unicode mode (unicode);

  • m — multiline search (multiline);

  • s — '.' matches all special characters, including end of line (dotall).

If the PATTERN body contains a named capture

(?<some_key>...)

then the found value is captured and placed under the specified name into the object for further filter application.

Extractors may also contain no named groups; in that case they are simply checks.

In any case, for the rule to apply, all extractor strings applied to the SIP message text must find matches.

Field: filter
Mode: in
Type: array
Default: []

Filter in REST API format applied to the object with extracted values.
Applied only in 'mask' mode.

If the rule was not ignored at the extractor stage, the filter is applied to the extraction result object.

The rule applies only if the filter returns true.

Field: modifiers
Mode: in
Type: array of str
Default: []

List of modifier strings. Each string is a regular expression command.
Applied only in 'mask' mode.

Format: /reg/PATTERN/REPLACEMENT or /reg/PATTERN/REPLACEMENT/OPTS.
For complex cases where the '/' character must be used within PATTERN or REPLACEMENT, more complex patterns can be used:
/reg{separator}/PATTERN_separator_REPLACEMENT, /reg{separator}/PATTERN_separator_REPLACEMENT_separator_OPTS, for example: '/reg{!}/PATTERN!REPLACEMENT!OPTS'.

All modifiers are applied to the message sequentially. Modifiers can use special commands in the REPLACEMENT part to substitute values from the extraction result object (for example, to move values from one header to another). To do this, specify '{{some_key}}'.

Option variants (listed in arbitrary order in concatenation):

  • g — multiple search and application (global);

  • i — case-insensitive search (caseless);

  • f — search only in the first line (firstline);

  • m — multiline search (multiline);

  • s — '.' matches all special characters, including end of line (dotall).

The modifier list may be empty; then the message remains unchanged, but the rule action is applied and can end further traversal of lower-priority rules.

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

Field: repair_contentlen
Mode: in
Type: intbool
Default: 0

If at least one applied rule has this mode set, the Content-Length header value is automatically recalculated on completion.
Enable this mode if a rule modifies content but does not recalculate the Content-Length header, or if several rules modify content to save resources.

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: 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

Rule application modes

Table 2. Rule application modes
Value Description

"mask"

Normal mode using regular expressions and filters.
Configured by the rule fields: 'extractors', 'filter', 'modifiers', 'action', and 'repair_contentlen'.

"module"

Mode of applying a custom Erlang module loaded with a patch.
The module name is specified in mode_extension.
The module must export a 'modify_message' function with one, two, or three arguments, or 'modify_message/0' returning a callback function.

-spec modify_message(Msg::binary())
   -> {ok, NewMsg::binary()} | false | drop

-spec modify_message(Msg::binary(), Dir)
   -> {ok, NewMsg::binary()} | false | drop
   when Dir :: incoming|outgoing.

-spec modify_message(Msg::binary(), Dir, Rule::map())
   -> {ok, NewMsg::binary()} | false | drop.
   when Dir :: incoming|outgoing.
  • If the callback returns a new message ({ok,NewMsg}) but the rule action is 'drop', the message is dropped.

  • If the callback returns 'drop', this result overrides the rule action and becomes final in rule processing.

  • If the callback returns 'false', the rule is skipped.

    Any other result is ignored.

"svcscript"

Thin mode for applying a special service script created in the master domain.
The service script code is specified in mode_extension.

The first parameter is the message; the second parameter is the message direction: incoming | outgoing.

(IMPLEMENTATION POSTPONED)

Actions when applying an incoming or outgoing request modification rule

Table 3. Actions when applying an incoming or outgoing request modification rule
Value Description

"apply_next"

Applies the rule and continues processing the following lower-priority rules.

"apply_last"

Applies the rule and stops processing subsequent rules.

"drop"

Drops the message, stops its processing, and ends the rule processing cycle. Makes sense only for the incoming direction and rules that do not modify the message.

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.