--- 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.9470 name: Accuracy - type: precision value: 0.9369 name: Precision - type: recall value: 0.9523 name: Recall widget: - text: "From: PayPal Security \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 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: ```bash 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: ```python 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`: ```bash 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 ```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