MailGuard

MailGuard is a self-hosted email security tool that monitors your Gmail inbox, flags phishing attempts, and uses a local AI model to summarize emails and surface what actually needs your attention.

---

---

What it does

• Fetches emails from one or more Gmail accounts via IMAP every 60 seconds
• Detects phishing by checking SPF, DKIM, DMARC headers and sender spoofing — emails scoring ≥ 70 are flagged and skipped
• Summarizes emails using a local LLM (Gemma 3), assigning a priority (1–5) and flagging action items
• Web dashboard — a Flask UI showing your inbox, stats, and live processing status
• TUI mode — a terminal dashboard built with rich for a quick overview without a browser

---

Requirements

• Python 3.10+
• A Gmail account with IMAP enabled and an App Password
• A local LLM server running at http://localhost:8909 (compatible with the /api/v1/chat endpoint, e.g. LM Studio or a custom wrapper)

---

Setup

1. Clone the repo

git clone https://github.com/your-username/mailguard.git
cd mailguard

2. Install dependencies

pip install flask requests rich

3. Configure your accounts

Create an accounts.json file in the project root:

[
  {
    "name": "Personal",
    "user": "you@gmail.com",
    "pass": "your-app-password"
  }
]

Use a Gmail App Password, not your regular password.

4. Start your LM Studio local LLM server on port 8909 with a model like google/gemma-3-4b.

LM studio

5. Run MailGuard

python main.py

This starts the background worker and opens the web dashboard at http://localhost:5000.

---

TUI mode

If you prefer the terminal:

python mailguard.py
python mailguard.py --db /path/to/mail_storage.db --refresh 10

---

Project structure

mailguard/
├── main.py              # Flask app + background worker
├── mailguard.py         # Terminal UI (rich)
├── accounts.json        # Your email credentials (not committed)
├── imap/
│   └── FetchMail.py     # IMAP fetcher + phishing check trigger
├── model/
│   ├── PhishingCheck.py # Header-based phishing scorer
│   └── MailSummary.py   # LLM summarization
└── utils/
    ├── db.py            # SQLite helpers
    └── HtmlSanitizer.py # Email body cleaning

---

Notes

• Email data is stored locally in mail_storage.db (SQLite)
• accounts.json is in .gitignore — keep it that way
• The LLM runs locally; no email content is sent to any external API