# SIP Security

> How sip_security_config gates inbound SIP: spam and scanner filtering, REGISTER rate limiting, and STIR/SHAKEN attestation.

The **SIP Security** screen in the admin section of the console
(`agent/sipSecurity`) is the editor for `sip_security_config` — the
TeleQuick engine's SIP-facing protection settings. Trunking
configuration is per trunk; `sip_security_config` is not. Everything on
this screen applies to the engine as a whole.

This page explains what the config covers and how it relates to the
per-trunk settings documented on the
[SIP trunking](/modalities/voice/transport-telephony/trunking) page. For
the current values in your deployment, read them off the screen — they
are deployment state, not documented constants.

## What sip_security_config covers

`sip_security_config` groups three controls, which are the three
sections of the screen:

| Control                            | Protects against                                                              |
| ---------------------------------- | ----------------------------------------------------------------------------- |
| Inbound spam / scanner filter      | Unsolicited INVITE traffic and SIP scanning from the public internet.          |
| REGISTER rate limit                | Registration floods and credential-guessing against the registrar surface.    |
| STIR/SHAKEN                        | Unattested outbound caller identity; carrier-side attestation requirements.   |

The same screen body renders in both the contact-centre console and the
voice-AI console, so what you change here is the same object regardless
of which surface you opened it from. Only the surrounding page chrome
differs.

## Engine-global vs per-trunk settings

This is the distinction that most often causes confusion, because the
two kinds of settings look adjacent in the console:

- **Per trunk** (on the trunking screen): the fields that describe *one*
  carrier relationship — where it points, how it authenticates, what
  headers it sends.
- **Engine-global** (`sip_security_config`, on this screen): the SIP
  protection posture for the engine, evaluated across all inbound SIP
  traffic and all registrations, not scoped to a single trunk.

Two consequences follow:

1. Editing `sip_security_config` changes behaviour for **every** trunk
   and tenant served by that engine. There is no per-trunk override of
   these controls on this screen.
2. If you need different security posture for different carriers, that
   separation has to come from your deployment topology (separate
   engines, separate SIP surfaces) rather than from this config object.

Treat a change here as a production-wide change and roll it out the way
you would any other engine-level change.

## Inbound spam and scanner filtering

Public SIP surfaces receive continuous scanning traffic: probing INVITEs,
enumeration attempts, and unsolicited call attempts that have no
legitimate trunk behind them. The inbound spam/scanner filter is the
control that drops this traffic at the SIP layer, before it becomes a
call the rest of the stack has to reason about.

Because the filter runs on inbound SIP and not inside a call, traffic it
rejects does not necessarily produce the call-level artefacts you would
normally reach for when debugging. See
[When a legitimate carrier gets blocked](#when-a-legitimate-carrier-gets-blocked)
for how to confirm what the filter actually matched.

The filter's match criteria and current settings are shown on the screen.
Read them there rather than assuming a default.

## REGISTER rate limiting

The registrar surface has its own control: a limit on REGISTER traffic.
Its purpose is to stop registration floods and repeated credential
attempts from consuming engine resources or brute-forcing endpoint
credentials.

Two things to keep in mind:

- The limit lives in `sip_security_config`, so it governs the engine's
  REGISTER surface as a whole. It is not a per-trunk or per-tenant
  registration quota.
- The limit and the way it is counted are shown on the screen. Do not
  hardcode an assumed value into client retry logic — read the
  configured value, then set device and softphone re-registration
  intervals so that normal fleet behaviour stays comfortably underneath
  it.

A fleet of endpoints that all re-register on the same schedule can look
like a flood. Stagger re-registration across your fleet rather than
raising the limit as a first response.

## STIR/SHAKEN attestation from this screen

STIR/SHAKEN is described in the regulatory documentation as a
requirement. This screen is where it is **enabled** for the engine.
Because the toggle sits in `sip_security_config`, attestation is an
engine-global posture, not something you switch on for one trunk and
leave off for another.

That matters when you combine it with a trunk's **compliance-headers
mode**, which *is* per trunk:

- `sip_security_config` decides whether the engine participates in
  STIR/SHAKEN at all.
- The trunk's compliance-headers mode decides how identity and
  compliance headers are presented on that specific carrier
  relationship.

So the two settings compose: enabling STIR/SHAKEN here does not override
what an individual trunk is configured to send, and setting a trunk's
compliance-headers mode does not enable attestation on an engine where
it is switched off. When a carrier reports missing or unexpected identity
information, check both — the engine-global switch on this screen and the
per-trunk mode on the
[trunking](/modalities/voice/transport-telephony/trunking) page.

## When a legitimate carrier gets blocked

The failure mode to plan for: a real carrier or a real endpoint fleet
trips one of these controls and its traffic stops arriving. Symptoms are
one-sided — the carrier reports sending traffic, and you see no
corresponding calls or registrations.

Because these controls act on the SIP exchange itself, the usual
call-level debugging path may have nothing in it. Work in this order:

1. **Confirm it is SIP-layer, not call-layer.** If a call fails before
   any `CallEvent` reaches the SDK, inspect the actual SIP exchange with
   HEPv3 capture to a Homer / heplify-server instance. See
   [Telemetry](/platform/telemetry) for how to enable capture and the
   caveat about leaving it on in production.
2. **Check whether the block is global.** `sip_security_config` is
   engine-global, so a control that is filtering one carrier is being
   applied to all of them. If several unrelated peers degraded at the
   same time, suspect this config rather than a single trunk.
3. **Separate the registrar case from the INVITE case.** Endpoints that
   cannot register point at the REGISTER rate limit; inbound calls that
   never appear point at the spam/scanner filter. They are independent
   controls with independent settings on this screen.
4. **Fix the cause, not the threshold.** For registrations, stagger
   re-registration across the fleet. For inbound calls, confirm the peer
   is the peer you expect before loosening a filter that is otherwise
   doing its job for every other trunk on the engine.

## Related

- [SIP trunking](/modalities/voice/transport-telephony/trunking) — the
  per-trunk fields, including compliance-headers mode
- [Telemetry](/platform/telemetry) — metrics, CDRs, and HEPv3 SIP capture
  for confirming what reached the engine
- [Authentication](/concepts/authentication) — credentials for the
  control-plane and data-plane surfaces, which these SIP-layer controls
  do not cover