Spam Scanner

https://spamscanner.net/
Admin
Spam Scanner is a scalable and performant API for anti-spam, email filtering, and phishing...
Tokens:19,122
Snippets:255
Trust Score:6.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install ClamAV on Ubuntu/Debian

Source: https://spamscanner.net/

Install ClamAV and its daemon on Ubuntu/Debian systems, update definitions, and start the service.

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

--------------------------------

### Clone Repository and Install Dependencies

Source: https://spamscanner.net/

Clone the SpamScanner repository and install its dependencies using pnpm.

```bash
git clone https://github.com/spamscanner/spamscanner.git
cd spamscanner

pnpm install
```

--------------------------------

### Enable and Start SpamScanner Systemd Service

Source: https://spamscanner.net/

Commands to enable the SpamScanner systemd service to start on boot and to start the service immediately.

```bash
sudo systemctl enable spamscanner
sudo systemctl start spamscanner
```

--------------------------------

### Install SpamScanner via npm

Source: https://spamscanner.net/

Install SpamScanner globally using npm or run it directly with npx. Requires Node.js to be installed.

```bash
# Install globally
npm install -g spamscanner

# Or use npx without installing
npx spamscanner --help

```

--------------------------------

### Install SpamScanner Standalone Binary on Linux (System-wide)

Source: https://spamscanner.net/

Download and install the standalone binary for Linux to /usr/local/bin for system-wide access. Requires sudo privileges. Ensure the binary is executable.

```bash
# 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"

```

--------------------------------

### Install SpamScanner Standalone Binary on Linux (User Directory)

Source: https://spamscanner.net/

Download and install the standalone binary for Linux to the user's local bin directory, avoiding the need for sudo. Ensure the binary is executable and the directory is in your PATH.

```bash
# 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"

```

--------------------------------

### Install SpamScanner Standalone Binary on Windows (Program Files)

Source: https://spamscanner.net/

Install the Windows standalone binary to the 'Program Files' directory using PowerShell. This typically requires Administrator privileges. The executable will be placed at 'C:\Program Files\spamscanner\spamscanner.exe'.

```powershell
# 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

```

--------------------------------

### Client Example for SpamScanner TCP Server

Source: https://spamscanner.net/

Example of how to send an email to the SpamScanner TCP server using `nc` (netcat) and receive a JSON response.

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

--------------------------------

### Install Spam Scanner via npm

Source: https://spamscanner.net/

Use this command to install the Spam Scanner package for project use.

```bash
npm install spamscanner
```

--------------------------------

### Basic SpamScanner Usage

Source: https://spamscanner.net/

Instantiate SpamScanner and scan a raw email string or Buffer. This is the simplest way to get started with email scanning.

```javascript
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: { ... },
//   ...
// }

```

--------------------------------

### Install ClamAV on CentOS/RHEL

Source: https://spamscanner.net/

Install ClamAV and its update utility on CentOS/RHEL systems.

```bash
sudo yum install clamav clamav-update
sudo freshclam
```

--------------------------------

### Install Spam Scanner Globally via npm

Source: https://spamscanner.net/

Install the Spam Scanner package globally for command-line interface (CLI) access.

```bash
npm install -g spamscanner
```

--------------------------------

### Verify SpamScanner Installation

Source: https://spamscanner.net/

Check if the SpamScanner CLI is installed correctly by verifying its version and checking for available updates.

```bash
# Check version
spamscanner version

# Check for updates
spamscanner update

```

--------------------------------

### Install SpamScanner Standalone Binary on macOS (Intel)

Source: https://spamscanner.net/

Download and install the standalone binary for macOS with Intel processors. Ensure the binary is executable and placed in a directory included in your system's PATH.

```bash
# 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

```

--------------------------------

### Install SpamScanner Standalone Binary on Windows (Current Directory)

Source: https://spamscanner.net/

Download the Windows standalone binary to the current directory using PowerShell. This is useful for testing or if you don't have administrator rights. Remember to add the directory to your PATH.

```powershell
# 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

```

--------------------------------

### Install ClamAV on macOS

Source: https://spamscanner.net/

Install ClamAV using Homebrew and update its virus definitions.

