Stop bots and scrapers, not people

• Browser automation

  Selenium, Puppeteer, Playwright, Cypress, TestCafe and headless Chrome, recognised by the traces they leave in the page.

  automation

• Stealth plugins and “undetected” builds

  Automation patched to look human. Shield looks for the patches themselves: replaced functions, detached windows, a Chromium posing as Chrome.

  stealth

• Antidetect browsers

  Spoofed fingerprints. Shield compares what the browser claims with what its engine does: the screen, the time zone, the language, the fonts, the canvas drawing.

  antidetectbrowser-soft

• HTML scrapers

  Programs that ask for pages without running them: no sensor report, too many pages, too fast.

  no-proofratewalk

• Fake Googlebot

  A crawler name is believed only when the official IP list and reverse DNS confirm it. Verified crawlers always get through.

  fake-crawlerrobotstrap

• Address fleets and data centres

  Browsers from hosting networks, User-Agents that lie, headers that do not match. IPv6 is counted per /64 network.

  datacenterua-claimclient-hintsstale-browser

• Fake votes, comments and sign-ups

  The form sends a sensor token and your server verifies it once, within 300 seconds. Verified with the visitor's address, a token copied to another address is refused.

  POST /verify

  The answer of POST /verify Copy

  {
    "success": true,
    "verdict": "human",
    "score": 3,
    "action": "allow",
    "age_s": 4
  }

