SIP Manipulation Rules (SMR)

Overview & Transformation Architecture
Business & Operational Significance
🎯 User Roles & Key Capabilities
Visual Interface & Layout
Field Reference & Rule Parameters
Transformation Engine Mechanics & PCRE Processing
Standard Enterprise Use Cases
Troubleshooting & Verification
Model Context Protocol (MCP) AI Integration
Glossary

1. Overview & Transformation Architecture

In Ring2All SBC, the SIP Manipulation Rules (SMR) module provides a powerful regular expression transformation engine for modifying, sanitizing, injecting, and stripping SIP headers and URIs in real time. Because different telecom carriers, PBX manufacturers, and softswitches interpret RFC 3261 standards with minor discrepancies, SMR bridges interoperability gaps dynamically without modifying core source code.

Incoming SIP Packet                       SMR Transformation Pipeline                   Outbound SIP Packet
┌──────────────────────────┐             ┌─────────────────────────────┐               ┌──────────────────────────┐
│ INVITE sip:+14155552671  │             │ 1. Match Target Header      │               │ INVITE sip:14155552671   │
│ From: "Alice" <sip:2000> │────► SMR ──►│ 2. Evaluate PCRE Regex      │───► Outbound ─► From: "Alice" <sip:2000> │
│ To: <sip:+14155552671>   │             │ 3. Apply Replacement Pattern│               │ X-Tenant-ID: ring2all-01 │
│ Contact: ...             │             │ 4. Order by Execution Index │               │ Privacy: id              │
└──────────────────────────┘             └─────────────────────────────┘               └──────────────────────────┘

Rules can target the Request-URI (R-URI), standard identity headers (From, To, Contact), diversion headers (Diversion, History-Info), authentication privacy headers (P-Asserted-Identity, Remote-Party-ID), or custom proprietary headers (X-Carrier-*).

2. Business & Operational Significance

Carrier Protocol Interoperability: Resolves vendor-specific incompatibilities (e.g., stripping the leading + for legacy carriers that only accept digits, or injecting technical routing prefixes).
Identity & Privacy Compliance: Masks caller identification (Anonymous) while preserving cryptographically asserted identities for emergency services and lawful intercept compliance.
Carrier Billing Attribution: Injects custom metadata headers (e.g., X-Tenant-ID, X-Account-Code) to allow downstream wholesale carrier switches to categorize and bill traffic accurately.
Dialed Number Normalization: Converts local 7-digit or 10-digit national numbers into globally recognized E.164 formats before hitting least-cost routing tables.

3. 🎯 User Roles & Key Capabilities

Role	Primary Use Case	Key Capabilities
SIP Interoperability Specialist	Vendor Dialplan Normalization	Author PCRE regex rules, test URI transformations, and align SIP headers with third-party carrier specifications.
Carrier Onboarding Engineer	Trunk Header Customization	Inject mandatory carrier authorization tokens and custom billing headers on egress trunk routes.
Security & Privacy Compliance Officer	Caller ID & CLI Masking	Enforce caller privacy regulations by stripping PAI or rewriting From display headers on outbound calls.
SBC Administrator	Execution Order Governance	Prioritize manipulation rule sequences and audit active header transformation filters.
AI Protocol Engineer / Interoperability Copilot	Regex Testing & Rule Synthesis	Synthesize PCRE regex patterns, validate SIP header manipulation rules, and dynamically apply transformations via MCP.

4. Visual Interface & Layout

The SMR interface provides a list of configured transformation rules with their target headers, match patterns, and execution priorities, along with a modal editor for creating and updating rules.

4.1 SIP Manipulation Rules List View

Displays all registered transformation rules, targets, direction, priority order, and operational status.

SIP Manipulation Rules List View

4.2 SMR Configuration Form

Modal editor for defining target headers, PCRE regex patterns, replacement expressions, and directionality.

SMR Configuration Form

5. Field Reference & Rule Parameters

Parameter Name	Data Type	Options / Format	Description
Rule Name	String	Text (e.g., `Strip Leading Plus E.164`)	Descriptive label explaining the intent of the manipulation rule.
Target Header / URI	Select	`Request-URI`, `From`, `To`, `PAI`, `Custom`	The specific SIP header or message part evaluated by this rule.
Header Name	String	`X-Tenant-ID` (Conditional)	Specific header name when `Target` is set to `Custom Header`.
Direction	Select	`Inbound`, `Outbound`, `Both`	Traffic flow where the rule executes: upon receiving a packet or before relaying it.
Match Regex (PCRE)	String	`^\+([0-9]+)$`	Perl-Compatible Regular Expression (PCRE) matched against the target string.
Replacement String	String	`$1` or `tenant-prod-100`	Replacement pattern. Supports backreferences (`$1`, `$2`) to capture groups.
Execution Priority	Integer	`1` to `100` (Default `50`)	Processing order. Rules with lower numbers execute first.
Rule Status	Switch	`Active` / `Disabled`	Toggle to enable or disable the rule without deleting it from the database.

