0

SIP Message Conversion Guide

 

Overview

The SIP Message Conversion (SMC) module, integrated within the VSXi and NSS products, is a powerful tool designed to manipulate and customize SIP messages. With its flexibility and versatility, SMC can be used in various applications, such as meeting specific carrier interoperability requirements, working with non-compliant devices, and performing advanced routing operations. This guide aims to provide you with a comprehensive walkthrough of the SMC module, enabling you to understand, configure, and troubleshoot SMC rules effectively.

Overview of SMC Functionality: SMC empowers network administrators with the ability to perform the following actions on SIP headers or parameters, including SDP:

  • Insert, delete, or modify SIP headers or parameters.

  • Copy or move header or parameter values.

  • Rename parameter names.

  • Manipulate numbering formats.

  • Read XML and ISUP body payload for use in SIP.

Note: Due to its extensive capabilities, it is important to exercise caution when utilizing SMC. To ensure the expected results, thorough debugging and testing should be conducted before implementing SMC in a production environment. This approach minimizes the potential for unintended consequences and helps maintain network stability and reliability.

Guide structure

This guide will cover the following key aspects of the SMC module, providing you with the knowledge and skills to work effectively with SMC rules:

  1. Understanding SMC components

  2. Creating SMC rules

  3. Testing and troubleshooting SMC rules

  4. Appendix - Special Applications

SMC Components

The SMC file structure is made up of two main components:

  • SMC Profile
  • SMC Rules

SMC uses JavaScript Object Notation (JSON) schema formatting for both SMC profiles and
rules, since it is easy to read and write and is easy for machines to parse and generate. If you are not familiar with JSON, the following links will be helpful to write and read SMCs:

SMC Profile

An SMC profile is a container of one or more SMC rules.  An SMC profile has a unique ProfileID and a Profile Name. A profile can contain one rule or more rules which will dictate how a SIP message is to be converted.

Each SMC profile follows the same basic format and is comprised of:

  • Profile Identification (ID and Name)
  • SMC Rules
    • Rule Scope
    • Rule Variables (Optional)
    • Rule Conditions (Optional)
    • Rule Actions

SMC Rule

SMC rules are the actionable component of SMC profiles. SMC rules define what an SMC profile will do.

Each SMC rule contains a minimum of one, but more often than not two, validations that act similar to the checkpoints. The first SMC rule validation is called rule scope and is required for all SMC rules. If the SIP message satisfies the rule scope, the first checkpoint gate raises and the message is allowed to continue down the road.
The second rule validation an SMC rule condition, which is an optional component of the SMC rule. If the SIP message satisfies the rule condition, again the checkpoint gate raises and the message is allowed to continue down the road e.g. actions are performed and the message is converted.

If, however the SIP messages does not satisfy either of these validations the SIP message will not be modified and the message will traverse in its original form.

Rule Scope

The first validation method that the SMC utilizes actually consists of two checkpoints. Just as SIP message types come in two forms: REQUESTS or RESPONSES. SMC rules are written for either REQUEST or RESPONSE message types. The first checkpoint ensures that the SIP message matches the intended message type and has one of two outcomes:

  1. If the SIP message is not of the same message type defined in the SMC rule, the SMC module will stop evaluating the SIP message and the message will be processed as-is.
  2. If the SIP message is of the same message type defined in the SMC rule, the SMC module will then pass the SIP message along for further validation based on the SMC message sub-type.

Multiple Methods or Response Codes can be separated with a comma.

"MsgType" : "Request",
"ReqMethod":"INVITE,REGISTER"

For processing SIP responses, you would use Response and RspCodeList.

"MsgType" : "Respone",
"RspCodeList":"200,503"

It is also possible to wildcard response codes using XX such as:

"MsgType" : "Respone",
"RspCodeList":"5XX"

 

Rule Actions

If you are reading this guide it is because you are trying to do something with a SIP message. SMC Actions are performed once a SIP message has satisfied both the Message Scope and any Conditions that you’ve defined (Note: Conditions are explained later in this guide). While most SMC Actions are placed towards the last portion of a rule, we think it makes sense to start with the ultimate goal which are actions and the expand upon.

In general there are two type of actions:

  • DROP. Drop action act similar to a firewall, it passes or not.
  • REPLACE. Replace actions allow modifying or changing the course of a SIP message somehow.

DROP_MSG

