Skip to content

Home

Jump to bottom
Dhafa Nazula Permadi edited this page Aug 25, 2025 · 1 revision

Home

Welcome to UmurSS7PCode — an educational SS7 network simulation and SMS forwarding platform. This wiki helps you install, explore, customize, and contribute safely and ethically.

Important: UmurSS7PCode is for education only. It does not access or interact with real telecom networks.

Highlights

  • Interactive 3D network topology (React + Three.js) with MSC, HLR, VLR, SMSC, STP nodes

  • Step‑by‑step SMS flow simulation with protocol callouts (MAP, SCCP, TCAP, MTP)

  • Security awareness modules (known SS7 issues, mitigations, ethics)

  • Modern UI (React, TypeScript, Tailwind, Framer Motion)

Quick Links

Screens & Modules

  • Topology — Explore nodes, links, and live path highlighting.

  • SMS Simulation — Play/pause the route, inspect each step, follow message paths.

  • Security — Learn typical vulnerabilities and mitigation principles.

Licensing

This project is released under the MIT License. See LICENSE in the repo.

Getting-Started

Prerequisites

  • Node.js ≥ 18

  • npm or yarn

  • A WebGL‑capable browser

Installation

# 1) Clone
git clone https://github.com/kangpcode/UmurSS7PCode.git
cd UmurSS7PCode

2) Install deps


npm install


3) Run dev server


npm run dev


open http://localhost:5173



(optional) Build & preview


npm run build
npm run preview

First Run Checklist

  • You see a 3D topology view with labeled nodes

  • Side panel shows node details when a node is clicked

  • SMS Simulation tab can play/pause and step through stages

Architecture

High-Level Overview

graph TD
  A[UI Layer (React + Tailwind)] --> B[3D Layer (react-three-fiber + drei + three.js)]
  A --> C[State & Logic (TypeScript)]
  C --> D[Simulation Engine]
  D --> E[Data Models (Nodes, Links, Steps)]
  C --> F[Security Awareness Content]

Core Packages

  • React (UI), TypeScript (types & safety), Vite (bundler)

  • tailwindcss (styling), framer-motion (micro‑interactions)

  • three.js, @react-three/fiber, @react-three/drei (3D topology)

  • lucide-react (icons)

Key Source Files (suggested)

  • src/components/NetworkVisualization.tsx — 3D scene, nodes, edges

  • src/components/SMSFlowSimulator.tsx — step engine, controls

  • src/data/networkComponents.ts — default nodes & connections

  • src/data/smsFlow.ts — default SMS routing steps & annotations

  • src/pages/* — Topology, Simulation, Security views

  • src/hooks/* — camera, selection, highlighting

  • src/styles/* — additional utilities

Data Model (suggested types)

export type NodeType = 'MSC'|'HLR'|'VLR'|'SMSC'|'STP';
export interface NetNode { id:string; type:NodeType; label:string; pos:[number,number,number]; meta?:Record<string,any>; }
export interface NetLink { id:string; from:string; to:string; protocol:'MTP'|'SCCP'|'TCAP'|'MAP'; bidirectional?:boolean; }
export interface Step { id:string; label:string; from:string; to:string; protocol:NetLink['protocol']; description:string; }

Simulation-Scenarios

Default: Mobile‑originated SMS (MO‑SMS)

sequenceDiagram
  participant MS as Mobile Station
  participant MSC
  participant VLR
  participant HLR
  participant SMSC
  participant STP

MS->>MSC: SMS SUBMIT (MAP)
MSC->>VLR: Auth/Check (MAP)
MSC->>HLR: Query routing (MAP/SendRoutingInfo)
HLR-->>MSC: IMSI/MSRN/SM routing info
MSC->>SMSC: Forward to SMSC (MAP/MT-ForwardSM)
SMSC-->>MSC: Acknowledge
MSC-->>MS: Delivery report

Other Scenarios (placeholders)

  • Mobile‑terminated SMS (MT‑SMS)

  • Roaming subscriber SMS

  • Congestion & retry demo

  • Basic failure injection (e.g., HLR timeout)

Each scenario is a Step[] with metadata to render tooltips and highlight active paths.

Security-and-Ethics

Scope

This project explains why SS7 weaknesses matter and how to defend—not how to attack.

Topics Covered

  • Typical SS7 issues (signaling trust, location tracking, SMS interception at conceptual level)

  • Defense patterns (firewalls, anomaly detection, signaling policy, 2FA out‑of‑band)

  • Ethical use & compliance reminders

Do: learn architecture and mitigations. Don’t: test on live networks or attempt unauthorized access.

Customization

Change Nodes & Layout

  • Edit src/data/networkComponents.ts (labels, types, positions)

  • Adjust layout algorithm or hardcode coordinates for symmetric scenes

Change SMS Steps

  • Edit src/data/smsFlow.ts (sequence, descriptions, protocols)

Styling

  • Tailwind utility classes in components

  • Add themes via CSS variables (light/dark)

3D Tuning

  • Node geometry/materials

  • Edge thickness and pulsing animation during active steps

Configuration

Create .env at repo root:

VITE_APP_TITLE=UmurSS7PCode
VITE_APP_VERSION=1.0.0

Optional flags you can add:

VITE_ENABLE_DEBUG_UI=true
VITE_DEFAULT_SCENARIO=mo_sms
VITE_CAMERA_PRESET=front_iso

Development

Scripts

npm run dev       # Vite dev server
npm run build     # production build
npm run preview   # serve dist/

Code Style

  • ESLint + TS rules enforced

  • Prefer function components & hooks

  • Strong typing for public interfaces

Testing (suggested)

  • Add component tests with Vitest/RTL

  • Snapshot test of scene graph for regression

Troubleshooting

Symptom Possible Cause Fix
Blank 3D canvas WebGL disabled Enable hardware acceleration; try another browser
Controls unresponsive Pointer lock not captured Click canvas once; check console
Build fails on CI Node < 18 or missing deps Use Node 18+; run npm ci
Layout looks skewed Camera/canvas resize Call invalidate() or ensure container size changes are handled

FAQ

Is this safe to run?
Yes. It’s a local, offline simulation with mock data only.

Does it emulate real SS7 traffic?
No. It visually demonstrates conceptual flows with annotated steps.

Can I add my telco’s topology?
Yes—edit data files and add custom nodes/links.

Why TypeScript?
Type safety for complex visualization state and props.

Roadmap

  • Additional scenarios (MT‑SMS, roaming)

  • Theming system & presets

  • Export/share scenario JSON

  • Accessibility audit (keyboard nav, ARIA)

  • i18n support

Glossary

  • SS7 — Signaling System No. 7, telecom signaling suite

  • MTP/SCCP/TCAP/MAP — Key protocol layers

  • MSC/HLR/VLR/SMSC/STP — Core network entities in GSM/SS7

References

  • GSM/SS7 protocol overviews (general)

  • Security best‑practice documents (general)

Contributing

See Development and open a Pull Request. Please keep contributions educat

Clone this wiki locally