Skip to content
Spectops

Whitelist & Blacklist Guide

Understanding how prefixes are filtered, added, and removed in Spectops

Key Concepts

Whitelist = Exclusion

Prefixes on the whitelist are never exported/announced. Use this for safe prefixes you never want to blackhole (e.g., your own infrastructure, partner networks, critical services).

Blacklist = Additive

Prefixes on the blacklist are always included in exports, even if no source provides them. Use this for manually adding known bad actors or custom prefixes you always want to block.

Precedence Rules

What happens when a prefix is on both whitelist and blacklist?

Whitelist Always Wins

If a prefix appears on both the whitelist and blacklist, it will be excluded. This is a safety measure to prevent accidental blocking of critical infrastructure.

Session Whitelist Has Highest Priority

Session whitelists override all blacklists (global, ASN, and session). Use session whitelists when you need to allow specific prefixes for a particular BGP session, even if they're blocked everywhere else.

Processing Order (from lowest to highest priority):

  1. Sources Aggregated - All enabled sources are combined and deduplicated
  2. Global Blacklist Added - System-wide blocked prefixes
  3. ASN Blacklist Added - Account-level blocked prefixes
  4. Session Blacklist Added - Per-session blocked prefixes
  5. Origin ASN BLOCK Rules Added - All prefixes from blocked ASNs (kept in sync automatically)
  6. Global Whitelist Applied - System-wide allowed prefixes (overrides blacklists)
  7. ASN Whitelist Applied - Account-level allowed prefixes (overrides blacklists)
  8. Origin ASN ALLOW Rules Applied - All prefixes from allowed ASNs (overrides blacklists)
  9. Session Whitelist Applied - Per-session allowed prefixes (HIGHEST PRIORITY)
  10. Exclusions Applied - Neighbor and own-prefix exclusions
  11. Output Generated - Final set is formatted for export or BGP announcement

Origin ASN Rules (Block Center)

Block or allow all prefixes announced by an external ASN

Origin ASN rules let you target an entire network by its ASN number. When you create a rule, the system automatically syncs all prefixes announced by that ASN from routing data and applies them to your exports and BGP sessions.

BLOCK Rules

All prefixes from the ASN are added to your blackhole set. Safety: you cannot block your own ASNs or AS49094.

ALLOW Rules

All prefixes from the ASN are added to your whitelist (exemption set). These override blacklists, including other Origin ASN BLOCK rules.

How it works:

  1. You add a rule for an ASN (e.g., AS64496) with action BLOCK or ALLOW
  2. The system resolves the set of prefixes announced by that ASN
  3. Prefixes are stored and kept in sync over time
  4. On each sync, affected BGP sessions and export lists are automatically updated

Export Lists (Non-BGP)

Downloadable blocklists for firewalls, DNS blockers, etc.

Export Lists let you download aggregated blocklists in various formats:

  • plain - One CIDR prefix per line (default)
  • JSON_TAGGED - JSON with provenance, communities, and metadata (v2 format)
  • bird - BIRD routing daemon filter format
  • mikrotik - MikroTik RouterOS address-list format
  • CIDR - Clean CIDR list
  • HOSTS - Hosts file format (0.0.0.0 sinkhole; CIDRs reduced to network address)
  • IPTABLES - iptables/ip6tables DROP rules
  • NGINX_DENY - nginx deny directives
  • NFT - nftables set elements
  • RPZ - DNS RPZ zone (BIND 9, Unbound, PowerDNS Recursor)

Export List Processing:

  1. Source prefixes are gathered (owner-scoped + system sources)
  2. Blacklist entries are added (export-list > account > global)
  3. Whitelist entries are removed (export-list > account > global)
  4. Rule engine filters based on configured rules
  5. Output is formatted per selected format

Export List Precedence (File Downloads)

Export lists use a three-level whitelist/blacklist precedence for file exports:

  1. Export-list level (highest priority) - Lists specific to this export list
  2. Account level - Your account's whitelist/blacklist entries
  3. Global level (lowest priority) - System-wide entries

Whitelist always overrides blacklist at each level. If a prefix is on both lists at the same level, it will be excluded from the export (whitelist wins).

Note: ASN-level lists are NOT applied to file exports. They only apply to BGP sessions.

Global List Toggles

Export Lists can be configured to apply or skip the global whitelist and blacklist:

  • Apply Global Whitelist - When enabled, global whitelist entries are removed from export
  • Apply Global Blacklist - When enabled, global blacklist entries are added to export

Both toggles are enabled by default. Account-level lists always apply to your exports.

Downloading Export Lists

Downloads require both an API key and a download token for security:

  • API Key - Authenticates your account and enforces rate limits
  • Download Token - Authorizes access to this specific export list (can be revoked independently)

Use format=JSON_TAGGED for the tagged JSON export.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.spectops.io/v1/export-lists/LIST_ID/download?token=YOUR_TOKEN&format=CIDR"

Manage your API keys and export lists from the dashboard after logging in.

When to Use Export Lists vs BGP

  • Export Lists: Firewalls, DNS blockers, nginx/Apache deny rules, nftables, no BGP capability
  • BGP: Network-level blackholing at router, ISP-grade traffic filtering, dynamic updates

BGP Exports

Prefixes announced via BGP to your routers

BGP exports involve multiple layers of filtering and can have both ASN-level and session-level controls.

BGP Export Precedence:

  1. Bound sources are aggregated
  2. Global blacklist entries are added (system-wide blocking)
  3. ASN blacklist entries are added (applies to all sessions for that ASN)
  4. Session blacklist entries are added (per-session)
  5. Global whitelist is applied (admin-managed)
  6. ASN whitelist is applied
  7. Session whitelist is applied (HIGHEST PRIORITY - overrides ALL blacklists)
  8. Neighbor exclusion is applied (per-session)
  9. Own prefix exclusion is applied (if enabled)
  10. Overlap policy is applied
  11. Community tags are added
  12. Prefixes are announced via BGP

Session Whitelist Use Cases

  • Allow specific prefixes for one peer that are globally blacklisted
  • Emergency override when you need to unblock something immediately for a specific session
  • Testing/staging sessions that need different filtering rules

Scope Reference

Where each type of list applies

List TypeScopeApplies To
Global BlacklistSystem-wideAll BGP exports (admin only)
Global WhitelistSystem-wideAll BGP exports (admin only)
ASN BlacklistPer ASN accountAll sessions for that ASN
ASN WhitelistPer ASN accountAll sessions for that ASN
Session BlacklistPer BGP sessionSingle BGP session only
Session Whitelist ⭐Per BGP sessionSingle BGP session only (HIGHEST PRIORITY)
Export List BlacklistPer export listSingle export list only
Export List WhitelistPer export listSingle export list only

Best Practices

  • ✓Always whitelist your own infrastructure prefixes to prevent accidental self-blocking
  • ✓Use ASN-level blacklists for prefixes you always want to block across all sessions
  • ✓Use session-level blacklists for session-specific blocking needs
  • ✓Use session whitelists sparingly - they override ALL other rules including global blacklists
  • ✓Regularly review your whitelist to ensure it's not too broad
  • !Remember: whitelist always wins - if something is whitelisted, blacklisting won't override it
  • !Session whitelist is the ultimate override - use with caution as it bypasses all security controls

Related Documentation

Getting Started Guide•BGP Setup Guide

Configuration examples and API documentation are available after logging in.