An automated SOC analyst — in your terminal — that ingests suspicious emails, scores the threat with transparent rules, hunts the attacker's look-alike domains, and actively blocks the infrastructure behind the attack.
MailGuard Pro is a self-hosted, terminal-native platform for a Security Operations Center (SOC). Employees forward suspicious emails to a shared mailbox; MailGuard Pro inspects each one the way an expert analyst would — but in seconds, consistently, and at scale — then goes further to prevent the attack. The interface is a command-line toolkit (mailguardpro <command>); an optional headless daemon runs the always-on pollers and a JSON API.
It does five things:
- Analyses emails — a multi-stage forensic pipeline (header authentication, content, links, sender reputation, attachments) produces a transparent 0–100 threat score with a full explanation of why.
- Hunts attacker infrastructure — Brand Recon proactively discovers registered look-alike domains impersonating a brand before they are weaponised.
- Enforces protection — four enterprise controls: threat-intel feeds, a DNS sinkhole, a Secure Web Gateway, and SPF/DKIM/DMARC enforcement.
- Responds — for every confirmed threat it auto-generates an incident-response playbook, deployable Snort/Suricata rules, and a forensic evidence PDF.
- Presents everything — through fast, scriptable command-line tools (and a JSON API when the daemon runs).
⚙️ Rule-based core & explainable — every decision traces to a specific signal. An optional AI layer (any OpenAI-compatible model) can be switched on to strengthen BEC/impersonation cases; it only adds to the transparent score.
The product is the terminal. One dispatcher, mailguardpro <command> (or node bin/cli.js):
🛡️ MailGuard Pro CLI
Usage: mailguardpro <command> [options]
inbox Scan the mailbox (demo/live) into the database
scan <domain> Full health, verdict & deep look-alike report
check <domain> Basic domain health and WHOIS check
recon <brand> Hunt for registered look-alike domains
inspect <url> Deep-inspect a single URL for phishing
takedown <domain> Generate automated abuse/takedown templates
user <sub> Manage daemon users (list|add|passwd|role|del)
daemon Start the background inbox-polling daemon + API
Each command runs directly against the local database and services — no web server, no login. Confirmed threats print their verdict, score breakdown, and generated Snort/Suricata IDS rules right in the terminal, and a forensic evidence PDF is available from the daemon API.
- Header forensics — SPF / DKIM / DMARC verification (hard vs soft fail), full relay-chain parsing, From/Reply-To/Return-Path spoofing detection.
- Content analysis — urgency, social-engineering tactics, credential/payment requests, newsletter detection.
- Link deep-analysis — URL masking, typosquatting (Levenshtein), homograph/IDN, shorteners, abused TLDs, redirect chains, WHOIS domain age, DNS/IP classification, live blocklist match.
- Advanced techniques — Unicode confusable-skeleton homoglyph detection (catches
pаypаl.com, punycodexn--decoded first), deceptive brand subdomains (paypal.com.secure-alert.ru), RLO/bidi & zero-width filename spoofs, and DGA / high-entropy domain scoring. - Domain intelligence — brand impersonation against a brand registry (global brands + PK institutions); locally-hosted phishing detection (kits on private IPs).
- Attachment analysis — dangerous types, double extensions (
invoice.pdf.exe), right-to-left-override extension spoofs, macro-enabled Office files, SHA-256 hashing. - AI Semantic Analysis — detects Business Email Compromise (BEC), executive impersonation, and urgent wire-transfer requests using an LLM integration that traditional rules miss.
- Transparent scoring — 0–100 with a per-signal breakdown and 5 severity bands.
- Forensic Evidence Reports — one-click export of highly detailed SOC PDF reports for ticketing and compliance.
- Brand Recon — resolves a brand's authentic domain, verifies it's live, generates typosquat/combosquat permutations, and reports which look-alikes are actually registered.
- URL Inspector — verdict (phishing / suspicious / legitimate) for any single link, even brand-new ones.
- Threat-intel feeds — OpenPhish + URLhaus (+ optional PhishTank) → local blocklist.
- DNS sinkhole — dependency-free UDP DNS server that answers blocked domains with a safe walled-garden page; exports to hosts / Pi-hole / dnsmasq / BIND RPZ.
- Secure Web Gateway — real-time allow/block policy (blocklist, newly-registered domains, abused TLDs, typosquats).
- Email-auth enforcement — SPF/DKIM/DMARC posture grading (A–F) + inbound rejection of protected-domain spoofing.
- Incident-response playbook — for every Medium/High/Critical email, auto-generates prioritised containment steps (block sender domain, sinkhole malicious URLs, SHA-256-based attachment quarantine, protect targeted accounts).
- IDS rule generation — deployable Snort 3 and Suricata signatures built from the email's own indicators (HTTP host, DNS query, file hash), with stable SIDs and sanitised content — validated to load cleanly under
snort -T/suricata -T.
- Unified command-line toolkit (
mailguardpro) —inbox,scan,check,recon,inspect,takedown,user,daemon— all self-contained against the local DB, no server required. - Optional headless daemon (live IMAP polling, threat-feed refresh, DNS sinkhole) + JSON API, CSV/PDF export, analyst-verdict calibration, false-positive safeguards.
- Dockerized (non-root container, unprivileged sinkhole port, HEALTHCHECK) for the daemon.
- Multi-user authentication + RBAC — scrypt-hashed accounts with admin / analyst / viewer roles; session login via HMAC-signed httpOnly cookie gates every
/apiroute. Manage users from the terminal (npm run user); an initial admin is seeded on first boot. - Audit trail — every login, logout, verdict, blocklist/protected-domain change and user-management action is written to an
audit_log(readable via/auth/audit, admin only). - Brute-force lockout & rate-limiting — login locks an IP after repeated failures; the expensive scan/recon endpoints are throttled.
- Locked-down CORS — same-origin by default; cross-origin only via an explicit
CORS_ORIGINallowlist (never*). - Strict Content-Security-Policy + helmet security headers.
- SSRF protection — server-side fetches of user-supplied URLs are blocked from private/loopback/link-local (cloud-metadata)/reserved addresses, with the validated IP pinned into the connection to defeat DNS rebinding.
Runs out of the box in demo mode (bundled sample emails, no credentials needed).
git clone https://github.com/Un-9oon/mailguard-pro.git
cd mailguard-pro
cp .env.example .env # DEMO_MODE=true by default
npm install
npm rebuild better-sqlite3 # build the native DB module (once)
npm link # optional: put `mailguardpro` on your PATH
mailguardpro inbox # analyse the bundled sample inboxThe core terminal tools (use mailguardpro <cmd>, or node bin/cli.js <cmd>, or the npm run alias):
mailguardpro inspect https://paypaal.com # verdict for a single URL
mailguardpro check example.com # inspect a domain
mailguardpro recon paypal # discover registered look-alikes
mailguardpro scan au.edu.pk # full health + verdict + look-alikes
mailguardpro takedown paypaal.com # abuse/takedown templatesnpm start # headless daemon + JSON API
# or containerised:
docker-compose up -d --buildFor live Gmail: enable 2-Step Verification, create an App Password, set IMAP_USER / IMAP_PASSWORD / DEMO_MODE=false in .env, then npm start.
Email → Parser → ┌─ Header forensics (SPF/DKIM/DMARC, spoofing, routing)
├─ Content analysis (urgency, social engineering)
├─ Link analysis (typosquat, redirects, WHOIS, blocklist)
├─ Domain intel (brand impersonation, locally-hosted kits)
├─ Attachment scan (dangerous types, macros, RLO, hashes)
├─ Email-auth enforcement (protected-domain spoofing)
└─ AI semantic analysis (optional — BEC/impersonation)
↓
Scoring engine (0–100, transparent weights)
↓
Verdict + breakdown → SQLite → terminal CLI (+ daemon API)
↓
If Medium/High/Critical → response playbook + Snort/Suricata rules → evidence PDF
Every stage is fault-isolated: one failure (e.g. a WHOIS timeout) never aborts the analysis.
Severity bands: 0–20 Clean · 21–40 Low · 41–60 Medium · 61–80 High · 81–100 Critical
| Layer | Technology |
|---|---|
| Runtime | Node.js 18+ |
| Interface | Node CLI dispatcher (bin/cli.js) |
| Database | SQLite (better-sqlite3) |
| Email (live) | IMAP — imapflow + mailparser |
| Daemon/API (optional) | Express + helmet |
| Reports | pdfkit (forensic evidence PDFs) |
- 📘 Complete Guide (PDF) — every feature explained with step-by-step instructions, worked examples, config, API, and a glossary.
- 📄 Technical Report — architecture and design deep-dive.
| Test | Result |
|---|---|
| Legitimate-email corpus — High/Critical false positives | 0% (target < 5%) |
| Confirmed PayPal phishing sample | 100 / Critical |
| Legitimate Google alert | 0 / Clean |
Homoglyph impersonation (pаypаl.com, Cyrillic) |
detected → Critical |
| Advanced-technique unit tests | 14 / 14 pass |
| Generated IDS rules | load clean under snort -T (3.12) + suricata -T (8.0.6) |
Brand Recon (paypal.com) |
74 live look-alikes in ~10 s |
| DNS sinkhole | blocked domain → sinkhole IP |
| Email-auth enforcement | spoof → reject, legit → deliver |
- Scheduled posture monitoring for protected domains.
- Provider-native AI clients (Anthropic) + cached AI verdicts.
MailGuard Pro is a defensive security tool intended for authorised use on your own mailboxes and infrastructure. Configure PROTECTED_DOMAINS, threat feeds, and the DNS sinkhole responsibly and in line with your organisation's policies.
Released under the MIT License — see LICENSE.