presentation/app/README.md

metadata

title: BITS Phishing Email Detector
emoji: 🛡️
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 6.29.1
python_version: 3.12.12
app_file: app.py
pinned: false
license: mit
short_description: 'From-scratch 337M encoder: legitimate / phishing / spam'

BITS Phishing Email Detector

Paste an email subject and body; the app returns the model's probability for each of three classes, Legitimate, Phishing and Spam, plus the roll-up Unwanted (phishing or spam) = P(Phishing) + P(Spam), the prediction time for that single sample, the tokens the model weighed most, and a list of rule-based cues for a human reader. The verdict is Legitimate when the unwanted roll-up is below 50% and otherwise the larger of Phishing / Spam. It is a defensive triage and training aid.

How it works

• Model. A 337M-parameter BERT-style pre-LayerNorm encoder (24 layers, d=1024, 16 heads, FFN 4096, vocabulary 32,768, 512 tokens) written from scratch in plain PyTorch (model.py; no transformers, no pretrained weights) with a three-way classification head. It was pretrained with masked language modelling on deduplicated Enron email and fine-tuned on public corpora: legitimate mail and spam from TREC-05/07, CEAS-08, Enron-Spam and SpamAssassin; phishing from the Nazario phishing archive and the Nigerian-fraud (advance-fee) archive (Champa et al. corpus mirror, CC-BY-4.0) plus BITS synthetic lures. Rows whose corpus never separated spam from phishing (TREC-05/07, CEAS-08 positives) were trained with a partial label on the combined phishing + spam mass, so they shape the legitimate-vs-unwanted decision without asserting which unwanted class they belong to. The TREC-06 corpus was held out entirely as the binary test set; a separate three-way holdout of rows the tokenizer never saw and that share no exact or near-duplicate text with the pretraining corpus (checked by content keys and shared 50-character shingles) gives the 3x3 confusion matrix.
• Input. subject + "\n\n" + body, byte-level BPE tokenised (NFKC, case preserved) and truncated to 512 tokens. Sender, headers and attachments are never read.
• Prediction time. timeit.default_timer around tokenize + forward + softmax, like the course reference app (benchmark: 0.074 s/sample).
• Token importance. Gradient x input saliency of the verdict's log-probability (log P(Legitimate), or log(P(Phishing) + P(Spam)) when the verdict is unwanted) with respect to the token embeddings; the top tokens are merged back into words and highlighted over the original text.
• Signals. Regex heuristics (urgency words, credential lures, link-text vs href host mismatch, lookalike domains, raw-IP URLs, ALL-CAPS share, reply-to redirection, generic greetings, risky attachment names). They are shown for context only; the probability comes from the model alone.
• Runtime. ZeroGPU (@spaces.GPU(duration=30), bf16) with the model placed on cuda at module level; falls back to CPU fp32. The weights (model.safetensors, config.json, tokenizer.json) are bundled in this Space next to app.py; app.py can also download them from the model repo named by the PHISH_MODEL_REPO variable with an HF_TOKEN secret.
• Training recipe of the deployed checkpoint. Fine-tune run ft-focal: focal loss (gamma 2.0) over the partial-label negative log-likelihood, AdamW, LR 3e-5 with warmup and linear decay, batch 32, early stopping on the validation F1 of the unwanted roll-up. It was chosen among six runs (cross-entropy, class-weighted cross-entropy, focal, synthetic supplement, 12 layers, scratch init) by validation metrics alone.

Model card

Weights, config, tokenizer, metrics and the full model card: https://huggingface.co/BuildITSystems/phishing-detector-encoder

Limitations

• Training data is English email from 1995-2022, the bulk of it 1998-2008 (Enron, TREC, CEAS, SpamAssassin); modern lures (MFA fatigue, QR codes, chat-app phishing) and non-English mail are out of distribution.
• Spam vs phishing follows corpus provenance, not a per-message review. "Phishing" means a row came from the Nazario or Nigerian-fraud archives or the synthetic lures; "Spam" means the SpamAssassin or Enron-Spam spam folders. The TREC-05/07 and CEAS-08 positives (the largest share of unwanted training mail) were never split and were trained only as "unwanted", so the phishing/spam boundary is softer than the legitimate/unwanted one. The roll-up Unwanted (phishing or spam) is the number to trust first and the one comparable with the earlier binary runs.
• Text only: no sender reputation, SPF/DKIM, link reputation or attachment analysis.
• Inputs longer than 512 tokens (about 1,800 characters) are judged on their opening.
• Legitimate mail is on average longer than spam in the training data; length is a known confound.
• Flagging is disabled and nothing pasted is stored, but do not paste secrets or confidential client content.

Context

Final project for the Skillspire AI & Machine Learning course, built by Nathan King at Build IT Systems (BITS). The project repository holds the data pipeline, tokenizer, pretraining and fine-tuning code, the run log of every experiment (layers, epochs, loss functions, crashes and fixes) and the evaluation on the unseen TREC-06 test set; the headline numbers are in the model card linked above.