• Foreword
• Installation
  • npm (Recommended)
  • Standalone Binary (No Node.js Required)
  • ClamAV Installation (Optional)
• CLI (Command Line Interface)
  • CLI Installation
  • Commands
  • Exit Codes
  • CLI Examples
• Why Spam Scanner
  • Key Advantages
• Features
  • Core Detection Features
  • Naive Bayes Classifier
  • Phishing Detection
  • Virus Scanning
  • Executable Detection
  • NSFW Image Detection
  • Toxicity Detection
  • Macro Detection
  • Language Detection
  • Pattern Recognition
  • URL Analysis
• Comparison
  • Spam Scanner vs. Alternatives
• Architecture
  • System Overview
  • Detection Flow
  • Component Architecture
• Requirements
  • System Requirements
  • Dependencies
• Quick Start
  • Basic Usage
  • With Configuration
  • Checking Specific Features
• API Documentation
  • Constructor Options
  • Methods
  • Result Object
• Advanced Usage
  • Custom Classifier
  • Custom Text Replacements
  • Language Filtering
  • Performance Monitoring
  • Selective Feature Disabling
  • Custom Timeout
  • Custom Logger
• ARF (Abuse Reporting Format)
  • Parsing ARF Reports
  • Creating ARF Reports
  • ARF Result Object
• Mail Server Integration
  • Postfix Integration
  • Dovecot Integration
  • TCP Server Mode
• Performance
  • Benchmarks
  • Optimization Tips
  • Memory Usage
• Contributing
  • Development Setup
  • Running Tests
• License
• Support
• Acknowledgments

Spam Scanner is a tool and service created after hitting countless roadblocks with existing spam-detection solutions. In other words, it's our current plan for spam and our better plan for spam.

Our goal is to build and utilize a scalable, performant, simple, easy to maintain, and powerful API for use in our service at Forward Email to limit spam and provide other measures to prevent attacks on our users.

Initially we tried using SpamAssassin, and later evaluated rspamd – but in the end we learned that all existing solutions (even ones besides these) are overtly complex, missing required features or documentation, incredibly challenging to configure; high-barrier to entry, or have proprietary storage backends (that could store and read your messages without your consent) that limit our scalability.

To us, we value privacy and the security of our data and users – specifically we have a "Zero-Tolerance Policy" on storing logs or metadata of any kind, whatsoever (see our Privacy Policy for more on that). None of these solutions honored this privacy policy (without removing essential spam-detection functionality), so we had to create our own tool – thus "Spam Scanner" was born.

npm install spamscanner

For CLI usage:

# Install globally
npm install -g spamscanner

# Or use npx without installing
npx spamscanner scan email.eml

Download a pre-built binary for your platform. These are self-contained executables that don't require Node.js.

See CLI Installation for download links and platform-specific instructions.

brew install clamav
freshclam

sudo apt-get update
sudo apt-get install clamav clamav-daemon
sudo freshclam
sudo systemctl start clamav-daemon

sudo yum install clamav clamav-update
sudo freshclam

SpamScanner provides a command-line interface for scanning emails directly from the terminal or integrating with mail servers.

SpamScanner can be installed via npm or as a standalone binary. The standalone binary includes Node.js and all dependencies, so no additional runtime is required.

# Install globally
npm install -g spamscanner

# Or use npx without installing
npx spamscanner --help

# Download manually for Apple Silicon (M1/M2/M3)
curl -fsSL https://github.com/spamscanner/spamscanner/releases/latest/download/spamscanner-darwin-arm64 -o /usr/local/bin/spamscanner
chmod +x /usr/local/bin/spamscanner

# Download manually for Intel Mac
curl -fsSL https://github.com/spamscanner/spamscanner/releases/latest/download/spamscanner-darwin-x64 -o /usr/local/bin/spamscanner
chmod +x /usr/local/bin/spamscanner

# Download and install to /usr/local/bin
sudo curl -fsSL https://github.com/spamscanner/spamscanner/releases/latest/download/spamscanner-linux-x64 -o /usr/local/bin/spamscanner
sudo chmod +x /usr/local/bin/spamscanner
# Add to PATH if not already: export PATH="$HOME/.local/bin:$PATH"

