scam-detector

Fast, accurate scam detection for images, text, and links.

Features

| Category | What it catches | |---|---| | 🖼️ Image scams | Fake celebrity tweets (Elon Musk, MrBeast), casino "Withdrawal Success" screenshots, QR code phishing, fake giveaway images, fake Discord Nitro / Steam gift screenshots | | 📝 Text scams | Phishing messages, crypto scams, prize-winner cons, account-suspension threats, tech-support scams, job scams, romance scams | | 🔗 Link / URL | Phishing links, typosquatting, homoglyph attacks, known phishing domains, suspicious TLDs, open redirects, malicious URL shorteners |

Two detection modes:

• Heuristic (default) — zero dependencies, fully offline, instant results
• AI mode — GPT-4 Vision for image analysis, GPT-4o-mini for text — 95%+ accuracy (requires your OpenAI API key)

Installation

npm install scam-detector
# or
pnpm add scam-detector
# or
yarn add scam-detector

Node ≥ 18 required (uses native fetch).

Quick Start

import { detect } from 'scam-detector';

// Auto-detect input type
const result = await detect("Congratulations! You've won a $500 Amazon gift card. Click here to claim.");
console.log(result.isScam);     // true
console.log(result.confidence); // 0.87
console.log(result.types);      // ['prize_winner']
console.log(result.severity);   // 'high'
console.log(result.reasons);    // ['Unsolicited prize winner claim', ...]

API

detect(input, options?) — auto router

The simplest entry point. Automatically routes to the right detector based on input type.

import { detect } from 'scam-detector';

// String that looks like a URL → link detection
await detect('https://discord-nitro.com/free-gift');

// Buffer/Uint8Array → image detection
await detect(imageBuffer, { openaiApiKey: 'sk-...' });

// Any other string → text detection (also scans embedded URLs)
await detect('Your account has been suspended. Verify now: http://paypa1.com');

detectText(text, options?) — text analysis

import { detectText } from 'scam-detector';

const result = await detectText(
  "ELON MUSK GIVEAWAY: Send 1 BTC, get 2 back! Limited time only!",
  { openaiApiKey: process.env.OPENAI_API_KEY } // optional
);

Options:

| Option | Type | Description | |---|---|---| | openaiApiKey | string | Enables AI-enhanced analysis via GPT-4o-mini | | customPatterns | RegExp[] | Additional patterns to flag as scams | | whitelistDomains | string[] | Domains to never flag |

detectLink(url, options?) — URL / link analysis

import { detectLink } from 'scam-detector';

const result = await detectLink('http://paypa1.com/login');
// { isScam: true, confidence: 0.92, types: ['homoglyph_attack'], ... }

What it checks:

• Known phishing domain database
• Typosquatting against 30+ popular domains (Levenshtein distance)
• Homoglyph attacks (paypa1.com, disc0rd.com, etc.)
• High-risk free TLDs (.tk, .ml, .ga, .xyz, etc.)
• IP-address hosts
• Excessive subdomains
• Open redirect parameters
• Scam keywords in path/query
• URL shorteners hiding the real destination
• Non-HTTPS connections

detectImage(image, options?) — image analysis

import { detectImage } from 'scam-detector';
import { readFileSync } from 'fs';

const imageBuffer = readFileSync('./suspicious-screenshot.png');

// Heuristic only (filename + caption signals, no API key)
const r1 = await detectImage(imageBuffer, {
  filename: 'withdrawal-success-5000usd.jpg',
  caption: 'Casino payout approved!',
});

// AI mode — full GPT-4 Vision analysis
const r2 = await detectImage(imageBuffer, {
  openaiApiKey: process.env.OPENAI_API_KEY,
  filename: 'elon-musk-bitcoin-giveaway.png',
});

Accepts:

• Buffer — from fs.readFile, axios responses, etc.
• Uint8Array — from fetch / Web APIs
• string — raw base64 or data:image/...;base64,... data URL

Options:

| Option | Type | Description | |---|---|---| | openaiApiKey | string | Enables GPT-4 Vision (highest accuracy) | | filename | string | Filename for heuristic signals | | caption | string | Alt text / caption for heuristic analysis | | timeout | number | OpenAI request timeout in ms (default 30000) |

Detection Result

All detectors return a DetectionResult:

interface DetectionResult {
  isScam: boolean;           // Primary verdict
  confidence: number;        // 0.0 – 1.0
  types: ScamType[];         // Detected scam categories
  reasons: string[];         // Human-readable explanations
  severity: Severity;        // 'low' | 'medium' | 'high' | 'critical'
  scores: Record<string, number>; // Raw signal scores for debugging
}

ScamType values

fake_celebrity_tweet · crypto_scam · casino_withdrawal · qr_phishing · fake_giveaway · discord_nitro · steam_gift · phishing_link · phishing_text · account_suspension · prize_winner · investment_scam · romance_scam · tech_support_scam · job_scam · suspicious_url · homoglyph_attack · typosquatting · malicious_shortlink · unknown

Usage Examples

Discord bot moderation

import { detect } from 'scam-detector';

client.on('messageCreate', async (msg) => {
  const result = await detect(msg.content);
  if (result.isScam && result.severity !== 'low') {
    await msg.delete();
    await msg.channel.send(`🚨 Scam blocked: ${result.reasons[0]}`);
  }
});

Image upload validation

import { detectImage } from 'scam-detector';

app.post('/upload', async (req, res) => {
  const result = await detectImage(req.file.buffer, {
    openaiApiKey: process.env.OPENAI_API_KEY,
    filename: req.file.originalname,
  });

  if (result.isScam) {
    return res.status(400).json({
      error: 'Scam content detected',
      details: result.reasons,
    });
  }
  // proceed with upload...
});

Batch URL scanning

import { detectLink } from 'scam-detector';

const urls = [
  'https://discord-nitro.com/free-gift',
  'https://paypa1.com/login',
  'https://github.com',
];

const results = await Promise.all(urls.map((url) => detectLink(url)));
const flagged = results.filter((r) => r.isScam);
console.log(`${flagged.length}/${urls.length} URLs flagged as scams`);

Accuracy

| Mode | Image | Text | Links | |---|---|---|---| | Heuristic only | ~60–70% | ~80–90% | ~85–95% | | + AI (OpenAI key) | 95%+ | 95%+ | 85–95% |

Link detection is entirely heuristic and requires no API key.

Privacy

• Heuristic mode: 100% local — no data leaves your machine.
• AI mode: Image/text content is sent to OpenAI's API for analysis. Review OpenAI's privacy policy before processing sensitive data.

License

MIT © scam-detector contributors