@ows-sdk/threat-intelligence

Enterprise-grade threat intelligence engine for real-time IP reputation analysis, threat feed integration, and comprehensive security assessments.

Architecture Overview

graph TB
    subgraph Client Application
        A[Your Application]
    end
    
    subgraph Threat Intelligence Engine
        B[ThreatIntelligenceEngine]
        C[IPReputationService]
        D[ThreatFeedManager]
        E[ThreatStore]
    end
    
    subgraph Resilience Layer
        F[Circuit Breaker]
        G[Rate Limiter]
        H[Retry with Backoff]
    end
    
    subgraph Data Layer
        I[(Redis Cache)]
        J[External Threat Feeds]
        K[IP Reputation Providers]
    end
    
    A --> B
    B --> C
    B --> D
    C --> E
    D --> E
    C --> F
    D --> F
    F --> G
    G --> H
    E --> I
    H --> J
    H --> K

Features

graph TB
    subgraph Core Capabilities
        A[IP Reputation Analysis]
        B[Threat Feed Integration]
        C[Multi-Indicator Support]
    end
    
    subgraph Detection Types
        D[Malicious IP Detection]
        E[VPN Detection]
        F[Proxy Detection]
        G[Tor Exit Node Detection]
    end
    
    subgraph Enterprise Features
        H[Redis Caching]
        I[Circuit Breaker Pattern]
        J[Exponential Backoff]
        K[Structured Logging]
        L[Health Checks]
    end
    
    A --> D
    A --> E
    A --> F
    A --> G
    B --> C
    H --> I
    I --> J
    J --> K
    K --> L

Installation

npm install @ows-sdk/threat-intelligence

Quick Start

import { ThreatIntelligenceEngine, KMSError } from '@ows-sdk/threat-intelligence';

const engine = new ThreatIntelligenceEngine({
  apiKey: 'kms_your_api_key_here' // Required — get yours at https://opendex.com
});

// Initialize (verifies API key against Opendex KMS)
await engine.init();

// Analyze a complete threat context
const threats = await engine.analyzeThreat({
  ip: '203.0.113.50',
  domain: 'suspicious-domain.com',
  email: '[email protected]',
  url: 'https://malicious-site.com/path'
});

// Get detailed IP reputation
const reputation = await engine.getIPReputation('203.0.113.50');

console.log(reputation);
// {
//   ip: '203.0.113.50',
//   reputation: 'suspicious',
//   score: 45,
//   categories: ['proxy'],
//   country: 'US',
//   isp: 'Example ISP',
//   threats: [...]
// }

// Clean up
await engine.close();

Data Flow

graph TB
    subgraph Input
        A[IP Address]
        B[Domain]
        C[Email]
        D[URL]
    end
    
    subgraph Authentication
        Z[Opendex KMS Verification]
    end
    
    subgraph Validation
        E[Zod Schema Validation]
    end
    
    subgraph Processing
        F{Cache Check}
        G[Fetch from Providers]
        H[Calculate Score]
        I[Determine Reputation]
    end
    
    subgraph Output
        J[ThreatIndicator Array]
        K[IPReputation Object]
    end
    
    A --> Z
    B --> Z
    C --> Z
    D --> Z
    Z --> E
    E --> F
    F -->|Cache Hit| J
    F -->|Cache Miss| G
    G --> H
    H --> I
    I --> K
    K --> J

API Reference

ThreatIntelligenceEngine

Main orchestrator for threat analysis operations.

import { ThreatIntelligenceEngine } from '@ows-sdk/threat-intelligence';

const engine = new ThreatIntelligenceEngine({
  ipReputationOptions: {
    redisUrl: 'redis://localhost:6379',
    cacheTtlSeconds: 3600,
  },
  threatFeedsOptions: {
    indicatorTtlSeconds: 3600,
    timeoutMs: 30000,
  }
});

Methods

| Method | Description | Returns | |--------|-------------|---------| | analyzeThreat(context) | Analyze IP, domain, email, or URL | Promise<ThreatIndicator[]> | | getIPReputation(ip) | Get detailed IP reputation | Promise<IPReputation \| null> | | close() | Close all connections | Promise<void> |

IPReputationService

Standalone service for IP reputation lookups.

import { IPReputationService } from '@ows-sdk/threat-intelligence';

const service = new IPReputationService({
  redisUrl: process.env.REDIS_URL,
  cacheTtlSeconds: 3600,
  provider: customProvider, // Optional: implement IPReputationProvider
  circuitBreakerOptions: {
    timeout: 3000,
    errorThresholdPercentage: 50,
    resetTimeout: 30000,
  }
});

const reputation = await service.getReputation('8.8.8.8');
const isThreat = await service.checkThreat('8.8.8.8');
const threats = await service.getThreats('8.8.8.8');

ThreatFeedManager

Manage and query external threat intelligence feeds.

import { ThreatFeedManager } from '@ows-sdk/threat-intelligence';

const manager = new ThreatFeedManager({
  indicatorTtlSeconds: 3600,
  timeoutMs: 30000,
});