# Or install to user directory (no sudo required)
mkdir -p ~/.local/bin
curl -fsSL https://github.com/spamscanner/spamscanner/releases/latest/download/spamscanner-linux-x64 -o ~/.local/bin/spamscanner
chmod +x ~/.local/bin/spamscanner
# Add to PATH if not already: export PATH="$HOME/.local/bin:$PATH"

# Using PowerShell (run as Administrator)
Invoke-WebRequest -Uri "https://github.com/spamscanner/spamscanner/releases/latest/download/spamscanner-win-x64.exe" -OutFile "C:\Program Files\spamscanner\spamscanner.exe"
# Add to PATH via System Properties > Environment Variables

# Or download to current directory
Invoke-WebRequest -Uri "https://github.com/spamscanner/spamscanner/releases/latest/download/spamscanner-win-x64.exe" -OutFile ".\spamscanner.exe"
# Add to PATH via System Properties > Environment Variables

# Check version
spamscanner version

# Check for updates
spamscanner update

SpamScanner CLI automatically checks for updates once every 24 hours and displays a notification if a new version is available. You can also manually check for updates:

# Check for updates
spamscanner update

# Disable automatic update checks
spamscanner scan email.eml --no-update-check

To update to the latest version, simply re-run the installation command for your platform or use npm:

# Update via npm
npm update -g spamscanner

# Or re-download the binary (macOS/Linux)
curl -fsSL https://github.com/spamscanner/spamscanner/releases/latest/download/spamscanner-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/x64/' | sed 's/aarch64/arm64/') -o /usr/local/bin/spamscanner
chmod +x /usr/local/bin/spamscanner

SpamScanner calculates a spam score based on multiple detection methods. You can configure which checks are included and customize the score weights.

Customize how much each detection type contributes to the total spam score:

For mail server integration, SpamScanner can add X-Spam headers to emails (similar to SpamAssassin and Stalwart):

X-Spam Headers Added:

These options configure the underlying SpamScanner engine:

Use ISO 639-1 language codes with the --languages option. Pass an empty string or all to enable all languages (default).

# Scan a file
spamscanner scan email.eml

# Scan from stdin (for Postfix integration)
cat email.eml | spamscanner scan -

# Scan with JSON output (includes score and tests)
spamscanner scan email.eml --json

# Scan with verbose output
spamscanner scan email.eml --verbose

# Scan with custom spam threshold
spamscanner scan email.eml --threshold 3.0

# Scan with only classifier and phishing checks
spamscanner scan email.eml --no-executables --no-macros --no-virus

# Scan and add X-Spam headers (for mail server integration)
spamscanner scan email.eml --add-headers

# Scan, add headers, and prepend [SPAM] to subject
spamscanner scan email.eml --add-headers --prepend-subject

# Scan with custom subject tag
spamscanner scan email.eml --add-headers --prepend-subject --subject-tag "[JUNK]"

# Enable NSFW and toxicity checks with custom weights
spamscanner scan email.eml --check-nsfw --check-toxicity --score-nsfw 5.0

# Start TCP server on custom port
spamscanner server --port 8080

# Start TCP server with custom threshold
spamscanner server --port 8080 --threshold 3.0

# Scan with specific language support (English, Spanish, French only)
spamscanner scan email.eml --languages en,es,fr

# Scan with mixed language detection enabled
spamscanner scan email.eml --mixed-language

# Scan with strict IDN/homograph detection
spamscanner scan email.eml --strict-idn

# Scan with custom NSFW threshold (more sensitive)
spamscanner scan email.eml --check-nsfw --nsfw-threshold 0.3

# Scan with custom ClamAV paths
spamscanner scan email.eml --clamscan-path /opt/clamav/bin/clamscan

