README.md

metadata

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
  - cross-signal-fusion
  - lexical-analysis
  - calibrated-probabilities
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: >-
            7-corpus benchmark (CEAS, Enron, SpamAssassin, Ling-Spam, Nazario,
            Nigerian, farshad72)
          type: ceas-2008
        metrics:
          - type: f1
            value: 0.9445
            name: F1 Score
          - type: accuracy
            value: 0.947
            name: Accuracy
          - type: precision
            value: 0.9369
            name: Precision
          - type: recall
            value: 0.9523
            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 v8

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

F1 0.944 on 5,000 held-out samples from a 7-corpus, 166K-email benchmark. 716K parameters (~90× smaller than DistilBERT). 815 emails/sec on a laptop GPU. 104 engineered features across 8 analysis modules. Temperature-calibrated confidence — probability outputs are empirically calibrated, not just monotonic scores. Every verdict explains itself with full per-feature attribution.

The only non-transformer phishing detection model on HuggingFace.

---

⚠️ Install — no PyPI package yet

pip install phishbyte does not work. Clone the source repository:

git clone https://github.com/AnonymousSingh-007/Phish_Byte.git
cd Phish_Byte
python -m venv venv && source venv/bin/activate   # Windows: .\venv\Scripts\Activate.ps1
pip install -r requirements.txt
python verify_install.py    # confirms everything before you start

Then from inside the cloned folder:

from phishbyte import PhishByteEngine

engine  = PhishByteEngine.from_pretrained("SamSec007/phishbyte")
verdict = engine.analyze(raw_email_string)

print(verdict.label)             # "phishing" or "legitimate"
print(verdict.probability)       # calibrated 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)   # all 104 signal values

from_pretrained() downloads ~3 MB (weights + thresholds + TF-IDF vocab) and caches locally. Every call after the first is instant.

---

Analyse a real email from Gmail

1. Open the email → ⋮ → Show original
2. Select all (Ctrl+A), copy (Ctrl+C)
3. Run python cli.py, paste when prompted, press Enter then Ctrl+Z (Windows) or Ctrl+D (Mac/Linux)

Or save as .eml:

python cli.py --file suspicious.eml

---

What changed in v8 vs v7

	v7	v8
Parameters	254K	716K
Features	85	104
Architecture	85→360→180×2→90→48→1	104→620→310×2→155→76→1
Training corpus	83K emails, 6 sources	166K emails, 7 sources
F1 (held-out)	0.950	0.944
Cross-signal fusion	None	Yes — 5 inter-module features
Lexical domain analysis	None	Yes — character-level on sender + link domain
BDI features	3	5 (+ IP-target forms, open redirects)
Confidence calibration	Post-hoc threshold	Learned temperature parameter (Platt scaling)
Training metric	Naive 0.5 cutoff	Youden-optimal threshold

The F1 drop from 0.950 to 0.944 reflects a harder benchmark — the corpus doubled in size and the evaluation pool now includes modern notification-style legitimate emails (CNN news digests, mailing lists, marketing email) that the 83K model never saw.

---

How it works — plain language

Eight independent analysis modules run on every email:

1. Domain analysis — checks whether From, Reply-To, and Return-Path addresses are internally consistent; detects display-name spoofing (e.g. "PayPal Security" sending from an unrelated domain); flags suspicious domain patterns
2. URL and body analysis — HTTPS/HTTP ratio, anchor text vs href mismatch, urgency language normalized per 100 words, link density by unique destinations
3. SPF validation — live DNS lookup to verify the sending server is authorized
4. Subject line analysis — urgency, currency, brand names, ALL-CAPS, fake RE: prefixes
5. Body Domain Identification (BDI) — finds the most common link destination domain; flags form actions pointing at raw IP addresses; detects open-redirect URL patterns
6. Lexical domain analysis — character-level forensics on the sender domain AND the most-linked domain: digit runs, hyphen stacking, Shannon entropy, typosquat distance to known brands (leet-normalized: paypa1 → paypal)
7. Cross-signal fusion — computes interaction features across all six modules: trust consistency (SPF pass + domain agreement + BDI match), multi-module agreement score, domain/BDI compounding, lexical brand confusion
8. TF-IDF vocabulary — 50 discriminative unigrams learned from the training corpus (no pretrained LM)

