mailuminati/guardian repository overview

⁠Mailuminati Guardian

Guardian is a high-performance, scalable spam/phishing detection and enforcement service designed to run next to your MTA and filtering engine.

It analyzes incoming emails ultra-fast (structure fingerprinting + proximity detection), applies immediate local learning from operator/user reports, and only reaches out to the Mailuminati Oracle when needed for shared, collaborative intelligence.

Guardian is built for anyone operating email infrastructure, from large providers to small and community-run servers, who wants fast decisions with minimal overhead.

-> https://github.com/Mailuminati/Guardian⁠

---

For Docker installations: Configuration is primarily managed via environment variables in docker-compose.yaml.

The following variables are available:

The last variables allow operators to fine-tune the impact of spam and ham reports on the local learning database. Adjust these values based on your specific requirements and the desired sensitivity of the system.

---

⁠Role in the Mailuminati Ecosystem

Guardian is responsible for:

• Local spam/phishing analysis of incoming emails
• Structural fingerprinting using TLSH
• Fast proximity detection via locality sensitive hashing (LSH)
• Immediate application of local learning
• Remote confirmation through the Mailuminati Oracle
• Enforcing final decisions (allow, spam, proximity match)

It acts as the first line of defense, minimizing latency and resource usage, while remaining connected to a broader community driven detection network.

---

⁠Local Intelligence vs Shared Intelligence

Guardian is built around a clear separation of concerns.

⁠Local Intelligence

Local analysis and learning allow Guardian to:

• Apply new detections immediately after a report
• Adapt instantly to operator specific threats and campaigns
• Remain effective even when disconnected from the Oracle
• Keep latency close to zero for the majority of messages

This ensures that confirmed spam or phishing reports have an instant impact on subsequent mail flows for the same operator.

⁠Shared Intelligence via the Oracle

The Mailuminati Oracle provides the indispensable collaborative dimension:

• Cross operator correlation of campaigns
• Shared clusters built from independent reports
• Protection against large scale or fast moving threats
• Early detection of campaigns unseen locally

By querying the Oracle only when meaningful proximity is detected, Guardian benefits from collective intelligence without sacrificing performance or privacy.