or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

examples

edge-cases.mdreal-world-scenarios.md

guides

quick-start.md

reference

api.mdconfiguration.md
index.md
tile.json

quick-start.mddocs/guides/

Quick Start Guide

This guide will help you get started with URL Sheriff for SSRF prevention.

Installation

npm install url-sheriff

Requirements: Node.js 22.0.0 or higher

Basic Usage

Import the Library

import URLSheriff from 'url-sheriff';

For CommonJS:

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

Create an Instance

import URLSheriff from 'url-sheriff';

// Default configuration (blocks all private IPs)
const sheriff = new URLSheriff();

Validate a URL

import URLSheriff from 'url-sheriff';

const sheriff = new URLSheriff();

try {
  await sheriff.isSafeURL('https://example.com'); // Returns true
  // URL is safe, proceed with request
} catch (error) {
  console.error('URL is unsafe:', error.message);
  // Handle unsafe URL
}

Handle Unsafe URLs

import URLSheriff from 'url-sheriff';

const sheriff = new URLSheriff();

try {
  await sheriff.isSafeURL('http://127.0.0.1:3000'); // Throws Error
} catch (error) {
  console.error(error.message); // "URL uses a private hostname"
}

Common Configuration Scenarios

Allow Trusted Internal Domains

import URLSheriff from 'url-sheriff';

const sheriff = new URLSheriff({
  allowList: [
    'localhost',
    '127.0.0.1',
    /^.*\.internal\.company\.com$/
  ]
});

await sheriff.isSafeURL('http://localhost:3000'); // Returns true
await sheriff.isSafeURL('https://app.internal.company.com'); // Returns true

Restrict to HTTPS Only

import URLSheriff from 'url-sheriff';

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

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

try {
  await sheriff.isSafeURL('http://example.com'); // Throws Error
} catch (error) {
  console.error(error.message); // "URL scheme 'http' is not allowed"
}

Use Custom DNS Resolvers

import URLSheriff from 'url-sheriff';

const sheriff = new URLSheriff({
  dnsResolvers: ['1.1.1.1', '8.8.8.8'] // Cloudflare and Google DNS
});

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

Next Steps

  • See Real-World Scenarios for comprehensive usage examples
  • Review API Reference for complete method documentation
  • Check Configuration Reference for detailed configuration options
  • Explore Edge Cases for advanced scenarios