// Register a threat feed
manager.registerFeed({
  name: 'abuse-ipdb',
  url: 'https://api.abuseipdb.com/api/v2/blacklist',
  format: 'json',
  updateInterval: 3600000,
  enabled: true,
});

// Check an indicator
const threat = await manager.checkIndicator('domain', 'malicious.com');

Types

interface ThreatIndicator {
  type: 'ip' | 'domain' | 'email' | 'hash' | 'url';
  value: string;
  severity: 'low' | 'medium' | 'high' | 'critical';
  source: string;
  firstSeen: Date;
  lastSeen: Date;
  confidence: number;
  metadata: Map<string, unknown>;
}

interface IPReputation {
  ip: string;
  reputation: 'trusted' | 'neutral' | 'suspicious' | 'malicious';
  score: number;        // 0-100, higher is safer
  categories: string[]; // e.g., ['vpn', 'proxy', 'tor']
  country: string;
  isp: string;
  asn: number;
  threats: ThreatIndicator[];
  lastUpdated: Date;
}

Reputation Score

graph TB
    subgraph Score Calculation
        A[Base Score: 100]
        B{Threat Detected?}
        C[Critical: -50]
        D[High: -30]
        E[Medium: -15]
        F[Low: -5]
    end
    
    subgraph Reputation Level
        G[80-100: Trusted]
        H[50-79: Neutral]
        I[30-49: Suspicious]
        J[0-29: Malicious]
    end
    
    A --> B
    B -->|Yes| C
    B -->|Yes| D
    B -->|Yes| E
    B -->|Yes| F
    C --> G
    D --> H
    E --> I
    F --> J

Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | REDIS_URL | Redis connection URL | redis://localhost:6379 | | REDIS_KEY_PREFIX | Cache key prefix | threat-intel | | REDIS_CACHE_TTL | Cache TTL in seconds | 3600 | | LOG_LEVEL | Logging level | info | | LOG_PRETTY | Pretty print logs | false | | CIRCUIT_BREAKER_ENABLED | Enable circuit breaker | true | | CIRCUIT_BREAKER_TIMEOUT | Timeout in ms | 3000 | | CIRCUIT_BREAKER_ERROR_THRESHOLD | Error threshold % | 50 | | CIRCUIT_BREAKER_RESET_TIMEOUT | Reset timeout in ms | 30000 | | RETRY_MAX_ATTEMPTS | Max retry attempts | 3 | | RETRY_INITIAL_DELAY_MS | Initial retry delay | 1000 | | RETRY_MAX_DELAY_MS | Max retry delay | 10000 | | RETRY_BACKOFF_MULTIPLIER | Backoff multiplier | 2 |

Programmatic Configuration

import { loadConfig } from '@ows-sdk/threat-intelligence';

const config = loadConfig();
// Returns validated configuration from environment variables

Custom IP Reputation Provider

Implement your own provider for external IP intelligence services:

import { IPReputationProvider, IPReputationService } from '@ows-sdk/threat-intelligence';

const customProvider: IPReputationProvider = {
  async isVPN(ip: string): Promise<boolean> {
    // Your VPN detection logic
    return false;
  },
  async isProxy(ip: string): Promise<boolean> {
    // Your proxy detection logic
    return false;
  },
  async isTor(ip: string): Promise<boolean> {
    // Your Tor detection logic
    return false;
  },
  async getGeo(ip: string): Promise<{ country: string; isp: string; asn: number }> {
    // Your geolocation logic
    return { country: 'US', isp: 'Example ISP', asn: 12345 };
  }
};

const service = new IPReputationService({
  provider: customProvider
});

Health Checks

import { HealthChecker } from '@ows-sdk/threat-intelligence';
import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL);
const health = new HealthChecker(redis);

const status = await health.check();
// { status: 'healthy', redis: 'connected', timestamp: '2024-...' }

Error Handling

import {
  ThreatIntelligenceEngine,
  KMSError,
  KMSValidationError,
  KMSTimeoutError,
  ValidationError,
  RedisConnectionError,
  ThreatFeedError,
} from '@ows-sdk/threat-intelligence';

const engine = new ThreatIntelligenceEngine({ apiKey: 'kms_...' });

try {
  await engine.init();
  await engine.analyzeThreat({ ip: '203.0.113.50' });
} catch (error) {
  // KMS Authentication errors
  if (error instanceof KMSValidationError) {
    console.error(`API key invalid [${error.code}]: ${error.userMessage}`);
  } else if (error instanceof KMSTimeoutError) {
    console.error('KMS is unreachable, retrying...');
  } else if (error instanceof KMSError) {
    console.error(`KMS error [${error.code}]: ${error.userMessage}`);
  }
  // Application errors
  else if (error instanceof ValidationError) {
    console.error('Invalid input:', error.message);
  } else if (error instanceof RedisConnectionError) {
    console.error('Redis connection failed:', error.message);
  } else if (error instanceof ThreatFeedError) {
    console.error('Threat feed error:', error.message);
  }
}

Requirements

• Node.js >= 20.0.0
• Redis >= 6.0 (for caching)

License

Proprietary - Copyright © 2024 Opendex, Inc. All rights reserved.

For licensing inquiries, contact: [email protected]