5G-SHIELD

Service API Security Testing Platform for free5GC Service-Based Interface (SBI) environments.

5G-SHIELD is a backend-first security testing platform that discovers reachable Network Functions (NFs), runs active API attack simulations, stores normalized findings, and streams live telemetry to a React dashboard.

Table of Contents

• Overview
• Core Features
• Architecture
• Repository Structure
• Prerequisites
• Quick Start (Docker)
• Local Development Setup
• API Reference
• WebSocket Stream
• Data Storage
• Security and Responsible Use
• Troubleshooting

Overview

5G-SHIELD helps security engineers and researchers validate API security posture across 5G core services by combining:

• NF discovery and health checks
• Active attack modules (JWT, BOLA, injection, SUPI manipulation, NRF spoofing)
• Severity-based finding normalization
• Persistent scan/findings history
• Real-time request and finding telemetry for UI observability

Core Features

• Config-driven target model from config.yaml
• Async HTTP engine using shared httpx client with HTTP/2 enabled
• FastAPI backend with background scan jobs
• TinyDB persistence for findings and scan history
• WebSocket fanout for live attack logs
• React dashboard for scanner controls, findings triage, and NF status

Architecture

Runtime layers:

• Transport: backend/core/http_client.py
• Scanner and attack orchestration: backend/core/scanner.py, backend/attacks
• Reporting and severity policy: backend/core/reporter.py
• Storage: backend/db/database.py
• API and WebSocket: backend/api
• UI: frontend/src

Execution flow (API mode):

1. UI starts a scan via POST /scan/run
2. Backend validates NF reachability and endpoint targets
3. Selected attack modules execute asynchronously
4. Request and finding events stream to ws /ws/attack-log
5. Findings are normalized, classified, and persisted
6. UI polls scan status and renders live logs/findings

Repository Structure

5g-shield/
├── backend/                # FastAPI scanner/attack engine
├── frontend/               # React dashboard (Vite)
├── free5gc/                # free5GC deployment files
├── config.yaml             # NF targets and scanner settings
└── docker-compose.yml      # 5G-SHIELD frontend + backend services

Prerequisites

• Docker and Docker Compose
• Python 3.10+ (for local backend development)
• Node.js 18+ (for local frontend development)
• Running free5GC stack on Docker network free5gc_privnet

Quick Start (Docker)

1. Start free5GC

From free5GC directory:

cd free5gc
docker compose -f docker-compose.yaml up -d

2. Start 5G-SHIELD

From repository root:

docker compose up -d --build

3. Access services

• Frontend: http://localhost:5173
• Backend API: http://localhost:8001

4. Verify runtime

curl -s http://localhost:8001/nfs/status | python3 -m json.tool

5. Stop services

docker compose down

Local Development Setup

Backend

python -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt
python backend/main.py serve

CLI mode examples:

python backend/main.py scan --attack all
python backend/main.py scan --attack jwt_attacks
python backend/main.py clear

Frontend

cd frontend
npm install
npm run dev

API Reference

Base URL: http://localhost:8001

• GET /nfs/status
• GET /findings
• GET /findings/{finding_id}
• DELETE /findings/{finding_id}
• DELETE /findings
• POST /scan/run?attack={all|nrf_spoofing|jwt_attacks|bola|injection|supi_manipulation}
• GET /scan/status/{scan_id}
• GET /scan/history

WebSocket Stream

Endpoint: ws://localhost:8001/ws/attack-log

Event types:

• request_log
• finding

This stream supports multi-client fanout for live scanner telemetry.

Data Storage

TinyDB files:

• backend/db/findings.json
• backend/db/scans.json

Security and Responsible Use

This platform performs active security testing techniques and should be used only on systems you own or are explicitly authorized to test.

Troubleshooting

• Services marked down in dashboard: Ensure config.yaml targets resolve on free5gc_privnet (service names are recommended over fixed IPs).
• WebSocket log not updating: Confirm backend container includes uvicorn standard extras and /ws/attack-log is reachable.
• Docker image pull failures: Verify DNS/network access from Docker daemon.
• Frontend branding not updating: Rebuild frontend image and hard-refresh browser cache.