```bash
brew install clamav
freshclam
```

--------------------------------

### Start SpamScanner TCP Server

Source: https://spamscanner.net/

Start SpamScanner as a persistent TCP server on a specified port and host. This is suitable for high-volume environments.

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

--------------------------------

### Install SpamScanner Standalone Binary on macOS (Apple Silicon)

Source: https://spamscanner.net/

Download and install the standalone binary for macOS with Apple Silicon (M1/M2/M3). Ensure the binary is executable and placed in a directory included in your system's PATH.

```bash
# 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

```

--------------------------------

### Example JSON Output Structure

Source: https://spamscanner.net/

This is an example of the JSON output produced when scanning with the --json flag. It details spam classification, scores, and detected tests.

```json
{
  "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)"
  }
}
```

--------------------------------

### Show SpamScanner Version

Source: https://spamscanner.net/

Display the currently installed version of the SpamScanner CLI.

```bash
spamscanner version

```

--------------------------------

### Start TCP server with custom threshold

Source: https://spamscanner.net/

Configure the SpamScanner TCP server to use a specific spam detection threshold.

```bash
spamscanner server --port 8080 --threshold 3.0
```

--------------------------------

### Use Spam Scanner CLI with npx

Source: https://spamscanner.net/

Execute Spam Scanner commands directly using npx without a global installation.

```bash
npx spamscanner scan email.eml
```

--------------------------------

### Scan with custom ClamAV paths

Source: https://spamscanner.net/

Specify custom paths for the ClamAV executable, useful in non-standard installations.

```bash
spamscanner scan email.eml --clamscan-path /opt/clamav/bin/clamscan
```

--------------------------------

### Systemd Service for SpamScanner TCP Server

Source: https://spamscanner.net/

Configuration file for a systemd service to manage the SpamScanner TCP server. Ensures the server starts on boot and restarts automatically if it fails.

```systemd
[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
```

--------------------------------

### Start SpamScanner TCP server

Source: https://spamscanner.net/

Run SpamScanner as a TCP server, allowing other applications to send emails for scanning over the network. Specify a custom port.

```bash
spamscanner server --port 8080
```

--------------------------------

### Start SpamScanner Server Mode

Source: https://spamscanner.net/

Run SpamScanner in a persistent server mode, likely for handling multiple scan requests over a network connection (e.g., TCP).

```bash
spamscanner server

```

--------------------------------

### Update SpamScanner via npm

Source: https://spamscanner.net/

Update the SpamScanner CLI to the latest version if it was installed using npm.

```bash
# Update via npm
npm update -g spamscanner

```

--------------------------------

### Run Tests and Build Project

Source: https://spamscanner.net/

Commands to run all tests, specific test files, tests with coverage, and build the project.

```bash
# Run tests
npm test

# Run tests with coverage
npm run test-coverage

# Build
pnpm run build
```

--------------------------------

### Running Specific Tests

Source: https://spamscanner.net/

Instructions for running all tests, a specific test file, or tests with code coverage.

```bash
# All tests
npm test

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

# With coverage
npm run test-coverage
```

--------------------------------

### Initialize SpamScanner with Options

Source: https://spamscanner.net/

Instantiate SpamScanner with custom configurations for macro detection, performance metrics, language support, and ClamAV preferences. Ensure ClamAV paths are correctly set if using 'clamscan' or 'clamdscan'.

```javascript
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,
  },
});
```

--------------------------------

### Configure Postfix Main.cf for SpamScanner

Source: https://spamscanner.net/

Configure the Postfix `main.cf` file to enable the SpamScanner content filter. This tells Postfix which content filter to use for processing emails.

```postfix
content_filter = spamscanner:dummy
```

--------------------------------

### Enable Performance Monitoring

Source: https://spamscanner.net/

Activate performance metrics collection to analyze scan times for different components. The results object will contain detailed timing information.

```javascript
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');

```

--------------------------------

### Scan with NSFW and toxicity checks

Source: https://spamscanner.net/

Enable NSFW and toxicity content checks, with options to customize their scoring weights.

```bash
spamscanner scan email.eml --check-nsfw --check-toxicity --score-nsfw 5.0
```

