spider_firewall

A Rust library to shield your system from malicious and unwanted websites by categorizing and blocking them.

Installation

Add spider_firewall to your Cargo project with:

cargo add spider_firewall

Size Tiers

The small tier is enabled by default. Enable medium or large for broader coverage — each tier includes all sources from the tier(s) below it.

# Default — small tier, all categories:
spider_firewall = "2.35"

# Medium tier:
spider_firewall = { version = "2.35", features = ["medium"] }

# Large tier:
spider_firewall = { version = "2.35", features = ["large"] }

# Small tier, only bad + ads (no tracking/gambling):
spider_firewall = { version = "2.35", default-features = false, features = ["default-tls", "bad", "ads", "small"] }

Category Features

Categories can be toggled independently (all enabled by default):

Usage

Checking for Bad Websites

You can check if a website is part of the bad websites list using the is_bad_website_url function.

use spider_firewall::is_bad_website_url;

fn main() {
    let u = url::Url::parse("https://badwebsite.com").expect("parse");
    let blocked = is_bad_website_url(u.host_str().unwrap_or_default());
    println!("Is blocked: {}", blocked);
}

Adding a Custom Firewall

You can add your own websites to the block list using the define_firewall! macro. This allows you to categorize new websites under a predefined or new category.

use spider_firewall::is_bad_website_url;

// Add "bad.com" to a custom category.
define_firewall!("unknown", "bad.com");

fn main() {
    let u = url::Url::parse("https://bad.com").expect("parse");
    let blocked = is_bad_website_url(u.host_str().unwrap_or_default());
    println!("Is blocked: {}", blocked);
}

Example with Custom Ads List

You can specify websites to be blocked under specific categories such as "ads".

use spider_firewall::is_ad_website_url;

// Add "ads.com" to the ads category.
define_firewall!("ads", "ads.com");

fn main() {
    let u = url::Url::parse("https://ads.com").expect("parse");
    let blocked = is_ad_website_url(u.host_str().unwrap_or_default());
    println!("Is blocked: {}", blocked);
}

IP blocking

Enable the opt-in ip feature to also block known-bad IPv4 network ranges. The ranges are embedded at build time from the Spamhaus DROP list and matched via longest-prefix (binary) search. IPv6 currently always returns false.

spider_firewall = { version = "2.35", features = ["ip"] }

use spider_firewall::{is_bad_ip, is_bad_ip_str};

fn main() {
    assert!(!is_bad_ip("8.8.8.8".parse().unwrap()));   // legitimate hosts are not blocked
    let blocked = is_bad_ip_str("1.2.3.4");            // convenience: parses the string
    println!("Is blocked: {}", blocked);
}

The feed is rate-limited (~1 download/day) and revocable, so it is fetched non-fatally at build time — a failed or rate-limited fetch yields zero ranges rather than breaking the build, and emits a cargo:warning reporting the embedded range count (or that IP blocking is inactive).

For production builds where IP blocking must not silently disable on a rate-limited fetch, set SPIDER_FIREWALL_IP_STRICT=1: the build then fails loudly if the DROP fetch returns zero ranges (instead of shipping with IP blocking inactive). Retry once the ~1/day limit resets.

Attribution: IP range data is provided by The Spamhaus Project under the Spamhaus DROP terms (free for any use, attribution required). © The Spamhaus Project.

Blocklist Sources

Small (default)

Medium (adds)

Large (adds)

Build Time

The initial build can take longer, approximately 5-10 minutes, as it may involve compiling dependencies and generating necessary data files.

Contributing

Contributions and improvements are welcome. Feel free to open issues or submit pull requests on the GitHub repository.

License

This project is licensed under the MIT License.