All 104 outputs concatenate into one vector and feed a residual MLP with a learned temperature scalar for calibrated confidence.

---

Architecture

raw email
  → 8 analysis modules → 104-dim feature vector
  → Layer 1 gate: composite score ≥ 0.85 → fast PHISHING verdict
  → Layer 2: residual MLP
      104 → 620 → 310 (×2 ResBlock) → 155 → 76 → 1
      + input-to-output skip connection
      + learned temperature scalar (Platt scaling)
  → calibrated P(phish) + PhishVerdict with 104-feature attribution

---

Benchmarks

Evaluated on 5,000 held-out samples, self-reported.

Metric	Phish_Byte v8	DistilBERT fine-tuned*
F1 score	0.944	~0.967
Accuracy	94.70%	~97%
Parameters	716K	66,000,000
Model size	~3 MB	~263 MB
Throughput (GPU)	815/sec	~50/sec
GPU required	No	Practically yes
Header + SPF analysis	Yes	No
Per-feature attribution	104 features	Token-level SHAP
Confidence calibrated	Yes (temperature)	No

* Self-reported by a different author on a different split. Not apples-to-apples — treat both F1 numbers as directional.

---

Feature groups (104 total)

Group	Count	What it captures
Domain	7	header consistency, brand impersonation, display-name spoof, suspicious pattern
URL + Body	10	link security, anchor mismatch, urgency, caps ratio, digit ratio
SPF	3	live DNS sender authorization
Subject	7	urgency, security theme, brand, currency, caps, fake RE, fake txn ID
BDI	5	MCLD mismatch, form action mismatch, external link ratio, IP-target form, open redirect
Lexical — sender domain	6	digit runs, hyphen runs, entropy, vowel anomaly, typosquat distance, length
Lexical — most-linked domain	6	same six on the dominant link destination
Cross-signal fusion	5	trust consistency, SPF-pass URL discount, multi-module agreement, domain/BDI compounding, lexical brand confusion
TF-IDF	50	top-50 discriminative unigrams from training corpus
Composite	5	per-module summary scores

---

Training corpus (166K emails, 7 sources)

Source	Emails
CEAS-2008, Enron, SpamAssassin, Ling-Spam, Nazario, Nigerian Fraud	~83K
farshad72/spam_email (HuggingFace)	~83K
Total after dedup	~166K

Balance: ~56% phishing / 44% legitimate.

---

Troubleshooting

Run python verify_install.py first — it identifies the exact problem rather than a confusing traceback.

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
Model download hangs	Check internet — Hub: huggingface.co/SamSec007/phishbyte
Windows symlink warning	Harmless — ignore or enable Developer Mode

---

Limitations — read before deploying

• Most training data predates 2010. Modern phishing (OAuth abuse, QR lures, redirect chains through legitimate cloud services) is underrepresented. Recall on 2020s attacks is not independently verified.
• No DMARC feature yet. Emails sent via legitimate ESPs (Marketo, Mailgun, SendGrid) will trigger spf_fail even when dmarc=pass. This causes false positives on marketing email from large organizations. DMARC extraction is the next planned feature.
• No adversarial robustness testing. Use as one signal in defence-in-depth, not a standalone gate.
• F1 0.944 is self-reported on a held-out split of the training corpus.
• English-language only.

---

Roadmap

• DMARC feature — fixes false positives on ESP-delivered legitimate email
• Retrain on 2020–2024 phishing data (PhishTank, OpenPhish, APWG eCrime)
• HuggingFace Space demo (try in-browser, zero install)
• PyPI package (pip install phishbyte)
• arXiv preprint
• Adversarial robustness test suite

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