DEMO_Android_JD

This is a DEMO on real-time jamming detection, based on Android logs. This demo implements the online detection workflow on Android UE-a submodule of SHIELD framework.

The following diagram shows the principal thread and object interactions:

Relevant publication:

[SHIELD: Scalable and Holistic Evaluation Framework for ML-Based 5G Jamming Detection.] J. Xu, A. Moheddine, V. Loscrì, A. Brighente, and M. Conti. In: Availability, Reliability and Security. ARES 2025. Lecture Notes in Computer Science, vol 15992. Springer, Cham. https://doi.org/10.1007/978-3-032-00624-0_12

Getting Started

Prerequisites

• adb in $PATH
• pyyaml
• onnxruntime (for ONNX models)
• pytorch (for legacy .pth models)
• scikit-learn
• numpy

Hardware

Usage

make run # python -m scripts.main [YOUR CONFIG FILE]

To test or to get a fast overview of the program, use the log replay feature to duplicate effects of our extracted logs:

make test # python -m scripts.main [YOUR CONFIG FILE] -r replay.log

Configuration

The project is configured via a yaml file. Below is a detailed explanation of each section.

logging

This section controls the application's logging behavior.

• level: Sets the minimum level of messages to be logged (e.g., DEBUG, INFO, WARNING, ERROR).

• format: Defines the structure of log messages using logging format strings.

• datefmt: Sets the date and time format for the logs.

io

Handles source of input data stream. In this project, we typically use ADB to extract logs from Android devices.

• cmd: The shell command to execute for capturing the data stream (e.g., from adb logcat).

• pattern: The regular expression used to parse each line of the input stream. It captures groups like timestamp, log source, and message.

• timefmt: The specific format of the timestamp captured by the pattern.

• replay_speed: A multiplier for replaying logged data. 2.0 means 200% speed. Only effective when replaying saved logs.

classifier

Defines the parameters for the machine learning model that classifies the data.

• model: Path to the pre-trained model. Supports both ONNX (.onnx) and legacy PyTorch (.pth) formats.

• scaler: Path to the scaler object used for data normalization (e.g., a .pkl file). Only required for legacy PyTorch models. ONNX models have the scaler integrated.

• input_size & output_size: Dimensions for the model's input and output layers (number of input features & label dimension).

• interval: The time interval in seconds at which the classifier runs.

• preprocessor: Specifies the steps for data preprocessing before it's fed to the model.

  • interpolate: Fills missing values and create smoother observations.

    • method: "linear", "polynomial", etc.
    • order: effective for "polynomial" method.
    • resample: sets the time frequency for the data points (e.g., '1s' for one second).

  • aggregate: Groups data over a time window.

    • n_steps: defines the window size. (Window size = n_steps * resample = 10 * 1s = 10s)
    • methods: lists the aggregation functions to apply (e.g., mean, std).

buffer

This is the core of the data extraction logic. It defines how to find, parse, and store different pieces of information from the raw log stream into structured buffers. This section needs adaptions for different Android devices.

• buffers: A list, where each item configures a separate data buffer.

  • name: A unique identifier for the buffer (e.g., ecsq, thermal).

  • selector: A simple string used to quickly filter relevant log lines before applying a more complex regex.

  • search / findall: Defines the regex strategy.

    search: Uses a pattern to find the first match in a line and extracts specific indexes from the captured groups.

    findall: Uses a pattern to find all matches in a line and extracts values associated with keys listed in indexes.

  • shape: Defines the dimensions [rows, columns] of the NumPy array used to store the data for this buffer. A bigger buffer yields more contextual information to classifier.

Model Specification

Inputs & Outputs

Input:

• Data Type: float32
• Shape: [batch_size, seq_len, 60]
  • batch_size: Number of samples (typically 1 for real-time inference)
  • seq_len: Sequence length, typically 10 time steps (10 seconds with 1s resampling)
  • 60: Number of features derived from 4 signal sources with 5 aggregation methods each
