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 example"
  - text: "From: alice@company.com\nReply-To: alice@company.com\nSubject: Team lunch tomorrow\n\nHi 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

```bash

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

cd Phish_Byte

```

### Step 2 — Create environment

```bash

python -m venv venv



# Windows:

.\venv\Scripts\Activate.ps1



# Mac / Linux:

source venv/bin/activate

```

### Step 3 — Install dependencies

```bash

pip install -r requirements.txt

```

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

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

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

```

### Step 4 — Verify everything works

```bash

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)

```python

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

```bash

# 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

```python

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

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