Amavisd Threat Intelligence Plugin

Integrate real-time phishing, malware, and spam detection into your Amavisd-new mail server using the AfterDark threat intelligence services.

View on GitHub v1.0.0 MIT License
This plugin integrates with DNSScience.io (DNS security, DNSBL) and BetterPhish.io (phishing intelligence) to provide comprehensive email threat detection.

Features

IP Reputation

Check sender IPs against DNSBL and API-based threat intelligence databases.

URL Analysis

Scan URLs in message body against phishing databases and reputation services.

Hash Lookups

Check attachment hashes (SHA256) against malware signature databases.

AI Detection

Machine learning-powered phishing detection via BetterPhish API.

Configurable Actions

REJECT, QUARANTINE, TAG, or SCORE per threat type.

Built-in Caching

Intelligent caching minimizes API calls and latency.

Requirements

  • Amavisd-new 2.11.0 or later
  • Perl 5.14+
  • Perl modules (most are core modules):
    • Net::DNS (usually pre-installed with amavisd)
    • HTTP::Tiny (core in Perl 5.14+)
    • JSON::PP (core module)
    • Digest::SHA (core module)
    • Storable (core module)

Quick Install

Use the automated installer script:

Bash 
# Clone the repository
git clone https://github.com/afterdarksys/betterphish-amavisd-plugin.git
cd betterphish-amavisd-plugin

# Run the installer
sudo ./install.sh

# Edit configuration with your API keys
sudo nano /etc/amavisd/conf.d/99-afterdark-threatintel.conf

# Add include to amavisd.conf
echo "include('/etc/amavisd/conf.d/99-afterdark-threatintel.conf');" | sudo tee -a /etc/amavisd/amavisd.conf

# Restart amavisd
sudo systemctl restart amavisd

Manual Installation

1. Install the Plugin Module

Bash 
# Create directory structure
sudo mkdir -p /usr/local/lib/amavisd/AfterDark/Amavis

# Copy the plugin module
sudo cp AfterDark/Amavis/ThreatIntel.pm /usr/local/lib/amavisd/AfterDark/Amavis/

# Set permissions
sudo chown root:root /usr/local/lib/amavisd/AfterDark/Amavis/ThreatIntel.pm
sudo chmod 644 /usr/local/lib/amavisd/AfterDark/Amavis/ThreatIntel.pm

2. Install Configuration

Bash 
# Create conf.d directory if needed
sudo mkdir -p /etc/amavisd/conf.d

# Copy configuration template
sudo cp conf.d/99-afterdark-threatintel.conf /etc/amavisd/conf.d/

# Edit and add your API keys
sudo nano /etc/amavisd/conf.d/99-afterdark-threatintel.conf

3. Include in amavisd.conf

Add this line to your /etc/amavisd/amavisd.conf (near the end):

Perl 
include('/etc/amavisd/conf.d/99-afterdark-threatintel.conf');

4. Create Cache Directory

Bash 
sudo mkdir -p /var/lib/amavis
sudo chown amavis:amavis /var/lib/amavis
sudo chmod 750 /var/lib/amavis

5. Restart Amavisd

Bash 
sudo systemctl restart amavisd

# Verify installation
grep -i "afterdark" /var/log/maillog
# Should see: "AfterDark::Amavis::ThreatIntel v1.0.0 initializing"

Get API Keys

DNSScience API Key (Recommended)

  1. Go to dnsscience.io
  2. Create an account or sign in
  3. Navigate to Dashboard → API Keys
  4. Generate a new API key

BetterPhish API Key (Optional)

  1. Go to BetterPhish Pricing
  2. Choose a plan that includes API access
  3. Your API key will be provided after signup
Note: Basic DNSBL lookups work without API keys, but rate limits apply. API keys unlock full threat intelligence capabilities.

Master Controls

VariableDefaultDescription
$afterdark_enabled 1 Master switch for the entire plugin
$dnsscience_enabled 1 Enable DNSScience integration
$betterphish_enabled 1 Enable BetterPhish integration

API Configuration

VariableDefaultDescription
$dnsscience_api_key '' Your DNSScience API key
$dnsscience_api_url 'https://api.dnsscience.io/v1' DNSScience API base URL
$dnsscience_dnsbl_zone 'dnsbl.dnsscience.io' DNSBL zone for IP lookups
$betterphish_api_key '' Your BetterPhish API key
$betterphish_api_url 'https://api.betterphish.io/v1' BetterPhish API base URL

