Skip to content
Tutorials Center
My learning

Topics

Lesson 74 of 80 ยท Projects

Project: Phishing Email Classifier

Build a phishing email classifier in Python: generate fake emails, engineer features, train a scikit-learn model, tune the threshold and see how attackers evade it.

Phishing is the most common way attackers get their first foothold, and mail filters stop an enormous number of attempts every day. Many of those filters use machine learning: a model that looks at a message, turns it into numbers and estimates how likely it is to be malicious. In this project you'll build a small version, and, more importantly, learn how to judge it honestly.

You will generate a few hundred fake emails (no real data, no real brands), extract features such as urgent wording, mismatched links and risky attachments, train a scikit-learn classifier, measure precision and recall, and then look at the cases it misses. The project is about the method and its limits, not about producing a filter you could deploy. If you want the human side first, read Phishing and Social Engineering.

The plan

flowchart LR
    A["Fake emails<br/>(generated)"] --> B["Feature<br/>extraction"]
    B --> C["Train / test<br/>split"]
    C --> D["Model<br/>(logistic regression)"]
    D --> E["Evaluate:<br/>precision, recall"]
    E --> F["Tune threshold,<br/>study mistakes"]

Every real model project follows this loop. The last step usually sends you back to the features.

Stage 1: fake emails and features

Real training data is a privacy problem and a moving target, so we generate our own. Each email is a small dictionary: sender, subject, body, a list of links (the text the reader sees, and where the link really goes), an attachment name and the true label. All domains end in .example, a name reserved for documentation, and the IP address comes from a range reserved for examples.

Some of the fakes are deliberately hard: a legitimate IT notice that says "urgent", a parcel link on a third-party domain, a phishing message with no urgent words at all, and a boss-impersonation message with no link. Real mail is messy, and a dataset where every phish shouts "URGENT!!!" would teach you nothing.

The features are what the model gets to see. They are ordinary, explainable signals:

  • counts of urgent and money-related words, and exclamation marks;
  • the number of links, whether a link goes to a bare IP address or a URL shortener;
  • whether the visible text of a link looks like one address but the link goes to another (the classic lookalike trick);
  • whether a link points to a domain different from the sender's;
  • a risky attachment type, or a free-mail sender pretending to be a boss.
Python Stage 1: generate emails and extract features

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Look at the table: every feature is higher on average for phishing, but none of them is perfect on its own. urgent_words is above zero for legitimate mail too (the IT notice), and n_links is lower for phishing, because the boss-impersonation and invoice scams have no link at all. A model's job is to weigh such imperfect clues together.

Stage 2: train and evaluate honestly

The cardinal rule of machine learning applies with full force in security: never evaluate on the data you trained on. A model can memorize its training examples and look perfect. So we split the data, train_test_split with stratify=y keeps the phishing share equal in both parts, train on 70 percent and report results only on the unseen 30 percent.

We use logistic regression, a simple model that gives each feature a weight and turns the weighted sum into a probability. It is a good first choice for security work because you can read the weights and explain a decision. A StandardScaler puts features on a comparable scale first.

The right metrics matter more than the model. With 35 percent phishing, "accuracy" is misleading, and the two kinds of mistake have very different costs:

  • Precision: of the mails flagged as phishing, how many really were? Low precision means false alarms: legitimate mail in the spam folder.
  • Recall: of all real phishing mails, how many did we catch? Low recall means attacks reach the inbox.
Python Stage 2: train, evaluate, inspect mistakes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The weights read like an analyst's checklist: a link that leads to a foreign domain and money-related wording push the score up the most. Reading them is also a sanity check. If a weight had the wrong sign, you would suspect a bug in the data.

Stage 3: the threshold is a business decision

The model does not output "phishing" or "legitimate". It outputs a probability, and predict simply cuts it at 0.5. That cut-off is a choice, and security teams choose it differently depending on the cost of each error:

  • A high threshold flags only the clearest cases. Few false alarms, but more attacks reach people.
  • A low threshold catches nearly everything, at the price of quarantining some real mail, which costs trust and support time.

