Zetian.AntiSpam 1.0.4

Zetian.AntiSpam - Advanced Spam Protection for SMTP

Comprehensive anti-spam solution for Zetian SMTP Server with multiple detection methods, machine learning, and flexible configuration options.

⚡ Features

• 📊 Statistics - Detailed metrics and reporting
• 🚫 RBL/DNSBL - Realtime blackhole list checking
• 🔧 Extensible - Easy to add custom spam checkers
• 📧 DKIM/DMARC - Email authentication protocols
• 🛡️ SPF Validation - Sender Policy Framework verification
• ⏱️ Greylisting - Temporary rejection for unknown senders
• ⚡ High Performance - Parallel checking with timeout support
• 🤖 Bayesian Filtering - Machine learning-based spam detection

📦 Installation

# Install Zetian SMTP Server (required)
dotnet add package Zetian

# Install AntiSpam Extension
dotnet add package Zetian.AntiSpam

🚀 Quick Start

Basic Anti-Spam Setup

using Zetian.Server;
using Zetian.AntiSpam.Extensions;

// Create SMTP server
var server = new SmtpServerBuilder()
    .Port(25)
    .ServerName("My SMTP Server")
    .Build();

// Add anti-spam with default settings
server.AddAntiSpam();

await server.StartAsync();

Custom Configuration

// Configure anti-spam features
server.AddAntiSpam(builder => builder
    .EnableSpf(failScore: 50)
    .EnableRbl("zen.spamhaus.org", "bl.spamcop.net")
    .EnableBayesian(spamThreshold: 0.85)
    .EnableGreylisting(initialDelay: TimeSpan.FromMinutes(5))
    .WithOptions(options =>
    {
        options.RejectThreshold = 60;
        options.TempFailThreshold = 40;
        options.RunChecksInParallel = true;
    }));

Aggressive Protection

// Use aggressive anti-spam settings
server.AddAntiSpam(builder => builder.UseAggressive());

Lenient Protection

// Use lenient settings for trusted environments
server.AddAntiSpam(builder => builder.UseLenient());

🎯 Individual Features

SPF Checking Only

server.AddSpfCheck(failScore: 50);

RBL/DNSBL Checking

server.AddRblCheck(
    "zen.spamhaus.org",
    "bl.spamcop.net",
    "b.barracudacentral.org"
);

Greylisting

// Add greylisting
server.AddGreylisting(initialDelay: TimeSpan.FromMinutes(5));

// Note: Domain whitelisting needs to be done at greylisting creation
// or by accessing the GreylistingChecker directly
var greylistingChecker = new GreylistingChecker(
    initialDelay: TimeSpan.FromMinutes(5));
greylistingChecker.Whitelist("trusted.com");
server.AddSpamChecker(greylistingChecker);

Bayesian Filtering

// Option 1: Add Bayesian to server
server.AddBayesianFilter(spamThreshold: 0.9);

// Option 2: Work with Bayesian directly for training
var bayesianFilter = new BayesianSpamFilter(spamThreshold: 0.9);
await bayesianFilter.TrainSpamAsync("spam content");
await bayesianFilter.TrainHamAsync("legitimate content");

// Then add trained filter to server
server.AddSpamChecker(bayesianFilter);

DKIM Signature Verification

// Add DKIM checking with strict mode
server.AddDkimCheck(
    failScore: 40,
    strictMode: true  // Require all essential headers to be signed
);

DMARC Policy Enforcement

// Add DMARC checking with policy enforcement
server.AddDmarcCheck(
    failScore: 70,        // Score for reject policy
    quarantineScore: 50,  // Score for quarantine policy
    enforcePolicy: true   // Enforce DMARC policies
);

Complete Email Authentication (SPF + DKIM + DMARC)

// Add all three authentication methods in one call
server.AddEmailAuthentication(
    strictMode: true,      // Strict DKIM validation
    enforcePolicy: true    // Enforce DMARC policies
);

// Or use the builder pattern
server.AddAntiSpam(builder => builder
    .EnableEmailAuthentication(strictMode: true, enforcePolicy: true)
    .WithOptions(options => {
        options.RejectThreshold = 60;
        options.EnableDetailedLogging = true;
    }));

🔧 Advanced Configuration

Custom Spam Checker

using Zetian.AntiSpam.Abstractions;

public class CustomSpamChecker : ISpamChecker
{
    public string Name => "Custom";
    public bool IsEnabled { get; set; } = true;

    public async Task<SpamCheckResult> CheckAsync(
        ISmtpMessage message,
        ISmtpSession session,
        CancellationToken cancellationToken)
    {
        // Custom logic here
        if (IsSpam(message))
        {
            return SpamCheckResult.Spam(75, "Custom rule triggered");
        }
        
        return SpamCheckResult.Clean(0);
    }
}

// Add custom checker
server.AddSpamChecker(new CustomSpamChecker());

Builder Pattern

