@fazelstudio/url-deep-trace

Enterprise-grade URL tracing engine with SSL forensics, threat intelligence, ML classification, and heuristic risk scoring. Designed for SOC operations, API security services, and penetration testing workflows.

Note: This library performs read-only, non-invasive analysis. It does not bypass authentication or paywalls.

Features

Core Tracing

• Redirect Chain Tracing — manual HTTP 3xx handling with cookie jar management
• Meta Refresh Detection — parses HTML for <meta http-equiv="refresh">
• JavaScript Redirect Detection — identifies location.href, location.replace, window.location
• Deep SSL/TLS Forensics — parallel socket-level certificate inspection with expiry tracking

Analysis Modules

Module	Description
Lexical Analyzer	URL entropy, subdomain analysis, homoglyph/punycode detection, port analysis
HTML Analyzer	Form analysis, script obfuscation, iframe inspection, external resource tracking
Domain Intelligence	DNS records (A, AAAA, MX, TXT, SPF, DMARC), TLD reputation, domain age estimation
Header Fingerprint	Security header audit (HSTS, CSP, XFO, etc.), cookie security, CORS analysis
Behavioral Analyzer	Redirect patterns, domain hopping, protocol switching, cloaking detection
Threat Intelligence	Phishing, malware, SQLi/XSS detection, brand impersonation, IOC extraction
ML Classifier	Feature extraction, weighted scoring (benign → malicious), explainable AI
Reputation Cache	SHA-256 URL indexing, LRU eviction, TTL-based expiration, blacklist/whitelist
Performance Manager	Batch processing, rate limiting, exponential backoff retry
Webhook Notifier	Conditional alerts (high risk, malicious), retry mechanism, batch notifications
Rate Limiter	Sliding window algorithm, per-domain limits, queue management
Reporting Engine	JSON/CSV export, executive/technical/compliance/incident reports

Risk Scoring

Multi-factor heuristic scoring (0–100):

Factor	Points
Excessive redirects (>5 hops)	+5–30
Protocol downgrade (HTTPS → HTTP)	+35
Certificate issues	+15–30
Suspicious TLD (.xyz, .top, etc.)	+12/domain
Meta refresh / JS redirects	+10–12
Circular redirects	+20
HTML obfuscation	+10–25
Phishing indicators	+10–25
Malware indicators	+15–30

Risk levels: minimal (0–29), low (30–59), medium (60–79), high (80–100)

Installation

npm install @fazelstudio/url-deep-trace

Optional dependencies for screenshot capture:

npm install playwright
# or
npm install puppeteer

Quick Start

import URLDeepTrace from '@fazelstudio/url-deep-trace';

const tracer = new URLDeepTrace({
  maxHops: 20,
  timeout: 15000,
  enableDeepAnalysis: true,
  enableThreatIntel: true,
  enableMLClassification: true,
});

const result = await tracer.analyze('https://example.com');

console.log('Risk Score:', result.security.risk.score);       // 15
console.log('Risk Level:', result.security.risk.level);      // "minimal"
console.log('ML Class:', result.mlClassification.classification);

API Reference

URLDeepTrace(options?)

Option	Type	Default	Description
maxHops	number	20	Maximum redirect hops
timeout	number	15000	Request timeout (ms)
userAgent	string	preset	Custom user agent
enableDeepAnalysis	boolean	true	Enable lexical, domain, header, HTML, TLS
enableThreatIntel	boolean	true	Enable threat intelligence
enableMLClassification	boolean	true	Enable ML classifier
maxConcurrent	number	5	Concurrent analysis limit
retryAttempts	number	2	Retry attempts on failure
retryDelay	number	1000	Delay (ms) between retries

Methods

Method	Description
analyze(url)	Analyze a single URL with full forensics
analyzeMultiple(urls)	Analyze multiple URLs concurrently
analyzeMultipleParallel(urls, options)	Analyze URLs in controlled batches
exportResults(results, format, options)	Export results as JSON or CSV

Response Structure

{
  success: true,
  url: "https://example.com",
  finalDestination: "https://example.com",
  trace: {
    totalHops: 1,
    chain: [{
      url: "https://example.com",
      statusCode: 200,
      protocol: "https",
      tlsInfo: { ... },
      lexical: { ... },
      domainInfo: { ... },
      headerFingerprint: { ... },
      htmlAnalysis: { ... },
      timing: { ... }
    }]
  },
  security: {
    risk: { score: 15, level: "minimal", factors: [...], details: { ... } }
  },
  metadata: {
    analyzedAt: "2026-01-21T10:30:00.000Z",
    executionTime: 2345
  }
}

Architecture

src/
├── index.js                 # Main entry point
├── tracer.js                # Recursive URL tracer
├── tls-inspector.js         # SSL/TLS forensics
├── lexical-analyzer.js      # URL pattern analysis
├── html-analyzer.js         # HTML structure inspection
├── domain-intelligence.js   # DNS and domain analysis
├── header-fingerprint.js    # HTTP header security audit
├── risk-engine.js           # Security risk scoring
├── performance-manager.js      # Batch processing & export
├── behavioral-analyzer.js  # Redirect behavior analysis
├── threat-intelligence.js  # Phishing, malware detection
├── ml-classifier.js        # ML classification engine
├── reputation-cache.js     # LRU cache with blacklist
├── rate-limiter.js         # Sliding window rate limiter
├── webhook-notifier.js      # Conditional alerting
├── reporting-engine.js      # Multi-format report generator
├── screenshot-capture.js   # Browser screenshot (optional)

Development

# Install
npm install

# Run tests
npm test
npm run test:all
npm run test:optimization

# Start API server
npm run server

# Lint & format
npm run lint
npm run format

License

MIT — © 2026 Fazel