--------------------------------

### SpamScanner Constructor

Source: https://spamscanner.net/

Initializes a new instance of the SpamScanner with customizable options for detection, performance, and security.

```APIDOC
## new SpamScanner(options)

### Description
Creates a new Spam Scanner instance with configurable options.

### Parameters
#### Options
- **enableMacroDetection** (boolean) - Optional - Default: `true` - Enable macro detection in emails and attachments.
- **enablePerformanceMetrics** (boolean) - Optional - Default: `false` - Track and return performance metrics.
- **timeout** (number) - Optional - Default: `30000` - Timeout in milliseconds for scans (virus, URL checks).
- **supportedLanguages** (string[]) - Optional - Default: `['en']` - Array of supported language codes. Empty array `[]` means all languages are supported.
- **enableMixedLanguageDetection** (boolean) - Optional - Default: `false` - Enable detection of mixed languages in emails.
- **enableAdvancedPatternRecognition** (boolean) - Optional - Default: `true` - Enable advanced pattern recognition (credit cards, phones, etc.).
- **toxicityThreshold** (number) - Optional - Default: `0.7` - Threshold for toxicity detection (0.0-1.0, higher = more strict).
- **nsfwThreshold** (number) - Optional - Default: `0.6` - Threshold for NSFW detection (0.0-1.0, higher = more strict).
- **debug** (boolean) - Optional - Default: `false` - Enable debug logging.
- **logger** (object) - Optional - Default: `console` - Custom logger object (must have `log`, `error`, `warn` methods).
- **clamscan** (object) - Optional - See below - ClamAV configuration options.
- **classifier** (object) - Optional - Default: `null` - Custom Naive Bayes classifier data.
- **replacements** (Map | object) - Optional - Default: `null` - Custom text replacements for preprocessing.

#### ClamAV Options (`clamscan`)
- **removeInfected** (boolean) - Optional - Default: `false` - Remove infected files.
- **quarantineInfected** (boolean) - Optional - Default: `false` - Quarantine infected files.
- **scanLog** (string | null) - Optional - Default: `null` - Path to scan log file.
- **debugMode** (boolean) - Optional - Default: `false` - Enable ClamAV debug mode.
- **fileList** (string | null) - Optional - Default: `null` - Path to file list.
- **scanRecursively** (boolean) - Optional - Default: `true` - Scan directories recursively.
- **clamscanPath** (string) - Optional - Default: `'/usr/bin/clamscan'` - Path to clamscan binary.
- **clamdscanPath** (string) - Optional - Default: `'/usr/bin/clamdscan'` - Path to clamdscan binary.
- **preference** (string) - Optional - Default: `'clamdscan'` - Preferred scanner: `'clamdscan'` or `'clamscan'`.

### Request Example
```javascript
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,
  },
});
```
```

--------------------------------

### Show SpamScanner Help Message

Source: https://spamscanner.net/

Display the help message for the SpamScanner CLI, listing all available commands and options.

```bash
spamscanner help

```

--------------------------------

### Scan, add headers, and prepend subject tag

Source: https://spamscanner.net/

Enhance mail server integration by adding X-Spam headers and prepending a tag to the email subject.

```bash
spamscanner scan email.eml --add-headers --prepend-subject
```

--------------------------------

### Configure Postfix Master.cf for SpamScanner

Source: https://spamscanner.net/

Configure the Postfix `master.cf` file to use SpamScanner as a pipe content filter. This involves specifying the SpamScanner executable and its arguments.

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

--------------------------------

### Scan with verbose output

Source: https://spamscanner.net/

Display more detailed information during the scanning process.

```bash
spamscanner scan email.eml --verbose
```

--------------------------------

### Create Dedicated User for SpamScanner

Source: https://spamscanner.net/

Create a dedicated system user for SpamScanner to enhance security. This user will be used by Postfix to run the SpamScanner process.

```bash
sudo useradd -r -s /bin/false spamscanner
```

--------------------------------

### Re-download SpamScanner Binary (macOS/Linux)

Source: https://spamscanner.net/

Re-download the latest standalone binary for macOS or Linux to update the SpamScanner CLI. This command dynamically determines the correct binary for your system architecture.

