Firewall Rules

1. Overview

CloShield's firewall uses an expression-based rule engine powered by gofilter. Each rule has:

• Name — A descriptive label for the rule
• Expression — A condition that matches requests
• Action — What to do when the rule matches (set/add/subtract suspicion level)
• Priority — Order in which rules are evaluated

Rules are evaluated in priority order on every request. The suspicion level determines which challenge stage (if any) is applied.

2. Writing Expressions

CloShield uses gofilter — a Wireshark-style display filter expression engine. Available fields and operators:

IP & Client Fields

• ip.src — Client IP address
• ip.country — ISO country code (resolved on demand)
• ip.asn — Autonomous system number (resolved on demand)
• ip.engine — Browser name from TLS fingerprint (e.g. "Chrome", "Firefox")
• ip.bot — Bot label from known bot fingerprint database
• ip.fingerprint — Raw TLS fingerprint string
• ip.http_requests — Total requests from this IP in current window
• ip.challenge_requests — Challenge failures from this IP in current window

HTTP Fields

• http.host — Host header
• http.method — HTTP method (GET, POST, etc.)
• http.url — Full request URL
• http.path — Request path
• http.user_agent — User-Agent header
• http.cookie — Cookie header

Proxy State Fields

• proxy.stage — Current challenge stage for this domain
• proxy.cloudflare — Whether domain is in Cloudflare mode
• proxy.stage_locked — Whether stage was manually set
• proxy.attack — Whether a bypass attack is in progress
• proxy.rps — Current requests per second
• proxy.rps_allowed — Current allowed requests per second

Operators

• eq, ne — Equal, not equal
• contains — String contains
• and, or — Logical AND, OR

Examples

# Block a specific IP
(ip.src eq 1.2.3.4)

# Block a country
(ip.country eq "CN")

# Block admin path
(http.path contains "/wp-admin")

# Complex: block POST to /api from Russia
(ip.country eq "RU") and (http.path contains "/api") and (http.method eq "POST")

# Escalate bots with unknown fingerprint
(ip.bot ne "") and (ip.engine eq "")

3. Actions

Each rule specifies an action number that modifies the suspicion level (susLv):

• N (absolute) — Set suspicion level to N and stop evaluating further rules
• +N (relative) — Add N to current suspicion level, continue evaluating
• -N (relative) — Subtract N from current suspicion level, continue evaluating

Suspicion Level → Challenge Stage

• 0: Whitelisted — no challenge
• 1: Stage 1 — Cookie verification (transparent to users)
• 2: Stage 2 — JavaScript proof-of-work
• 3: Stage 3 — Image CAPTCHA
• 4+: Blocked — 403 Forbidden response

4. Rule Evaluation

Rules are evaluated in the order they are defined. Managed rules (IP whitelist/blacklist, country blocks, ASN blocks) run first, followed by your manual rules.

• Absolute actions (just N) stop evaluation immediately and set the final suspicion level
• Relative actions (+N / -N) are cumulative — multiple rules can contribute to the final level

5. Common Rule Patterns

Practical examples using correct gofilter syntax:

• Block WordPress admin probes — (http.path contains "/wp-admin") with action 4
• Whitelist monitoring IP — (ip.src eq 10.0.0.1) with action 0
• Escalate unknown bots — (ip.engine eq "") and (ip.http_requests eq 0) with action +2
• Block by ASN — (ip.asn eq 12345) with action 4
• Geographic restrictions — (ip.country eq "XX") with action 4 for regions you don't serve
• Challenge during active attack — (proxy.attack eq true) and (ip.fingerprint eq "unknown") with action +1

6. Testing Rules

Before deploying aggressive rules, test them carefully:

• Use the Traffic Analytics page to see which rules are triggering
• Watch the "Rule Matches" column in the request log
• Test with a small suspicion level first (e.g. add 2) before escalating to block