Eternita Edge · bot & abuse defence
A rule on your own edge sends a suspicious visitor to a proof-of-work puzzle their browser solves in well under a second — instead of a 429, or a captcha served from someone else’s network. The puzzle, its check and the pass all come from your node.
robots.txt forbids, or keeps failing the puzzle, goes on a ban list for a while — and comes off on its own.# conf/guard-rules.conf — one line
search-challenge | uri~^/search ; client-type:guest ; !cookie-hmac:fc_pass ; rate:30/1m | challenge pow
Guests without a pass who search more than 30 times a minute solve a puzzle instead of getting a 429. Challenge pages are Pro; without them the same rule runs as a dry run, logged and harmless.
$200, credited toward a Cacheability Assessment or Pro. Which paths the bots hit, and the rules that would challenge or ban them.
How It Works
The edge is the layer you run between the internet and your app. It sees every request before your app does — so a request refused or challenged there is a page your origin never renders.
bots.conf — and a crawler can be required to come from its own published
network, so a fake Googlebot is not a Googlebot.Retry-After, never a lost body. Fragments and the challenge page itself are
never challenged.The Whole Setup
The rules decide; the Pro plugins only act on what the rules say. A guard rule sends a visitor to a challenge. The challenge page shows the puzzle and checks the answer. The pass is checked by the same open-source rule engine that sent the visitor there, with a key the plugin never sees.
A honeypot is a link nobody can see, to a path your robots.txt
forbids. A person never follows it and a polite crawler is told not to — so one request is
enough. The node logs the address it resolved behind your proxies, not the one a scanner wrote
in a header.
Bans are temporary and bounded. Each defence rule says how many events in what
window earn a ban, and for how long; a repeat offender’s ban doubles up to a ceiling you
set. Loopback, private ranges, your own proxies and anything you list in never are
never banned. dry-run = true counts what a rule would ban and bans nothing —
start there.
Every rule, page and ban reloads without a restart, from the console or the node.
# conf/guard-rules.conf — first match wins.
# Your exemptions (monitoring, verified crawlers) go first.
banned | client-ip:@lists/banned.txt | reject:403 Forbidden
honeypot | uri~^/no-crawl/ | reject:404 Not Found | trap
challenge-verify | uri~^/fc-x/challenge/verify ; rate:10/1m | reject:429
search-challenge | uri~^/search ; client-type:guest ; !cookie-hmac:fc_pass ; rate:30/1m | challenge pow
The ban list is refused; the honeypot is caught; the puzzle’s own answers are rate-limited; guests who search too fast get a puzzle.
# conf/defence.conf (Pro) — what earns a ban
defence {
list = banned
rules = [
{ name = trap, on = guard.matched, rule = honeypot,
ban = 1h, max-ban = 1d }
{ name = failed, on = challenge.result, outcome = fail,
threshold = 5, window = 10m, ban = 6h, dry-run = true }
]
}
One honeypot hit bans for an hour, longer each time it comes back. Five failed puzzles in ten minutes would ban for six hours — once the dry run shows it catches only what you meant.
Who Sees What
Exactly what goes where, so the privacy page stays true.
The page, its script and the check are served by your node under /fc-x/challenge/.
No third-party script, no tracking, and the only cookie is the pass itself — set once the
visitor has solved the puzzle.
If you configure Cloudflare Turnstile instead, the visitor’s browser and your node talk to Cloudflare to verify the answer. An outage there is never a free pass: the visitor is asked to try again.
Every decision about a visitor’s request — challenged, refused, let through — is made by the open-source engine, from rules you wrote. Remove the Pro jars and the same rules run on the free engine: a challenge rule becomes a dry run, and nobody is left banned.
Free and Pro
Everything a request needs is in the Apache-2.0 engine. Pro adds the challenge pages and the defence that acts on its own — $3,600 per node per year, 2-node minimum.
| Capability | Community — free | Pro |
|---|---|---|
| Guard rules, rate limits, dry run | Included | Included |
| Honeypot paths | Included — logged with the real address | Included, and can ban |
| Verified crawler lists | Googlebot, Bingbot, Applebot — an open-source example plugin | Included |
| Challenge rules and the signed pass | The rule and the pass check; with no challenge page it runs as a dry run, or as the reject you name |
Included |
| Challenge pages | Your own page can sign a pass the engine accepts | Proof of work, or Cloudflare Turnstile; your own template |
| Temporary bans | A list you keep yourself, read live | From limits, honeypot hits and failed challenges; released on time |
| Alerts | Metrics and logs to alert on | Slack, Teams, PagerDuty, Opsgenie, webhook, mail, syslog — e.g. when the pass rate falls |
What It Is Not
Know where the line is before you buy anything.
No fingerprinting, no reputation network, no machine learning. A puzzle makes every pass cost work; a scraper driving a real browser can still solve it — and then meets your rate limits and the ban list. If you need detection, keep your bot-management vendor.
No signature set, no TLS termination, no global network to absorb a flood. Put a CDN in front if you need one; this is the edge behind it, next to your app.
Bans are per node today, with no fleet-wide list yet, and a pass is tied to the address that earned it. Behind a load balancer, set the shared secret so any node can check any puzzle.
Next Step
45 minutes with an engineer on your own traffic: which paths bots hit, and the rules that would challenge, slow or ban them. $200, credited toward an Assessment or Pro — or ask us a question for free.