Skip to content

Understanding Rule Lists

Rule lists are a fundamental feature in Peakhour that provides a powerful abstraction for managing complex configurations. They allow you to create reusable, maintainable collections of values that can be referenced across multiple rules and configurations, promoting consistency and reducing duplication.

The Purpose of Rule Lists

Traditional security and CDN configurations often require hardcoding values directly into rules, leading to several challenges:

  • Maintenance overhead: Updating a single value requires modifying multiple rules
  • Error-prone management: Manual updates across multiple locations increase mistake likelihood
  • Scalability issues: Large sets of values become unwieldy within individual rules
  • Lack of reusability: Similar value sets must be recreated for different use cases

Rule lists solve these problems by providing centralized, reusable value collections that can be referenced by name across your entire configuration.

Rule List Types and Their Applications

IP Lists: Network-Based Control

IP lists contain collections of IP addresses, CIDR ranges, or network identifiers, enabling network-level access control:

Common use cases:

  • Administrative access control: Define trusted networks for management functions
  • Geographic restrictions: Combine with geolocation for region-specific policies
  • Partner network allowlists: Maintain approved external networks
  • Threat intelligence integration: Block known malicious IP ranges
  • Compliance requirements: Implement regulatory network restrictions

Technical considerations:

  • CIDR notation supports efficient range representation
  • IPv4 and IPv6 addresses are supported
  • List performance scales well with thousands of entries
  • Updates propagate globally within seconds

Text Lists: Content-Based Matching

Text lists contain string values for matching against HTTP headers, user agents, TLS signatures, or other textual data:

Common use cases:

  • User agent filtering: Control access based on client identification
  • Bot management: Maintain lists of known good or bad bots
  • API client management: Whitelist specific application identifiers
  • Security fingerprinting: Block clients with suspicious characteristics
  • Legacy system support: Accommodate older systems with specific requirements

Matching behavior:

  • Exact string matching is performed by default
  • Case sensitivity depends on the field being matched
  • Regular expressions are not supported within lists
  • Unicode strings are fully supported

Integer Lists: Numeric Classification

Integer lists contain numeric values useful for matching against ASNs, ports, or other numeric identifiers:

Common use cases:

  • ASN-based policies: Apply rules based on hosting provider or ISP
  • Quality of service: Prioritize traffic from specific network operators
  • Compliance filtering: Block or allow based on regulatory classifications
  • Performance optimization: Route traffic optimally based on network characteristics
  • Cost management: Apply different policies based on bandwidth costs

Numeric handling:

  • 32-bit signed integers are supported
  • Ranges are not directly supported (use individual values)
  • Negative values are permitted where applicable

Rule List Architecture

Centralized Management

Rule lists are managed centrally within your Peakhour account, providing:

  • Single source of truth: One location for maintaining value sets
  • Global scope: Lists can be used across all domains in your account
  • Immediate propagation: Changes distribute to all edge locations quickly
  • Audit trail: All modifications are logged for compliance and debugging

Reference Mechanism

Rule lists are referenced using the $list_name syntax within rules:

# Firewall rule using IP list
ip.src in $trusted_admin_ips

# Rate limiting with ASN list  
ip.geoip.asnum in $premium_isps

# User agent filtering with text list
http.user_agent in $allowed_api_clients

This indirection provides several benefits:

  • Abstraction: Rule logic remains separate from data
  • Flexibility: Same list can be used in different contexts
  • Maintainability: List updates automatically affect all referencing rules

Special List Types

In addition to standard lists, Peakhour supports special list types that provide dynamic data.

Anomaly Lists

Anomaly lists allow you to match against traffic patterns that Peakhour has identified as anomalous. These lists are prefixed with _anomaly_.

When you use a list like $_anomaly_client_pages, the system checks if the provided value (e.g., a client IP address) is present in the named anomaly list for your domain. This is a powerful way to build rules that react to dynamically detected security threats.

Blocklists

You can match against Peakhour's curated IP reputation blocklists. These lists are prefixed with _blocklist_.

For example, to check if a source IP is on the dshield blocklist, you would use ip.src in $_blocklist_dshield.

Performance Characteristics

Rule lists are optimized for high-performance lookups:

  • Memory-resident: Lists are loaded into memory at edge locations
  • Hash-based lookup: O(1) average-case lookup performance
  • Optimized storage: Efficient internal representation minimizes memory usage
  • Concurrent access: Multiple rules can access lists simultaneously without contention

Integration Patterns

Layered Security

Rule lists enable sophisticated security architectures:

# Layer 1: Block known threats
ip.src in $threat_intel_ips → deny

# Layer 2: Rate limit general traffic  
ip.src not in $trusted_partners → rate_limit(zone: "general")

# Layer 3: Allow privileged access
ip.src in $admin_networks → allow_admin_endpoints

Dynamic Policy Management

Lists can be updated independently of rule deployment:

  • Incident response: Rapidly block threatening IPs without rule changes
  • Business requirements: Add new partners or remove old ones instantly
  • Seasonal adjustments: Modify policies for traffic pattern changes
  • A/B testing: Gradually roll out changes by modifying list membership

Configuration Templating

Lists enable configuration templates that work across environments:

# Development environment
$admin_networks = ["10.0.0.0/8", "127.0.0.1"]

# Production environment  
$admin_networks = ["203.0.113.0/24", "198.51.100.0/24"]

Operational Considerations

List Sizing

While rule lists can scale to thousands of entries, consider:

  • Memory usage: Large lists consume more memory at edge locations
  • Update propagation: Larger lists take slightly longer to distribute
  • Management complexity: Very large lists become harder to maintain manually
  • Performance impact: Extremely large lists may have minimal lookup overhead

Update Propagation

Understanding update behavior is crucial for operational planning:

  • Global distribution: Updates propagate to all edge locations within seconds
  • Atomic updates: List changes are applied atomically to prevent inconsistent states
  • Zero-downtime: Updates don't interrupt ongoing request processing
  • Rollback capability: Previous list versions can be restored if needed

Monitoring and Alerting

Effective rule list management requires observability:

  • Usage tracking: Monitor which rules reference each list
  • Performance metrics: Track lookup performance and hit rates
  • Change auditing: Log all list modifications with timestamps and user information
  • Impact analysis: Understand how list changes affect traffic patterns

Rule lists represent a powerful abstraction that enables sophisticated, maintainable CDN and security configurations while providing the flexibility to adapt quickly to changing business and threat environments.