Qbm-AI-in-Marin-port-Security-for-Spoofing

AI-Driven Maritime Blockchain Framework Overview

This repository presents an AI-driven maritime blockchain framework designed to analyze, validate, and secure AIS-based maritime traffic data. The primary goal of this research is to detect anomalous vessel behaviors from raw AIS time-series data and to record only AI-validated state transitions in a blockchain-inspired verification layer.

Unlike conventional approaches that treat blockchain as a passive data storage mechanism, this work explicitly models blockchain as a consensus layer driven by AI-derived trust and anomaly evidence. The system is intended for research in maritime security, anomaly detection, data provenance, and trustworthy cyber-physical systems.

Research Motivation

Maritime AIS data is vulnerable to noise, spoofing, missing signals, and intentional manipulation. Simply storing raw AIS messages on-chain does not guarantee trustworthiness.

This research addresses the problem by introducing:

Behavior-aware AI models that interpret vessel dynamics over time

Explicitly engineered maritime anomaly features, rather than generic sequence embeddings

A verification-first blockchain architecture, where only validated behavioral transitions are committed

The resulting framework enables tamper-resistant, auditable, and explainable maritime event tracking.

How to Run

1. Environment Setup

Python 3.9 or later is recommended.

conda create -n maritime-ai python=3.9 conda activate maritime-ai pip install -r requirements.txt

2. Data Preparation

Place raw AIS data in the following directory:

data/raw/

Run the preprocessing and feature extraction pipeline:

python prepare_data.py

This step converts raw AIS messages into windowed time-series feature datasets stored in:

data/processed/

Note: This process may take several hours depending on dataset size.

3. Model Training

Train the anomaly detection model:

python train.py

Model checkpoints and logs will be saved automatically.

4. Evaluation and Analysis

Run evaluation scripts to generate metrics and visual outputs:

python evaluate.py

Results will be stored in:

results/

Benchmark Matrix (S0S3 x A0A5)

This repository now supports reproducible matrix execution aligned with the AIS threat-model extension.

Primary matrix:

• Architecture scenarios: S0,S1,S2,S3
• Attacks (default): A0,A1,A2,A3,A4,A5
  • Optional near-replay: add A4P to benchmark.attacks in configs/default.yaml
• Default verifier per scenario:
  • S0 -> none
  • S1 -> none
  • S2 -> s2_strict
  • S3 -> s3_mev

Run:

python -m experiments.run_benchmark_matrix --config configs/default.yaml --max-windows 300

Optional S3 verifier ablation (s3_mev,qbm,strongq):

python -m experiments.run_benchmark_matrix --config configs/default.yaml --max-windows 300 --include-s3-ablation

Output:

• Per-run simulation CSV/JSON in results/tables/
• Consolidated matrix summary in results/tables/benchmark_matrix.csv
• S1 replay vulnerability table/figure:
  • results/tables/s1_replay_vulnerability.csv
  • results/figures/s1_replay_ftr.png
• A4 verifier contrast table/figure:
  • results/tables/a4_verifier_contrast.csv
  • results/figures/a4_verifier_ftr_asr.png
    (requires --include-s3-ablation to compare s3_mev vs qbm vs strongq)

StrongQ Shot Stability

Run shot-count sweep for StrongQ verification:

python -m experiments.strongq_shot_stability --config configs/default.yaml --scenario S3 --attack-id A4 --max-windows 120

Output:

• results/tables/strongq_shot_stability.csv
• results/figures/strongq_shot_stability.png

S3 Threshold Sensitivity

Run 3 profile sweep for S3 thresholds (epsilon, theta):

python -m experiments.s3_threshold_sensitivity --config configs/default.yaml --attack-id A5 --max-windows 120

Output:

• results/tables/s3_threshold_sensitivity.csv
• results/figures/s3_threshold_sensitivity.png
• results/figures/s3_threshold_sensitivity_asr.png
• results/figures/s3_threshold_sensitivity_ftr.png
• results/figures/s3_threshold_sensitivity_dropped_by_verification.png
• results/tables/meta_s3_threshold_<profile>.json

Node Count Sweep (3 vs 5)

Run S0,S2,S3 with A2,A5 under node count 5:

python -m experiments.node_count_sweep --config configs/default.yaml --node-counts 5 --scenarios S0,S2,S3 --attacks A2,A5 --max-windows 120

Output:

• results/tables/node_count_sweep.csv
• results/figures/node_count_sweep_asr.png
• results/figures/node_count_sweep_ftr.png
• results/figures/node_count_sweep_dropped_by_verification.png
• results/tables/meta_node_count_<scenario>_<attack>_n<node_count>.json

Research Status

This repository is an active research codebase. Interfaces, features, and model configurations may change as experiments evolve.

The code is not intended for production deployment without further validation.

Canonical Verifier Path

The authoritative S3 verifier implementation is:

qbm/verifiers/s3_mev.py

Do not use or publish standalone/root-level copies such as s3_mev.py.
If a legacy single-file copy exists in local workspaces, treat it as deprecated and exclude it from artifact release.

Attack ID Semantics (A4 vs A4P)

• A4 (time-shifted replay, replay-evasion baseline / hard-case):
  • Reuses previously committed evidence while rebinding event_id/window_id/timestamp/node_id to evade simple replay identifiers.
  • Paper positioning: keep A4 as the replay-evasion baseline / hard-case. In many runs it is already blocked by classical gates (little room for StrongQ to flip), which is fine and should be reported explicitly.
• A4P (near-replay, uncertainty regime representative):
  • Starts from the same time-shifted replay mechanism as A4, then applies partial perturbations (top-k mutation, confidence/uncertainty jitter, partial context drift).
  • Paper positioning: treat A4P as the “uncertainty regime” where samples cluster near tau (gray-zone), so StrongQ can be meaningfully called and produce observable veto flips.

Implementation reference:

• qbm/attacks.py

Config reference:

• configs/default.yaml -> experiments.A4
• configs/default.yaml -> experiments.A4P

S3 Config Parameters (Status)

The following S3 options in configs/default.yaml are active in runtime code paths (qbm/train.py + qbm/verifiers/s3_mev.py):

• Core gate: s3_soft_tau, s3_soft_gray_margin
• Tau calibration: s3_auto_tau_from_a0, s3_tau_freeze_after_calibration, s3_tau_calibration_windows, s3_tau_quantile, s3_tau_min_samples
• Gray margin calibration: s3_auto_gray_margin_from_a0, s3_target_gray_rate_a0, s3_gray_margin_min, s3_gray_margin_max
• Gray-zone policy: s3_grayzone_use_strongq, s3_grayzone_requires_policy_hint, s3_grayzone_no_policy_action
• StrongQ mode/risk: s3_strongq_mode, s3_risk_policy_ratio_floor, s3_risk_context_floor, s3_risk_explanation_floor, s3_risk_tau_band
• StrongQ threshold calibration: s3_auto_strongq_threshold, s3_strongq_threshold_quantile, s3_strongq_threshold_min_samples

Release Packaging Hygiene

For code release bundles, keep runtime artifacts separate from source:

• Exclude cache files: __pycache__/, *.pyc
• Exclude generated outputs from code archive: results/tables/, results/figures/
• Publish generated metrics/figures as a separate artifact archive if needed for reproducibility

License & Copyright

© UCS LAB. All rights reserved.

This code and associated research materials are the intellectual property of UCS LAB. Unauthorized copying, redistribution, or commercial use without explicit permission is prohibited.

For academic or collaborative inquiries, please contact the authors through UCS LAB.

Citation

If you use this code in academic work, please cite the corresponding paper (to be updated).