Protect sign-ups with ShieldShiba
A free captcha that checks the email address and the browser.
ShieldShiba sits next to the email field on a sign-up or contact form. When a visitor types an address, the widget runs a short proof-of-work in the browser and checks the email, the IP, and the browser. There is no puzzle. A visitor who looks automated waits a few seconds longer while their browser does more work. A visitor who passes sees Verified and the form gets a token. Your server sends that token to PostShiba before it accepts the sign-up.
The token is bound to the email the visitor typed, so a solved check cannot be reused for a different address. Blocked visitors never see the reason. When the block came from their IP, usually a VPN or proxy, the widget asks them to turn off the VPN and try again. When you block free email, it asks them to use their business email address. Only your server and the ShieldShiba page see the reasons.
PostShiba stores the email's domain and a keyed SHA-256 digest (HMAC) of the address, never the address itself. It also keeps the IP, the user agent, and the verdict.
Before you start
- A PostShiba account. Open Security, then ShieldShiba.
- The hostnames that will embed the widget.
1. Create a site
On ShieldShiba, choose Add site. List the hostnames under Allowed hostnames. Subdomains of a listed hostname are allowed.
Each site has two keys.
- The Site key starts with
ss_pk_. It is public and goes in your HTML. - The Secret key starts with
ss_sk_. Keep it on your server. Use Rotate secret on the same page if it leaks. The old secret stops working at once.
Four settings are per site.
- Block hosting networks is on by default. Turn it off to allow data-center and hosting IPs.
- Block free email is off by default. Turn it on if sign-ups should use a work address.
- Camera check instead of a block is off by default. See Ask for a camera check.
- Ask for a camera check is off by default. See Ask for a camera check.
2. Embed the widget
Load the script once, then put a <shield-shiba> tag inside the form. Point email-field at the email input with a CSS selector.
When the visitor passes, the widget adds a hidden input named shield_shiba_token to the form. A blocked visitor gets no token.
The widget also adds one text field that no visitor can see or reach. The field has no name, so the browser never posts it with your form. Only a script that fills every input writes in it. Leave it empty in your own scripts and tests.
3. Verify the token
Send the token, the email from the submitted form, and your secret key to the verify endpoint. No API key. The email must match the address the visitor typed.
A valid token returns 200.
Accept the sign-up only when success is true and verdict is good_boy. Blocked visitors never get a token, so a successful verify always returns good_boy. hostname is the page the widget ran on. email is normalized. A visitor who passed the camera check returns reasons: ["liveness"]. A visitor who passed after extra work returns the signs of automation that caused it, such as reasons: ["robotic_typing"].
Each token is single-use and valid for 5 minutes. Just before a token expires, the widget clears it and asks the visitor to verify again.
| Status | Body | Meaning |
|---|---|---|
401 |
{"success": false, "error": "invalid_secret"} |
The secret key does not belong to the token's site. |
422 |
{"success": false, "error": "invalid_token"} |
The token is missing, unknown, already used, expired, or bound to a different email. |
Treat any error as a failed check. Ask the visitor to try again. The account labels these verdicts Passed and Blocked.
Reasons
Some checks block on their own. The inspector stops at the first one that fails. That reason is stored on the blocked row in the account.
| Reason | Meaning |
|---|---|
invalid_email |
The address is not well formed. |
no_mx |
The domain has no mail server. |
temp_email |
The domain is a disposable or temporary inbox. |
sfs_domain |
The domain is on the StopForumSpam blocklist. |
free_email |
The domain is free webmail. Only when Block free email is on. |
network_bounced |
The address hard-bounced or was reported as spam with more than one PostShiba sender. |
machine_agent |
The browser is scripted. Headless tools, curl, webdriver, or a form filled in under 300 ms. |
sfs_ip |
The IP is on the StopForumSpam blocklist. |
abuseipdb_listed |
The IP has an AbuseIPDB confidence score of 50 or higher. |
tor |
The IP is a Tor exit node. |
hosting_ip |
The IP belongs to a data center or hosting network. Only when Block hosting networks is on. |
not_live |
The camera check did not show one live person doing the poses, or it reused stills from another check. Only when a camera check is on. |
suspicious |
Several signs of automation at once. The signs follow it in the list. See Signs of automation. |
Do not show these strings to the visitor. For sfs_ip, abuseipdb_listed, tor, and hosting_ip, the widget already tells the visitor to turn off their VPN and try again. For free_email, it asks them to use their business email address.
Signs of automation
Other checks are evidence, not proof. An office behind one IP looks like a bot farm, and a password manager types like a script. So no sign that a real browser can show blocks a visitor on its own, apart from recently_reported_ip.
Each sign adds to a score. Signs with one likely cause count once. A changed user agent gives both ua_mismatch and platform_mismatch, and the other network signs can never block without a sign from the browser. A visitor with a low score passes as before. A visitor with a higher score gets a harder proof-of-work instead of a token. Their widget shows Extra check, solves it in a few seconds, and then passes. Their token's reasons list the signs. A visitor with a high score is blocked with the reason suspicious and told to try another browser or network, or gets the camera check when Camera check instead of a block is on.
| Reason | Meaning |
|---|---|
no_accept_language |
The request named no language. Every browser names one. |
odd_fetch_metadata |
The browser's own description of the request does not fit a request from the widget. |
platform_mismatch |
The operating system in the user agent is not the one the browser reports elsewhere. |
ua_mismatch |
The page, its background worker, and the request name different browsers. |
ip_changed |
The proof-of-work was solved from a different IP than the one that asked for it. |
noisy_network, very_noisy_network |
ShieldShiba blocked bots from 3 or more, or 10 or more, addresses on the same network in the last 24 hours, on any site. |
reported_ip, often_reported_ip |
The IP has an AbuseIPDB confidence score of 10 or higher, or 25 or higher, and below the 50 that blocks. The visitor gets the hardest proof-of-work, and one sign from the browser blocks them. |
recently_reported_ip |
In the last 14 days the IP was reported to AbuseIPDB, and over 90 days at least 3 reporters named at least 2 kinds of abuse. This sign alone is a high score, whatever the confidence score. The widget tells the visitor to turn off their VPN and try again. |
many_emails, very_many_emails |
The same IP checked more than 5, or more than 20, different emails on this site in an hour. |
no_signals |
The client reported nothing about the browser. The widget always does, so this sign alone is a high score. |
no_render |
The browser did not lay out the widget, as a script without a screen does not. |
no_interaction |
No click, tap, or key press reached the page before the check. |
no_languages |
The browser lists no languages. |
robotic_typing |
The email was typed faster or more evenly than a person types. |
honeypot |
Something wrote in the hidden field. |
automation |
An automation tool left its traces on the page. |
ShieldShiba also starts a visitor on a harder proof-of-work when the request or the network already shows one of these signs. The widget reports counts and timings only. It never reads which keys the visitor pressed or where the pointer was.
Your own browser tests look automated too. Add the IP of your test runner to the allowlist.
Ask for a camera check
Turn on Ask for a camera check to stop AI agents and scripted sign-ups that pass the other checks. It is off by default and set per site.
Turn on Camera check instead of a block to ask only the visitors with a high automation score. Everyone else never sees the camera. A person whom the score got wrong can then prove it, where they would otherwise be blocked as suspicious.
After the email passes, the widget asks the visitor to turn on their camera. It shows five quick poses in a random order, like turn left, raise your eyebrows, or smile, and takes one still for each. AI checks that the stills show one live person in front of the camera doing those poses, not a photo, a screen, or a generated face. Then the form gets its token.
The stills are checked once and never stored. PostShiba sends them to its AI provider with storage turned off and keeps only a short fingerprint of each for a week, so the same stills can't pass twice. A fingerprint can't be turned back into a picture. No video is recorded.
A visitor without a camera, or who won't turn it on, can't pass. Only turn it on where that is acceptable. Allowlisted visitors skip the camera check like every other check.
Let a trusted visitor through
Some real people can't turn off their VPN, like a traveller on a mobile eSIM. Add them to the site's Allowlist on the ShieldShiba page. An entry is an IP, an IP range such as 198.51.100.0/24, an email domain, or a full email address. A domain also covers its subdomains. A visitor who matches any entry skips every check and passes with the reason allowlisted.
On a blocked row under Latest checks, Allow IP and Allow domain add that row's IP or domain in one click. Mobile carriers change IPs often, so for an eSIM user, allow their email address or domain instead of the IP.
Check the token in Rails
Read the token from the form params and call verify before you create the user.
Log reasons on a failure if you want to see why a sign-up was blocked.
If you send a welcome email after User.create!, use a Send only key from Create an API key. The verify call itself needs no API key.