In the run above, lowering the threshold to 0.2 catches every phishing mail in the test set while precision falls, and the price is paid by one kind of legitimate mail: the parcel notices whose tracking link points to a third-party carrier domain, which looks just like a "foreign link". At threshold 0.5 the model caught every account scam, prize and boss message, and missed the quiet document-share lures and some invoice mails. A common compromise is a two-tier policy: delete or quarantine above a high score, add a warning banner between the thresholds, and let the lowest scores through.

Stage 4: what detection cannot do

Now the honest part. Run the model on a message an attacker wrote knowing how filters work: calm wording, no exclamation marks, no money words, a link whose visible text does not pretend to be a URL.

Python Stage 4: the evasion experiment

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Every step the attacker takes removes a signal. Calm wording alone only lowers the score a little (the lookalike link still gives the scam away), but once the link text no longer pretends to be a URL, the verdict flips to deliver. The last move is the nastiest: sending the link from a compromised legitimate account or website leaves the message with no suspicious domain at all. The trained model from Stage 2 shows the same weakness in practice: the mails it missed were exactly the quiet ones. That leads to some hard lessons:

  • Features are a contract the attacker can read. Anything you detect, a determined adversary can avoid. This is called evasion, and it is the central weakness of every signature or model that attackers can probe.
  • Models age. Attack styles change (new brands, new wording, QR codes inside images), so the data distribution drifts and recall decays quietly. Plan to retrain and to measure on fresh samples.
  • Synthetic data flatters you. Our fakes were written by one author in a few templates. Real mail has many authors, languages and formats, and the scores on real traffic would be lower.
  • Content is not the only signal. Strong mail defenses add sender authentication (SPF, DKIM, DMARC), link rewriting with safe-browsing checks at click time, attachment sandboxes, and reputation data. A classifier is one layer in defense in depth, not the whole wall.
  • People remain a control. Reporting buttons and good training catch what the filter does not (see Phishing and Social Engineering).

Ideas to extend it

  • Add a text model: turn subject and body into word counts with TfidfVectorizer and compare it with the hand-made features, or combine both.
  • Try a RandomForestClassifier and compare it with logistic regression. Is the gain worth losing readable weights?
  • Use cross-validation (cross_val_score) to see how much the result changes between splits. With a 180-email test set, one different split can move recall by several points.
  • Write down the cost of a missed phish and of a false alarm, then pick the threshold that minimizes the total expected cost.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why do we report metrics only on the test set?

    The goal is to know how the model behaves on mail it has never seen. Scores on the training data reward memorization, not generalization.
  2. 2. A mail filter quarantines far too much legitimate mail. Which metric is low?

    Precision is the share of flagged mails that are really phishing. Many false alarms mean low precision. Low recall would mean attacks getting through.
  3. 3. What happens when you lower the decision threshold from 0.5 to 0.2?

    A lower threshold flags more messages: more real phishing is caught, but more legitimate mail is flagged too. Choosing the balance is a policy decision.
  4. 4. Why is an attacker able to evade a feature-based classifier?

    Anything the filter looks for can be probed and avoided. That is why detection is layered with authentication, click-time checks, sandboxes and user reporting.
  5. 5. Why is a dataset where every phishing email is full of capital letters and exclamation marks a poor test?

    An unrealistically easy dataset inflates the scores. The messages that cause real damage are often the quiet ones, so a useful dataset must include them.

Summary

  • A phishing classifier turns each email into explainable features, trains on one part of the data and is judged only on a held-out part.
  • Precision (false alarms) and recall (missed attacks) matter more than accuracy; the decision threshold trades one for the other.
  • Readable weights make a model auditable: they show what it relies on and expose bugs.
  • Hard and quiet cases, such as calm wording or messages with no link, are where simple models fail.
  • Attackers can evade any known signal, data drifts, and synthetic data flatters; treat the model as one layer among sender authentication, click-time checks and trained people.

Next: Practice: Fundamentals and Cryptography, a set of exercises with solutions to check what you have learned so far.