mailrs-shield

SMTP server anti-spam primitives in three modules: DNSBL lookups, greylisting policy, and FCrDNS (forward-confirmed reverse DNS) checks — async, transport-agnostic, mostly zero-I/O.

Extracted from mailrs so any Rust mail server can drop these in without re-implementing the same DNS-walking patterns. The Rust ecosystem currently has no dedicated crates for any of these three primitives.

What's inside

shield::dnsbl — DNS blocklist queries

Look up an inbound client IP against zones like Spamhaus ZEN, Barracuda, etc. Comes with an in-process TTL cache so repeat connections don't re-query.

use hickory_resolver::TokioResolver;
use mailrs_shield::dnsbl::check_dnsbl;
use std::net::IpAddr;

# async fn run() -> Result<(), Box<dyn std::error::Error>> {
let resolver = TokioResolver::builder_tokio()?.build()?;
let ip: IpAddr = "203.0.113.42".parse()?;
let zones = &["zen.spamhaus.org".to_string(), "b.barracudacentral.org".to_string()];
let result = check_dnsbl(&resolver, ip, zones).await;
println!("{result:?}");
# Ok(())
# }

shield::greylist — Greylisting policy

Pure policy (Harris 2003 / RFC 6647): defer the first time you see a (client_ip, sender, recipient) triplet, accept after the configured delay if the sender retries. Legitimate MTAs queue and retry; most spam bots don't.

use mailrs_shield::greylist::{GreylistConfig, GreylistDecision, evaluate_triplet};

let cfg = GreylistConfig::default();   // 5-minute initial delay, 36-day pass window
assert_eq!(evaluate_triplet(None, 1000, &cfg), GreylistDecision::Defer);
assert_eq!(evaluate_triplet(Some(1000), 1100, &cfg), GreylistDecision::TooEarly);
assert_eq!(evaluate_triplet(Some(1000), 1400, &cfg), GreylistDecision::Accept);

GreylistDb runs the policy over a pluggable GreylistBackend behind a single check() call. The default kevy-store feature ships an in-process kevy backend:

# #[cfg(feature = "kevy-store")]
# fn _ex() -> Result<(), Box<dyn std::error::Error>> {
# tokio_test::block_on(async {
use mailrs_shield::greylist::{GreylistConfig, GreylistDb, triplet_key};

let store = kevy_embedded::Store::open(kevy_embedded::Config::default())?;
let db = GreylistDb::new(store);
let cfg = GreylistConfig::default();
let key = triplet_key("192.0.2.1", "alice@example.com", "bob@example.com");
let now = 1700000000;
let decision = db.check(&key, now, &cfg).await;
# Ok::<(), Box<dyn std::error::Error>>(())
# })
# }

To plug in your own store, implement GreylistBackend (get, set_with_ttl, expire — three key-value operations), build the store with GreylistDb::with_backend, and check the backend from a test with greylist::check_greylist_backend(&backend).await. With default-features = false, features = ["store"] the crate has no storage dependency at all.

shield::ptr — FCrDNS check

Score an inbound client by whether its IP's reverse DNS forward-resolves back to a name matching the EHLO domain. Returns 0.0 on full match, 1.0 on no match — easy to fold into a spam score.

use hickory_resolver::TokioResolver;
use mailrs_shield::ptr::check_client_ptr;
use std::net::IpAddr;

# async fn run() -> Result<(), Box<dyn std::error::Error>> {
let resolver = TokioResolver::builder_tokio()?.build()?;
let ip: IpAddr = "192.0.2.1".parse()?;
let score = check_client_ptr(&resolver, ip, "mta.example.com").await;
println!("{score:.1}");
# Ok(())
# }

Performance

Microbenchmarks for the pure helpers (no live resolver hits) live in benches/ops.rs. Measured with criterion 0.8 on Apple Silicon (M-series), cargo bench, release profile.

Live-resolver paths (check_client_ptr, dnsbl::check, greylist::GreylistDb::check) aren't bench-able offline; production latency is dominated by DNS round-trips on the resolver paths. With the in-process kevy backend the GreylistDb store path makes no network call.

Run with cargo bench -p mailrs-shield. See tests/perf_gate.rs for the regression budgets.

Feature flags

Use default-features = false, features = ["store"] when you bring your own backend.

License

Licensed under either of Apache License 2.0 or MIT license at your option.