6. Transformation Engine Mechanics & PCRE Processing

Under the hood, SMR executes using Kamailio’s textops, textopsx, and uac modules:

# SMR Execution Flow in Kamailio routing script
route[APPLY_OUTBOUND_SMR] {
    # Rule 10: Strip leading '+' from Request-URI
    if ($rU =~ "^\+([0-9]+)$") {
        $rU = $(rU{s.substr,1,0});
        xlog("L_INFO", "[SMR] Stripped leading +: new R-URI=$rU\n");
    }

    # Rule 20: Inject X-Tenant-ID Header
    if (!is_present_hf("X-Tenant-ID")) {
        append_hf("X-Tenant-ID: ring2all-prod\r\n");
    }

    # Rule 30: Anonymize Caller ID if privacy requested
    if ($hdr(Privacy) == "id") {
        uac_replace_from("Anonymous", "sip:anonymous@anonymous.invalid");
    }
}

Because transformations operate directly on message buffers in shared memory, rule evaluation introduces zero measurable latency.

7. Standard Enterprise Use Cases

Case 1: Strip Leading Plus (`+`) for Legacy Trunks

Target: Request-URI
Direction: Outbound
Match Regex: ^\+([0-9]+)$
Replacement: $1
Result: +14155552671 becomes 14155552671.

Case 2: Inject Carrier Account Metadata

Target: Custom Header (X-Carrier-Account)
Direction: Outbound
Match Regex: .*
Replacement: ACCT-99201
Result: Injects X-Carrier-Account: ACCT-99201\r\n into the SIP request before dispatching to the carrier.

Case 3: Caller ID Anonymization for Outbound Calls

Target: From Header
Direction: Outbound
Match Regex: ^"?(.*?)"?\s*<sip:.*@(.*)>$
Replacement: "Anonymous" <sip:anonymous@anonymous.invalid>
Result: Masks the caller’s true display name and telephone number while preserving the internal Call-ID.

8. Troubleshooting & Verification

Validating Transformations via SIP Tracing

Capture live SIP packets using the SIP Traces & Diagnostics module (sip-traces) to confirm that headers are correctly rewritten on egress:

# Verify headers on outbound trunk interface
grep -E "(X-Tenant-ID|From:|To:|INVITE)" /var/log/kamailio.log

Hot-Reloading Manipulation Rules via RPC

smr.reload

9. Model Context Protocol (MCP) AI Integration

The Smart Message Routing & SIP Manipulation Rules (SMR) module integrates with the Model Context Protocol (MCP) to allow diagnostic agents to query active header modification rules, inspect regex match conditions, create new header mutations, and safely remove obsolete rules.

Available MCP Tools

Tool Name	Operation Type	Risk Level	Description
`list_smr_rules`	Status Query	`read`	List all SIP Manipulation rules (header transformations, regex filters, directions, and priorities).
`get_smr_rule_status`	Detailed Audit	`read`	Get configuration, regex matching, and header actions of a specific SMR rule.
`create_smr_rule`	Configuration Mutation	`operational`	Create a new SIP header manipulation rule in Kamailio (e.g. rewrite PAI, strip custom headers).
`delete_smr_rule`	Configuration Deletion	`operational`	Delete a SIP manipulation rule and regenerate Kamailio SMR routing drop-in configuration.

Tool Schemas & Payloads

1. `list_smr_rules`

Input Schema

{
  "type": "object",
  "properties": {
    "direction": {
      "type": "string",
      "enum": ["inbound", "outbound", "both"],
      "description": "Filter by message direction."
    },
    "status": {
      "type": "string",
      "enum": ["active", "disabled"],
      "description": "Filter by operational status."
    }
  }
}

Output Payload Example