{
  "isSpam": true,
  "score": 7.5,
  "threshold": 5.0,
  "tests": ["BAYES_SPAM(5.0)", "PHISHING_DETECTED(2.5)"],
  "message": "Spam",
  "results": {
    "classification": { "category": "spam", "probability": 0.95 },
    "phishing": [{ "type": "suspicious_link", "url": "http://example.com" }]
  },
  "headers": {
    "X-Spam-Status": "Yes, score=7.5 required=5.0 tests=BAYES_SPAM(5.0),PHISHING_DETECTED(2.5) version=6.0.1",
    "X-Spam-Score": "7.5",
    "X-Spam-Flag": "YES",
    "X-Spam-Tests": "BAYES_SPAM(5.0), PHISHING_DETECTED(2.5)"
  }
}

• 🔒 Privacy-First - Zero logging, zero metadata storage
• 🚀 Modern - Built with Node.js 18+, ES modules, and latest AI models
• 🎯 Accurate - 88%+ detection accuracy with Naive Bayes classifier
• ⚡ Fast - Scans emails in under 3 seconds (with model caching)
• 🛡️ Comprehensive - 10+ detection methods (virus, phishing, NSFW, toxicity, macros, etc.)
• 🌍 Multilingual - Supports 40+ languages with automatic detection
• 🔧 Easy to Use - Simple API, extensive documentation, TypeScript support
• 📊 Battle-Tested - Used in production at Forward Email

Spam Scanner includes modern, essential, and performant features that help reduce spam, phishing, and executable attacks.

Our Naive Bayesian classifier is available in this repository, the npm package, and is updated frequently as it gains upstream, anonymous, SHA-256 hashed data from Forward Email.

• Training Data: 100,000+ spam and ham emails
• Accuracy: 88%+ classification accuracy
• Languages: Supports 40+ languages with language-specific tokenization
• Stemming: Porter Stemmer for English, Snowball for 15+ other languages
• Privacy: All training data is anonymized and SHA-256 hashed

Advanced phishing detection using multiple techniques:

• IDN Homograph Detection: Detects lookalike domains (e.g., аpple.com using Cyrillic "а")
• Confusables Integration: Uses Unicode confusables database to detect character substitution
• TLD Analysis: Validates TLDs and detects suspicious domain patterns
• Link Analysis: Checks for mismatched display text and actual URLs
• Cloudflare Detection: Identifies domains blocked by Cloudflare

Integrates with ClamAV for comprehensive virus detection:

• Real-time Scanning: Scans all email attachments
• Buffer Support: Direct buffer scanning without file I/O
• Timeout Protection: Configurable scan timeouts
• Virus Database: Uses ClamAV's regularly updated virus definitions

Detects dangerous executable files:

• 195+ File Extensions: exe, dll, bat, vbs, ps1, scr, pif, cmd, com, etc.
• Magic Number Verification: Detects renamed executables by file content
• Office Macros: Detects macro-enabled Office documents (docm, xlsm, pptm)
• Legacy Office: Flags legacy Office formats (doc, xls, ppt) as high-risk
• PDF JavaScript: Detects malicious JavaScript in PDF files
• Archive Detection: Flags archives (zip, rar, 7z) that may hide executables

AI-powered image content analysis using TensorFlow.js:

• Categories: Porn, Hentai, Sexy, Neutral, Drawing
• Model: NSFWJS model trained on 60K+ images
• Threshold: Configurable detection threshold (default: 0.7)
• Performance: Model caching for fast subsequent scans
• Formats: Supports JPEG, PNG, GIF, WebP, BMP

Detects toxic language using TensorFlow.js Toxicity model:

• Categories: Identity attack, insult, obscenity, severe toxicity, sexual explicit, threat
• Threshold: Configurable toxicity threshold (default: 0.7)
• Languages: Optimized for English, supports other languages
• Performance: Model caching for fast subsequent scans

Detects malicious macros in email content and attachments:

• VBA Macros: Detects Visual Basic for Applications code
• PowerShell: Detects PowerShell scripts and commands
• JavaScript: Detects JavaScript code in emails
• Batch Scripts: Detects Windows batch files
• Office Documents: Scans docm, xlsm, pptm, xlam, dotm, xltm, potm
• PDF JavaScript: Detects JavaScript in PDF attachments

