Feature: Link Guard - URL rewriting and click-time protection for inbound email

[deeztek]

Summary

Implement URL rewriting for inbound emails that redirects all links through a Hermes safe-link proxy endpoint. When a user clicks a rewritten link, Hermes checks the URL against malicious URL services (e.g., VirusTotal, Google Safe Browsing) before redirecting the user to the original destination. Outbound emails should have rewritten URLs restored to their original form.

Why

URL-based phishing and malware delivery is one of the most common email attack vectors. Even if an email passes spam/virus checks at delivery time, the linked URL may become malicious after delivery (delayed weaponization). Safe-link rewriting protects users at click-time, not just at delivery time.

Inbound Flow

1. Email arrives and passes through Amavis content filtering
2. Before delivery to mailbox (or relay), a URL rewriting filter processes the message body
3. All URLs (http/https) in the email body are replaced with a Hermes proxy URL:
   • Original: https://example.com/page
   • Rewritten: https://hermes-console/safe-link?url=<encoded-original>&token=<HMAC>
4. The HMAC token prevents tampering with the encoded URL
5. Email is delivered with rewritten URLs

Click-Time Checking

1. User clicks rewritten link in their email client
2. Browser hits Hermes /safe-link endpoint
3. Hermes decodes and validates the URL (HMAC check)
4. Hermes checks the URL against one or more threat intelligence services:
   • VirusTotal API (free tier: 4 req/min, 500 req/day)
   • Google Safe Browsing API (free tier: 10,000 req/day)
   • URLhaus (free, no API key needed)
   • Cache results to reduce API calls
5. If safe: redirect user to original URL
6. If malicious: show warning page with option to proceed or go back
7. If service unavailable: configurable behavior (allow with warning, or block)

Outbound Flow

1. When an email is sent outbound (relay), check if it contains Hermes rewritten URLs
2. Restore all rewritten URLs to their original form before sending
3. This prevents Hermes internal URLs from leaking to external recipients

Admin Settings

• Enable/disable URL rewriting globally
• Choose threat intelligence provider(s)
• API key configuration for VirusTotal/Google Safe Browsing
• Cache TTL for URL check results
• Whitelist domains that should never be rewritten (e.g., internal domains)
• Action on service unavailable (allow/warn/block)

Technical Considerations

• URL rewriting could be done via Amavis custom hook, a Postfix content filter, or a Sieve filter
• The safe-link endpoint should be publicly accessible (no Authelia) since email recipients click from external clients
• HMAC signing prevents URL manipulation
• Consider database table for caching URL check results with TTL
• Rate limiting on the safe-link endpoint to prevent abuse
• Handle HTML emails (rewrite href attributes) and plain text emails (rewrite bare URLs)

Similar Products

• Microsoft Defender Safe Links
• Proofpoint URL Defense
• Mimecast URL Protect
• Barracuda Link Protection

Dependencies

• Dovecot mailbox implementation (Dovecot Implementation - Master Issue #148) for local delivery
• Public endpoint infrastructure (similar to quarantine release at /user-auth/)

[deeztek]

Implementation plan created at docs/URL-SAFE-LINKS-IMPLEMENTATION.md.

Approach: Python milter (pymilter) as a standalone Docker container (hermes_url_rewriter).

Key decisions:

• Python milter over Amavis hook (safer — bugs won't crash mail flow)
• URLhaus as primary free threat intelligence (no API key, no rate limits)
• Optional VirusTotal and Google Safe Browsing with API keys
• Click-time checking (privacy: URLs only checked when clicked, not at delivery)
• HMAC-signed rewritten URLs with configurable expiry
• Outbound stripping to prevent internal URLs leaking externally
• Anti-abuse: recursive URL unwrapping with depth limit

Estimated effort: 7-12 sessions across 6 phases.

Note: No existing open-source implementation of email safe-link URL rewriting exists. Hermes would be the first.