```bash
# 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

```

--------------------------------

### Scan with specific language support

Source: https://spamscanner.net/

Limit the language analysis to a predefined set of languages, such as English, Spanish, and French.

```bash
spamscanner scan email.eml --languages en,es,fr
```

--------------------------------

### Scan and add X-Spam headers

Source: https://spamscanner.net/

Configure SpamScanner to add standard X-Spam headers to the email, useful for mail server integration.

```bash
spamscanner scan email.eml --add-headers
```

--------------------------------

### SpamScanner General CLI Options

Source: https://spamscanner.net/

Common options applicable to most SpamScanner CLI commands, including help, version, JSON output, verbosity, debugging, timeouts, and update checks.

```bash
-h, --help
-v, --version
-j, --json
--verbose
--debug
--timeout <ms>
--no-update-check

```

--------------------------------

### Scan with custom NSFW threshold

Source: https://spamscanner.net/

Adjust the NSFW content detection threshold for increased sensitivity.

```bash
spamscanner scan email.eml --check-nsfw --nsfw-threshold 0.3
```

--------------------------------

### SpamScanner with Custom Configuration

Source: https://spamscanner.net/

Configure SpamScanner with various options such as performance metrics, language filtering, macro detection, timeouts, and custom ClamAV settings. This allows for fine-tuning the scanning process.

```javascript
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);

```

--------------------------------

### Dovecot Sieve Script for Spam Scanning

Source: https://spamscanner.net/

Create a Sieve script for Dovecot to pipe incoming emails to SpamScanner for scanning. This script requires the 'vnd.dovecot.pipe' extension.

```sieve
require ["vnd.dovecot.pipe"];

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

--------------------------------

### Scan a file with SpamScanner

Source: https://spamscanner.net/

Basic command to scan a single email file for spam. Use '-' to scan from standard input.

```bash
spamscanner scan email.eml
```

```bash
cat email.eml | spamscanner scan -
```

--------------------------------

### Integrate Custom Logger

Source: https://spamscanner.net/

Provide a custom logger instance, such as one configured with Winston, to control how SpamScanner logs its debug information.

```javascript
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
});

```

--------------------------------

### Train and Use a Custom Classifier

Source: https://spamscanner.net/

Integrate a pre-trained custom classifier by providing its JSON representation to the SpamScanner constructor. Ensure the classifier is trained on relevant data before serialization.

```javascript
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()
});

```

--------------------------------

### Reload Postfix Service

Source: https://spamscanner.net/

Reload the Postfix service after making configuration changes to apply the new settings for SpamScanner integration.

```bash
sudo postfix reload
```

--------------------------------

### Scan with custom subject tag

Source: https://spamscanner.net/

Customize the tag that is prepended to the subject line when adding X-Spam headers.

```bash
spamscanner scan email.eml --add-headers --prepend-subject --subject-tag "[JUNK]"
```

--------------------------------

### scanner.getTokens(str, locale, isHTML)

Source: https://spamscanner.net/

Tokenizes text for classification. It takes a string, locale, and an optional boolean for HTML content, returning a promise with an array of tokens.

```APIDOC
## scanner.getTokens(str, locale, isHTML)

### Description
Tokenizes text for classification.

### Parameters
#### Path Parameters
* None
#### Query Parameters
* None
#### Request Body
* None

### Method
* Not applicable (JavaScript function call)

### Endpoint
* Not applicable (JavaScript function call)

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

### Returns
`Promise<string[]>` - Array of tokens

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

--------------------------------

### Enable Specific Spam Detection Methods

Source: https://spamscanner.net/

Explicitly enable specific detection methods for SpamScanner scoring. By default, classifier, phishing, executables, and macros are included.

```bash
--check-classifier
--check-phishing
--check-executables
--check-macros
--check-virus
--check-nsfw
--check-toxicity

```

--------------------------------

### Scan with mixed language detection

Source: https://spamscanner.net/

Enable the detection of emails containing content in multiple languages.

```bash
spamscanner scan email.eml --mixed-language
```

--------------------------------

### Scan Email File with SpamScanner

Source: https://spamscanner.net/