{
  "success": true,
  "data": {
    "totalRules": 2,
    "rules": [
      {
        "id": 1,
        "name": "Strip Leading Plus",
        "direction": "outbound",
        "matchHeader": "Request-URI",
        "matchRegex": "^\\+([0-9]+)$",
        "actionType": "modify",
        "actionValue": "$1",
        "priority": 10,
        "status": "active"
      },
      {
        "id": 2,
        "name": "Inject Carrier Token",
        "direction": "outbound",
        "matchHeader": "X-Carrier-Token",
        "matchRegex": ".*",
        "actionType": "add",
        "actionValue": "SEC-TOKEN-9982",
        "priority": 20,
        "status": "active"
      }
    ]
  }
}

2. `create_smr_rule`

Input Schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Descriptive rule name (e.g. 'Strip X-Call-ID', 'Normalize E164 CLI')."
    },
    "direction": {
      "type": "string",
      "enum": ["inbound", "outbound", "both"],
      "description": "Direction to apply rule."
    },
    "matchHeader": {
      "type": "string",
      "description": "Target SIP Header (e.g. 'P-Asserted-Identity', 'X-Account-ID', 'From')."
    },
    "matchRegex": {
      "type": "string",
      "description": "Regex pattern to match or extract (e.g. '.*', '^\\+?1([0-9]{10})$')."
    },
    "actionType": {
      "type": "string",
      "enum": ["add", "remove", "modify", "strip_prefix"],
      "description": "Action to perform on the header."
    },
    "actionValue": {
      "type": "string",
      "description": "New value or replacement expression."
    },
    "priority": {
      "type": "number",
      "description": "Rule evaluation order (default: 10). Lower number runs first."
    }
  },
  "required": ["name", "direction", "matchHeader", "actionType"]
}

Output Payload Example

{
  "success": true,
  "data": {
    "message": "SMR rule created successfully and Kamailio configuration reloaded.",
    "ruleId": 3
  }
}

Natural Language AI Prompts

English Examples

“List all outbound SIP manipulation rules currently active on the SBC.”
“Create an outbound SMR rule to strip the leading plus from Request-URI for legacy carrier trunks.”
“Inspect the configuration and regex pattern of SMR rule ID 1.”

Spanish Examples (Español)

“Lista todas las reglas de manipulación SIP salientes actualmente activas en el SBC.”
“Crea una regla SMR saliente para eliminar el signo más inicial del Request-URI para troncales carrier legadas.”
“Inspecciona la configuración y el patrón regex de la regla SMR con ID 1.”

Enterprise Safeguards & Access Governance

PCRE Syntax Guardrails: Regular expressions are syntax-checked prior to injection to prevent Kamailio routing script parse crashes.
Automatic Configuration Regeneration: The create_smr_rule tool writes drop-in configuration to /etc/kamailio/smr_rules.cfg and executes kamcmd core.reload atomically.
Role Authorization: Rule creation and deletion require noc_network_engineer or sbc_system_admin privileges.

10. Glossary

SMR (SIP Manipulation Rules): A rule-based framework for parsing and modifying SIP headers and message components in real time.
PCRE (Perl-Compatible Regular Expressions): A standardized regular expression library providing advanced pattern matching and capture group substitution.
Request-URI (R-URI): The first line of a SIP request indicating the destination user, host, and port where the request is being addressed.
Backreference: A regular expression feature allowing parts of a matched string ($1, $2) to be reused inside the replacement expression.

SIP Manipulation Rules (SMR)

Table of Contents

1. Overview & Transformation Architecture

2. Business & Operational Significance

3. 🎯 User Roles & Key Capabilities

4. Visual Interface & Layout

4.1 SIP Manipulation Rules List View

4.2 SMR Configuration Form

5. Field Reference & Rule Parameters

6. Transformation Engine Mechanics & PCRE Processing

7. Standard Enterprise Use Cases

Case 1: Strip Leading Plus (+) for Legacy Trunks

Case 2: Inject Carrier Account Metadata

Case 3: Caller ID Anonymization for Outbound Calls

8. Troubleshooting & Verification

Validating Transformations via SIP Tracing

Hot-Reloading Manipulation Rules via RPC

9. Model Context Protocol (MCP) AI Integration

Available MCP Tools

Tool Schemas & Payloads

1. list_smr_rules

Input Schema

Output Payload Example

2. create_smr_rule

Input Schema

Output Payload Example

Natural Language AI Prompts

English Examples

Spanish Examples (Español)

Enterprise Safeguards & Access Governance

10. Glossary

Case 1: Strip Leading Plus (`+`) for Legacy Trunks

1. `list_smr_rules`

2. `create_smr_rule`