var builder = new AntiSpamBuilder()
    .WithDnsClient(customDnsClient)
    .EnableSpf()
    .EnableRbl(new[]
    {
        new RblProvider
        {
            Name = "Custom RBL",
            Zone = "custom.rbl.org",
            ExpectedResponses = ["127.0.0.2"]
        }
    })
    .EnableBayesian()
    .AddChecker(new CustomSpamChecker());

var antiSpamService = builder.Build();

📊 Monitoring & Statistics

// Get anti-spam statistics
// NOTE: Currently returns empty stats due to implementation limitations
// Future versions will properly track statistics
var stats = server.GetAntiSpamStatistics();
Console.WriteLine($"Messages Checked: {stats.MessagesChecked}");
Console.WriteLine($"Messages Blocked: {stats.MessagesBlocked}");
Console.WriteLine($"Block Rate: {stats.BlockRate:F1}%");

// Work with Bayesian filter directly
var bayesianFilter = new BayesianSpamFilter();
await bayesianFilter.TrainSpamAsync("spam content here");
await bayesianFilter.TrainHamAsync("legitimate content here");

// Get Bayesian statistics
var bayesianStats = bayesianFilter.GetStatistics();
Console.WriteLine($"Total Spam Messages: {bayesianStats.TotalSpamMessages}");
Console.WriteLine($"Total Ham Messages: {bayesianStats.TotalHamMessages}");
Console.WriteLine($"Unique Words: {bayesianStats.UniqueWords}");

🎓 Training Bayesian Filter

From Files

// Create and train Bayesian filter
var bayesianFilter = new BayesianSpamFilter();

// Load training data
var spamEmails = Directory.GetFiles("spam/", "*.eml")
    .Select(File.ReadAllText);

var hamEmails = Directory.GetFiles("ham/", "*.eml")
    .Select(File.ReadAllText);

// Train the filter
foreach (var spam in spamEmails)
{
    await bayesianFilter.TrainSpamAsync(spam);
}

foreach (var ham in hamEmails)
{
    await bayesianFilter.TrainHamAsync(ham);
}

// Add trained filter to server
server.AddSpamChecker(bayesianFilter);

Interactive Training

// Create Bayesian filter for training
var bayesianFilter = new BayesianSpamFilter();
server.AddSpamChecker(bayesianFilter);

server.MessageReceived += async (sender, e) =>
{
    // Let user classify messages
    if (UserMarksAsSpam(e.Message))
    {
        var content = ExtractContent(e.Message);
        await bayesianFilter.TrainSpamAsync(content);
    }
};

🛠️ Score Interpretation

🔍 SPF Results

🔐 DKIM Results

📋 DMARC Results

🌐 Default RBL Providers

• SpamCop - User-reported spam
• Barracuda - Commercial spam database
• Spamhaus ZEN - Comprehensive spam/exploit list
• SORBS - Multiple spam databases (disabled by default)
• UCEPROTECT - Aggressive blocking (disabled by default)

⚙️ Configuration Options

public class AntiSpamOptions
{
    // Score threshold for rejection (default: 50)
    public double RejectThreshold { get; set; }
    
    // Score threshold for temp failure (default: 30)
    public double TempFailThreshold { get; set; }
    
    // Run checks in parallel (default: true)
    public bool RunChecksInParallel { get; set; }
    
    // Timeout per checker (default: 10 seconds)
    public TimeSpan CheckerTimeout { get; set; }
    
    // Continue after spam detection (default: false)
    public bool ContinueOnSpamDetection { get; set; }
    
    // Enable detailed logging (default: false)
    public bool EnableDetailedLogging { get; set; }
}

📚 Best Practices

1. Regular Updates - Keep RBL lists and training data current
2. Whitelist Partners - Add trusted partners to greylisting whitelist
3. Train Bayesian - Provide adequate training data for better accuracy
4. Monitor Statistics - Regularly review block rates and adjust thresholds
5. Use Multiple Methods - Combine different checkers for better detection
6. Start Conservative - Begin with lenient settings and adjust based on false positives

🔒 Security Considerations

• Bayesian filters need balanced training data
• Greylisting may delay legitimate mail initially
• RBL queries may expose client IPs to third parties
• SPF checks require DNS lookups - ensure reliable DNS

🚀 Performance Tips

• Limit RBL providers to essential ones
• Set appropriate timeouts for DNS queries
• Pre-train Bayesian filter before deployment
• Use caching DNS client for repeated lookups
• Enable parallel checking for better performance

📋 Requirements

• Windows, Linux, or macOS
• .NET 6.0, 7.0, 8.0, 9.0, or 10.0
• Zetian SMTP Server package
• DnsClient.NET for DNS lookups

📚 Documentation & Support

• Issues: GitHub Issues
• Examples: GitHub Examples
• Discussions: GitHub Discussions
• Documentation: Zetian Documentation

📄 License

MIT License - see LICENSE

Built with ❤️ for the .NET community