Integration Documentation

Send your signalling firewall or probe exports in whichever way suits you — all three feed the same pipeline: SFTP drop box (scheduled exports, the usual choice), portal upload (CSV/JSON, ideal for a pilot sample) or REST API (pushed by your firewall, STP/DEA or probe for near-real-time). Nothing is installed in your network and SignalsGuard never connects into your STP or DEA — you push data out. SFTP credentials are issued per data provider; every upload is malware-checked and reviewed before loading.

Architecture: Signalling firewall / STP / DEA / probe export → SFTP drop box, portal upload or HTTPS API → classification & detection engine → dashboard, intelligence, compliance reports and alerts

What we need from you

We ingest signalling metadata only — no subscriber PII. Specifically: operation type, protocol, source Global Title or Diameter realm, timestamp, and outcome. We never ask for IMSI, MSISDN, call content, or location coordinates.

Authentication

All API requests require authentication. We support two methods:

Bearer JWT Token

Obtain a JWT by calling POST /api/auth/login with your email and password. Pass it in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

API Key (recommended for probe integration)

Generate an API key in the platform under My account → API Access. Pass it in the X-API-Key header:

X-API-Key: sgk_a1b2c3d4e5f6...

Note: API keys are scoped to your tenant. Rotate them in the platform without service disruption. Keys start with sgk_ and are 52 characters long.

Quickstart

Send your first event in under 2 minutes:

curl -X POST https://signalsguard-api-production.up.railway.app/api/ingest/metadata \
  -H "X-API-Key: sgk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": [{
    "event_time": "2026-09-07T10:23:00Z",
    "protocol": "SS7",
    "operation": "SRI",
    "source_country": "RU",
    "source_operator": "RU mobile GT range",
    "severity": "high",
    "summary": "SRI from non-partner GT to HLR"
  }]}'

A successful response returns {"ok": true, "inserted": 1}. The event will appear in your dashboard within seconds.

Ingest Endpoint

POST /api/ingest/metadata

Submit one or more signalling events. Accepts up to 1,000 events per request. Events are processed synchronously and immediately visible in the platform.

Request body

{
  "events": [
    {
      "event_time":      "2026-09-07T10:23:00Z",   // ISO 8601 UTC
      "protocol":        "SS7",                     // SS7 | Diameter | GTP-C | SIP
      "operation":       "SRI",                     // see Protocol Reference
      "gsma_category":   "A.1",                     // ignored - SignalsGuard always classifies the operation itself
      "severity":        "high",                    // critical | high | medium | low
      "status":          "blocked",                 // blocked | alerted | monitored
      "source_country":  "RU",                      // ISO 3166-1 alpha-2
      "source_operator": "RU mobile GT range",                 // the SENDING network (owner of the source GT/realm), not your own
      "confidence":      87,                        // 0-100
      "campaign_id":     "camp_abc123",             // optional - groups events you know belong together
      "summary":         "SRI from non-partner GT to HLR targeting UK subscriber"
    }
  ]
}

Event Schema

All fields except event_time, protocol, and operation are optional but improve detection quality.

Field	Type	Description
event_time	required	ISO 8601 UTC timestamp of when the signalling event was observed
protocol	required	SS7, Diameter, GTP-C, or SIP
operation	required	The MAP/Diameter/GTP-C/SIP operation code or name (e.g. SRI, ATI, AIR, Create-Session-Req)
gsma_category	optional	Ignored. SignalsGuard assigns the threat category (A.1–C.1) and FS.11 filtering category from the operation, so classification is consistent across all sources.
severity	optional	critical / high / medium / low. Auto-scored from operation type and context if omitted.
status	optional	blocked / alerted / monitored. Reflects action taken by your firewall or probe.
source_country	optional	ISO 3166-1 alpha-2 country code of signalling source (derived from GT E.164 prefix if not supplied)
source_operator	optional	Name or identifier of originating operator/network (STP name, GT prefix, Diameter peer FQDN)
confidence	optional	Integer 0-100. Your probe's confidence that this is a threat event.
campaign_id	optional	Group related events into a correlation campaign. Use the same ID for events that are part of the same attack chain (e.g. SRI + PRN + ISD from the same source).
summary	optional	Human-readable description of the event. Used in AI report generation.

