npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

url-sheriff

v2.0.0

Published

validate and prevent against SSRF

Readme

Install

npm install --save url-sheriff

Usage

Basic Usage

import URLSheriff from 'url-sheriff'

const sheriff = new URLSheriff()

await sheriff.isSafeURL('https://example.com') // true

// Throws `URL uses a private hostname`
await sheriff.isSafeURL('http://127.0.0.1:3000')

Secure Defaults

URL Sheriff allows only http and https URLs by default. A URL being accepted by new URL() means it is syntactically valid; it does not mean the URL is safe for a server to access. Hostless URLs and hostnames that resolve to no IP addresses are rejected because URL Sheriff cannot establish a safe network destination.

Scheme checks are applied before hostname, allow-list, and IP-address validation. Configure every additional scheme explicitly and ensure the downstream client is safe for that scheme.

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

Resolved IP addresses are always checked for private ranges. They are not matched against the allow-list.

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

The effective default is always ['http', 'https']:

const sheriff = new URLSheriff()

sheriff.getAllowedSchemes() // ['http', 'https']

Opt in to additional schemes explicitly:

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

await sheriff.isSafeURL('ftp://example.com') // true when the host resolves publicly

Schemes are matched case-insensitively. Passing an empty list or calling clearSchemeRestrictions() restores the secure HTTP/HTTPS defaults:

sheriff.setAllowedSchemes([])
sheriff.getAllowedSchemes() // ['http', 'https']

sheriff.setAllowedSchemes(['ftp'])
sheriff.clearSchemeRestrictions()
sheriff.getAllowedSchemes() // ['http', 'https']

Explicitly enabling a scheme does not bypass hostname validation. Hostless URLs such as file:///etc/passwd are rejected because there is no network destination to validate. DNS resolution must also return at least one address before a URL can be considered safe.

Migrating from 1.x

Version 2.0.0 changes scheme handling to fail closed:

  • Unconfigured instances allow HTTP and HTTPS instead of every scheme.
  • Consumers that require FTP or another scheme must add it to allowedSchemes explicitly.
  • allowedSchemes: [] and clearSchemeRestrictions() restore HTTP/HTTPS defaults instead of allowing every scheme.
  • getAllowedSchemes() returns the effective list instead of null.
  • Hostless URLs and hostnames resolving to no addresses now throw errors instead of returning true.

References and Prior work

Documentation

Contributing

Please consult CONTRIBUTING for guidelines on contributing to this project.

Author

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