SamSec007/phishbyte

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

1. Open the email in Gmail
2. Click ⋮ → Show original
3. Select all (Ctrl+A), copy (Ctrl+C)
4. Run python cli.py, paste when prompted
5. 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