Scan a specific email file using the SpamScanner CLI. This is the primary command for analyzing individual email messages.

```bash
spamscanner scan <file>

```

--------------------------------

### Scan with JSON output

Source: https://spamscanner.net/

Obtain detailed scan results in JSON format, including the spam score and the tests that contributed to the classification.

```bash
spamscanner scan email.eml --json
```

--------------------------------

### Scan with strict IDN/homograph detection

Source: https://spamscanner.net/

Enforce strict detection of Internationalized Domain Names (IDN) and homograph attacks to prevent phishing.

```bash
spamscanner scan email.eml --strict-idn
```

--------------------------------

### Create ARF Reports with SpamScanner

Source: https://spamscanner.net/

Creates an ARF report message object using the ArfParser.create method. This is useful for generating feedback reports to send to ISPs.

```javascript
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

```

--------------------------------

### Scan Result Object

Source: https://spamscanner.net/

The `scan()` method returns a comprehensive result object detailing the spam analysis. It includes overall classification, specific detection results for phishing, executables, macros, viruses, patterns, toxicity, and NSFW content, as well as extracted links, tokens, email metadata, and performance metrics.

```APIDOC
## Scan Result Object

### Description
This object represents the comprehensive result of a spam scan operation. It provides detailed information about the classification, various detection mechanisms, extracted data, original email content, and performance metrics.

### Fields
- **isSpam** (boolean) - Indicates the overall spam classification of the content.
- **message** (string) - A human-readable message, either 'Ham' or 'Spam: <reasons>'.
- **results** (object) - Contains detailed results from various detection modules.
  - **classification** (object)
    - **category** ('spam' | 'ham') - The determined category.
    - **probability** (number) - The probability of the determined category.
  - **phishing** (array) - List of phishing detection results.
    - **type** ('idn_homograph' | 'suspicious_link' | 'confusables') - The type of phishing detection.
    - **domain** (string) - The detected phishing domain.
    - **message** (string) - A descriptive message for the phishing detection.
  - **executables** (array) - List of detected executable files or potentially harmful documents.
    - **filename** (string) - The name of the file.
    - **type** ('executable' | 'office_document' | 'legacy_office' | 'pdf_javascript' | 'archive') - The type of executable or document.
    - **extension** (string) - The file extension.
    - **risk** ('high' | 'medium' | 'low') - The assessed risk level.
  - **macros** (array) - List of detected macro-related threats.
    - **type** ('vba_macro' | 'powershell' | 'javascript' | 'batch') - The type of macro threat.
    - **message** (string) - A descriptive message for the macro detection.
  - **arbitrary** (array) - Placeholder for custom detection results.
  - **viruses** (array) - List of detected viruses.
    - **filename** (string) - The name of the infected file.
    - **virus** (array) - List of detected virus names.
    - **type** ('virus') - Indicates virus detection.
  - **patterns** (object) - Counts of various patterns found in the content.
    - **credit_cards** (number) - Count of credit card numbers.
    - **phone_numbers** (number) - Count of phone numbers.
    - **emails** (number) - Count of email addresses.
    - **ips** (number) - Count of IP addresses.
    - **urls** (number) - Count of URLs.
    - **bitcoin** (number) - Count of Bitcoin addresses.
    - **dates** (number) - Count of dates.
    - **file_paths** (number) - Count of file paths.
  - **idnHomographAttack** (array) - List of detected IDN homograph attacks.
  - **toxicity** (array) - List of toxicity detection results.
    - **type** ('toxicity') - Indicates toxicity detection.
    - **category** ('identity_attack' | 'insult' | 'obscene' | 'severe_toxicity' | 'sexual_explicit' | 'threat') - The category of toxicity.
    - **probability** (number) - The probability of the toxicity category.
    - **description** (string) - A description of the toxicity detected.
  - **nsfw** (array) - List of NSFW (Not Safe For Work) detection results.
    - **type** ('nsfw') - Indicates NSFW detection.
    - **filename** (string) - The filename associated with the NSFW content.
    - **category** ('Porn' | 'Hentai' | 'Sexy' | 'Neutral' | 'Drawing') - The NSFW category.
    - **probability** (number) - The probability of the NSFW category.
    - **description** (string) - A description of the NSFW content.
- **links** (array) - An array of all URLs extracted from the content.
- **tokens** (array) - An array of tokens extracted from the content.
- **mail** (object) - Contains metadata about the email.
  - **from** (object) - Sender information.
  - **to** (array) - Recipient information.
  - **subject** (string) - The email subject.
  - **text** (string) - The plain text content of the email.
  - **html** (string) - The HTML content of the email.
  - **attachments** (array) - Information about email attachments.
  - **headers** (object) - The email headers.
- **metrics** (object) - Performance metrics for the scan (if enabled).
  - **totalTime** (number) - Total scan time in milliseconds.
  - **classificationTime** (number) - Time spent on classification.
  - **phishingTime** (number) - Time spent on phishing detection.
  - **executableTime** (number) - Time spent on executable detection.
  - **macroTime** (number) - Time spent on macro detection.
  - **virusTime** (number) - Time spent on virus scanning.
  - **patternTime** (number) - Time spent on pattern recognition.
  - **idnTime** (number) - Time spent on IDN homograph attack detection.
  - **memoryUsage** (object) - Information about memory usage during the scan.
```

