Final model card: full install guide, usage, features, limitations, troubleshooting

d2e6aef verified 1 day ago

10.6 kB

language:
  - en
license: mit
library_name: phishbyte
pipeline_tag: text-classification
tags:
  - phishing-detection
  - email-security
  - cybersecurity
  - security
  - pytorch
  - from-scratch
  - no-pretrained-weights
  - cascading-inference
  - lightweight
  - explainable-ai
  - nlp
  - phishing
  - spam-detection
  - malware-detection
  - threat-detection
  - email-classification
  - text-classification
  - feature-engineering
  - interpretable-ml
  - tfidf
  - residual-network
datasets:
  - ceas-2008
  - enron-email
  - spamassassin
  - ling-spam
  - nazario-phishing
  - nigerian-fraud
metrics:
  - f1
  - precision
  - recall
  - accuracy
model-index:
  - name: phishbyte
    results:
      - task:
          type: text-classification
          name: Phishing Email Detection
        dataset:
          name: >-
            6-corpus benchmark (CEAS, Enron, SpamAssassin, Ling-Spam, Nazario,
            Nigerian)
          type: ceas-2008
        metrics:
          - type: f1
            value: 0.9503
            name: F1 Score
          - type: accuracy
            value: 0.9494
            name: Accuracy
          - type: precision
            value: 0.949
            name: Precision
          - type: recall
            value: 0.9516
            name: Recall
widget:
  - text: >-
      From: PayPal Security <security@paypa1-alert.tk>

      Reply-To: attacker@evil-domain.ru

      Subject: URGENT: Your account will be suspended


      Dear Customer, your PayPal account has been suspended. Verify now at
      http://paypal-login.tk/verify
    example_title: Phishing email example
  - text: |-
      From: alice@company.com
      Reply-To: alice@company.com
      Subject: Team lunch tomorrow

      Hi everyone, lunch is at noon in the usual spot. See you there!
    example_title: Legitimate email example

Phish_Byte v7

A from-scratch PyTorch model for email phishing detection — no pretrained weights, no transformers, no fine-tuning.

F1 0.950 · 254K parameters (260× smaller than DistilBERT) · 995 emails/sec on a laptop GPU · 85 engineered features · every verdict explains itself.

What makes this different

Every other phishing detection model on HuggingFace fine-tunes a transformer (DistilBERT, BERT, RoBERTa). Phish_Byte is the only one built from scratch:

	Phish_Byte v7	DistilBERT fine-tuned
F1 score	0.950	~0.967
Parameters	254K	66,000,000
Model size	~1 MB	~263 MB
Throughput (GPU)	995/sec	~50/sec
GPU required	No	Practically yes
Header + SPF analysis	Yes	No
Explainability	85 features	Token-level SHAP
Pretrained weights	None	DistilBERT

The F1 gap is ~1.7 points. The size and throughput advantage is 260× and 20× respectively. The header analysis (SPF, display-name spoofing, most-common link domain) is unique to Phish_Byte.

⚠️ Install — read this first

pip install phishbyte does not work. There is no PyPI package yet (it is on the roadmap). The only working path is cloning the source repository.

Step 1 — Clone

git clone https://github.com/AnonymousSingh-007/Phish_Byte.git
cd Phish_Byte

Step 2 — Create environment

python -m venv venv

# Windows:
.\venv\Scripts\Activate.ps1

# Mac / Linux:
source venv/bin/activate

Step 3 — Install dependencies

pip install -r requirements.txt

Minimal deps: torch, huggingface_hub, safetensors, dnspython, numpy, pandas.

For GPU acceleration (RTX 50-series / Blackwell):

pip install torch --index-url https://download.pytorch.org/whl/cu128

Step 4 — Verify everything works

python verify_install.py

This checks every dependency and every source file, then does a live test-download from this Hub repo. Run this before reporting any issue — it tells you exactly what is missing.

Expected output (all green):

✅ Python 3.11.x
✅ torch
✅ huggingface_hub
✅ safetensors
✅ dns
✅ numpy
✅ pandas
✅ phishbyte/__init__.py
... (all source files)
✅ from phishbyte import PhishByteEngine — works
✅ Model loaded from Hub successfully
✅ INSTALLATION VERIFIED

Usage

Run from Python (inside the cloned folder)

from phishbyte import PhishByteEngine

# Downloads ~1 MB of weights from this Hub repo on first call
# Cached locally after that — instant on every subsequent call
engine = PhishByteEngine.from_pretrained("SamSec007/phishbyte")

# Analyze any raw email string (headers + body)
verdict = engine.analyze(raw_email_string)

print(verdict.label)             # "phishing" or "legitimate"
print(verdict.probability)       # P(phish) in [0.0, 1.0]
print(verdict.confidence)        # "high" / "medium" / "low"
print(verdict.layer_used)        # 1 = rules decided, 2 = MLP decided
print(verdict.feature_weights)   # dict of 85 feature scores
print(verdict)                   # formatted terminal display

CLI

# Demo on a known phishing sample from training data
python cli.py --demo phish