Check Types

VariableDefaultDescription
$afterdark_check_ips 1 Check sender IP addresses
$afterdark_check_urls 1 Check URLs in message body
$afterdark_check_hashes 1 Check attachment file hashes

Actions

Configure what happens when threats are detected. Available actions:

  • REJECT - Reject with 5xx SMTP error
  • QUARANTINE - Accept but quarantine the message
  • TAG - Accept but add headers indicating threat
  • SCORE - Add spam score points only
  • PASS - Take no action (just log)
VariableDefaultDescription
$afterdark_action_on_phishing 'REJECT' Action for phishing URLs/domains
$afterdark_action_on_malware 'REJECT' Action for malware attachments
$afterdark_action_on_spam_source 'SCORE' Action for known spam sources

Spam Scoring

Scores added to SpamAssassin when threats are detected (applies when action is SCORE or TAG):

VariableDefaultDescription
$afterdark_spam_score_phishing 10.0 Score for confirmed phishing
$afterdark_spam_score_malware 15.0 Score for confirmed malware
$afterdark_spam_score_suspicious 3.0 Score for suspicious/spam source IPs

Caching & Performance

VariableDefaultDescription
$afterdark_cache_enabled 1 Enable result caching
$afterdark_cache_ttl 3600 Cache TTL in seconds (1 hour)
$afterdark_cache_file '/var/lib/amavis/afterdark_cache.db' Cache file path
$afterdark_timeout 5 API request timeout (seconds)
$afterdark_add_headers 1 Add X-AfterDark-* headers
$afterdark_log_level 2 0=none, 1=errors, 2=info, 3=debug

Headers Added

When threats are detected, the following headers are injected:

Email Headers 
X-AfterDark-ThreatIntel: version=1.0.0; score=10.0; action=REJECT; threats=1
X-AfterDark-Threat-1: type=url; value=http://phish.example.com; threat=phishing; score=10.0; sources=betterphish
X-AfterDark-DNSScience: enabled
X-AfterDark-BetterPhish: enabled

DNSBL Return Codes

When querying dnsbl.dnsscience.io, return codes indicate threat types:

Return CodeThreat Type
127.0.0.1Spam source
127.0.0.2Malware
127.0.0.3Phishing
127.0.0.4Botnet
127.0.0.5Exploit
127.0.0.6Proxy
127.0.0.7Suspicious

SpamAssassin Integration

Create custom SpamAssassin rules that trigger on AfterDark headers:

/etc/spamassassin/local.cf 
# Match AfterDark threat headers
header   AFTERDARK_PHISHING X-AfterDark-ThreatIntel =~ /threat=phishing/i
score    AFTERDARK_PHISHING 5.0
describe AFTERDARK_PHISHING AfterDark detected phishing

header   AFTERDARK_MALWARE X-AfterDark-ThreatIntel =~ /threat=malware/i
score    AFTERDARK_MALWARE 8.0
describe AFTERDARK_MALWARE AfterDark detected malware

Testing

Test DNSBL Lookup

Bash 
# Test with reversed test IP
dig +short 1.0.0.127.dnsbl.dnsscience.io A
dig +short 1.0.0.127.dnsbl.dnsscience.io TXT

Test API Connectivity

Bash 
# Test DNSScience API
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.dnsscience.io/v1/threat-intel/reputation?domain=example.com"

# Test BetterPhish API
curl "https://api.betterphish.io/v1/lookup?url=https://example.com"

Verify Plugin Loading

Bash 
# Check Perl can load the module
perl -I/usr/local/lib/amavisd -e 'use AfterDark::Amavis::ThreatIntel; print "OK\n"'

Troubleshooting

Plugin Not Loading

Bash 
# Test if Perl can find and load the module
perl -I/usr/local/lib/amavisd -e 'use AfterDark::Amavis::ThreatIntel; print "OK\n"'

# If it fails, check the error message for missing dependencies

API Timeouts

Increase timeout if you have slow connectivity:

Perl 
$afterdark_timeout = 10;  # 10 seconds

Cache Issues

Clear the cache if you see stale results:

Bash 
sudo rm /var/lib/amavis/afterdark_cache.db
sudo systemctl restart amavisd

Enable Debug Logging

Perl 
$afterdark_log_level = 3;  # Debug mode

Then monitor logs:

Bash 
tail -f /var/log/maillog | grep -i afterdark
Need more help? Check the GitHub repository for issues and discussions, or email support@afterdarksys.com.