phishguard 1.0.0

Email phishing and spam detection library with built-in REST API

phishdetect

Email phishing and spam detection library — drop it into any Python project or run it as a standalone REST API on your mail server.

Install

pip install phishdetect

Use as a Python library

from phishdetect import PhishingDetector

detector = PhishingDetector()

result = detector.analyze({
    "sender":   "[e-mail]",
    "subject":  "Urgent: verify your account NOW!!",
    "content":  "Click here to reset your password immediately.",
    "reply_to": "",   # optional
})

print(result["risk_score"])   # "HIGH", "MEDIUM", or "LOW"
print(result["risk_level"])   # 0–100 numeric score
print(result["warnings"])     # detailed list of every signal found

Integrate with your mail server

from phishdetect import PhishingDetector

detector = PhishingDetector()

def on_email_received(email):
    result = detector.analyze({
        "sender":  email.from_address,
        "subject": email.subject,
        "content": email.body,
    })

    if result["risk_score"] == "HIGH":
        quarantine(email)
    elif result["risk_score"] == "MEDIUM":
        add_warning_banner(email)
    else:
        deliver(email)

Run as a REST API server

phishdetect-server
# Server starts at http://0.0.0.0:5000

API endpoints

Method	Endpoint	Description
POST	/analyze	Analyze an email for phishing
GET	/health	Health check
GET	/status	Domain intelligence database info
POST	/update	Refresh the Tranco domain list

Example API call

curl -X POST http://localhost:5000/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "sender":  "[e-mail]",
    "subject": "Urgent: verify your account",
    "content": "Click here to reset your password."
  }'

What it detects

• Lookalike domains — paypa1.com vs paypal.com (Levenshtein distance)
• Homoglyph attacks — Unicode characters that look like Latin letters (е, о, а)
• Subdomain abuse — paypal.attacker.com pretending to be PayPal
• Suspicious keywords — urgency, financial fraud, prize/lottery patterns
• Deceptive links — visible URL differs from actual href destination
• Reply-To mismatch — replies routed to a different domain
• New domains — recently registered domains flagged via WHOIS
• Spam signals — ALL CAPS subjects, excessive exclamation marks, bulk patterns

How the domain database works

On first run, phishdetect automatically downloads the Tranco top-1M domain list and stores the top 50,000 domains in a local SQLite database at ~/.phishdetect/phishing.db. This refreshes weekly. No API key required.

License

MIT