Open-source email threat analysis platform for identifying spam, phishing, and malicious content with precision.
EMLyzer analyzes suspicious emails by uploading .eml or .msg files, or pasting the raw source directly. In seconds, it delivers a complete report with explainable risk score, header analysis, body content assessment, URL evaluation, attachment inspection, and reputation service checks.
Tip
💡 No API keys required to get started. Integrations with external services (AbuseIPDB, VirusTotal, etc.) are optional and configurable later.
| 📄 Document | 📝 Purpose |
|---|---|
| 📋 REQUIREMENTS.md | System requirements and prerequisites |
| 🚀 INSTALLATION.md | Step-by-step installation guide |
| ⚙️ CONFIGURATION.md | Environment setup and API keys |
| 📖 USAGE.md | How to use the application |
| 📡 API.md | REST API reference for developers |
- Install Python 3.13 from python.org (check "Add Python to PATH")
- Download and extract the project
- Double-click
start.bat - Open your browser to http://localhost:8000
git clone https://github.com/overwrite00/EMLyzer.git
cd EMLyzer
chmod +x start.sh
./start.shThen open http://localhost:8000
⏱️ First run downloads and installs dependencies (~2-5 minutes). Subsequent runs start in seconds.
Email (.eml / .msg / plain text)
│
▼
┌─────────────────────────────────────────────┐
│ 📧 Header Analysis → SPF/DKIM/DMARC, │
│ identity mismatch, │
│ SMTP routing │
│ │
│ 📝 Body Analysis → phishing patterns, │
│ obfuscated links, │
│ hidden HTML, NLP │
│ │
│ 🔗 URL Analysis → direct IPs, │
│ shorteners, │
│ Punycode, domain │
│ age (WHOIS) │
│ │
│ 📎 Attachment Analysis → hashes, VBA │
│ macros, JS in PDF │
│ │
│ 🌐 Reputation Checks → AbuseIPDB, │
│ VirusTotal, │
│ OpenPhish, PhishTank
│ Shodan, URLhaus... │
└─────────────────────────────────────────────┘
│
▼
📊 Risk Score 0–100 + 📄 Editable .docx Report
- 🔍 Complete email analysis — Headers, body, URLs, attachments
- 🧠 AI-powered phishing detection — Machine learning classifier (Random Forest)
- 🌐 Multi-language support — Italian 🇮🇹 and English 🇬🇧
- 🛡️ 19 reputation services — AbuseIPDB, VirusTotal, crt.sh, Shodan, and more
- 🛰️ Threat Intelligence — auto-refreshing IOC feeds, curated known-campaign patterns with backtesting, CERT-AGID bulletin board
- 📄 Editable reports — Generate professional Word (.docx) documents
- 🎨 Modern web UI — Clean, responsive interface (React 19 + Vite)
- 💾 Offline-first — No cloud dependencies, local SQLite database
- 🆓 Free & open-source — MIT license, MIT licensed dependencies only
- 🚀 Fast analysis — Email analyzed in seconds, not minutes
- 📱 Cross-platform — Windows, macOS, Linux
v0.17.3 — 🔒 Security and correctness release: resolves the open frontend dependency advisories for Vite, source-map-js, follow-redirects and Zod; protects the URLScan diagnostic endpoint; blocks SSRF in redirect-chain analysis; anchors the bundled NLP model to a reviewed SHA-256 digest; fixes hostname extraction in reputation checks; and restores CodeQL result uploads on pull requests while pinning GitHub Actions to full commit SHAs. The suite contains 214 tests (213 pass locally and 1 optional RTFDE test is skipped).
v0.17.2 — 🛠️ Bugfix release for Outlook .msg files: recipients, SPF/DKIM/DMARC results, Message-ID, the Received chain and the other transport-header fields were silently dropped, so header scoring ran without authentication data (re-analyze older .msg analyses to recompute them); RTF-only .msg bodies (Outlook 97-2003) are now recoverable with the optional RTFDE package. Also: SQLAlchemy 2.1 with the asyncio extra, a high-severity dev-dependency advisory (brace-expansion) resolved, other dependency updates, and a repaired project-automation workflow. All 199 tests passing ✅ in CI (the one end-to-end test that needs the optional RTFDE package is skipped where it is not installed), zero regressions.
v0.17.1 — 🐛 Follow-up to the Threat Intelligence release: fixed CERT-AGID bulletins not loading on first visit, added example placeholders and a collapsible mini-guide to the known-campaign form, and added a "Ri-analizza" (Re-analyze) button so an already-analyzed email can pick up a known campaign created or edited afterward. Documented the whole Threat Intelligence panel in docs/USAGE.md.
v0.17.0 — 🛰️ Threat Intelligence release: automatic refresh of local IOC feeds (OpenPhish, Spamhaus, URLhaus) with a shared caching/scheduling infrastructure, a curated "Known Campaigns" system with manual CRUD, corpus backtesting, CERT-AGID bulletin board, and internal auto-learning proposals — all backed by a new "Threat Intelligence" UI panel. Fixed several correctness bugs along the way (word-boundary campaign matching, dead risk_contribution weight, a spurious mega-cluster in internal clustering, JSON-less rate-limit responses) and hardened write endpoints with a local admin token; the app now binds to 127.0.0.1 by default. All 189 tests passing ✅ (1 skipped), zero regressions.
v0.16.3 — 📦 Dependency release: Updated backend (mail-parser, scikit-learn) and frontend (React, Vite, ESLint and more) dependencies, hardened the actions/checkout CI action, and reserialized the tabular phishing model with scikit-learn 1.9.1. All 124 tests passing ✅ (1 skipped), zero regressions.
v0.16.2 — 🔒 Maintenance release: Removed the unused NLTK dependency (unpatched path traversal vulnerability), updated backend and frontend dependencies (Pydantic, Uvicorn, Axios, Vite, ESLint and more), and repaired the CI test/workflow suite. All 124 tests passing ✅ (1 skipped), zero regressions.
📖 See full version history → CHANGELOG.md
- Python 3.11–3.13 (3.13 recommended ⭐)
- RAM 512 MB minimum (1 GB recommended)
- Disk 500 MB for installation
- Browser Chrome, Firefox, Safari, or Edge (90+)
Important
✅ For complete requirements, see REQUIREMENTS.md
Follow INSTALLATION.md for step-by-step instructions.
Set up optional reputation services in CONFIGURATION.md.
Learn the interface in USAGE.md.
Explore the API in API.md.
| Layer | Technology | Notes |
|---|---|---|
| Backend | Python 3.13, FastAPI, SQLAlchemy async | REST API + email analysis engine |
| Frontend | React 19, Vite 8, no external UI libs | Responsive web dashboard |
| Database | SQLite (local) | No external DB required |
| Analysis | scikit-learn NLP, dnspython, beautifulsoup4 | Phishing detection + URL parsing |
| Reports | python-docx | Editable Word documents |
✅ 122 automated tests — all passing, zero technical debt
- Unit tests for all analyzers
- Integration tests for API routes
- Reputation service mocking
- CI/CD on every commit (GitHub Actions)
Run locally:
./run_tests.sh # Linux/macOS
run_tests.bat # Windows- 🛡️ No cloud dependencies — Everything runs locally
- 🔒 No telemetry — Zero data collection
- 📁 Local SQLite — Your data stays on your machine
- 🔓 Open source — Fully auditable code
- ⚡ Offline capable — Works without internet (except reputation services)
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/your-feature) - Commit changes with clear messages
- Push to your fork
- Open a Pull Request to
developbranch
Note
📖 All PRs should target the develop branch, not main.
Distributed under the MIT License. See LICENSE for details.
- 📖 Documentation: See docs/ folder
- 🐛 Report issues: GitHub Issues
- 💬 Questions: Open a GitHub Discussion
Developed by Graziano Mariella
Distributed with MIT License · View License
Last updated: 2026-10-25 ← Contributing | Docs →