--------------------------------

### Scan Email from Standard Input with SpamScanner

Source: https://spamscanner.net/

Pipe email content directly to the SpamScanner CLI for scanning. This is useful for integrating with other tools or processing emails from network streams.

```bash
spamscanner scan -

```

--------------------------------

### scanner.scan(source)

Source: https://spamscanner.net/

Scans an email for spam, viruses, phishing, and other threats. Returns a promise that resolves with the scan result object.

```APIDOC
## scanner.scan(source)

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

### Method
`scanner.scan`

### Parameters
#### Path Parameters
- **source** (string | Buffer) - Required - Raw email content (RFC 822 format)

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

### Request Example
```javascript
const result = await scanner.scan(emailString);
```

### Edge Cases
- **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).
```

--------------------------------

### scanner.getExecutableResults(mail)

Source: https://spamscanner.net/

Detects executable files in email attachments. It takes a parsed email object and returns a promise that resolves to an array of executable detection results.

```APIDOC
## scanner.getExecutableResults(mail)

### Description
Detects executable files in email attachments.

### Parameters
#### Path Parameters
* None
#### Query Parameters
* None
#### Request Body
* None

### Method
* Not applicable (JavaScript function call)

### Endpoint
* Not applicable (JavaScript function call)

### Parameters
* `mail` (object) - Required - Parsed email object from `mailparser`

### Returns
`Promise<array>` - Array of executable detection results

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

--------------------------------

### Classify Tokens using Naive Bayes

Source: https://spamscanner.net/

Classify an array of tokens as 'spam' or 'ham' using the Naive Bayes classifier. This method requires pre-extracted tokens from an email source.

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

--------------------------------

### scanner.extractAllUrls(mail, originalSource)

Source: https://spamscanner.net/

Extracts all URLs from an email, given the parsed email object and the original email source. It returns an array of URLs.

```APIDOC
## scanner.extractAllUrls(mail, originalSource)

### Description
Extracts all URLs from email.

### Parameters
#### Path Parameters
* None
#### Query Parameters
* None
#### Request Body
* None

### Method
* Not applicable (JavaScript function call)

### Endpoint
* Not applicable (JavaScript function call)

### Parameters
* `mail` (object) - Required - Parsed email object
* `originalSource` (string) - Required - Original email source

### Returns
`string[]` - Array of URLs

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

--------------------------------

### scanner.getTokensAndMailFromSource(source)

Source: https://spamscanner.net/

Parses raw email content and extracts tokens for classification, along with the parsed email object.

```APIDOC
## scanner.getTokensAndMailFromSource(source)

### Description
Parses email and extracts tokens for classification.

### Method
`scanner.getTokensAndMailFromSource`

### Parameters
#### Path Parameters
- **source** (string | Buffer) - Required - Raw email content

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

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

--------------------------------

### scanner.parseUrlWithTldts(url)

Source: https://spamscanner.net/

Parses a URL using tldts for accurate Top-Level Domain (TLD) extraction. It takes a URL string and returns an object with parsed URL components.

```APIDOC
## scanner.parseUrlWithTldts(url)