Hybrid language detection using franc and lande:

• 40+ Languages: Supports all major world languages
• Automatic Detection: Detects language from email content
• Fallback System: Uses lande when franc returns "undetermined"
• Mixed Language Support: Optional mixed language detection
• Language Filtering: Filter results to supported languages only

Detects various patterns in email content:

• Credit Cards: Visa, MasterCard, Amex, Discover, etc.
• Phone Numbers: International phone number formats
• Email Addresses: RFC-compliant email detection
• IP Addresses: IPv4 and IPv6 addresses
• URLs: Full URL extraction and analysis
• Bitcoin Addresses: Cryptocurrency wallet addresses
• MAC Addresses: Network hardware addresses
• Hex Colors: Color codes (#RRGGBB)
• Floating Point Numbers: Decimal numbers
• Dates: Multiple date formats (MM/DD/YYYY, YYYY-MM-DD, etc.)
• File Paths: Windows and Unix file paths

Comprehensive URL analysis and validation:

• TLD Parsing: Uses tldts for accurate TLD extraction
• Domain Analysis: Extracts domain, subdomain, public suffix
• IP Detection: Identifies IP-based URLs
• Cloudflare Check: Detects Cloudflare-blocked domains
• URL Normalization: Normalizes URLs for consistent analysis
• Suspicious Pattern Detection: Identifies phishing URL patterns

graph TB
    A[Email Input] --> B{Spam Scanner}
    B --> C[Preprocessing]
    C --> D[Language Detection]
    D --> E[Tokenization]
    E --> F[Naive Bayes Classification]

    B --> G[Phishing Detection]
    G --> G1[IDN Homograph Check]
    G --> G2[Confusables Analysis]
    G --> G3[URL Analysis]

    B --> H[Attachment Scanning]
    H --> H1[Virus Scan]
    H --> H2[Executable Check]
    H --> H3[Macro Detection]
    H --> H4[NSFW Detection]

    B --> I[Content Analysis]
    I --> I1[Toxicity Detection]
    I --> I2[Pattern Recognition]

    F --> J[Result Aggregation]
    G --> J
    H --> J
    I --> J

    J --> K{Is Spam?}
    K -->|Yes| L[Spam Result]
    K -->|No| M[Ham Result]

sequenceDiagram
    participant Client
    participant Scanner
    participant Classifier
    participant ClamAV
    participant TensorFlow

    Client->>Scanner: scan(email)
    Scanner->>Scanner: Parse Email
    Scanner->>Scanner: Extract URLs
    Scanner->>Scanner: Detect Language

    par Parallel Detection
        Scanner->>Classifier: Classify Tokens
        Scanner->>ClamAV: Scan Attachments
        Scanner->>TensorFlow: Detect NSFW
        Scanner->>TensorFlow: Detect Toxicity
        Scanner->>Scanner: Check Phishing
        Scanner->>Scanner: Check Macros
    end

    Scanner->>Scanner: Aggregate Results
    Scanner->>Client: Return Result

graph LR
    A[Spam Scanner] --> B[Core Engine]
    A --> C[Classifiers]
    A --> D[Detectors]
    A --> E[Analyzers]

    B --> B1[Email Parser]
    B --> B2[Tokenizer]
    B --> B3[Preprocessor]

    C --> C1[Naive Bayes]
    C --> C2[TensorFlow NSFW]
    C --> C3[TensorFlow Toxicity]

    D --> D1[Phishing Detector]
    D --> D2[Virus Scanner]
    D --> D3[Macro Detector]
    D --> D4[Executable Detector]

    E --> E1[Language Analyzer]
    E --> E2[URL Analyzer]
    E --> E3[Pattern Analyzer]

• Node.js: >= 18.0.0
• ClamAV: Latest version (for virus scanning)
• Memory: 2GB+ RAM recommended (for TensorFlow models)
• Disk Space: 500MB+ (for models and virus definitions)

• @tensorflow/tfjs-node: For NSFW and toxicity detection
• @ladjs/naivebayes: For spam classification
• clamscan: For virus scanning
• mailparser: For email parsing
• natural: For NLP and tokenization
• tldts: For TLD parsing
• confusables: For Unicode confusables detection

import SpamScanner from 'spamscanner';

const scanner = new SpamScanner();

// Raw email string or Buffer
const email = `
From: sender@example.com
To: recipient@example.com
Subject: Test Email

This is a test email.
`;

const result = await scanner.scan(email);

console.log(result);
// {
//   isSpam: false,
//   message: 'Ham',
//   results: { ... },
//   ...
// }

import SpamScanner from 'spamscanner';

const scanner = new SpamScanner({
  // Enable performance metrics
  enablePerformanceMetrics: true,

  // Filter to supported languages
  supportedLanguages: ['en', 'es', 'fr', 'de'],

  // Enable macro detection
  enableMacroDetection: true,

  // Set scan timeout
  timeout: 30000,

  // Custom ClamAV configuration
  clamscan: {
    preference: 'clamdscan',
    clamdscanPath: '/usr/bin/clamdscan',
  },
});

const result = await scanner.scan(email);

// Check if email is spam
if (result.isSpam) {
  console.log('Spam detected!');
  console.log('Reason:', result.message);
}

// Check for viruses
if (result.results.viruses && result.results.viruses.length > 0) {
  console.log('Viruses found:', result.results.viruses);
}

// Check for phishing
if (result.results.phishing && result.results.phishing.length > 0) {
  console.log('Phishing detected:', result.results.phishing);
}

// Check for executables
if (result.results.executables && result.results.executables.length > 0) {
  console.log('Executables found:', result.results.executables);
}

// Check for NSFW content
if (result.results.nsfw && result.results.nsfw.length > 0) {
  console.log('NSFW content detected:', result.results.nsfw);
}

// Check for toxic language
if (result.results.toxicity && result.results.toxicity.length > 0) {
  console.log('Toxic language detected:', result.results.toxicity);
}

Creates a new Spam Scanner instance.

const scanner = new SpamScanner({
  enableMacroDetection: true,
  enablePerformanceMetrics: true,
  timeout: 60000,
  supportedLanguages: ['en', 'es', 'fr', 'de', 'ja', 'zh'],
  enableMixedLanguageDetection: false,
  enableAdvancedPatternRecognition: true,
  debug: false,
  logger: console,
  clamscan: {
    preference: 'clamdscan',
    clamdscanPath: '/usr/bin/clamdscan',
    scanRecursively: true,
    debugMode: false,
  },
});

Scans an email for spam, viruses, phishing, and other threats.

• source (string | Buffer) - Raw email content (RFC 822 format)

Promise<object> - Scan result object (see Result Object)

const result = await scanner.scan(emailString);

• Empty email: Returns isSpam: false with empty results
• Invalid email format: Attempts to parse, may return partial results
• Timeout: Returns partial results if scan exceeds timeout option
• ClamAV unavailable: Skips virus scanning, continues with other checks
• TensorFlow model loading: First scan may take 30+ seconds, subsequent scans are fast (models cached)

Parses email and extracts tokens for classification.

• source (string | Buffer) - Raw email content

Promise<object> - Object with tokens (array) and mail (parsed email object)

const {tokens, mail} = await scanner.getTokensAndMailFromSource(emailString);
console.log('Tokens:', tokens);
console.log('Subject:', mail.subject);

Classifies tokens as spam or ham using Naive Bayes classifier.

• tokens (string[]) - Array of tokens from email

Promise<object> - Classification result with category and probability

const classification = await scanner.getClassification(tokens);
console.log('Category:', classification.category); // 'spam' or 'ham'
console.log('Probability:', classification.probability); // 0.0 - 1.0

Detects phishing attempts in email.

• mail (object) - Parsed email object from mailparser

Promise<array> - Array of phishing detection results

const phishing = await scanner.getPhishingResults(mail);
// [
//   {
//     type: 'idn_homograph',
//     domain: 'аpple.com',
//     message: 'IDN homograph attack detected'
//   }
// ]

Detects executable files in email attachments.

• mail (object) - Parsed email object from mailparser

Promise<array> - Array of executable detection results

const executables = await scanner.getExecutableResults(mail);
// [
//   {
//     filename: 'malware.exe',
//     type: 'executable',
//     extension: 'exe',
//     risk: 'high'
//   }
// ]

Scans email attachments for viruses using ClamAV.

• mail (object) - Parsed email object from mailparser

Promise<array> - Array of virus detection results

const viruses = await scanner.getVirusResults(mail);
// [
//   {
//     filename: 'infected.pdf',
//     virus: ['Trojan.PDF.Generic'],
//     type: 'virus'
//   }
// ]

Detects macros in email content and attachments.

• mail (object) - Parsed email object from mailparser

Promise<array> - Array of macro detection results

const macros = await scanner.getMacroResults(mail);
// [
//   {
//     type: 'vba_macro',
//     message: 'VBA macro detected in email content'
//   }
// ]

Detects NSFW content in image attachments using TensorFlow.js.

• mail (object) - Parsed email object from mailparser

Promise<array> - Array of NSFW detection results

const nsfw = await scanner.getNSFWResults(mail);
// [
//   {
//     type: 'nsfw',
//     filename: 'image.jpg',
//     category: 'Porn',
//     probability: 0.85,
//     description: 'NSFW image detected: Porn (85.0%)'
//   }
// ]

Detects toxic language in email content using TensorFlow.js.

• mail (object) - Parsed email object from mailparser

Promise<array> - Array of toxicity detection results

const toxicity = await scanner.getToxicityResults(mail);
// [
//   {
//     type: 'toxicity',
//     category: 'threat',
//     probability: 0.92,
//     description: 'Toxic content detected: threat (92.0%)'
//   },
//   {
//     type: 'toxicity',
//     category: 'insult',
//     probability: 0.78,
//     description: 'Toxic content detected: insult (78.0%)'
//   }
// ]

Tokenizes text for classification.

• str (string) - Text to tokenize
• locale (string) - Language code (e.g., "en", "es", "fr")
• isHTML (boolean) - Whether text contains HTML (default: false)

Promise<string[]> - Array of tokens

const tokens = await scanner.getTokens('Hello world', 'en', false);
// ['hello', 'world']

Normalizes language codes to standard format.

• locale (string) - Language code or locale string

string - Normalized language code

const normalized = scanner.parseLocale('en-US');
// 'en'

Detects language using hybrid franc/lande approach.

• text (string) - Text to analyze

Promise<string> - Detected language code

const language = await scanner.detectLanguageHybrid('Bonjour le monde');
// 'fr'

Extracts all URLs from email.

• mail (object) - Parsed email object
• originalSource (string) - Original email source

string[] - Array of URLs

const urls = scanner.extractAllUrls(mail, emailString);
// ['https://example.com', 'http://test.com']

Parses URL using tldts for accurate TLD extraction.

• url (string) - URL to parse

object - Parsed URL components

const parsed = scanner.parseUrlWithTldts('https://subdomain.example.co.uk/path');
// {
//   domain: 'example.co.uk',
//   subdomain: 'subdomain',
//   hostname: 'subdomain.example.co.uk',
//   publicSuffix: 'co.uk',
//   isIp: false
// }

The scan() method returns a comprehensive result object:

{
  // Overall spam classification
  isSpam: boolean,
  message: string, // 'Ham' or 'Spam: <reasons>'

  // Detection results
  results: {
    // Classification details
    classification: {
      category: 'spam' | 'ham',
      probability: number
    },

    // Phishing detection
    phishing: [
      {
        type: 'idn_homograph' | 'suspicious_link' | 'confusables',
        domain: string,
        message: string
      }
    ],

    // Executable detection
    executables: [
      {
        filename: string,
        type: 'executable' | 'office_document' | 'legacy_office' | 'pdf_javascript' | 'archive',
        extension: string,
        risk: 'high' | 'medium' | 'low'
      }
    ],

    // Macro detection
    macros: [
      {
        type: 'vba_macro' | 'powershell' | 'javascript' | 'batch',
        message: string
      }
    ],

    // Arbitrary results (custom detections)
    arbitrary: [],

    // Virus scanning
    viruses: [
      {
        filename: string,
        virus: string[],
        type: 'virus'
      }
    ],

    // Pattern recognition
    patterns: {
      credit_cards: number,
      phone_numbers: number,
      emails: number,
      ips: number,
      urls: number,
      bitcoin: number,
      dates: number,
      file_paths: number
    },

    // IDN homograph attack detection
    idnHomographAttack: [],

    // Toxicity detection (array of results)
    toxicity: [
      {
        type: 'toxicity',
        category: 'identity_attack' | 'insult' | 'obscene' | 'severe_toxicity' | 'sexual_explicit' | 'threat',
        probability: number,
        description: string
      }
    ],

    // NSFW detection (array of results)
    nsfw: [
      {
        type: 'nsfw',
        filename: string,
        category: 'Porn' | 'Hentai' | 'Sexy' | 'Neutral' | 'Drawing',
        probability: number,
        description: string
      }
    ]
  },

  // All URLs extracted from email
  links: string[],

  // Tokens extracted from email
  tokens: string[],

  // Email metadata
  mail: {
    from: object,
    to: object[],
    subject: string,
    text: string,
    html: string,
    attachments: object[],
    headers: object
  },

  // Performance metrics (if enabled)
  metrics: {
    totalTime: number, // milliseconds
    classificationTime: number,
    phishingTime: number,
    executableTime: number,
    macroTime: number,
    virusTime: number,
    patternTime: number,
    idnTime: number,
    memoryUsage: object
  }
}

import SpamScanner from 'spamscanner';
import NaiveBayes from '@ladjs/naivebayes';

// Train custom classifier
const classifier = new NaiveBayes();
classifier.learn('buy viagra now', 'spam');
classifier.learn('hello friend', 'ham');

const scanner = new SpamScanner({
  classifier: classifier.toJson()
});

const scanner = new SpamScanner({
  replacements: new Map([
    ['u', 'you'],
    ['ur', 'your'],
    ['r', 'are'],
    ['b4', 'before']
  ])
});

// Only accept English, Spanish, and French emails
const scanner = new SpamScanner({
  supportedLanguages: ['en', 'es', 'fr']
});

// Accept all languages
const scanner2 = new SpamScanner({
  supportedLanguages: []
});

const scanner = new SpamScanner({
  enablePerformanceMetrics: true
});

const result = await scanner.scan(email);

console.log('Total scan time:', result.metrics.totalTime, 'ms');
console.log('Classification time:', result.metrics.classificationTime, 'ms');
console.log('Virus scan time:', result.metrics.virusScanTime, 'ms');

// Disable macro detection for performance
const scanner = new SpamScanner({
  enableMacroDetection: false
});

// Disable advanced pattern recognition
const scanner2 = new SpamScanner({
  enableAdvancedPatternRecognition: false
});

// Set 60-second timeout for slow scans
const scanner = new SpamScanner({
  timeout: 60000
});

import winston from 'winston';

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.File({ filename: 'spam-scanner.log' })
  ]
});

