Skip to content

README.md

Latest commit

 

History

History
148 lines (106 loc) · 3.68 KB

README.md

File metadata and controls

148 lines (106 loc) · 3.68 KB

URL Checker

A Node.js utility to check URL validity, availability, and potential risks.

Features

  • Validates URL format
  • Checks URL availability (HTTP response)
  • Detects potential security risks:
    • Suspicious protocols (javascript:, data:, file:)
    • IP addresses instead of domain names
    • Phishing indicators
    • Suspicious TLDs
  • Supports both single URL and array of URLs
  • Returns Boolean for single URL
  • Returns Object/Dictionary for array of URLs

Installation

npm install

Usage

Single URL Check

Check a single URL and get a boolean result:

const { checkUrl } = require('./index');

// Check a single URL (with availability check)
const result = await checkUrl('https://www.google.com');
console.log(result); // true if safe and available, false otherwise

// Check a single URL (without availability check)
const result2 = await checkUrl('https://www.google.com', { checkAvailability: false });
console.log(result2); // true if valid and safe, false otherwise

Multiple URLs Check

Check multiple URLs and get an object with results:

const { checkUrls } = require('./index');

// Check multiple URLs
const urls = [
  'https://www.google.com',
  'https://www.github.com',
  'invalid-url',
  'javascript:alert(1)'
];

// With availability check (default)
const results = await checkUrls(urls);

// Without availability check
const results2 = await checkUrls(urls, { checkAvailability: false });

console.log(results);
// {
//   'https://www.google.com': true,
//   'https://www.github.com': true,
//   'invalid-url': false,
//   'javascript:alert(1)': false
// }

API

checkUrl(urlString, options)

Checks a single URL for validity, availability, and potential risks.

Parameters:

  • urlString (string): The URL to check
  • options (Object, optional): Configuration options
    • checkAvailability (boolean): Whether to check URL availability via HTTP request (default: true)

Returns:

  • Promise<boolean>: Returns true if the URL is safe and available, false otherwise

checkUrls(urls, options)

Checks multiple URLs for validity, availability, and potential risks.

Parameters:

  • urls (string[]): Array of URLs to check
  • options (Object, optional): Configuration options
    • checkAvailability (boolean): Whether to check URL availability via HTTP request (default: true)

Returns:

  • Promise<Object>: Returns an object where keys are URLs and values are booleans indicating safety

Testing

Run the tests:

npm test

How It Works

The URL checker performs the following checks:

  1. Validity Check: Validates the URL format and ensures it uses http or https protocol
  2. Risk Detection: Checks for suspicious patterns including:
    • Dangerous protocols (javascript:, data:, file:)
    • IP addresses instead of domain names
    • Phishing indicators (@ symbol)
    • Suspicious keywords (exec, eval)
    • Suspicious TLDs (.tk, .ml, .ga, .cf, .gq, .zip, .mov)
  3. Availability Check: Sends an HTTP HEAD request to verify the URL responds

If all checks pass, the URL is considered safe and returns true. If any check fails, it returns false.

Example

const { checkUrl, checkUrls } = require('./index');

async function main() {
  // Check single URL
  const isSafe = await checkUrl('https://www.example.com');
  console.log(`Is https://www.example.com safe? ${isSafe}`);
  
  // Check multiple URLs
  const results = await checkUrls([
    'https://www.google.com',
    'https://malicious-site.tk',
    'javascript:void(0)'
  ]);
  
  for (const [url, isSafe] of Object.entries(results)) {
    console.log(`${url}: ${isSafe ? 'Safe ✓' : 'Unsafe ✗'}`);
  }
}

main();

License

ISC