# Demo on a known legitimate sample
python cli.py --demo legit

# Analyze a .eml file
python cli.py --file suspicious.eml

# Paste raw email interactively
python cli.py

# JSON output (for scripting)
python cli.py --demo --json

Analyze a real email from Gmail

Open the email in Gmail
Click ⋮ → Show original
Select all (Ctrl+A), copy (Ctrl+C)
Run python cli.py, paste when prompted
Press Enter then Ctrl+Z (Windows) or Ctrl+D (Mac/Linux) to submit

Understanding the verdict

PhishVerdict(
    label           = "phishing",
    probability     = 0.9735,      # how confident the model is
    confidence      = "high",      # high ≥ 0.795, low ≤ 0.695, medium in-between
    layer_used      = 2,           # 1 = rules veto, 2 = MLP decision
    feature_weights = {
        # Which signals fired and how strongly
        "display_name_mismatch":    1.00,  # "PayPal" in name, attacker domain
        "mcld_mismatch":            1.00,  # most common link domain ≠ sender
        "spf_fail":                 1.00,  # SPF DNS check failed
        "tfidf_verify":             0.82,  # high TF-IDF score for "verify"
        "external_link_ratio":      0.90,  # 90% of links go to external domains
        "urgency_score":            0.65,  # urgency keywords in body
        ...
    },
    detail = "MLP probability: 97.35%. Layer 1 score: 19.76%.",
)

Architecture

raw email
    │
    ▼
Layer 1 — 6 rule scorers (~1 ms)
  domain · URL+body · SPF · subject · BDI · TF-IDF
  → 85-dimensional feature vector
  → composite score ≥ 0.85? → fast PHISHING verdict (obvious cases)
    │
    ▼ (everything else — ~100% of real traffic)
Layer 2 — residual MLP (~3 ms)
  85 → 360 → 180 (×2 ResBlock) → 90 → 48 → 1 (sigmoid)
  254K parameters · randomly initialized · trained from scratch
  + input-to-output skip connection
    │
    ▼
PhishVerdict
  { label · probability · confidence · layer_used · feature_weights }

The Layer 1 → Layer 2 routing is intentional: cheap signals handle the clear cases, the neural network handles the ambiguous ones. layer_used tells you which path ran for each email — useful for latency auditing and cost accounting at scale.

Feature groups (85 total)

Group	Count	What it captures
Domain	7	From/Reply-To/Return-Path mismatch, freemail, brand impersonation, display name spoof, suspicious domain pattern
URL + Body	10	HTTPS ratio, anchor mismatch, suspicious TLD, urgency (normalized per 100 words), link density, caps ratio, digit ratio, special chars, avg word length, HTML/text ratio
SPF	3	SPF fail, no record, no sending IP
Subject	7	urgency, security theme, brand name, currency, all caps, fake RE prefix, fake transaction ID
BDI	3	Most common link domain mismatch, form action domain mismatch, external link ratio
TF-IDF	50	Top-50 discriminative unigrams learned from training corpus (no pretrained embeddings)
Composite	5	Per-module layer scores

Training data

Dataset	Emails	Era
CEAS-2008	39,154	2008
Enron	~29K	1999–2002
SpamAssassin	~10K	2002–2003
Nigerian Fraud	~3.3K	2000s
Nazario	~1.5K	2000s
Ling-Spam	~2.8K	1990s–2000s
Total (after dedup)	~83K	balanced ~50/50

Limitations — read before deploying

Training data is 15+ years old. These corpora predate OAuth phishing, QR code lures, redirect chains through Google Docs / Dropbox / OneDrive, and modern adversarial HTML. Recall on 2020s-era attacks is untested and likely degraded.
TF-IDF vocabulary is era-locked. Learned from 2000s corpora. Modern phishing vocabulary is not represented.
No adversarial robustness testing has been performed. An attacker aware of the feature set could craft bypasses. Use as one signal in a defence-in-depth stack, not a standalone gate.
F1 0.950 is self-reported on a held-out split of the training corpus, not independently verified.
English-language only.

Troubleshooting

Run python verify_install.py first — it catches nearly every issue below automatically.

Error	Fix
`ModuleNotFoundError: No module named 'phishbyte'`	Not in cloned folder or venv not activated
`ImportError: cannot import name 'X'`	`git pull origin main`
`pip install phishbyte` fails	No PyPI package yet — clone the repo
`NameError: save_model_as_safetensor`	`pip install safetensors`
Windows symlink warning	Harmless — ignore or enable Developer Mode

Roadmap

Retrain on 2020–2024 phishing data (PhishTank, OpenPhish, APWG eCrime)
Adversarial robustness test suite
HuggingFace Space demo (zero-install browser trial)
PyPI package (pip install phishbyte)
arXiv preprint

Citation

@software{phishbyte2026,
  author = {Singh, Samratth},
  title  = {Phish_Byte: Cascading from-scratch PyTorch phishing detection},
  year   = {2026},
  url    = {https://github.com/AnonymousSingh-007/Phish_Byte}
}

License

MIT