Second Project Back: A Phishing Email Analyzer (Still a Beginner, Still Learning)

#python #security #ai #programming

Second Project Back: A Phishing Email Analyzer (Still a Beginner, Still Learning)

A little while ago I wrote about coming back to documenting my work after a long quiet stretch, starting with a small IOC enrichment tool. This is the next entry in that same habit — a phishing email analyzer, built for the same reason: phishing makes up the overwhelming majority of L1 SOC tickets, and I wanted to actually understand the mechanics behind the checks analysts run every day, instead of just knowing the term "SPF/DKIM/DMARC" without having implemented any of it myself.

Same disclaimer as last time: this isn't a novel tool. Proper email security gateways and existing phishing analysis tools do this far better, with years of edge cases baked in that I haven't encountered yet. This is a beginner project built to learn by doing, not a claim that I've built something the industry needs.

What It Does

Upload a raw .eml file (or paste the raw source), and it:

Extracts headers and flags mismatches between From, Reply-To, and Return-Path
Actually verifies SPF against DNS records and the real originating IP
Cryptographically verifies the DKIM signature against the sender's public key
Checks DMARC policy
Flags lookalike/typosquatted domains
Hashes attachments and checks them against VirusTotal and MalwareBazaar
Spits out a incident report I can paste straight into a case writeup

The Part That Actually Taught Me Something

Building the SPF/DKIM checks is where I learned the most, mostly by getting things wrong first.

Received headers are in reverse order. I assumed — like reading anything else — that the first Received: header at the top of an email would be the first hop, chronologically. It's the opposite. Mail servers prepend new Received headers as the message moves along, so the top one is the most recent hop and the bottom one is closest to the original sender. My first version of the origin-IP extraction logic was quietly reading the wrong end of the chain and flagging the recipient's own mail server as "suspicious." Small thing, but a wrong assumption like that would have made every result in this tool backwards if I hadn't caught it.

SPF checks the Return-Path domain, not the From domain. This one surprised me. The visible "From" address is what a human reads, but SPF authentication is actually evaluated against the envelope sender — the Return-Path — which the recipient never even sees by default. That's exactly why Reply-To/Return-Path spoofing works as an attack in the first place: the part a human trusts (From) isn't the part the mail server verifies (Return-Path). Getting this distinction right in code meant actually understanding why the attack works, not just detecting that it happened.

Trusting a pre-computed result is a trap — same lesson as my last project's MalwareBazaar issue, different context this time. It would've been much faster to just read the Authentication-Results header the receiving mail server already left behind, stating whether SPF/DKIM/DMARC passed. But that header is written by some mail server in the delivery chain — and if the whole point of the tool is catching sophisticated spoofing, trusting a self-reported result defeats the purpose. So this version does the DNS lookups and DKIM signature verification itself, independently.

What's Still Rough (On Purpose, Documented, Not Hidden)

SPF include: mechanisms (third-party senders like include:_spf.google.com) aren't recursively resolved — the tool flags them for manual review instead of chasing the chain down. Proper recursive SPF resolution is a project on its own.
DMARC organizational domain lookup is simplified — a fully correct version needs the Public Suffix List to know where the real organizational boundary sits (think .co.uk vs .com), which I haven't implemented yet.
Homograph detection is edit-distance based against a fixed brand list, not a comprehensive Unicode confusable-character database.

None of these are hidden in the code — they're commented directly where the simplification happens, partly so I remember what to improve, partly because I'd rather be upfront about where the tool's edges are than let it look more complete than it is.

Why Keep Writing These

Same reason as before — the value isn't in looking finished, it's in having an honest record of what I understood well enough to build versus what I'm still learning. If the SPF/Return-Path distinction was new to me, it's probably new to other people making the same jump from development into security, and that's worth writing down plainly rather than only presenting the polished result.

Next up is likely a home SIEM lab, and probably a case where I actually run one of my own tools against a real (safely sourced) phishing sample instead of the fabricated test email I used to build this one.

Muhammad Abdullah — learning SOC analysis, building things along the way.
GitHub: m-abdullah-06