phishnano 0.1.0

Lightweight phishing URL detection library with embedded ML model
Documentation

phishnano

Lightweight phishing URL detection library with an embedded Random Forest model. Designed for integration into password managers, browser extensions, and security gateways where local, privacy-preserving inference is required.

Features

  • Embedded model: Zero configuration, the bincode model is compiled into the library via include_bytes!
  • Compact: ~110 KB embedded model, no external files needed
  • Fast inference: ~20 microseconds per URL
  • Zero network dependency: Fully local inference, no API calls
  • Cross-platform: Windows / macOS / Linux

Quick Start

Add to your Cargo.toml:

[dependencies]
phishnano = "0.1"

use phishnano::{load_default_model, predict_url};

fn main() -> anyhow::Result<()> {
    let model = load_default_model()?;
    let score = predict_url("http://suspicious-url.com", &model);

    if score >= 0.45 {
        println!("Warning: potential phishing site (score={:.4})", score);
    } else {
        println!("Safe (score={:.4})", score);
    }
    Ok(())
}

Performance

Metric Value
Accuracy 95%
Phishing precision 97%
Phishing recall 93%
Normal precision 93%
Normal recall 97%
AUC-ROC 0.9907
Model size (embedded) ~110 KB (bincode)
Inference latency ~20 us
Default threshold 0.45

CLI Tool

# Install
cargo install phishnano-cli

# Classify a URL (uses the embedded model, no external files needed)
phishnano-cli "http://example.com"

# With a custom threshold
phishnano-cli "http://example.com" --threshold 0.60

# Load a custom model file instead of the embedded one
phishnano-cli "http://example.com" --model my_model.bincode

# Convert a JSON model to bincode
phishnano-cli --convert model_data.json model_data.bincode

Project Structure

phishnano/
|-- Cargo.toml                # Library crate + workspace root
|-- src/                      # Library source code
|   |-- lib.rs
|   |-- model.rs              # Model struct, load_default_model(), include_bytes!
|   |-- extractor.rs          # Feature extraction (n-gram + manual)
|   `-- predictor.rs          # Random forest prediction
|-- resources/                # Model files
|   |-- model_data.bincode    # Embedded bincode model (~110 KB)
|   |-- model_data.json       # JSON model for debugging
|   `-- test_features.json    # Cross-language test data
|-- phishnano-cli/            # CLI binary crate (workspace member)
|   |-- Cargo.toml
|   `-- src/
|       `-- main.rs
|-- training/                 # Training scripts (not published to crates.io)
|   |-- data/                 # Training datasets (gitignored)
|   `-- scripts/              # Python training scripts
|       |-- train.py
|       |-- export.py
|       |-- threshold_analysis.py
|       |-- model_analysis.py
|       |-- download_phreshphish.py
|       |-- requirements.txt
|       `-- README.md
|-- .github/
|   `-- workflows/
|       |-- ci.yml            # CI: build + test + clippy + fmt
|       `-- publish.yml       # CD: publish to crates.io on tag push
|-- .gitignore
|-- LICENSE
`-- README.md

Training

The model is pre-trained and embedded in the library. Training data and scripts are maintained in a separate repository and are not included in this crate.

Model Architecture

phishnano uses a Random Forest classifier with 25 decision trees (max depth 7) trained on 410,000+ labeled URLs.

Feature extraction

Each URL is converted to a 519-dimensional feature vector:

  • 500 n-gram features: Character 2-grams and 3-grams, hashed into 500 buckets using MurmurHash3 (unsigned, seed=0)
  • 19 manual features: URL length, domain length, special character counts, digit ratio, path/query length, TLD code, sensitive word detection, etc.

Hyperparameters

Parameter Value
n_estimators 25
max_depth 7
min_samples_split 10
class_weight {0: 1, 1: 2.0}
random_state 42
test_size 0.2 (stratified)

Training data sources

The model is trained on ~496,000 labeled URLs (after deduplication) drawn from public phishing feeds (PhishTank, OpenPhish, Kaggle), legitimate URL rankings (Tranco, Majestic, US federal .gov domains), and the PhreshPhish dataset (HuggingFace).

CI/CD

  • CI (.github/workflows/ci.yml): Builds and tests on push/PR across Ubuntu, Windows, and macOS. Runs cargo fmt --check, cargo clippy -- -D warnings, cargo build --release --all, and cargo test --all.
  • Publish (.github/workflows/publish.yml): Publishes both phishnano (library) and phishnano-cli to crates.io when a version tag (v*) is pushed. Requires the CARGO_REGISTRY_TOKEN repository secret.

License

MIT