• Feature Composition:
  • ECSQ (Extended Cell Signal Quality): 6 features × 5 aggregations = 30 features
  • Thermal sensors: 2 features × 5 aggregations = 10 features
  • RF transmission power: 1 feature × 5 aggregations = 5 features
  • Signal strength (RSRP, RSRQ, SINR): 3 features × 5 aggregations = 15 features
• Aggregation Methods: mean, max, min, std, amplitude
• Preprocessing: RobustScaler normalization (integrated in ONNX models, separate for PyTorch models)

Output:

• Data Type: float32
• Shape: [batch_size, 1]
• Range: [0.0, 1.0] (probability score via sigmoid activation)
• Interpretation:
  • Score > 0.5: ANOMALY (potential jamming detected)
  • Score ≤ 0.5: NORMAL (no jamming detected)

Limitations

• Sequence Length: The model expects time series data with a minimum sequence length. Shorter sequences may produce unreliable results.
• Feature Count: Input must have exactly 60 features. Missing or extra features will cause inference to fail.
• Data Quality: The model assumes continuous data streams. Large gaps or missing data may affect accuracy.
• Domain Specificity: Trained on specific Android device logs (OnePlus Nord 2T). Performance may vary on different devices without retraining.
• Real-time Constraints: Inference interval (default 5s) must be longer than preprocessing + inference time to avoid queue buildup.
• Buffer Dependencies: Requires all 4 buffer types (ecsq, thermal, erftx, signal) to be populated for accurate predictions.

Model Execution

Using ONNX Runtime (Recommended)

1. Convert existing PyTorch models to ONNX:

python scripts/convert_to_onnx.py

This creates lstm_model.onnx files in models/r0/ and models/r1/ directories.

2. Update your config file:

classifier:
  model: "models/r0/lstm_model.onnx"
  # scaler not needed - integrated in ONNX model
  input_size: 60
  output_size: 1

3. Run inference:

import onnxruntime as ort
import numpy as np

# Load model
session = ort.InferenceSession("models/r0/lstm_model.onnx")

# Prepare input (example: batch=1, seq_len=10, features=60)
input_data = np.random.randn(1, 10, 60).astype(np.float32)

# Run inference
input_name = session.get_inputs()[0].name
output = session.run(None, {input_name: input_data})[0]

# Interpret result
probability = output[0][0]
prediction = "ANOMALY" if probability > 0.5 else "NORMAL"
print(f"Prediction: {prediction} (score: {probability:.4f})")

Using PyTorch (Legacy)

Load and run with PyTorch:

import torch
from models.lstm import LSTMModel

# Load model
model = LSTMModel(input_size=60, output_size=1)
model.load_model("models/r0/lstm_model.pth", scaler_path="models/r0/lstm_scaler.pkl")
model.eval()

# Prepare input
input_data = torch.randn(1, 10, 60)

# Run inference
with torch.no_grad():
    output = model(input_data)
    probability = output[0][0].item()
    prediction = "ANOMALY" if probability > 0.5 else "NORMAL"
    print(f"Prediction: {prediction} (score: {probability:.4f})")

Note: The system automatically detects the model format based on file extension (.onnx vs .pth) and uses the appropriate runtime.

Citation

@InProceedings{10.1007/978-3-032-00624-0_12,
author="Xu, Jiali, Moheddine, Aya, Loscr{\`i}, Val{\'e}ria, Brighente, Alessandro and Conti, Mauro",
title="SHIELD: Scalable and Holistic Evaluation Framework for ML-Based 5G Jamming Detection",
booktitle="Availability, Reliability and Security",
year="2025",
publisher="Springer Nature Switzerland",
address="Cham",
pages="235--256",
isbn="978-3-032-00624-0"
}

🇪🇺 Acknowledgments & Funding

This repository was developed by Inria as part of the MLSysOps project.

The MLSysOps consortium consists of 12 European partners across academia and industry, working together to optimize AI-driven operations in the Cloud-Edge Continuum.

This project has received funding from the European Union’s Horizon Europe research and innovation programme under grant agreement No. 101092912.