### Description
Parses URL using tldts for accurate TLD extraction.

### Parameters
#### Path Parameters
* None
#### Query Parameters
* None
#### Request Body
* None

### Method
* Not applicable (JavaScript function call)

### Endpoint
* Not applicable (JavaScript function call)

### Parameters
* `url` (string) - Required - URL to parse

### Returns
`object` - Parsed URL components

### Example
```javascript
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
// }
```
```

--------------------------------

### scanner.getClassification(tokens)

Source: https://spamscanner.net/

Classifies an array of tokens as spam or ham using a Naive Bayes classifier.

```APIDOC
## scanner.getClassification(tokens)

### Description
Classifies tokens as spam or ham using Naive Bayes classifier.

### Method
`scanner.getClassification`

### Parameters
#### Path Parameters
- **tokens** (string[]) - Required - Array of tokens from email

### Returns
`Promise<object>` - Classification result with `category` and `probability`

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

--------------------------------

### Configure SpamScanner Scan Threshold

Source: https://spamscanner.net/

Set a custom spam score threshold for the SpamScanner. Scores above this value will be flagged as spam. The default is 5.0.

```bash
--threshold <score>

```

--------------------------------

### Define Custom Text Replacements

Source: https://spamscanner.net/

Configure custom text replacements to normalize or standardize input text before scanning. This is useful for handling common abbreviations or slang.

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

```

--------------------------------

### Extract Tokens and Mail from Source

Source: https://spamscanner.net/

Parse raw email content to extract classification tokens and a structured email object. This is useful for custom classification or analysis of email components like the subject.

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

--------------------------------

### Set Custom Timeout

Source: https://spamscanner.net/

Configure a custom timeout duration in milliseconds for scan operations. This prevents scans from running indefinitely.

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

```

--------------------------------

### Scan Email Content

Source: https://spamscanner.net/

Use the `scan` method to process raw email content (RFC 822 format) for spam, viruses, and other threats. Be aware of potential timeouts and the initial TensorFlow model loading time.

```javascript
const result = await scanner.scan(emailString);
```

--------------------------------

### scanner.getToxicityResults(mail)

Source: https://spamscanner.net/

Detects toxic language in email content using TensorFlow.js. This function takes a parsed email object and returns a promise with toxicity detection results.

```APIDOC
## scanner.getToxicityResults(mail)

### Description
Detects toxic language in email content using TensorFlow.js.

### Parameters
#### Path Parameters
* None
#### Query Parameters
* None
#### Request Body
* None

### Method
* Not applicable (JavaScript function call)

### Endpoint
* Not applicable (JavaScript function call)

### Parameters
* `mail` (object) - Required - Parsed email object from `mailparser`

### Returns
`Promise<array>` - Array of toxicity detection results

### Example
```javascript
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%)'
//   }
// ]
```
```

--------------------------------

### Detect Executable Files in Email Attachments

Source: https://spamscanner.net/

Use `scanner.getExecutableResults` to identify executable files within email attachments. This function returns an array of objects, each detailing the filename, type, extension, and risk level of detected executables.

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

--------------------------------

### Filter Supported Languages

Source: https://spamscanner.net/

Specify a list of supported language codes to restrict scanning to specific languages. An empty array accepts all languages.

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

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

```

--------------------------------

### scanner.detectLanguageHybrid(text)

Source: https://spamscanner.net/

Detects language using a hybrid approach combining franc and lande. It takes text as input and returns a promise with the detected language code.

```APIDOC
## scanner.detectLanguageHybrid(text)

### Description
Detects language using hybrid franc/lande approach.

### Parameters
#### Path Parameters
* None
#### Query Parameters
* None
#### Request Body
* None

### Method
* Not applicable (JavaScript function call)

### Endpoint
* Not applicable (JavaScript function call)

### Parameters
* `text` (string) - Required - Text to analyze

### Returns
`Promise<string>` - Detected language code

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

--------------------------------

### Detect Language Using Hybrid Approach

Source: https://spamscanner.net/