Protocol Reference

SS7 MAP Operations

SRI          SendRoutingInfo (opcode 45)     - High: used to obtain MSRN for call delivery or interception
PRN          ProvideRoamingNumber (opcode 4)  - High: obtains MSRN from VLR
ATI          AnyTimeInterrogation (opcode 71) - Critical: location/state query without subscriber consent
PSI          ProvideSubscriberInfo (opcode 70) - High: retrieves subscriber location, state
SAI          SendAuthenticationInfo (opcode 56) - Critical: auth vector harvesting
CL           CancelLocation (opcode 3)        - Critical: forces deregistration for call rerouting
ISD          InsertSubscriberData (opcode 7)  - High: profile manipulation
UL           UpdateLocation (opcode 2)        - High: fraudulent registration
SRI-SM       SendRoutingInfoForSM (opcode 45) - Medium: SMS routing, used for enumeration

Diameter Operations

AIR          Authentication-Information-Request (S6a) - Critical: auth vector harvest
ULR          Update-Location-Request (S6a)            - High: fraudulent location update
LIR          Location-Information-Request (SLh)        - Critical: HSS location query
SLR          Subscriber-Location-Report (SLh)          - High: location reporting
RAR          Re-Auth-Request (Gx, Sh)                 - Medium: policy change trigger

GTP-C v2 Operations

Create-Session-Req     - Critical if TEID=0x00000000 or from non-SGW IP
Modify-Bearer-Req      - High: session parameter manipulation
Delete-Session-Req     - Medium: session termination abuse
Create-Bearer-Req      - High: dedicated bearer hijacking

SIP Operations

REGISTER      - High: rogue registration for call interception
INVITE        - Medium: unsolicited session initiation
REFER         - High: call transfer relay for interception
SUBSCRIBE     - Medium: presence/location subscription abuse

GSMA FS.11 Category Reference

SignalsGuard automatically classifies events against GSMA FS.11 categories. Supply gsma_category in your events to override auto-classification.

Category	Name	Typical Operations
A.1	Active Interception	SRI, PRN, MAP-SRI, SLh-LIR
A.2	Subscriber Data Harvesting	ATI, SAI, PSI, Diameter-AIR
A.3	Traffic Manipulation	CL, ISD, SIP-REFER, SIP-REGISTER
A.4	Data Path Interference	GTP-C Create-Session, Modify-Bearer
B.1	Subscriber Profile Manipulation	ISD, MAP-InsertSubscriberData
B.2	Mobility Manipulation	UL, MAP-UpdateLocation
B.3	Network Abuse	SRI-SM, MAP-SRI-for-SM
C.1	Network Integrity	Policy violations, firewall bypass

Ericsson Probe Integration

For Ericsson STP (Signal Transfer Point) and MSC-S, configure your SNMP or proprietary probe export to generate a JSON event per detected operation and forward to SignalsGuard via the ingest endpoint.

Ericsson STP CEX export mapping

STP CEX field         -> SignalsGuard field
OpCode                -> operation (use MAP opcode name e.g. "SRI", "ATI")
OriginatingGT         -> source_operator (use GT prefix for operator lookup)
OriginatingCountry    -> source_country
Timestamp             -> event_time
ActionTaken           -> status (block->"blocked", alert->"alerted", pass->"monitored")
ThreatCategory        -> gsma_category (if your STP supports GSMA categorisation)

Tip: Ericsson STP can be configured to call an HTTP webhook on each threat action. Point the webhook URL at /api/ingest/metadata with the X-API-Key header and a JSON adapter script on the STP node to map fields.

Nokia / Alcatel-Lucent Integration

Nokia SGSN-MME, Nokia 7750 SR, and Alcatel Signalling Gateway can export CDRs or SNMP traps. Use the Nokia NetAct northbound interface or a middleware adapter to convert Nokia signalling events to the SignalsGuard JSON schema.

