URL Sheriff

URL Sheriff is a security library that validates URLs and prevents Server-Side Request Forgery (SSRF) attacks by detecting and blocking requests to private or internal network addresses.

Package Information

• Package Name: url-sheriff
• Package Type: npm
• Language: TypeScript
• Installation: npm install url-sheriff
• Minimum Node Version: 22.0.0

Quick Reference for Agents

Primary Use Case: Validate URLs before making HTTP requests to prevent SSRF attacks.

Core Method: isSafeURL(url: string | URL): Promise<boolean> - Main validation method that throws Error if URL is unsafe.

Key Capabilities:

• Blocks private IP ranges (RFC 1918: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
• Blocks loopback addresses (127.0.0.0/8, ::1)
• Blocks link-local addresses (169.254.0.0/16, fe80::/10)
• DNS resolution with validation of all resolved IPs
• Custom DNS resolvers support
• Allow-list for trusted internal domains (string or regex patterns)
• Scheme/protocol restrictions (e.g., HTTPS-only)
• IPv4 and IPv6 support including IPv4-mapped IPv6 addresses

When to Use:

• Validating user-provided URLs before fetching
• API endpoints that accept URLs as input
• Webhook receivers that need to make outbound requests
• Any service that processes URLs from untrusted sources
• Preventing SSRF attacks in server-side applications

Error Handling: All methods throw standard JavaScript Error objects. Always wrap isSafeURL() calls in try-catch blocks.

Core Imports

import URLSheriff from 'url-sheriff';

For CommonJS:

const URLSheriff = require('url-sheriff');

Quick Start

import URLSheriff from 'url-sheriff';

const sheriff = new URLSheriff();

try {
  await sheriff.isSafeURL('https://example.com'); // Returns true
  await sheriff.isSafeURL('http://127.0.0.1:3000'); // Throws Error
} catch (error) {
  console.error('URL is unsafe:', error.message);
}

See Quick Start Guide for detailed getting started instructions.

Architecture Overview

URL Sheriff performs multi-layered URL validation:

1. URL Parsing: Validates URL structure and extracts hostname and scheme
2. Scheme Validation: Checks if the URL protocol is allowed (when configured)
3. Allow-list Checking: Matches hostname against configured allow-list entries (strings and regex patterns)
4. IP Address Detection: Identifies if hostname is a direct IP address and validates it's not in private ranges
5. DNS Resolution: Resolves domain names to IP addresses and validates all resolved IPs are not private
6. Private IP Detection: Uses ipaddr.js to identify private, loopback, and internal network addresses

The library supports custom DNS resolvers, runtime allow-list management, and debug logging via Node.js debuglog.

Quick Reference Tables

Main Methods

Configuration Options

Error Messages

Documentation Structure

Guides

• Quick Start Guide - Step-by-step getting started instructions
  • Installation and setup
  • Basic usage patterns
  • Common configuration scenarios

Examples

• Real-World Scenarios - Comprehensive usage examples

  • URL validation patterns
  • Allow-list management
  • Scheme restrictions
  • Integration patterns (Express.js, request wrappers, batch validation)
  • Security best practices
  • Performance optimization

• Edge Cases - Advanced scenarios and corner cases

  • IPv6 handling
  • Private IP range coverage
  • Malformed URL handling
  • DNS resolution edge cases
  • Allow-list edge cases
  • Scheme validation edge cases
  • Concurrent validation

Reference

• API Reference - Complete API documentation

  • URLSheriff class methods
  • Method signatures and return types
  • Parameter descriptions
  • Error conditions

• Configuration Reference - Detailed configuration options

  • URLSheriffConfig interface
  • Configuration option details
  • Behavior specifications

Security Considerations

URL Sheriff protects against SSRF attacks by:

1. Blocking Private IP Ranges: RFC 1918 networks (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
2. Blocking Loopback Addresses: 127.0.0.0/8 and ::1
3. Blocking Link-Local Addresses: 169.254.0.0/16 and fe80::/10
4. DNS Resolution Validation: Validates all resolved IP addresses
5. IPv4-Mapped IPv6 Handling: Correctly identifies private IPv4 addresses in IPv6 format

See Real-World Scenarios for security best practices.

Debug Logging

Enable debug logging with Node.js util.debuglog:

NODE_DEBUG=url-sheriff node your-app.js

Debug logs include initialization, URL parsing, DNS resolution, allow-list checking, IP validation, and scheme validation.

Dependencies

• ipaddr.js (v2.2.0): IP address parsing and validation
• Node.js built-in modules: url, node:dns/promises, node:util