A from-scratch PyTorch model for email phishing detection — no pretrained language model, no transformer, no fine-tuning.
743,571 parameters. Every signal is a feature computed directly from the email itself, fed through a context-gating architecture that learns how one piece of evidence should change the interpretation of another — rather than a fixed hand-written rule deciding that for it.
The only non-transformer phishing detection model on HuggingFace.
This checks every Python package and every source file is present, then does a live test download of the model weights from this Hub repo. If anything is missing, it tells you exactly what — not a confusing traceback. Expected output when everything is correct:
✅ 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
Basic usage — analyze any raw email
python
1from phishbyte import PhishByteEngine
23# First call downloads ~3 MB (weights + thresholds + vocabulary) from this4# Hub repo and caches it locally. Every call after is instant.5engine = PhishByteEngine.from_pretrained("SamSec007/phishbyte")67verdict = engine.analyze(raw_email_string)89print(verdict.label)# "phishing" or "legitimate"10print(verdict.probability)# calibrated confidence, 0.0 to 1.011print(verdict.confidence)# "high" / "medium" / "low"12print(verdict.layer_used)# 1 = a fast rule made the call, 2 = the full network did13print(verdict.feature_weights)# every signal computed for this specific email
Analyze a real email from your own Gmail
Step 1. Open the suspicious email in Gmail.
Step 2. Click the ⋮ menu in the top right of the email, then click Show original. This opens a new tab with the complete raw email, including every header.
Step 3. Select all the text (Ctrl+A) and copy it (Ctrl+C).
Step 4. Run the CLI:
python cli.py
Step 5. Paste the email when prompted, then press Enter followed by Ctrl+Z on Windows (or Ctrl+D on Mac/Linux) to submit it.
Analyze a saved .eml file
python cli.py --file suspicious.eml
Quick demo — no files needed
bash
1python cli.py --demo phish # a representative phishing example2python cli.py --demo legit # a representative legitimate example
Reading the verdict object
python
1PhishVerdict(2 label ="phishing",3 probability =0.9735,4 confidence ="high",5 layer_used =2,6 feature_weights ={7"display_name_mismatch":1.00,# "PayPal" in display name, unrelated domain8"mcld_mismatch":1.00,# most-linked domain isn't the sender's9"auth_alignment_score":0.95,# authentication does NOT validate this sender10"coercive_urgency_score":0.82,# pressure language: "verify now", "suspended"11"professional_formality_score":0.02,# essentially none — this isn't formal writing12...13},14 detail ="MLP probability (calibrated): 97.35%. Trust consistency: 0.10. Auth alignment: 0.95.",15)
How it works, stage by stage
Stage 1 — Parsing. The raw email string is split into its headers (From, Reply-To, Return-Path, Subject, Authentication-Results) and its body, using Python's standard email parser. This handles both plain-text and HTML/multipart emails.
Stage 2 — Domain analysis. Checks whether the From, Reply-To, and Return-Path addresses are consistent with each other; whether the display name claims a known brand (like "PayPal Security") while the actual domain is unrelated; and whether the domain itself looks auto-generated, based on digit density, hyphen count, and length.
Stage 3 — URL and body analysis. Extracts every link in the email, checks whether visible link text matches where the link actually points, measures how many distinct destination domains the links spread across, and looks at structural characteristics of the body like unusual capitalization density.
Stage 4 — Authentication validation (SPF, DKIM, DMARC). Reads the Authentication-Results header that the receiving mail server already computed, extracting whether SPF passed, whether DKIM signed the message with a domain that matches the sender, and what DMARC — the policy that ties SPF and DKIM together — concluded. This is a live, structural check, not a keyword guess.
Stage 5 — Subject line analysis. The same kind of pattern-matching as the body, scoped to the subject: brand names, currency symbols, ALL-CAPS shouting, fake "RE:" prefixes designed to look like an ongoing conversation.
Stage 6 — Link and form forensics. Finds the single most common destination domain across every link in the email and compares it to the sender. Checks whether any form on the page submits directly to a raw IP address instead of a domain — legitimate sites essentially never do this. Detects "open redirect" URL patterns commonly used to disguise a final destination.
Stage 7 — Lexical domain analysis. A character-by-character look at domain names: does the domain have an unusual run of digits? Does it read like a real word or a randomly generated string? Is it a near-miss spelling of a known brand, once common digit-for-letter substitutions are normalized (micros0ft → microsoft)?
Stage 8 — Cross-signal agreement check. Looks at whether the independent modules above agree with each other. Three modules independently raising concern is much stronger evidence than one module alone.
Stage 9 — Context feature computation. This is where v10 diverges most from earlier versions. Urgency language in the body is split into two independent numbers — how coercive it is ("verify immediately or your account will be suspended") versus how professionally formal it is ("we kindly ask for your commitment to this important task") — because a single blended urgency score cannot tell these apart, and they mean very different things. A separate signal captures how strongly DMARC and DKIM validate the sender, independent of what the link-forensics stage found — so the network can weigh "the links go somewhere else" differently depending on whether the sender proved its identity or not. A similar context signal exists for Reply-To addresses that use free email providers like Gmail.
Stage 10 — Fusion. All the evidence from stages 2 through 9 is split into two groups — raw evidence (facts about this email) and context evidence (facts that should change how the raw evidence is read) — and handed to a small neural layer whose only job is learning a gate: for this particular email, how much should the context evidence turn up or down the weight given to each piece of raw evidence. This gate is learned from real data, not hardcoded.
Stage 11 — Decision. The fused representation, plus 50 word-frequency signals learned from the training corpus, feeds a residual neural network. Its output passes through a learned temperature parameter before being converted into a final probability, so that "80% confident" is empirically close to being right 80% of the time.
Architecture
raw email
│
▼
parsing → domain / URL / auth (SPF+DKIM+DMARC) / subject / link-forensics / lexical
│
▼
cross-signal agreement check
│
▼
context feature computation
(coercive vs. professional urgency, auth-verified sender context,
freemail Reply-To context, observational tracking-pattern signal)
│
├──────────────┬───────────────┐
▼ ▼ │
RAW evidence CONTEXT evidence │
(38 numbers) (13 numbers) │
│ │ │
└──────┬───────┘ │
▼ │
Context Fusion Layer │
(learns a gate: how much │
should context reweight │
each raw signal, per email) │
│ │
▼ │
fused representation (64) ──────┘
│ TF-IDF (50)
└────┬────────┘
▼
residual MLP: 620 → 310 (×2 residual blocks) → 155 → 76 → 1
│
▼
temperature-calibrated confidence score
│
▼
PhishVerdict — label, confidence, and every signal that fired
743,571 parameters total. For comparison, DistilBERT-based phishing detectors on HuggingFace use 66,000,000+ parameters — roughly 90× more.
Version history
v2 — 12,545 parameters, 29 features, single dataset (CEAS-2008, ~39K emails). The original prototype. A small MLP over hand-picked domain, URL, and subject features, with a cascading Layer 1 (cheap rules) → Layer 2 (neural network) design that every later version kept.
v7 — 254K parameters, 85 features, 83K emails across 6 datasets. Added a TF-IDF vocabulary learned directly from the training corpus, and Body Domain Identification — checking the most common link destination against the sender. First version tested for generalization beyond a single dataset.
v8 — 716K parameters, 104 features, 166K emails across 7 datasets. Added character-level lexical domain analysis (digit runs, entropy, typosquat distance) and a cross-signal layer that checks whether independent modules agree with each other rather than scoring each one in isolation.
v9 — 718K parameters, 107 features. Replaced a naive SPF-only authentication check — which misfired constantly on legitimate marketing platforms like Marketo and Mailgun that relay mail on a brand's behalf — with a proper DMARC/DKIM alignment check that reads what the receiving mail server already validated.
v10 (current) — 743,571 parameters, context-gated fusion architecture. Split urgency detection into two independent signals — coercive pressure versus professional formality — that were previously conflated into a single blended number. Restructured the network so raw evidence and context evidence enter as separate inputs to a learned fusion layer, instead of being concatenated together and left for the network to disentangle unaided.
pressure/threat language, independent of formal tone
Auth-verified ESP context
1
how strongly DMARC/DKIM validate the sender
Professional formality (context)
1
formal/professional tone, independent of coercive urgency
Freemail Reply-To context
2
raw fact + how much authentication offsets it
Tracking pattern (observational)
1
structural resemblance to ESP tracking infrastructure — never used to exempt anything on its own
Cross-signal fusion (context)
5
agreement between independent modules
Auth alignment (context)
3
DMARC pass, DKIM alignment, composite score
TF-IDF
50
words learned directly from the training corpus
101 features total (38 raw + 13 context + 50 TF-IDF).
Training data
Dataset
Source
Contribution
CEAS-2008
Kaggle
~39K emails, 2008-era phishing
Enron
Kaggle
~29K emails, legitimate corporate correspondence
SpamAssassin
Kaggle
~10K emails, mixed spam/legitimate
Nigerian Fraud
Kaggle
~3.3K emails, advance-fee fraud
Nazario
Kaggle
~1.5K emails, phishing corpus
Ling-Spam
Kaggle
~2.8K emails
farshad72/spam_email
HuggingFace
83K rows, includes modern notification-style legitimate email
puyang2025/seven-phishing-email-datasets
HuggingFace
203K rows, unified 7-source corpus
Combined, after deduplication
—
~166,000 emails, ~56% phishing / 44% legitimate
Benchmarks
Evaluated on 12,000 held-out samples, self-reported.
Metric
Value
F1 score
0.9445
Accuracy
94.77%
Precision
0.9402
Recall
0.9489
Parameters
743,571
Model size on disk
~3 MB
Throughput (GPU)
~630 emails/sec
GPU required
No
Limitations
Read this before deploying anywhere real.
Most training data predates 2010. Modern phishing techniques — OAuth abuse, QR code lures, redirect chains through legitimate cloud services — are underrepresented even after adding modern HuggingFace datasets.
False positives on legitimate marketing and notification email are reduced but not eliminated. The context-gating architecture measurably helps here, but this remains an active area of work rather than a solved problem.
No adversarial robustness testing has been performed. An attacker aware of the exact feature set could plausibly craft targeted bypasses. Use as one signal in a defence-in-depth stack, not a standalone gate.
Benchmark numbers are self-reported on a held-out split of the training corpus, not independently verified or peer-reviewed.
Not production-hardened — no retry logic, rate limiting, or async network handling.
English-language only.
Citation
No peer-reviewed paper exists yet. Until then, cite the repository directly:
bibtex
1@software{phishbyte2026,
2 author = {Singh, Samratth},
3 title = {Phish_Byte: Context-gated fusion architecture for from-scratch email phishing detection},
4 year = {2026},
5 url = {https://github.com/AnonymousSingh-007/Phish_Byte}
6}
