Configuration Reference

Detailed configuration options for URL Sheriff.

URLSheriffConfig Interface

Configuration interface for initializing URLSheriff.

interface URLSheriffConfig {
  /**
   * Optional array of custom DNS resolver IP addresses (e.g., ['1.1.1.1', '8.8.8.8'])
   * When provided, these resolvers are used instead of system DNS
   * Resolvers are tried in order until one succeeds
   */
  dnsResolvers?: string[];

  /**
   * Optional array of allowed hostnames or patterns
   * Entries can be:
   * - String literals: exact hostname matches (e.g., 'localhost', '127.0.0.1')
   *   - Case-sensitive matching
   *   - Matches against hostname only, not resolved IP addresses
   * - RegExp patterns: pattern-based matching (e.g., /^.*\.internal\.company\.com$/)
   *   - Case-sensitive by default (use /i flag for case-insensitive)
   *   - Matches against hostname only
   * URLs matching allow-list entries bypass private IP checks
   */
  allowList?: Array<string | RegExp>;

  /**
   * Optional array of allowed URL schemes/protocols (e.g., ['http', 'https', 'ftp'])
   * When provided, only URLs with these schemes are allowed
   * Schemes are case-insensitive and automatically normalized to lowercase
   * When omitted or null, all schemes are allowed
   */
  allowedSchemes?: string[];
}

Configuration Options

dnsResolvers

Type: string[]? (optional)

Description: Array of custom DNS resolver IP addresses. When provided, these resolvers are used instead of system DNS. Resolvers are tried in order until one succeeds.

Example:

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

Behavior:

• If provided, resolveHostnameViaServers() method becomes available
• Resolvers are tried sequentially until one succeeds
• Only IPv4 addresses are returned when using custom resolvers
• If not provided, system DNS resolver is used (via hostnameLookup())

allowList

Type: Array<string | RegExp>? (optional)

Description: Array of allowed hostnames or patterns. URLs matching allow-list entries bypass private IP checks.

Entry Types:

1. String literals: Exact hostname matches

   • Case-sensitive matching
   • Matches against hostname only, not resolved IP addresses
   • Example: 'localhost', '127.0.0.1'

2. RegExp patterns: Pattern-based matching

   • Case-sensitive by default (use /i flag for case-insensitive)
   • Matches against hostname only
   • Example: /^.*\.internal\.company\.com$/

Example:

const sheriff = new URLSheriff({
  allowList: [
    'localhost',                           // Exact string match
    '127.0.0.1',                          // IP address match
    /^.*\.internal\.company\.com$/,       // Regex pattern match
    /^api-\d+\.staging\.example\.org$/    // Dynamic subdomain pattern
  ]
});

Important Notes:

• Allow-list entries match against hostname only, not resolved IP addresses
• If a domain resolves to a private IP but the hostname matches an allow-list entry, it's allowed
• If a domain resolves to a private IP but the hostname doesn't match, it's blocked
• String literals are case-sensitive
• RegExp patterns are case-sensitive by default (use /i flag for case-insensitive)
• The allow-list provides an exception to private IP checks - ensure entries are genuinely trusted

allowedSchemes

Type: string[]? (optional)

Description: Array of allowed URL schemes/protocols. When provided, only URLs with these schemes are allowed. Schemes are case-insensitive and automatically normalized to lowercase.

Example:

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

Behavior:

• Schemes are case-insensitive ('HTTPS', 'https', 'Https' all work)
• Schemes are automatically normalized to lowercase
• When omitted or null, all schemes are allowed
• Empty array ([]) clears restrictions (same as null)
• Can be updated at runtime using setAllowedSchemes()

Common Use Cases:

• Production: ['https'] - Only HTTPS allowed
• Development: ['http', 'https'] - HTTP and HTTPS allowed
• All protocols: undefined or null - No restrictions

Configuration Examples

Default Configuration

No restrictions, blocks all private IPs:

const sheriff = new URLSheriff();

Production Configuration

HTTPS-only with minimal allow-list:

const sheriff = new URLSheriff({
  allowedSchemes: ['https'],
  allowList: ['trusted-api.internal.com']
});

Development Configuration

Allow HTTP/HTTPS and localhost:

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

Custom DNS Configuration

Use specific DNS resolvers:

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

Complex Allow-list Configuration

Mix of string literals and regex patterns:

const sheriff = new URLSheriff({
  allowList: [
    'localhost',
    '127.0.0.1',
    /^.*\.internal\.company\.com$/,
    /^api-\d+\.staging\.example\.org$/,
    /^service-[a-z]+\.dev\.company\.com:\d+$/
  ]
});

Runtime Configuration Changes

Configuration can be modified at runtime using instance methods:

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

// Update allowed schemes
sheriff.setAllowedSchemes(['https', 'http']);

// Add to allow-list
sheriff.addToAllowList(['new-trusted-domain.com']);

// Remove from allow-list
sheriff.removeFromAllowList(['localhost']);

// Clear scheme restrictions
sheriff.clearSchemeRestrictions();

// Get current configuration
const schemes = sheriff.getAllowedSchemes();
const allowList = sheriff.getAllowList();

Note: dnsResolvers cannot be changed after instantiation. Create a new instance if different DNS resolvers are needed.