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
datasets:
  - ceas-2008
metrics:
  - f1
  - precision
  - recall
  - accuracy
model-index:
  - name: phishbyte
    results:
      - task:
          type: text-classification
          name: Phishing Email Detection
        dataset:
          name: CEAS-2008
          type: ceas-2008
        metrics:
          - type: f1
            value: 0.948
            name: F1 Score
          - type: accuracy
            value: 0.944
            name: Accuracy
          - type: precision
            value: 0.9537
            name: Precision
          - type: recall
            value: 0.9432
            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 tomorrow in the usual spot. See you there!"
    example_title: "Legitimate email example"
---

# Phish_Byte

A from-scratch PyTorch model for **email phishing detection**.
**F1 0.948** on CEAS-2008. **12,545 parameters** (≈9,000× smaller than DistilBERT).
**1,500+ emails/sec** on a laptop GPU. Every verdict explains itself.

> **v3 in progress:** expanding to 50K parameters + 6-dataset corpus training.

## 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)   # per-feature attribution
```

## Why this exists

Every phishing detection model on HuggingFace is a fine-tuned transformer —
DistilBERT, BERT, RoBERTa. 65–110M parameters. ~250 MB on disk. ~50 ms/email.

Phish_Byte is different:
- Custom MLP trained **from scratch** — no pretrained weights
- **29 engineered features** across domain, URL, SPF, subject, and character-level signals
- **Cascading inference** — cheap rules handle obvious cases, MLP handles the rest
- **Full email header analysis** including live SPF validation
- Runs on **CPU without a GPU**
- Every verdict includes **which signals fired and why**

## Benchmarks (CEAS-2008, n=2,000 held-out)

| Metric | Phish_Byte | DistilBERT fine-tuned |
|--------|:----------:|:---------------------:|
| F1 score | **0.948** | ~0.967 |
| Parameters | **12,545** | 66,000,000 |
| Model size | **52 KB** | ~250 MB |
| Throughput (GPU) | **1,527/sec** | ~50/sec |
| GPU required | **No** | Practically yes |
| Header analysis | **Yes (SPF, DKIM)** | No |
| Explainability | **29-feature attribution** | Token-level SHAP |

## Feature signals (29 inputs)

| Category | Features |
|----------|----------|
| Domain (5) | mismatch, Reply-To diff, Return-Path diff, freemail flag, brand impersonation |
| URL (5) | HTTPS ratio, anchor mismatch, suspicious TLD, urgency, link density |
| SPF (3) | fail, no record, no sending IP |
| Subject (7) | urgency, security theme, brand name, currency, all-caps, fake RE, fake transaction ID |
| Character-level (5) | caps ratio, digit ratio, special density, word length, HTML ratio |
| Composite (4) | per-layer normalized scores |

## Architecture

```
raw email
  → Layer 1 (rule scorers, ~1ms) → confidence gate
  → Layer 2 (custom MLP, ~3ms) → PhishVerdict
    {label, probability, confidence, layer_used, feature_weights}
```

## Install

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

```python
from phishbyte import PhishByteEngine
engine = PhishByteEngine.from_pretrained("SamSec007/phishbyte")
verdict = engine.analyze(raw_email_string)
```

## Limitations

- ~5% error rate (F1 0.948). Use as one signal in defence-in-depth.
- Trained on CEAS-2008 (English, 2008-era phishing). Modern attack patterns may reduce recall.
- SPF validation skipped during training on historical data — re-enables at inference time.

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