PubSentry already scores every visitor automatically. Rules are your manual override — the publisher's final say on top of the engine. Use them to allowlist your own office IP so your team is never flagged, hard-block a network that's hammering you, or watch a country quietly before you act on it. This page explains exactly how rules match, how they change a verdict, and the safety guarantees baked into the system.
Six things you can match on
A rule matches a request by one entity and one value:
- IP address — a single exact IP (e.g.
203.0.113.7). - IP range (CIDR) — an IPv4 block in CIDR notation (e.g.
203.0.113.0/24). Containment is computed by mask, best-effort for IPv4. - Network (ASN) — the autonomous-system number behind the visitor's IP (e.g.
14061). PubSentry derives the ASN from its offline IP-intelligence dataset, so you can block an entire hosting provider or datacenter range in one rule. - Country — an ISO country code (e.g.
VN), matched against the geo derived server-side. - Device fingerprint — a non-PII device id computed by the tag (fnv1a hash of stable browser/env signals), useful for pinning a single recurring abuser.
- Referrer — a substring match against the referrer domain (e.g.
cheap-traffic.example), to cut off a known junk-traffic source.
Every match is evaluated against signals PubSentry already has on the request. Critically, raw IP and User-Agent are hashed server-side (HMAC-SHA256) and then dropped — they are never stored raw. That's a deliberate privacy choice, and it shapes one thing below (the look-back).
Three actions, and how they win
Each rule carries one action:
- block — force the verdict to a block. The engine's score is overridden; the request is treated as invalid and (in Block mode) the ad is suppressed before it fires.
- allow — force the verdict to allow. This is your allowlist.
- monitor — escalate an otherwise-clean request to "monitor": it's recorded and surfaced, but the ad still serves.
When more than one rule matches the same request, precedence is fixed and unambiguous:
- allow wins over everything. If any allow rule matches, the request is allowed — full stop.
- then block. If no allow matched but a block did, the request is blocked.
- then monitor, but only to escalate a request that was otherwise going to be allowed.
This ordering is the whole point of the allowlist guarantee: an allow rule can never be overridden by a block rule, the engine, or anything else. Allowlist your own IP and your team is structurally incapable of being blocked. That directly serves PubSentry's first principle — FPR = 0, never block a real human.
Rules are applied server-side as a verdict override, inside the same one scoring engine the tag, edge, and server all share. They don't live in the page. You manage them in the dashboard; they're stored per-site in Redis and read on the hot path by the ingest service. A disabled rule is ignored entirely.
The look-back: see the blast radius before you save
Blocking is consequential, so before you commit a rule PubSentry shows you what it would have done over your selected time window — matched requests, how many are currently blocked / monitored / allowed, and how many verdicts the rule would flip. A block rule that flips 4,000 requests is a very different decision from one that flips 3, and you see which before you click save.
One honest limitation, by design: IP and CIDR rules can't be previewed against history. Because raw IPs are never retained (the privacy choice above), there's no column to match them against retroactively. The look-back covers ASN, country, device fingerprint, and referrer rules, where the matchable value is stored. For IP/CIDR rules the dashboard says so plainly rather than showing a fake number — and either way, an allowlist rule's projected human false-positives is always zero.
A good first rule
The single best rule to add first is an allowlist for your own office or VPN IP. It guarantees your team, your QA, and your ad-ops checks never count against you — and because allow wins over everything, it's permanent insurance against a self-inflicted false positive.
From there, common patterns:
- Block a hosting ASN that's sending obvious datacenter traffic.
- Monitor a country you're suspicious of, watch the verdicts accumulate, then decide.
- Block a referrer domain you've identified as a paid junk-traffic source.
Rules complement automatic scoring — they don't replace it. The engine catches obvious invalid traffic at near-100% recall with zero false positives on its own; rules are for the cases where you have context the engine doesn't.
Where rules fit with everything else
Rules are part of PubSentry's DEFEND controls, alongside Protection Mode (Measure vs Block) and Safety Mode (how strict scoring is). A rule's block only suppresses an ad when the site is in Block mode — in Measure mode the verdict is still recorded and shown, but no ad is suppressed. So you can stage a new block rule in Measure, confirm the look-back and live verdicts look right, then flip to Block.
None of this changes your install. Rules live in the dashboard, not the snippet. The tag is the same single async line either way:
<script async src="https://pubsentry.com/t.js" data-site="st_xxxx"></script>Programmatic access — coming on Enterprise
Today, rules are managed in the dashboard. A public, scoped API and signed event webhooks — to create rules programmatically and stream verdict events (block fired, rule applied, account-safety dropped) into your own tooling — are on the roadmap and slated for the Enterprise plan. We don't ship a half-built API pretending to be live; when it lands, it'll be documented here. All product features ship on every plan and tiers differ only by volume — the API/webhooks surface is part of the small Enterprise contractual set (alongside SSO, SOC 2 DPA, data residency, and SLA).