const scanner = new SpamScanner({
  debug: true,
  logger: logger
});

SpamScanner includes a native ARF (Abuse Reporting Format) parser for handling email feedback reports from ISPs and email providers.

import {ArfParser} from 'spamscanner/arf';
import fs from 'node:fs';

// Read an ARF report email
const arfEmail = fs.readFileSync('feedback_report.eml');

// Parse the ARF report
const report = await ArfParser.parse(arfEmail);

console.log('Feedback Type:', report.feedbackType);
console.log('Source IP:', report.sourceIp);
console.log('Original Sender:', report.originalMailFrom);
console.log('Original Recipients:', report.originalRcptTo);

// Use tryParse for safe parsing (returns null if not ARF)
const report = await ArfParser.tryParse(emailContent);

if (report) {
  console.log('ARF report detected:', report.feedbackType);
} else {
  console.log('Not an ARF report');
}

import {ArfParser} from 'spamscanner/arf';

const arfMessage = ArfParser.create({
  feedbackType: 'abuse',
  userAgent: 'MyMailServer/1.0',
  from: 'abuse@yourdomain.com',
  to: 'abuse@theirisp.com',
  originalMessage: originalEmailContent,
  humanReadable: 'This email was reported as spam by our users.',
  sourceIp: '192.168.1.100',
  originalMailFrom: 'spammer@example.com',
  originalRcptTo: ['victim@yourdomain.com'],
  arrivalDate: new Date(),
  reportingMta: 'mail.yourdomain.com',
});

