Install

npm install --save url-sheriff

Usage

Basic Usage

import URLSheriff from 'url-sheriff'

// initialize
const sheriff = new URLSheriff()

// this will throw an Error exception
sheriff.isSafeURL('http://127.0.0.1:3000')

Using Custom DNS Resolvers

You can specify custom DNS resolvers to use when resolving hostnames:

import URLSheriff from 'url-sheriff'

const sheriff = new URLSheriff({
  dnsResolvers: ['1.1.1.1', '8.8.8.8']
})

// Will use the specified DNS resolvers for hostname lookups
await sheriff.isSafeURL('https://example.com')

Using Allow-lists

URL Sheriff supports allow-lists to specify domains or IP addresses that should be considered safe, even if they would normally be flagged as private or internal.

Initializing with an Allow-list

import URLSheriff from 'url-sheriff'

const sheriff = new URLSheriff({
  allowList: [
    'localhost',                    // String literal
    '127.0.0.1',                    // IP address
    /^.*\.internal\.company\.com$/  // RegExp pattern
  ]
})

// This will now return true instead of throwing an error
const isSafe = await sheriff.isSafeURL('http://localhost:3000')

Managing the Allow-list

You can add or remove entries from the allow-list after initialization:

// Add new entries to the allow-list
sheriff.addToAllowList(['trusted-domain.com', /^api-\d+\.example\.org$/])

// Remove entries from the allow-list
sheriff.removeFromAllowList(['no-longer-trusted.com'])

// Get the current allow-list
const currentAllowList = sheriff.getAllowList()

How the Allow-list Works

1. When checking if a URL is safe, the hostname is first checked against the allow-list.
2. If the hostname matches any entry in the allow-list (either a string literal or a regex pattern), the URL is immediately considered safe.
3. If the hostname doesn't match any entry in the allow-list, the normal safety checks proceed:
   • Check if the hostname is a valid IP address and if it's private
   • Resolve the hostname to IP addresses and check if any are private
4. Additionally, if any of the resolved IP addresses match entries in the allow-list, the URL is considered safe.

Debug Logging

URLSheriff uses Node.js's built-in util.debuglog for debug logging. To enable debug logs, set the NODE_DEBUG environment variable to include url-sheriff:

# Enable debug logs for URLSheriff
NODE_DEBUG=url-sheriff node your-app.js

# Enable multiple debug namespaces
NODE_DEBUG=url-sheriff,http,net node your-app.js

When debug logging is enabled, URLSheriff will output detailed information about:

• Initialization and configuration
• URL parsing and validation steps
• DNS resolution processes
• Allow-list checks
• IP address validation results

This can be helpful for:

• Troubleshooting URL validation issues
• Understanding why certain URLs are being blocked
• Verifying that DNS resolution is working correctly
• Monitoring allow-list functionality

Allowed Schemes

Initialize with allowed schemes

const sheriff = new URLSheriff({
  allowedSchemes: ['https', 'http']
});

Or set allowed schemes after initialization

sheriff.setAllowedSchemes(['https']);

Check if a URL is safe

await sheriff.isSafeURL('https://example.com'); // This will pass
await sheriff.isSafeURL('ftp://example.com');   // This will throw an error

Get current allowed schemes

const schemes = sheriff.getAllowedSchemes(); // Returns ['https']

Remove all scheme restrictions

sheriff.clearSchemeRestrictions();

Contributing

Please consult CONTRIBUTING for guidelines on contributing to this project.

Author

url-sheriff © Liran Tal, Released under the Apache-2.0 License.