1. Put the sensor on your pages

   Direct, one line in the page. Recommended: through a first-party proxy, from your own domain. No third-party request, it works under script-src 'self', and ad blockers do not see it.

   HTMLCaddynginx

   Copy

   <!-- in every page, direct -->
   <script src="https://api.satelit.md/shield/v1/sensor.js"
     data-site="shp_XXXXXXXXXXXXXXXXXXXXXXXX" async></script>

   # Caddyfile: /_sh/* goes to Shield, with your secret and the visitor's address
   example.md {
   	handle_path /_sh/* {
   		rewrite * /shield/v1{uri}
   		reverse_proxy https://api.satelit.md {
   			header_up Host {upstream_hostport}
   			header_up X-Shield-Secret {env.SHIELD_SECRET}
   			header_up X-Shield-Client-IP {client_ip}
   			header_up -Cookie
   			header_up -Authorization
   		}
   	}
   	# ... the rest of your site
   }
   
   # in every page:
   # <script src="/_sh/sensor.js" data-site="shp_XXXXXXXXXXXXXXXXXXXXXXXX" data-base="/_sh" async></script>

   # nginx: /_sh/ goes to Shield, with your secret and the visitor's address
   location /_sh/ {
       proxy_pass https://api.satelit.md/shield/v1/;
       proxy_ssl_server_name on;
       proxy_set_header Host api.satelit.md;
       proxy_set_header X-Shield-Secret "shs_...";        # keep this file out of your repository
       proxy_set_header X-Shield-Client-IP $remote_addr;  # behind Cloudflare: $http_cf_connecting_ip
       proxy_set_header Cookie "";
       proxy_set_header Authorization "";
   }
   
   # in every page:
   # <script src="/_sh/sensor.js" data-site="shp_XXXXXXXXXXXXXXXXXXXXXXXX" data-base="/_sh" async></script>

2. Verify the token on forms

   On a vote, a comment or a sign-up, the page asks for a token with SatelitShield.token() and sends it with the form. Your server verifies it once, within 300 seconds.

   In the page Copy

   // a fresh token goes with the form, in a hidden field
   form.addEventListener("submit", function (e) {
     e.preventDefault();
     SatelitShield.token(function (token) {
       form.elements.shield_token.value = token;
       form.submit();
     });
   });

   POST /shield/v1/verify

   curlJavaScriptPythonPHP

   Copy

   curl https://api.satelit.md/shield/v1/verify \
     -H "Authorization: Bearer $SHIELD_SECRET" \
     -H "Content-Type: application/json" \
     -d '{
       "token": "<the token from the form>",
       "ip": "203.0.113.9"
     }'

   // Node 18+: the token came with the form, ip is the visitor's address
   async function fromPerson(token, ip) {
     const res = await fetch("https://api.satelit.md/shield/v1/verify", {
       method: "POST",
       headers: { Authorization: `Bearer ${process.env.SHIELD_SECRET}`, "Content-Type": "application/json" },
       body: JSON.stringify({ token, ip }),
     });
     const v = await res.json();
     return v.success === true && v.action !== "block";
   }

   import json, os, urllib.request
   
   def from_person(token, ip):
       req = urllib.request.Request(
           "https://api.satelit.md/shield/v1/verify",
           data=json.dumps({"token": token, "ip": ip}).encode(),
           headers={"Authorization": f"Bearer {os.environ['SHIELD_SECRET']}", "Content-Type": "application/json"},
       )
       with urllib.request.urlopen(req, timeout=5) as res:
           v = json.load(res)
       return v.get("success") is True and v.get("action") != "block"

   <?php
   function from_person(string $token, string $ip): bool {
       $ch = curl_init("https://api.satelit.md/shield/v1/verify");
       curl_setopt_array($ch, [
           CURLOPT_RETURNTRANSFER => true,
           CURLOPT_POST => true,
           CURLOPT_TIMEOUT => 5,
           CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("SHIELD_SECRET"), "Content-Type: application/json"],
           CURLOPT_POSTFIELDS => json_encode(["token" => $token, "ip" => $ip]),
       ]);
       $v = json_decode(curl_exec($ch), true);
       curl_close($ch);
       return ($v["success"] ?? false) === true && ($v["action"] ?? "") !== "block";
   }

3. Put the decision in your server

   Optional, for the whole site. A middleware keeps the decisions in memory, reads them from /decisions every 15–30 seconds and sends the requests to /ingest in batches. No visitor's request waits for the network.

   shield-middleware.mjsshield-pass.mjs

   Copy

   // Satelit Shield in a Node server: Express or any (req, res, next) stack. Node 18+, no packages.
   // The decisions stay in memory and are read again every 20 s, so a visitor's request never waits for the network.
   // Every request is sent to /ingest in batches. /_sh/ (the sensor) is served by the proxy in front, step 1.
   import { clientKey, passValid } from "./shield-pass.mjs";
   
   const API = process.env.SHIELD_API || "https://api.satelit.md/shield/v1";
   const SECRET = process.env.SHIELD_SECRET;   // shs_..., never in a page
   const SITE = process.env.SHIELD_SITE;       // shp_..., the public site key
   const HEADERS = { Authorization: `Bearer ${SECRET}`, "Content-Type": "application/json" };
   const decisions = new Map();                // client key -> { a: "b" | "g", rule, until }
   const lines = [];
   let cursor = "0";
   
   export async function poll() {
     const res = await fetch(`${API}/decisions?since=${cursor}`, { headers: HEADERS });
     if (!res.ok) return;
     const body = await res.json();
     if (body.full) decisions.clear();
     for (const d of body.items) {
       if (d.a === "-") decisions.delete(d.key);
       else decisions.set(d.key, d);
     }
     cursor = body.cursor;
   }
   
   export async function flush() {
     while (lines.length) {
       const batch = lines.splice(0, 500);
       await fetch(`${API}/ingest`, { method: "POST", headers: HEADERS, body: JSON.stringify({ lines: batch }) }).catch(() => {});
     }
   }
   
   export function start() {
     const quiet = (job) => () => job().catch(() => {});
     quiet(poll)();
     setInterval(quiet(poll), 20_000).unref();
     setInterval(quiet(flush), 5_000).unref();
   }
   
   const cookie = (req, name) => new RegExp(`(?:^|;\\s*)${name}=([^;]*)`).exec(req.headers.cookie ?? "")?.[1] ?? "";
   const page = (mode, text) => `<!doctype html><html data-shield="${mode}"><head><meta charset="utf-8">`
     + `<meta content="noindex" name="robots"><meta name="viewport" content="width=device-width">`
     + `<script src="/_sh/sensor.js" data-site="${SITE}" data-base="/_sh" async></script></head><body><p>${text}</p></body></html>`;
   
   export function shield(req, res, next) {
     const ip = req.ip ?? req.socket.remoteAddress;   // behind a proxy: Express's "trust proxy" gives the visitor's address
     const ua = req.headers["user-agent"] ?? "";
     const path = (req.originalUrl ?? req.url).split("?")[0];
     const shp = cookie(req, "__shp");
     const pass = !shp ? 0 : passValid(shp, SECRET, ip, ua) ? 1 : 2;
     const d = decisions.get(clientKey(ip));
     const on = d && (!d.until || Date.parse(d.until) > Date.now()) ? d.a : "";
     // a ban is a 403; a check is a 429 unless the browser holds a valid pass (a pass never opens a ban)
     const gate = on === "b" ? 403 : on === "g" && pass !== 1 ? 429 : 0;
     res.on("finish", () => {
       const type = String(res.getHeader("content-type") ?? "");
       const kind = /\.(css|js|mjs|png|jpe?g|gif|svg|webp|avif|ico|woff2?)$/i.test(path) ? "asset" : /json/.test(type) ? "api" : "html";
       const h = (name) => req.headers[name] ?? "";
       lines.push({
         t: Date.now(), ip, ua, m: req.method, p: path, s: res.statusCode, k: kind,
         h: { sfs: h("sec-fetch-site"), chua: h("sec-ch-ua"), chm: h("sec-ch-ua-mobile"), chp: h("sec-ch-ua-platform"), al: h("accept-language"), ref: h("referer") },
         pass, seen: cookie(req, "__shs") === "1" ? 1 : 0, g: gate === 429 ? 1 : 0,
       });
     });
     if (!gate) return next();
     res.statusCode = gate;
     res.setHeader("Content-Type", "text/html; charset=utf-8");
     res.setHeader("Cache-Control", "no-store");
     res.end(gate === 429 ? page("check", "Checking your browser.") : page("ban", "Access blocked."));
   }
   

   // Satelit Shield: check a pass (the __shp cookie) on your own server, with no call to Shield. Node 18+.
   // A pass is p1.{exp}.{token}.{sig}; sig is the first 22 characters of
   // base64url(HMAC-SHA256(pass key, "p1|{exp}|{token}|{client key}|{User-Agent}")).
   import { createHash, createHmac, timingSafeEqual } from "node:crypto";
   
   // The pass key: HMAC-SHA256 with the key sha256_hex(secret) over "satelit-shield-pass-v1", in hex.
   export function passKey(secret) {
     const key = createHash("sha256").update(secret).digest("hex");
     return createHmac("sha256", key).update("satelit-shield-pass-v1").digest("hex");
   }
   
   // The client key: an IPv4 address as it is, an IPv6 address as its /64 (the first four groups and "::").
   export function clientKey(ip) {
     const v4 = /^(?:::ffff:)?(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(ip);
     if (v4) return v4[1];
     const [head, tail = ""] = ip.toLowerCase().split("%")[0].split("::");
     const a = head ? head.split(":") : [];
     const b = tail ? tail.split(":") : [];
     const groups = [...a, ...Array(Math.max(0, 8 - a.length - b.length)).fill("0"), ...b];
     return groups.slice(0, 4).map((g) => parseInt(g, 16).toString(16)).join(":") + "::";
   }
   
   // True when the pass has not expired and was signed for this address and this browser.
   export function passValid(pass, secret, ip, userAgent, now = Date.now() / 1000) {
     const m = /^p1\.(\d+)\.([0-9a-f]{16})\.([A-Za-z0-9_-]{22})$/.exec(pass ?? "");
     if (!m || Number(m[1]) <= now) return false;
     const message = `p1|${m[1]}|${m[2]}|${clientKey(ip)}|${userAgent}`;
     const sig = createHmac("sha256", passKey(secret)).update(message).digest("base64url").slice(0, 22);
     return timingSafeEqual(Buffer.from(sig), Buffer.from(m[3]));
   }
   

All of Shield's documentation