// Send arfMessage to the abuse address

SpamScanner can be integrated with popular mail servers like Postfix and Dovecot as a content filter.

This is the recommended method for most Postfix setups.

1. Create a dedicated user (recommended for security):

sudo useradd -r -s /bin/false spamscanner

2. Edit /etc/postfix/master.cf:

# SpamScanner content filter
spamscanner unix - n n - - pipe
  flags=Rq user=spamscanner argv=/usr/local/bin/spamscanner scan -

3. Edit /etc/postfix/main.cf:

content_filter = spamscanner:dummy

4. Reload Postfix:

sudo postfix reload

Postfix will now pipe all incoming emails to SpamScanner. If SpamScanner exits with code 1 (spam), Postfix will reject the message.

1. Enable Pigeonhole Sieve (ensure dovecot-pigeonhole is installed)

2. Create a Sieve script (/var/lib/dovecot/sieve/default.sieve):

require ["vnd.dovecot.pipe"];

# Scan all incoming mail
if header :contains "X-Spam-Flag" "NO" {
  pipe "/usr/local/bin/spamscanner-sieve-helper";
}

3. Create a helper script (/usr/local/bin/spamscanner-sieve-helper):

#!/bin/bash
EMAIL=$(cat)
RESULT=$(echo "$EMAIL" | /usr/local/bin/spamscanner scan -)
if [[ $? -eq 1 ]]; then
  echo "X-Spam-Flag: YES" | cat - <(echo "$EMAIL")
