CatchDem - Ghana Mobile Money Fraud Detector

A comprehensive fraud detection package for mobile money transactions using AWS Bedrock AI models. This package helps users identify fraudulent SMS messages and transaction screenshots commonly used in mobile money scams in Ghana. Supports multiple AWS Bedrock models with Nova Lite as the default.

Features

• 🔍 Text Analysis: Analyze SMS messages for fraud patterns
• 🖼️ Image Analysis: Analyze transaction screenshots and images (in-memory processing)
• ☁️ AWS Integration: Uses AWS Bedrock AI models (Nova Lite default, customizable)
• 🎯 Flexible Models: Support for multiple AWS Bedrock models (Claude, Nova, etc.)
• 🛡️ Ghana-Focused: Specifically trained on Ghana mobile money fraud patterns
• 📊 Detailed Results: Provides confidence scores and detailed analysis
• 🚀 Easy to Use: Simple API with TypeScript support
• ⚡ No S3 Required: Direct in-memory image processing

Installation

npm install momo-fraud-detector

Quick Start

Text Analysis

import { FraudDetector, AWSConfig } from "momo-fraud-detector";

const awsConfig: AWSConfig = {
  region: "us-east-1",
  accessKeyId: "your-access-key-id",
  secretAccessKey: "your-secret-access-key",
};

// Using default Nova Lite model
const detector = new FraudDetector({ aws: awsConfig });

// Or using a custom model
const detectorWithCustomModel = new FraudDetector({
  aws: awsConfig,
  modelId: "anthropic.claude-3-sonnet-20240229-v1:0", // Custom model
});

// Analyze SMS text
const result = await detector.analyzeText({
  text: "Congratulations! You have won GHS 10,000. Send your PIN to claim your prize.",
});

console.log(result);
// Output:
// {
//   status: "FRAUD",
//   confidence: 95,
//   analysisDetails: "FRAUD - This message requests PIN information which legitimate services never do. The urgent language and promise of money are classic fraud indicators."
// }

Image Analysis

import { FraudDetector, AWSConfig } from "momo-fraud-detector";
import { readFileSync } from "fs";

const awsConfig: AWSConfig = {
  region: "us-east-1",
  accessKeyId: "your-access-key-id",
  secretAccessKey: "your-secret-access-key",
};

const detector = new FraudDetector({ aws: awsConfig });

// Analyze image from file path
const result = await detector.analyzeImage({
  image: "/path/to/screenshot.jpg",
  context: "Received this transaction receipt via WhatsApp",
});

// Or analyze image from buffer
const imageBuffer = readFileSync("/path/to/screenshot.jpg");
const result2 = await detector.analyzeImage({
  image: imageBuffer,
});

console.log(result);

Convenience Functions

For quick one-off analyses, you can use the convenience functions:

import { detectTextFraud, detectImageFraud } from "momo-fraud-detector";

// Quick text analysis with default model
const textResult = await detectTextFraud(
  "Your MTN account has been suspended. Click here to reactivate: bit.ly/fake-link",
  awsConfig,
  { debug: true }
);

// Quick text analysis with custom model
const textResultCustom = await detectTextFraud(
  "Suspicious SMS content here",
  awsConfig,
  {
    modelId: "anthropic.claude-3-haiku-20240307-v1:0",
    debug: true,
  }
);

// Quick image analysis with custom model
const imageResult = await detectImageFraud("/path/to/image.jpg", awsConfig, {
  modelId: "anthropic.claude-3-sonnet-20240229-v1:0",
  context: "Suspicious transaction receipt",
});

Configuration

AWS Configuration

interface AWSConfig {
  region: string; // AWS region (e.g., 'us-east-1')
  accessKeyId: string; // AWS access key ID
  secretAccessKey: string; // AWS secret access key
}

Fraud Detector Options

interface FraudDetectorOptions {
  aws: AWSConfig; // AWS configuration
  modelId?: string; // AWS Bedrock model ID (defaults to 'us.amazon.nova-lite-v1:0')
  customPrompt?: string; // Custom master prompt (optional)
  debug?: boolean; // Enable debug logging
  timeout?: number; // API timeout in milliseconds (default: 30000)
  maxImageSize?: number; // Max image size in bytes (default: 10MB)
}

API Reference

FraudDetector Class

Constructor

new FraudDetector(options: FraudDetectorOptions)

Methods

analyzeText(input: TextAnalysisInput): Promise

Analyze SMS text for fraud patterns.

interface TextAnalysisInput {
  text: string; // SMS text content
}

analyzeImage(input: ImageAnalysisInput): Promise

Analyze transaction screenshot or image for fraud.

interface ImageAnalysisInput {
  image: Buffer | string; // Image buffer or file path
  context?: string; // Additional context about the image
}

testConnection(): Promise

Test connection to the configured AWS Bedrock model.

Result Format

interface FraudDetectionResult {
  status: FraudStatus; // FRAUD or NOT_FRAUD
  confidence: number; // Confidence level (60-95)
  analysisDetails: string; // Detailed analysis explanation
}

Model Compatibility

The package supports multiple AWS Bedrock models:

Recommended Models

