Home

HunterTrace v3 — Email Forensics & Attacker Attribution

HunterTrace is a passive email forensics tool that attributes threat actors to geographic regions using only email headers and metadata. No network probing, no honeypots, no active scanning — everything is derived from what the attacker already sent you.

---

What it does

Given a raw .eml file, HunterTrace runs an 8-stage pipeline that:

1. Extracts all hop IPs from Received: headers, handling IPv4, IPv6, and webmail leaks
2. Classifies each IP (VPN, datacenter, residential ISP, mail relay, Tor)
3. Traces the proxy chain to identify the most likely real origin IP
4. Enriches IPs with WHOIS, ASN, and geolocation data
5. Correlates infrastructure across multiple emails from the same actor
6. Aggregates threat intelligence signals
7. Runs a Bayesian attribution engine over 8 independent signals
8. Outputs a confidence-scored country attribution with an ACI (Attribution Confidence Index)

---

Quick Start

git clone https://github.com/akshaydotweb/huntertrace
cd huntertrace
pip install -r requirements.txt

# Single email
python hunterTrace.py suspicious_email.eml

# Full campaign (directory of .eml files)
python hunterTrace.py --campaign ./emails/ --output results/

# With attack graph visualisation
python attackGraphBuilder.py --input results/ --output graph.html
open graph.html

Requirements

• Python 3.10+
• requests, python-whois (optional, improves WHOIS enrichment)
• Network access for live IP geolocation (ip-api.com, free tier sufficient)

---

Installation

pip install -r requirements.txt

Optional dependencies (each enables additional pipeline stages):

Package	Stage	Benefit
python-whois	Stage 3B	WHOIS org/ASN enrichment
geoip2 + MaxMind DB	Stage 4	Offline geolocation fallback
networkx	Graph builder	Attack graph export to GraphML

---

Output Files

After a campaign run, HunterTrace produces:

File	Contents
v3_attribution_*.json	Per-actor country attribution with confidence scores
v3_actor_profiles_*.json	Infrastructure fingerprints, TTP profiles
v3_correlation_*.json	Cross-email infrastructure clustering
attackerGraph.html	Interactive 4-tab visualisation
evaluation_report.json	Accuracy metrics if ground truth labels provided

---

Running the Evaluation

# Against labelled corpus
python runEval.py --no-ablation --no-baselines

# With full ablation study (slow, ~20 min)
python runEval.py

# Verify attribution claims independently
python fixAndVerify.py --auto

---

Navigation

• How Attribution Works — the 8 signals and Bayesian model
• Reading Results — ACI scores, tiers, attack graph
• False Positive Handling — VPN audit methodology