Employ `scanner.detectLanguageHybrid` to detect the language of a given text using a hybrid approach combining franc and lande. It returns the detected language code.

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

--------------------------------

### scanner.parseLocale(locale)

Source: https://spamscanner.net/

Normalizes language codes to a standard format. It accepts a locale string and returns the normalized language code.

```APIDOC
## scanner.parseLocale(locale)

### Description
Normalizes language codes to standard format.

### Parameters
#### Path Parameters
* None
#### Query Parameters
* None
#### Request Body
* None

### Method
* Not applicable (JavaScript function call)

### Endpoint
* Not applicable (JavaScript function call)

### Parameters
* `locale` (string) - Required - Language code or locale string

### Returns
`string` - Normalized language code

### Example
```javascript
const normalized = scanner.parseLocale('en-US');
// 'en'
```
```

--------------------------------

### Scan with custom spam threshold

Source: https://spamscanner.net/

Adjust the spam detection threshold. Scores above this value will be classified as spam.

```bash
spamscanner scan email.eml --threshold 3.0
```

--------------------------------

### scanner.getNSFWResults(mail)

Source: https://spamscanner.net/

Detects NSFW content in image attachments using TensorFlow.js. It processes a parsed email object and returns a promise with NSFW detection results.

```APIDOC
## scanner.getNSFWResults(mail)

### Description
Detects NSFW content in image attachments using TensorFlow.js.

### Parameters
#### Path Parameters
* None
#### Query Parameters
* None
#### Request Body
* None

### Method
* Not applicable (JavaScript function call)

### Endpoint
* Not applicable (JavaScript function call)

### Parameters
* `mail` (object) - Required - Parsed email object from `mailparser`

### Returns
`Promise<array>` - Array of NSFW detection results

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

--------------------------------

### scanner.getPhishingResults(mail)

Source: https://spamscanner.net/

Detects phishing attempts within a parsed email object.

```APIDOC
## scanner.getPhishingResults(mail)

### Description
Detects phishing attempts in email.

### Method
`scanner.getPhishingResults`

### Parameters
#### Path Parameters
- **mail** (object) - Required - Parsed email object from `mailparser`

### Returns
`Promise<array>` - Array of phishing detection results

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

--------------------------------

### SpamScanner Sieve Helper Script

Source: https://spamscanner.net/

A bash script used by Dovecot's Sieve to interact with SpamScanner. It pipes the email content to SpamScanner and checks the exit code to determine if it's spam.

```bash
#!/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
```

--------------------------------

### scanner.getMacroResults(mail)

Source: https://spamscanner.net/

Detects macros in email content and attachments. This function takes a parsed email object and returns a promise with an array of macro detection results.

```APIDOC
## scanner.getMacroResults(mail)

### Description
Detects macros in email content and attachments.

### Parameters
#### Path Parameters
* None
#### Query Parameters
* None
#### Request Body
* None

### Method
* Not applicable (JavaScript function call)

### Endpoint
* Not applicable (JavaScript function call)

### Parameters
* `mail` (object) - Required - Parsed email object from `mailparser`

### Returns
`Promise<array>` - Array of macro detection results

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

--------------------------------

### Detect NSFW Content in Image Attachments

Source: https://spamscanner.net/

Use `scanner.getNSFWResults` to identify Not Safe For Work (NSFW) content in image attachments using TensorFlow.js. The results include filename, category, probability, and a description of the detected NSFW content.

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

--------------------------------

### Safely Parse ARF Reports

Source: https://spamscanner.net/

Uses tryParse for safe parsing, which returns null if the content is not a valid ARF report. This prevents errors when processing unknown email formats.

```javascript
// 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');
}

```

--------------------------------

### Parse URL with Accurate TLD Extraction

Source: https://spamscanner.net/

Utilize `scanner.parseUrlWithTldts` to parse a URL and extract its components, including domain, subdomain, and public suffix, using the tldts library for accuracy. It returns an object with parsed URL details.

```javascript
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
// }
```

--------------------------------

### Detect Phishing Attempts

Source: https://spamscanner.net/

Analyze a parsed email object to detect potential phishing attempts, such as IDN homograph attacks. The result is an array of detection findings.

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