# Example: Nokia SignallingGuard (NSG) syslog to SignalsGuard adapter
# Each NSG syslog line (RFC 5424 format) is parsed and forwarded:

nokia_op_map = {
  "OPCODE_SRI":  {"operation": "SRI",  "protocol": "SS7", "gsma_category": "A.1"},
  "OPCODE_ATI":  {"operation": "ATI",  "protocol": "SS7", "gsma_category": "A.2"},
  "OPCODE_ISD":  {"operation": "ISD",  "protocol": "SS7", "gsma_category": "B.1"},
  "DIAMETER_AIR":{"operation": "AIR",  "protocol": "Diameter", "gsma_category": "A.2"},
}

Huawei Integration

Huawei STP, USN9810 MSC, and GBSS can export to syslog or via the CORBA/REST northbound interface of the eSight NMS. Map the MSISDN-free signalling fields to the SignalsGuard schema:

Huawei field        -> SignalsGuard field
signalType          -> operation
networkElement      -> source_operator
callingPartyCountry -> source_country
eventTime           -> event_time
alarmLevel          -> severity (critical=4, major=3, minor=2, warning=1)

eSight webhook: Configure eSight REST northbound to POST to a local adapter running on the Huawei NMS server, which translates to the SignalsGuard JSON format and forwards via HTTPS.

Generic / PCAP Integration

If your network uses vendor-agnostic SS7 probes, network taps, or PCAP capture, you can process signalling traffic with open-source tools and forward to SignalsGuard:

Using tshark (Wireshark CLI)

# Extract SS7 MAP operations from PCAP and POST to SignalsGuard
tshark -r capture.pcap -Y "gsm_map" \
  -T fields -e frame.time -e gsm_map.opr.code -e e164.number \
  | python3 sg_adapter.py --api-key sgk_YOUR_KEY

Using SigPloit / Diameter framework

# Any framework generating MAP/Diameter events can POST JSON events
# to /api/ingest/metadata with the X-API-Key header.
# See Quickstart above for the minimum required fields.

Rate limit: The ingest endpoint accepts up to 1,000 events per request. Batch events where possible rather than one HTTP call per event.

Platform API — Events

GET/api/events

Retrieve signalling events for your tenant. Supports filtering by protocol, severity, time range.

GET/api/reputation?days=30&operator=MegaFon

Reputation scoring for source operators. Returns grade A-F based on event history.

GET/api/campaigns?range=90

Campaigns active in the last range days (default 90): attack chains SignalsGuard detected automatically (kind: "detected", with chain_type, source, confidence and event IDs) and events sharing a client-supplied campaign ID (kind: "tagged").

Platform API — Compliance Report

GET/api/compliance/report?days=30

Generate a multi-regulatory compliance report. Automatically scoped to your registered jurisdiction (UK Telecoms Security Regulations for UK operators, EU NIS2 for EU, FCC/CSRIC for USA). Returns executive summary, regulatory matrix, and Chart.js-ready data.

POST/api/advisory/report

Generate an AI-powered threat intelligence brief. Returns attack chain narratives, threat actor assessment, GSMA regulatory mapping, and technical recommendations.

Platform API — Webhooks

SignalsGuard can push alerts to your SIEM, SOC tooling, or incident management system via HMAC-signed webhooks.

Configure a webhook

POST /api/webhooks
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "url": "https://your-soc.example.com/signalsguard-alerts",
  "secret": "your-webhook-signing-secret"
}

Webhook payload

{
  "event_id": "evt_abc123",
  "severity": "critical",
  "operation": "ATI",
  "protocol": "SS7",
  "gsma_category": "A.2",
  "source_country": "RU",
  "source_operator": "RU mobile GT range",
  "detected_at": "2026-09-07T10:23:00Z",
  "summary": "ATI from non-partner GT targeting HLR"
}

Verify webhook signature

# Python example
import hmac, hashlib

def verify(payload_bytes, secret, header_sig):
    expected = "sha256=" + hmac.new(
        secret.encode(), payload_bytes, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header_sig)

