@flwrlabs/fed-phish-guard

10
3
flwr new @flwrlabs/fed-phish-guard

Federated Phishing URL Detection with Flower and PyTorch

This project implements federated learning for phishing URL detection using Flower and PyTorch.

It combines:

  • A CNN-based text model for URL classification
  • Byte-level encoding of URLs
  • Federated training across distributed clients
  • Support for both simulation and deployment modes

The system is designed to handle imbalanced data and realistic client-level data partitioning.

Fetch the App

Install Flower:

pip install flwr

Fetch the app:

flwr new @flwrlabs/fed-phish-guard

Then, install dependencies:

cd fed-phish-guard && pip install -e .

Project structure:

fed-phish-guard
├── phishguard
│   ├── __init__.py
│   ├── client_app.py   # Client-side training logic
│   ├── server_app.py   # Server-side orchestration and evaluation
│   ├── model.py        # CNN model for URL classification
│   ├── train.py        # Training and evaluation loops
│   └── data.py         # Data loading and preprocessing
├── pyproject.toml

Run the App

This Flower App supports both simulation and deployment workflows.

Run with the Simulation Engine

In simulation mode:

  • Dataset is automatically loaded from Hugging Face (flwrlabs/fed-phishing-urls)
  • Data is partitioned naturally by client_id

Run with default settings:

flwr run .

Override configuration:

flwr run . --run-config "num-server-rounds=10 batch-size=64"

Key configuration options (from pyproject.toml):

  • seed: base random seed for deterministic server and client execution (default: 42)
  • num-server-rounds: number of FL rounds
  • local-epochs: local training epochs
  • batch-size: batch size
  • embed-dim: embedding size
  • num-filters: CNN filters
  • dropout: dropout rate
  • learning-rate-max/min: cosine annealing schedule
  • fraction-train: fraction of clients participating per round

For a reproducible run with a different seed:

PYTHONHASHSEED=2026 flwr run . --run-config "seed=2026"

The server uses the base seed, while each client round receives a stable seed derived from the base seed, client partition, and server round. Deterministic PyTorch kernels are required; the run fails instead of silently using a known nondeterministic kernel. Exact replay also requires the same data, participating clients, dependency versions, hardware, and runtime configuration.

The seed must be an integer between 0 and 4294967295. The run seed controls model initialization, training randomness, and client sampling. Dataset partitioning keeps its existing fixed seed so seed sweeps compare the same client data. Sampling and aggregation use sorted Flower node IDs, so exact replay requires the same node-ID-to-partition mapping and client availability. For local data, the client seed uses partition-id when provided, otherwise data-path; give clients distinct stable identities to obtain distinct streams. Set PYTHONHASHSEED before starting the ServerApp and ClientApp runtimes (including remote workers), since setting it in an already running interpreter has no effect on that interpreter's hash seed. Timing and memory metrics are not deterministic.

Model

The model is a CNN-based architecture for URL classification:

  • Input: byte-level encoded URLs
  • Embedding layer for byte tokens
  • Parallel multi-scale convolutions (kernel sizes 3, 5, 7)
  • Stacked convolutional blocks with pooling
  • Global max pooling
  • Fully connected classifier

Data Pipeline

Dataset:

  • Hugging Face: flwrlabs/fed-phishing-urls

Processing steps:

  1. Convert URLs → byte sequences
  2. Map bytes to indices (vocabulary size = 258)
  3. Pad/truncate to fixed length (default: 256)
  4. Create PyTorch datasets

Supports:

  • Simulation mode → federated partitions via FederatedDataset
  • Deployment mode → load local datasets from disk

Class imbalance handling:

  • Weighted sampling per client
  • Positive class weighting for loss

Training

Each client:

  • Receives global model weights

  • Trains locally using:

    • BCEWithLogitsLoss
    • Gradient clipping
    • AdamW optimizer

  • Applies cosine annealing learning rate

Training loop defined in:

After each round, clients return:

  • Updated model weights
  • Aggregated training metrics (loss, accuracy, F1)

Evaluation

Server-side evaluation:

  • Uses centralized test split

  • Reports:

    • Loss
    • Accuracy
    • Precision
    • Recall
    • F1-score
    • ROC-AUC

Run with the Deployment Engine

To run in deployment mode:

Step 1: Prepare local datasets

Prepare datasets in Hugging Face format (Dataset or DatasetDict with train split).

Step 2: Start SuperNodes

flower-supernode \
    --insecure \
    --superlink <SUPERLINK-FLEET-API> \
    --node-config="data-path=/path/to/local_dataset"

Step 3: Run federation

flwr run . <SUPERLINK-CONNECTION> --stream

Benchmarking and System Metrics

This app writes a benchmark summary next to the standard Flower result pickle:

result_<run-name>_communication.json

The summary includes per-round and total communication volume:

  • total_comm_bytes
  • comm_bytes_total per training round

Enable system metric tracking with:

flwr run . <SUPERLINK-CONNECTION> --stream --run-config "benchmark-system-metrics=true"

When enabled, the benchmark summary also includes:

  • client_train_time_sec
  • server_aggregation_time_sec
  • round_wall_clock_sec
  • client_peak_cpu_memory_mb
  • client_peak_gpu_memory_mb

Server-side centralized evaluation can be disabled for benchmark-only runs:

flwr run . <SUPERLINK-CONNECTION> --stream --run-config "benchmark-run-server-eval=false"

Dataset Fingerprint Verification

FedPhishGuard supports a preflight dataset fingerprint check before training. Enable it with:

flwr run . <SUPERLINK-CONNECTION> --stream --run-config "benchmark-verify-dataset=true"

The server asks each connected client for its partition metadata, then verifies the connected clients against the benchmark manifest. The verification result is written into result_<run-name>_communication.json under verification. If any partition does not match, the run fails before training.

Notes

  • Designed for cybersecurity / phishing detection tasks
  • Uses byte-level encoding to handle arbitrary URLs
  • Handles class imbalance via sampling and loss weighting
  • Automatically uses GPU if available
  • Efficient for variable-length text inputs