The action does not contain any sub-actions. The DROP_MSG action does exactly how it sounds. If a message arrives that satisfies Message Scope, Condition(s) and DROP_MSG is the defined action, that message will immediately be dropped without any response.

This action does not need any attributes within it.

"Rules": [
    {
      "MsgType": "REQUEST",
      "ReqMethod": "INVITE",
      "DataFile": "number_blocking.csv",
      "DataFileBSearchIndex": 1,
      "Conditions": [
        {
          "Header": "From:",
          "HeaderAttr": "HEADER_SECTION_ONLY",
          "Macro": "GETURI_USERNAME",
          "Operator": "BSEARCH_EQ"
        }
      ],
      "Action": "DROP_MSG"
    }
  ]

DROP_MSG_RECORD

Similar behavior to DROP_MSG except that sometimes it is desired to record traffic matching the DROP_MSG action. This is a way of combining DROP_MSG with AUDIT_RECORD as one action.

{
   "ProfileID": 100,
   "ProfileName": "Drop REGISTER and INVITEs from specified user agents",
   "Rules": [
      {
         "MsgType": "REQUEST",
         "ReqMethod": "REGISTER,INVITE",
         "DataFile": "user_agents.csv",
         "DataFileBSearchIndex": 1,
 "LogicalConjunction": "OR",
         "Conditions": [
            {
               "Header": "User-Agent:",
               "HeaderAttr": "HEADER_SECTION_ONLY",
               "RegEx1": "[a-zA-Z]+",
               "Operator": "BSEARCH_EQ"
            },
{
  "Header": "s=",
  "HeaderAttr": "BODY_SECTION_ONLY",
  "RegEx1": "[a-zA-Z]+",
  "Operator": "BSEARCH_EQ"
}
         ],
         "Action": "DROP_MSG_RECORD"
      }
   ]
}

REPLACE_MSG

REPLACE_MSG is a group of actions offered by the SMC. These actions allow you to perform several different types of
modifications to a SIP message based on the sub-action that you use.

In your SMC rule before invoking any of the actions below you MUST first declare the action type:

"Action": "REPLACE_MSG".