# The signature is in the X-SignalsGuard-Signature header

CSV Bulk Import

The CSV import endpoint allows you to upload signalling event exports from your existing firewall or probe platform — no live integration required. This is the recommended starting point for operators evaluating SignalsGuard or running a PoC.

Supported sources: Mobileum NTAS, Evolved Intelligence Connectis, Route Mobile STP exports, Tata Communications firewalls, Huawei eSight CSV exports, and any signalling probe that can export to CSV/TSV format.

POST /api/ingest/csv

Upload a CSV file of signalling events. Accepts multipart/form-data with field name file. Max file size 5 MB (~50,000 events).

Request format

POST /api/ingest/csv
Authorization: Bearer YOUR_TOKEN
Content-Type: multipart/form-data

# Field: file (CSV file)

CSV column reference

Column	Required	Description
event_time	Required	ISO 8601 timestamp. Also accepts: `timestamp`, `time` column aliases.
protocol	Required	SS7, Diameter, GTP-C, SIP, GTP-U, M3UA. Also accepts: `proto`.
operation	Required	Message type: MAP-ATI, MAP-SRI, MAP-ISD, MAP-UL, MAP-SAI, S6a-AIR, Create-Session-Req etc. Also accepts: `op`, `message_type`.
severity	Optional	critical, high, medium, low, info. Defaults to medium.
status	Optional	blocked, alerted, allowed, detected. Defaults to detected.
gsma_category	Optional	Ignored — assigned by SignalsGuard from the operation.
source_country	Optional	ISO 3166-1 alpha-2 country code. Also accepts: `country`.
source_operator	Optional	Source operator or network name. Also accepts: `operator`.
confidence	Optional	Integer 0–100. Detection confidence score.
campaign_id	Optional	Your internal correlation ID to group related events into attack chains. Also accepts: `campaign`.
summary	Optional	Free-text event description. Also accepts: `description`, `notes`.

Example CSV

event_time,protocol,operation,severity,status,source_country,source_operator,confidence,campaign_id,summary
2026-09-01T09:14:00Z,SS7,MAP-ATI,critical,blocked,RU,RU transit GT range,94,camp_ru_sweep_01,ATI from RU GT targeting UK HLR - bulk location sweep
2026-09-01T09:15:22Z,SS7,MAP-ATI,critical,blocked,RU,RU transit GT range,92,camp_ru_sweep_01,ATI continuation - second MSISDN range
2026-09-01T11:03:00Z,SS7,MAP-ISD,critical,blocked,KP,North Korea Telecom,96,camp_kp_isd_01,ISD to VLR injecting CFU to rogue PSTN - interception attempt

Response

{
  "ok": true,
  "total_rows": 150,
  "inserted": 147,
  "skipped": 3,
  "errors": [
    "Row 12: unknown protocol SCTP",
    "Row 88: invalid event_time format"
  ]
}

curl example

curl -X POST https://api.signalsguard.com/api/ingest/csv \\
  -H "Authorization: Bearer $SG_TOKEN" \\
  -F "file=@/path/to/firewall-export.csv"

Tip: Include a campaign_id column to preserve your probe's correlation identifiers. SignalsGuard uses these to group correlated events into attack chain narratives in the Reports brief.

FAQ

Can I push events in batches?

Yes. The ingest endpoint accepts up to 1,000 events per request. Batch at 100-500 events every few seconds rather than per-event HTTP calls for best throughput.

What if I don't have gsma_category?

Leave it out. SignalsGuard auto-classifies based on operation type and protocol using the 30-pattern detection library. Supply it only if your probe already classifies events.

Can I test without a live network?

Yes. Push synthetic events to the ingest endpoint. A demo tenant with pre-loaded synthetic data is available — or request a free 5-day pilot to test with your own data.

How is my data isolated from other tenants?

All queries filter by tenant_id at the database level. Your events are never returned to another tenant. API keys and JWT tokens are scoped to your tenant exclusively.

What TLS version is required?

TLS 1.2 or higher. We recommend TLS 1.3. The API endpoint is HTTPS-only. HTTP requests are rejected.