README.md

---
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.9490
            name: Precision
          - type: recall
            value: 0.9516
            name: Recall
widget:
  - text: "From: PayPal Security <security@paypa1-alert.tk>\nReply-To: attacker@evil-domain.ru\nSubject: URGENT: Your account will be suspended\n\nDear Customer, your PayPal account has been suspended. Verify now at http://paypal-login.tk/verify"
    example_title: "Phishing email"
  - text: "From: alice@company.com\nReply-To: alice@company.com\nSubject: Team lunch tomorrow\n\nHi everyone, lunch is at noon tomorrow. See you there!"
    example_title: "Legitimate email"
---

# Phish_Byte v7

A from-scratch PyTorch model for **email phishing detection**.

**F1 0.950** on 5,000 held-out samples from a 6-corpus benchmark.
**254K parameters** (≈260× smaller than DistilBERT).
**995 emails/sec** on a laptop GPU.
**85 engineered features** (35 rule-based + 50 TF-IDF learned from corpus).
Every verdict explains itself with full per-feature attribution.

> **The only non-transformer phishing detection model on HuggingFace.**

## Quick start

```python
from phishbyte import PhishByteEngine

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

print(verdict.label)             # "phishing"
print(verdict.probability)       # 0.9735
print(verdict.confidence)        # "high"
print(verdict.layer_used)        # 2
print(verdict.feature_weights)   # 85-feature attribution
```

## Analyse a real email from Gmail

1. Open the email in Gmail
2. Click ⋮ → **Show original**
3. Copy all (Ctrl+A, Ctrl+C)

```python
engine = PhishByteEngine.from_pretrained("SamSec007/phishbyte")
verdict = engine.analyze(pasted_raw_email)
print(verdict)
```

Or save as `.eml` and run:

```bash
python cli.py --file suspicious.eml
```

## What changed in v7

- **85 features** (was 29) — added 50 TF-IDF unigrams + 3 BDI features + 2 domain features + 1 composite
- **254K parameters** (was 12K) — deeper residual MLP with two ResBlocks and input skip connection
- **6-dataset training** (was CEAS-2008 only) — Enron, SpamAssassin, Ling-Spam, Nazario, Nigerian Fraud
- **TF-IDF vocabulary** — 50 most discriminative unigrams learned from training corpus. No pretrained LM.
- **Body Domain Identification** — most common link domain mismatch, form action mismatch, external link ratio
- **Display name spoofing** — catches "PayPal Security" \<attacker@evil.com\>
- **Calibrated training metrics** — F1 at Youden-optimal threshold, not naive 0.5 cutoff

## Architecture

```
raw email
  → Layer 1 (6 rule scorers, ~1ms) → veto gate (obvious phishing only)
  → Layer 2 (residual MLP, ~3ms)
      85 → 360 → 180 (×2 ResBlock) → 90 → 48 → 1 (sigmoid)
      + input-to-output skip connection
  → PhishVerdict {label, probability, confidence, layer_used, feature_weights}
```

## Benchmarks (5,000 held-out, 6-corpus)

| Metric | Phish_Byte v7 | DistilBERT fine-tuned |
|--------|:------------:|:---------------------:|
| F1 score | **0.950** | ~0.967 |
| Accuracy | **94.94%** | ~97% |
| 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 |
| Per-feature attribution | **85 features** | Token-level SHAP |

## Feature groups (85 total)

| Group | Count | Examples |
|-------|:-----:|---------|
| Domain | 7 | mismatch, Reply-To diff, brand impersonation, display name spoof, suspicious pattern |
| URL + Body | 10 | HTTPS ratio, anchor mismatch, urgency (normalized), caps ratio, digit ratio |
| SPF | 3 | fail, no record, no IP |
| Subject | 7 | urgency, security theme, brand, currency, all caps, fake RE, fake txn ID |
| BDI | 3 | most common link domain mismatch, form action mismatch, external link ratio |
| TF-IDF | 50 | top-50 discriminative unigrams from training corpus |
| Composite | 5 | per-module layer scores |

## Training data

CEAS-2008 + Enron + SpamAssassin + Ling-Spam + Nazario + Nigerian Fraud = **~83K emails** (balanced 50/50).

Same 6-corpus benchmark used by the top DistilBERT model on HuggingFace.

## Install

```bash
pip install huggingface_hub safetensors dnspython
```

## Limitations

- ~5% error rate. Use as one signal in defence-in-depth.
- Trained on English-language phishing (2003–2008 era). Modern attacks and non-English emails will degrade recall.
- SPF validation skipped for training (historical domains). Re-enables at inference on live emails.
- TF-IDF vocabulary is corpus-specific. Retrain on your own data for best domain fit.

## Citation

```bibtex
@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