• Nova Lite (us.amazon.nova-lite-v1:0) - Default, optimized for cost and speed
• Claude 3 Haiku (anthropic.claude-3-haiku-20240307-v1:0) - Fast and efficient
• Claude 3 Sonnet (anthropic.claude-3-sonnet-20240229-v1:0) - Balanced performance
• Claude 3 Opus (anthropic.claude-3-opus-20240229-v1:0) - Highest accuracy

Model Selection Guidelines

• Nova Lite: Best for high-volume, cost-sensitive applications
• Claude Haiku: Good balance of speed and accuracy for real-time applications
• Claude Sonnet: Recommended for production applications requiring high accuracy
• Claude Opus: Use when maximum accuracy is critical, regardless of cost

Usage Example with Different Models

// Cost-optimized (default)
const fastDetector = new FraudDetector({
  aws: awsConfig,
  modelId: "us.amazon.nova-lite-v1:0",
});

// Balanced performance
const balancedDetector = new FraudDetector({
  aws: awsConfig,
  modelId: "anthropic.claude-3-sonnet-20240229-v1:0",
});

// Maximum accuracy
const preciseDetector = new FraudDetector({
  aws: awsConfig,
  modelId: "anthropic.claude-3-opus-20240229-v1:0",
});

Fraud Patterns Detected

The package is specifically designed to detect common fraud patterns in Ghana:

1. Fake Transaction Notifications

• SMS claiming money was sent/received when no actual transaction occurred
• Incorrect sender names or phone numbers
• Unusual transaction reference numbers

2. Phishing Attempts

• Messages asking for PIN, passwords, or personal information
• Fake customer service numbers
• Links to fake websites

3. SIM Swap Fraud

• Messages about SIM card changes or activations
• Unexpected password reset alerts

4. Fake Promotions/Rewards

• "You have won" messages with unrealistic prizes
• Fake lottery notifications
• Messages requiring fees to claim rewards

5. Impersonation Scams

• Messages claiming to be from banks, telcos, or government
• Incorrect official language or formatting

6. Investment/Romance Scams

• Get-rich-quick schemes
• Romantic messages from unknown numbers

Error Handling

The package provides specific error types for different scenarios:

import {
  FraudDetectionError,
  AWSServiceError,
  InvalidInputError,
  ConfigurationError,
  ImageProcessingError,
} from "momo-fraud-detector";

try {
  const result = await detector.analyzeText({ text: "..." });
} catch (error) {
  if (error instanceof InvalidInputError) {
    console.error("Invalid input:", error.message);
  } else if (error instanceof AWSServiceError) {
    console.error("AWS service error:", error.message);
  } else if (error instanceof ConfigurationError) {
    console.error("Configuration error:", error.message);
  }
}

AWS Setup

1. Create AWS Account

Sign up for an AWS account if you don't have one.

2. Enable AWS Bedrock Models

• Go to AWS Bedrock console
• Enable the models you want to use (Nova Lite is enabled by default)
• For other models like Claude, request access if needed
• Available models include:
  • us.amazon.nova-lite-v1:0 (default)
  • anthropic.claude-3-sonnet-20240229-v1:0
  • anthropic.claude-3-haiku-20240307-v1:0
  • anthropic.claude-3-opus-20240229-v1:0

3. No Additional Setup Required

The package now processes images in-memory, so no S3 bucket setup is required.

4. Create IAM User

Create an IAM user with the following permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ],
      "Resource": [
        "arn:aws:bedrock:*:*:model/us.amazon.nova-lite-v1:0",
        "arn:aws:bedrock:*:*:model/anthropic.claude-3-*"
      ]
    }
  ]
}

Examples

Basic Usage

import { FraudDetector } from "momo-fraud-detector";

const detector = new FraudDetector({
  aws: {
    region: "us-east-1",
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
  modelId: "us.amazon.nova-lite-v1:0", // Optional: specify model
  debug: true,
});

// Test connection
const isConnected = await detector.testConnection();
console.log("Connected to AWS:", isConnected);

// Analyze suspicious SMS
const smsResult = await detector.analyzeText({
  text: "URGENT: Your account will be blocked. Send PIN to 1234 to prevent this.",
});

console.log("SMS Analysis:", smsResult);

Batch Processing

const suspiciousMessages = [
  "You have won GHS 50,000! Call 0244123456 to claim.",
  "Your MTN MoMo PIN has expired. Reply with your PIN to renew.",
  "Legitimate transaction: You have received GHS 100 from John Doe.",
];

const results = await Promise.all(
  suspiciousMessages.map((text) => detector.analyzeText({ text }))
);

results.forEach((result, index) => {
  console.log(`Message ${index + 1}: ${result.status} (${result.confidence}%)`);
});

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For support, please open an issue on GitHub or contact the development team.

Changelog

v1.0.0

• Initial release
• Text and image fraud detection
• Support for multiple AWS Bedrock models (Nova Lite, Claude 3 series)
• Configurable modelId parameter with Nova Lite as default
• Ghana-specific fraud patterns
• TypeScript support
• In-memory image processing
• Comprehensive error handling
• Debug logging support