Usage

Basic Analysis

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

const tracer = new URLDeepTrace();

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

console.log('Risk Score:', result.security.risk.score);
console.log('Risk Level:', result.security.risk.level);

Configuration 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 analysis
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

analyze(url)

Analyze a single URL with full forensics.

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

analyzeMultiple(urls)

Analyze multiple URLs concurrently.

const results = await tracer.analyzeMultiple([
  'https://example.com',
  'https://example.org',
]);

analyzeMultipleParallel(urls, options)

Analyze URLs in controlled batches with concurrency limits.

const results = await tracer.analyzeMultipleParallel(urls, {
  batchSize: 5,
  delayBetweenBatches: 1000,
});

exportResults(results, format, options)

Export analysis results as JSON or CSV.

const json = await tracer.exportResults(results, 'json');
const csv = await tracer.exportResults(results, '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: { /* certificate details */ },
      lexical: { /* URL pattern analysis */ },
      domainInfo: { /* DNS records, TLD reputation */ },
      headerFingerprint: { /* security headers */ },
      htmlAnalysis: { /* form, script, iframe analysis */ },
      timing: { /* request timing */ }
    }]
  },
  security: {
    risk: {
      score: 15,
      level: "minimal",
      factors: [],
      details: {}
    }
  },
  metadata: {
    analyzedAt: "2026-01-21T10:30:00.000Z",
    executionTime: 2345
  }
}

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

Score	Level
0–29	Minimal
30–59	Low
60–79	Medium
80–100	High