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

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

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

pip install huggingface_hub safetensors dnspython

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

@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