Example:

 "Action": "REPLACE_MSG",
           "ReplaceDefs": [
            {
               "ReplaceType": "FINDSUB_LINES",
               "Header": "P-Asserted-Identity:",
               "HeaderAttr": "HEADER_SECTION_ONLY",
               "Output": "{$PAI-DisplayName} <sip:{$PAI-UserName}@{$PAI-Host};verstat=TN-Validation-Passed>"
         }

ADD_LINE

Creates a new line. For example, you can add a line after the From header. When using ADD_LINE you must define an existing SIP header to define the location of where the new line will be added. For example if I select Header: Contact the new line will be created after the SIP Contact header. The line being added is specified in the Output attribute. This action requires an Output attribute.

{
"ReplaceType": "ADD_LINE",
"Header": "GEOLOCATION:",
"HeaderAttr": "HEADER_SECTION_ONLY",
"Output": "X-MS-SBC: SANSAY VSXi"
}

REWRITE_LINE

Rewrites an entire SIP Header. The line location is identified by the header. This action requires an Output attribute.

{
"ReplaceType": "REWRITE_LINE",
"Header": "TOPLINE",
"HeaderAttr": "HEADER_SECTION_ONLY",
"Output": "SIP/2.0 603 Network Blocked"
}

DELETE_LINES

Deletes a specific line. The line being deleted is specified in the Header attribute. The line location is identified by the header.

{
"ReplaceType": "DELETE_LINES",
"Header": "Cisco-Guid:",
"HeaderAttr": "HEADER_SECTION_ONLY"
}

FINDSUB_LINES

This is a find and replace operation for parts of a line/SIP header.  The line location is identified by the header. This action requires an Output attribute. An empty output provides the function of stripping/deleting content.

{
"ReplaceType": "FINDSUB_LINES",
"Header": "TOPLINE",
"HeaderAttr": "HEADER_SECTION_ONLY",
"Macro": "GETURI_USERNAME",
"RegEx1": "^011",
"Output": "+"
}

APPEND_LINES

Appends content to a specific line. The line location is identified by the header. This action requires an Output attribute.

{
"ReplaceType": "APPEND_LINES",
"Header": "TOPLINE",
"HeaderAttr": "HEADER_SECTION_ONLY",
"RegEx1": "^SIP/2.0",
"Output": ";user=phone"
}

FINDINSERTAFTER_LINES

Find content within sip and insert right after it. Insert is done without deleting the matched content. This action requires an Output attribute.

{
"ReplaceType": "FINDINSERTAFTER_LINES",
"Header": "TOPLINE",
"HeaderAttr": "HEADER_SECTION_ONLY",
"RegEx1": "sip:",
"Output": "Key{$To-Host-ID}\$"
}

FINDINSERTBEFORE_LINES

Find content within sip and insert right before it. Insert is done without deleting the matched content. This action requires an Output attribute.

{
          "ReplaceType": "FINDINSERTBEFORE_LINES",
          "Header": "From:",
          "HeaderAttr": "HEADER_SECTION_ONLY",
          "RegEx1": ">",
          "Output": ";otg={$DataFile.Field2}"
        },

AUDIT_RECORD

Audit Record is a passive SMC action. It can be used for debugging or data logging. Audit Record will not modify, reject or drop the SIP message like any of the other actions listed previously. It is best used with Variables do correlate contents of a SIP message with the data being logged. Positive matches get written to a log file. This action requires an Output attribute.

{
"ReplaceType": "AUDIT_RECORD",
"Output": "NOTICE: {$VARIABLE1},{$VARIABLE2}"
}

Rule Conditions

While conditions are optional it is the one component which allows you to control message
conversions at a granular level. It is also the one where you will, most likely, spend a majority of your time while working with SMC profiles.
Think of conditions as TRUE/FALSE statements, where you are comparing one side of an
equation to the other side of the equation. If the condition evaluates to TRUE, the process can continue and if it evaluates to FALSE the process will stop. You can control rule condition concatenation by designating whether or not the rule utilizes AND or OR condition evaluation. This is designated by specifying a LogicalConjunction for the
rule condition section.

For example:

{   "MsgType": "REQUEST",
    "ReqMethod": "REGISTER,INVITE",
    "DataFile": "Bad_IPs.csv",
    "DataFileBSearchIndex": 1,
    "LogicalConjunction": "OR",
    "Conditions":
    [ {   "Header": "RemoteIP:",
          "HeaderAttr": "HEADER_SECTION_ONLY", 
          "Operator": "IP_LOOKUP" "RightOperand": "{$DataFile.Field1}" } ],
"Action": "DROP_MSG_RECORD" }

If no LogicalConjunction is specified, the system will default to OR.

Since conditions rely on logic, they are always used in conjunctions with operators. Here's a list of operators supported by SMC:

Rule Operators

Rule Operators can be used in Condiitons, Variables and Rules and enable you to be laser-focused on the scope of message.

EQ and NEQ

Equals or not equals (i.e. exists or not). Case insentive option: I_EQ & I_NEQ

PREFIX and NPREFIX

Starts with (or not). Case insensitive option: I_PREFIX & I_NPREFIX

SUFFIX & NSUFFIX

Ends with (or not). Case insentive option: I_SUFFIX & I_NSUFFIX

GT / GTE / LT / LTE

Numeric comparison: greater than, less than ...

BETWEEN / NBETWEEN

Numeric comparison: between ...

BSEARCH_EQ

Binary search within an SMC Data File. Binary search is an efficient algorithm for finding an item from a sorted list of items, in this case within an SMC Data File. It works by repeatedly dividing in half the portion of the list that could contain the item, until you've narrowed down the possible locations to just one. BSEARCH_EQ is required when consulting an SMC Data File. BSEARCH_EQ is much more efficient than an operator like CONTAINS.

Case insentivie option: BSEARCH_I_EQ

IPLookup

IP_Lookup is a new operator that enables the VSXi SMC to interpret IPv4 and IPv6 CIDR notation and therefore expand SMC's network-layer operations. This new feature makes SMCs that use IP network information more efficient and easy. Here are some examples of supported notations:

  • 192.168.50.0/23
  • 192.168.0.0/16
  • 192.169.50.1
  • 192.170.50.0/24
  • 2001:0db8:85a3:0000:0000:8a2e:0370:7334
  • ::/0

Previous releases only supported classfull IP notation (e.g. 192.170.50 would be used to cover a /24. However a /23 would need two entries).

IP_Lookup is defined as a new SMC operator. We anticipate that it will mostly be used in conjunction with special variable RemoteIP for blacklisting/whitelisting use cases in addition to niche cases like special routing. If you are not familiar with RemoteIP, this feature allows SMC to perform layer-3 lookups as opposed to searching for IPs at layer-7 (SIP).

{
  "ProfileID": 2022,
  "ProfileName": "IP Lookup. Drop INVITEs/REGISTERs from CIDRs",
  "Rules": [
    {
      "MsgType": "REQUEST",
      "ReqMethod": "REGISTER,INVITE",
  "StoredVariables": [
{
          "VariableName": "{$SIP.RemoteIP}",
  "Porting": "IMPORT"
}
  ],
      "Action": "REPLACE_MSG",
  "ReplaceDefs":[
{
          "ReplaceType": "ADD_LINE",
  "Header": "From:",
          "HeaderAttr": "HEADER_SECTION_ONLY",
          "Output": "RemoteIP: {$SIP.RemoteIP}"
        }
  ]
    },
    {
      "MsgType": "REQUEST",
      "ReqMethod": "REGISTER,INVITE",
      "DataFile": "Bad_IPs.csv",
      "DataFileBSearchIndex": 1,
  "LogicalConjunction": "OR",
      "Conditions": [
        {
          "Header": "RemoteIP:",
          "HeaderAttr": "HEADER_SECTION_ONLY",
          "Operator": "IP_LOOKUP"
          "RightOperand": "{$DataFile.Field1}"
        }
      ],
      "Action": "DROP_MSG_RECORD"
    }
  ]
}

Rule Variables

Variables are an optional component of SMC rules, though they are used more often than not and something that you should be comfortable working with. An SMC profile can include a maximum of 256 variables defined.

Variables like in programming are a container with a descriptive label that stores something which will be used later and an important thing to remember here is, that something will be information extracted from the original SIP message (excepting Reserved Variables, below).

Here's an example of a variable:

 "StoredVariables": [
        {
          "VariableName": "{$PAI-DisplayName}",
          "Header": "P-Asserted-Identity:",
          "HeaderAttr": "HEADER_SECTION_ONLY",
          "Macro": "GETDISPLAYNAME"
        },
       {
          "VariableName": "{$f-DisplayName}",
          "Header": "f:",
          "HeaderAttr": "HEADER_SECTION_ONLY",
          "Macro": "GETDISPLAYNAME"
        },
       {
          "VariableName": "{$From-DisplayName}",
          "Header": "From:",
          "HeaderAttr": "HEADER_SECTION_ONLY",
          "Macro": "GETDISPLAYNAME"
        }],

Variables are often part of Conditions and Actions.

It is common and best practice to define Stored Variables immediately after the general SMC message scope, such as below:

{
      "MsgType": "REQUEST",
      "ReqMethod": "INVITE",
      "DataFile": "stir-shaken_blocked_TN.csv",
      "DataFileBSearchIndex": 1,
      "StoredVariables": [
        {
          "VariableName": "{$To-UserName}",
          "Header": "To:",
          "HeaderAttr": "HEADER_SECTION_ONLY",
          "Macro": "GETURI_USERNAME"
        },

Reserved Variables

Reserved variables are special Rule Variables that are not user-defined nor carried within the SIP message itself.

RejectCallXXX

Some times you want to use SMC's flexible scope and conditions to reject specific traffic. The definition of "reject" in this context is to generate a SIP response to a request. RejectCall is ALWAYS used in conjunction with SMC's ADD LINE Action. The response code is customizable to valid SIP responses in the 400-699 range, for example RejectCall403.

The below SMC makes use reject any REGISTER request with a 403. Please note that the Sansay-SMC-{$SIP.Export} line is only handled internally by the VSXi and will not be added to a SIP message.

{
  "ProfileID": 205,
  "ProfileName": "RejectCall603",
  "Rules": [
    {
      "MsgType": "REQUEST",
      "ReqMethod": "REGISTER",
      "DataFile": "Disconnected_IPs.csv",
      "DataFileBSearchIndex": 1,
      "Conditions":
      [ { "Header": "RemoteIP:",
          "HeaderAttr": "HEADER_SECTION_ONLY", 
          "Operator": "IP_LOOKUP"
          "RightOperand": "{$DataFile.Field1}" }
      ],
      "Action": "REPLACE_MSG",
      "ReplaceDefs": [
        {
          "ReplaceType": "ADD_LINE",
          "Header": "From:",
          "HeaderAttr": "HEADER_SECTION_ONLY",
          "Output": "Sansay-SMC-{$SIP.Export}: RejectCall403"
        }
      ]
    }
  ]
}

RemoteIP

RemoteIP is a reserved variables that allows importing the SIP message layer-3 source address. This extends SMC capabilities at the network level and beyond the content of SIP messages.

RemoteIP can be used for a wide variety of applications including:

  • IP Whitelisting
  • IP Blacklisting
  • Source-based treatment (based on originating IP).

Here's an example SMC.

{
   "ProfileID": 100,
   "ProfileName": "Drop REQUESTS and INVITEs from specified IANA IPs Version 2",
   "Rules": [
      {
         "MsgType": "REQUEST",
         "ReqMethod": "REGISTER,INVITE",
         "StoredVariables": [
            {
               "VariableName": "{$SIP.RemoteIP}",
               "Porting": "IMPORT"
            }
         ],
         "Action": "REPLACE_MSG",
         "ReplaceDefs": [
            {
               "ReplaceType": "ADD_LINE",
               "Header": "From:",
               "HeaderAttr": "HEADER_SECTION_ONLY",
               "Output": "RemoteIP: {$SIP.RemoteIP}"
            }
         ]
      },
      {
         "MsgType": "REQUEST",
         "ReqMethod": "REGISTER,INVITE",
         "DataFile": "IP-blocks.csv",
         "DataFileBSearchIndex": 1,
         "Conditions": [
            {
               "Header": "RemoteIP:",
               "HeaderAttr": "HEADER_SECTION_ONLY",
               "RegEx1": "[0-9]{1,3}.",
               "Operator": "BSEARCH_EQ"
            }
         ],
         "Action": "DROP_MSG_RECORD"
      },
      {
         "MsgType": "REQUEST",
         "ReqMethod": "REGISTER,INVITE",
         "Conditions": [
            {
               "Header": "RemoteIP:",
               "HeaderAttr": "HEADER_SECTION_ONLY",
               "Operator": "NEQ",
               "RightOperand": ""
            }
         ],
         "Action": "REPLACE_MSG",
         "ReplaceDefs": [
            {
               "ReplaceType": "DELETE_LINES",
               "Header": "RemoteIP:",
               "HeaderAttr": "HEADER_SECTION_ONLY"
            }
         ]
      }
   ]
}

RemoteIP is best used in conjunction with the IPLookup operator.

Date

The Date reserved variable allows importing the system's current time for use with a header such as a SIP Date header. Here's the debug output of the Date reserved variable in action:

SMC profile 100, rule seq 0: evaluation = TRUE 
p=100/r=0/a=0: ADD_LINE (line 5) = "Date: Thu, 18 Mar 2021 21:06:48 GMT"
SMC ThdBuf Alloc 7F23090AE338
SMC profile 100: SMC modified SIP message, NewBufSize=822/822, OrigBufSize=785, IsBufTruncated=0 
SMC profile 100: NewBodyContentLength=208, OrigBodyContentLength=208
SMC ThdBuf Restore 7F23090AE338 
Post SMC - UDP Message from 74.62.23.98:64240 on service port 200 54.177.185.224:5065. 

INVITE sip:8587542211@sansaylab1.com SIP/2.0 
Via: SIP/2.0/UDP 10.33.59.6:64240;branch=z9hG4bK-524287-1---b6759d2c792e4968;rport 
Max-Forwards: 70 
Contact: <sip:8587542200@10.33.59.6:64240> 
Date: Thu, 18 Mar 2021 21:06:48 GMT To: <sip:8587542211@sansaylab1.com>
From: "Sansay Lab 1"<sip:8587542200@sansaylab1.com>;tag=ad12805e 
Call-ID: 102650NDk5NGEzYjNiOGQxZTM3YTcwMzUwOGQxNzAxODYwMzQ 
CSeq: 1 INVITE Allow: OPTIONS, SUBSCRIBE, NOTIFY, INVITE, ACK, CANCEL, BYE, REFER, INFO, MESSAGE 
Content-Type: application/sdp 
Supported: replaces User-Agent: Bria 5 release 5.8.3 stamp 102650 Content-Length: 208

Here's how it looks in an SMC profile:

{
  "ProfileID": 106,
  "ProfileName": "Add date header",
  "Rules":[
  {
  "MsgType": "REQUEST",
  "ReqMethod": "INVITE",
  "StoredVariables":[
    {
     "VariableName": "{$SMC.Date}",
     "Porting": "IMPORT"
    }
  ],
  "LogicalConjunction": "AND",
  "Conditions": [
    {
      "Header": "Date:",
      "HeaderAttr": "HEADER_SECTION_ONLY",
      "Operator": "EQ",
      "RightOperand": ""
    }
  ],
  "Action": "REPLACE_MSG",
  "ReplaceDefs": [
    {
      "ReplaceType": "ADD_LINE",
      "Header": "Contact:",
      "HeaderAttr": "HEADER_SECTION_ONLY",
      "Output": "Date: {$SMC.Date}"
    }
   ]
  }
 ]
}

Rule Macros

Macros are shortcuts that allows the extraction of pre-defined contents of a SIP message. Each macro is based off of the SIP URI scheme defined in RFC 3261 and extracts particular information from the SIP message. Macros can be used with Variables, Conditions and Actions.

Let's use the following PAI Header as an example to illustrate SMC macros:

P-Asserted-Identity: Batman <sip:18665551000@192.168.0.10:5060;isup-oli=62>
  • GETDISPLAYNAME Extracts the display name Batman
  • GETURI  Extracts the URI 18665551000@192.168.0.10
  • GETURI_USERNAME Extracts the URI username 18665551000
  • GETURI_HOST Extracts the URI host 192.168.0.10
  • GETURI_PORT Extracts the URI port 5060
  • GETURI_PARAMETERES Extracts parameters after the URI isup-oli=62

The example below demonstrates the flow during variable creation, using a build-in function to extract information from the SIP message .

"ReplaceDefs":
[ { "ReplaceType": "FINDSUB_LINES",
    "Header": "From:",
    "HeaderAttr": "HEADER_SECTION_ONLY",
    "Macro": "GETURI_USERNAME",
    "Output": "{$DataFile.Field2}" } ]

Rule Regex

Regular expressions (RegEx) are special strings of text used to describe a search pattern, similar to the wildcard (*) you used in your document search but with RegEx you can easily pare down that list to one result instead of hundreds or even thousands. Regular expressions are a very broad subject and beyond the scope of this document. For additional information on RegEx here are a few links to get you started:

The SMC module also supports the POSIX Extended Regular Expressions (ERE) and each variable can make use of two regular expressions.

SMC allows for two RegEx levels: RegEx1 and RegEx2. RegEx1 is the first pass. RegEx2 is optional and can be used to further extract text past the first RegEx.

RegEx are useful when a Macro is not specific enough. RegEx can be used within Variables, Conditions and Actions.

For example: Extract the trunk group from a header using “tgrp=” as the string:
Header in SIP message: Contact: <sip:anonymous;tgrp=80181;trunk-
context=1234512340@192.168.0.10:5060>

"RegEx1": "tgrp=[0-9]+;",
"RegEx2": "[0-9]+"

Break

The break statement has the capacity to control the flow of an SMC rule. The break statement works best when rules are crafted with a specific sequence in mind. If there's a rule whose behavior will hinder the effect of any subsequent rules then this is where you want to use the break statement.

Let's consider the following scenario:

  • SMC Rule 1: SMC SIP packet drop via whitelist approach
  • SMC Rule 2: SIP Header re-write
  • SMC Rule 3: SIP ANI/DNIS normalization
  • SMC Rule 4: SIP Header addition

In this example, if Rule 1 returns a positive match, it does not make sense to continue with the other SMC rules until the SMC profile exists. A break statement will allow SMC Profile 1 to exit on SMC Rule 1 if it evaluated true. Break is inserted prior to closing a specific rule (i.e. prior to rule's closing } bracket).

Here's an example:

{
  "ProfileID": 1,
  "ProfileName": "Whitelist and SIP header modifications",
  "Rules": [
    {
      "MsgType": "REQUEST",
      "ReqMethod": "INVITE",
      "DataFile": "Whitelist.csv",
      "DataFileBSearchIndex": 1,
      "Conditions": [
        {
          "Header": "User-Agent:",
          "HeaderAttr": "HEADER_SECTION_ONLY",
          "Operator": "BSEARCH_EQ"
        }
      ],
      "Action": "DROP_MSG",
       "Break": 1
    },
    {
      "MsgType": "REQUEST",
      "ReqMethod": "INVITE",
      ...

    },

When using Break, it must be used with Value 1. Break behavior can be temporarily disabled using Break: 0.

Rule Comments

SMC Rule Comments help document the purpose of speciifc SMC rules within an SMC profile. While the SMC Profile Name is a required field and describes the general intent of the SMC Profile, SMC Rule Comments are optional and provide context of specific SMC rule.

{   "ProfileID": 1,
          "ProfileName": "E.164 normalization and Whitelist and SIP header modifications",
          "Rules":
    [     {
           "Comment":"Modify INVITE To E.164",
           "MsgType": "REQUEST",
           "ReqMethod": "INVITE",

 

Special Applications

Media Inspector

Media inspector enables you to remove bad actors from establishing calls through your network by examining the media IP in the SDP. In many of these cases the bad actor may not necessarily be a direct customer or vendor. Media inspector primary use cases are:

  • False Answer Supervision (FAS).
  • Fraudulent and/or Unlawful traffic.
  • Bad media quality.

  

Here's an example:

{
  "ProfileID": 901,
  "ProfileName": "In - reject calls per media IP",
  "Rules": [
    {
      "MsgType": "REQUEST",
      "RspCodeList": "INVITE",
      "DataFile": "BadMediaIP.csv",
      "DataFileBSearchIndex": 1,
  "LogicalConjunction": "OR",
      "Conditions": [
        {
          "Header": "c=",
          "HeaderAttr": "BODY_SECTION_ONLY",
          "Operator": "IP_LOOKUP"
          "RightOperand": "{$DataFile.Field1}"
        }
      ],
      "Action": "REPLACE_MSG",
      "ReplaceDefs": [
        {
          "ReplaceType": "ADD_LINE",
          "Header": "Call-ID:",
          "HeaderAttr": "BODY_SECTION_ONLY",
          "Output": "Sansay-SMC-BlockMedia"
        }
      ]
    }
  ]
}

You do LCR through vendor X. Vendor A may end up sending their calls to vendors M, N, O or P. If it turns out that calls to P are highly likely to experience FAS, you only want to block P, not all of A (or its sub-vendors).

STIR/SHAKEN

One of the elements STIR/SHAKEN call authentication and verification includes is the current time to prevent the usage of stale tokens. STIR/SHAKEN PASSPorT carries an iat parameter that represents the current time in seconds since the Epoch. Some devices compare the passport's iat against a SIP Date header.

With SMC a Date header can be added using reserved variable SMC.Date

"{$SMC.Date}"

Example:

{
  "ProfileID": 106,
  "ProfileName": "Add date header",
  "Rules":[
  {
  "MsgType": "REQUEST",
  "ReqMethod": "INVITE",
  "StoredVariables":[
    {
     "VariableName": "{$SMC.Date}",
     "Porting": "IMPORT"
    }
  ],
  "LogicalConjunction": "AND",
  "Conditions": [
    {
      "Header": "Date:",
      "HeaderAttr": "HEADER_SECTION_ONLY",
      "Operator": "EQ",
      "RightOperand": ""
    },
    {
      "Header": "Identity:",
      "HeaderAttr": "HEADER_SECTION_ONLY",
      "Operator": "NEQ",
      "RightOperand": ""
    }
  ],
  "Action": "REPLACE_MSG",
  "ReplaceDefs": [
    {
      "ReplaceType": "ADD_LINE",
      "Header": "Contact:",
      "HeaderAttr": "HEADER_SECTION_ONLY",
      "Output": "Date: {$SMC.Date}"
    }
   ]
  }
 ]
}

ISUP

The VSXi supports parsing ISUP/MIME body for use in SIP. This done using the following reserved variables:

  • ISUP.IsPresent
  • ISUP.NCI
  • ISUP.CPN
  • ISUP.CPC
  • ISUP.FCI
  • ISUP.ParamJP
  • ISUP.ParamOLI

The below SMC checks for INVITEs with ISUP and adds X-headers with ISUP contents.

{
  "ProfileID": 100,
  "ProfileName": "Test ISUP",
  "Rules": [
    {
      "MsgType": "REQUEST",
      "ReqMethod": "INVITE",
      "Conditions": [
        {
          "Header": "1",
          "HeaderAttr": "CONDITION_LITERAL",
          "Operator": "EQ",
          "RightOperand": "{$ISUP.IsPresent}"
        }
      ],
      "Action": "REPLACE_MSG",
      "ReplaceDefs": [
        {
          "ReplaceType": "ADD_LINE",
          "Header": "P-Asserted-Identity:",
          "HeaderAttr": "HEADER_SECTION_ONLY",
          "Output": "X-ISUP-NCI: {$ISUP.NCI}"
        },
        {
          "ReplaceType": "ADD_LINE",
          "Header": "P-Asserted-Identity:",
          "HeaderAttr": "HEADER_SECTION_ONLY",
          "Output": "X-ISUP-FCI: {$ISUP.FCI}"
        },
        {
          "ReplaceType": "ADD_LINE",
          "Header": "P-Asserted-Identity:",
          "HeaderAttr": "HEADER_SECTION_ONLY",
          "Output": "X-ISUP-CPC: {$ISUP.CPC}"
        },
        {
          "ReplaceType": "ADD_LINE",
          "Header": "P-Asserted-Identity:",
          "HeaderAttr": "HEADER_SECTION_ONLY",
          "Output": "X-ISUP-CPN: {$ISUP.CPN}"
        },
        {
          "ReplaceType": "ADD_LINE",
          "Header": "P-Asserted-Identity:",
          "HeaderAttr": "HEADER_SECTION_ONLY",
          "Output": "X-ISUP-JIP: {$ISUP.ParamJIP}"
        },
        {
          "ReplaceType": "ADD_LINE",
          "Header": "P-Asserted-Identity:",
          "HeaderAttr": "HEADER_SECTION_ONLY",
          "Output": "X-ISUP-OLI: {$ISUP.ParamOLI}"
        }
      ]
    }
  ]
}

Randomizer

SMC supports three different randomizers: 1K, 10K and 100k. The randomizers will create a random number from 1 until the maximum number. 1K is 1-1000, 10k is 1-10000 and 100k is 1-100000.  This random number can be used for a variety of purposes including using it as an index with an SMC Data File. When an SMC Data File has an index, values from other columns can be used with the desired action.

Before you can use a system variable, it must first be imported within the rule where the
variable is to be used. An example of importing the system variable {$SMC.Rand1000} for use can be seen below.

{
  "ProfileID": "100",
  "ProfileName": "Random Number",
  "Rules": [
    {
      "MsgType": "REQUEST",
      "ReqMethod": "INVITE",
      "DataFile": "Randomize.csv",
      "StoredVariables": [
        {
          "VariableName": "{$SMC.Rand1000}",
          "Header": "From:",
          "HeaderAttr": "HEADER_SECTION_ONLY",
          "Porting": "IMPORT"
        }
      ],
      "DataFileBSearchIndex": "1",
      "Conditions": [
        {
          "Header": "From:",
          "HeaderAttr": "HEADER_SECTION_ONLY",
          "Macro": "GETURI_USERNAME",
          "RegEx1": "[0-9]{1,12}",
          "Operator": "LT",
          "RightOperand": "10"
        }
      ],
      "Action": "REPLACE_MSG",
      "ReplaceDefs": [
        {
          "ReplaceType": "FINDSUB_LINES",
          "Header": "From:",
          "HeaderAttr": "HEADER_SECTION_ONLY",
          "Macro": "GETURI_USERNAME",
          "Output": "{$DataFile.Field2}"
        }
      ]
    }
  ]
}

Syntax Spec

You can use this table for guidance when buidling your SMC of as a quick reference.

Reply

null
Login to reply

Content aside

Related Articles
APIBAN Integration
VSXI REST API Guide Version 11
SIP Message Conversion Guide
Google SIP Link Configuration Guide
Programmable SIP Trunking
ROME REST API
VSXi-10.5.1.x resources XML schema
VSXi-10.2.2.x resources XML schema
VSXi RADIUS specification document
ROME HRS migration tools
VSXi WebRTC API User Guide
ROME SOAP API Interface Command List
VSXi monitoring top KPI list and recommended thresholds
VSXi SOAP API Interface Command List
VSXi CDR to MySQL: Table definition and script
VSXi CDR Specification / Layout
ROME QDR Specification
ROME SNMP MIB
VSXi SNMP MIB
VSXi WebRTC webphone SDK 2.3.4
CDR Parser
VSXi SOAP / WS Client
SOAP API and GUI Table Association Chart
ROME SOAP / Web Services Client
Integration with Microsoft Teams
VSXi SOAP / Web Services API Guide