else
  echo "$EMAIL"
fi

For high-volume environments, run SpamScanner as a persistent TCP server:

# Start the server
spamscanner server --port 7830 --host 127.0.0.1

Create /etc/systemd/system/spamscanner.service:

[Unit]
Description=SpamScanner TCP Server
After=network.target

[Service]
Type=simple
User=spamscanner
ExecStart=/usr/local/bin/spamscanner server --port 7830
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable spamscanner
sudo systemctl start spamscanner

# Send email to TCP server and get JSON response
cat email.eml | nc localhost 7830

1. Model Caching: Keep scanner instance alive to cache TensorFlow models
2. Disable Unused Features: Turn off macro detection or pattern recognition if not needed
3. Adjust Timeout: Increase timeout for large emails with many attachments
4. Use clamdscan: Prefer clamdscan over clamscan for faster virus scanning
5. Limit Languages: Specify supportedLanguages to skip unnecessary language detection

• Base: 50-100MB
• With TensorFlow Models: 500MB-1GB
• Per Scan: 10-50MB (temporary)

We welcome contributions! Please see our Contributing Guide for details.

# Clone repository
git clone https://github.com/spamscanner/spamscanner.git
cd spamscanner

# Install dependencies
pnpm install

# Run tests
npm test

# Run tests with coverage
npm run test-coverage

# Build
pnpm run build

# All tests
npm test

# Specific test file
node --test test/test.js

# With coverage
npm run test-coverage

Business Source License 1.1 © Forward Email

• Documentation: https://spamscanner.net
• Issues: GitHub Issues
• Email: mailto:support@forwardemail.net

• Forward Email - Production usage and testing
• TensorFlow.js - NSFW and toxicity detection
• ClamAV - Virus scanning
• Natural - NLP and tokenization
• tldts - TLD parsing
• confusables - Unicode confusables detection

Made with ❤️ by the Forward Email team