← All guides
Proxy & VPN detection

Keitaro fraud filter: block proxy, VPN and bot clicks with a custom filter or a gate

Keitaro has no VPN filter and its proxy check reads headers. Score each click with FraudNova from a custom PHP filter or a redirect gate.

Published

Keitaro runs on your own server, is written in PHP, and lets you add your own filters to a stream. That means you can score every click with FraudNova before Keitaro decides where to send it, and send proxy, VPN and bot traffic to a safe page instead of your offer.

This guide covers two ways to do it: a custom Keitaro filter that calls FraudNova directly, and a small redirect gate that works with any tracker. Both use the same rules and both cost 1 credit per new visitor IP per day. If you run more than one tracker, start with our overview of fraud filtering for affiliate trackers.

What Keitaro gives you, and where it stops

Keitaro ships with useful stream filters, but they were not built to tell you whether a visitor is hiding behind a VPN.

  • Proxy filter. Keitaro's documentation says this filter checks the request's HTTP headers, and that it works better with the IP2Location PX2 database. That means a proxy that does not announce itself in its headers is unlikely to be caught.
  • No VPN filter. The documentation is direct about it: "There is no filtering by VPN in the tracker."
  • Bot filter. This one matches visitors against the tracker's own bot list.

None of these gives you a single risk score for the IP, and none of them looks at the network the visitor is coming from. That is the gap FraudNova fills. A check on the visitor's IP returns a fraud_score from 0 to 100 plus flags such as proxy, vpn, tor and bot_status. You can see the full list on the proxy and VPN detection API page.

Option A: a custom Keitaro filter

Keitaro loads custom filters from /var/www/keitaro/var/filters/. We publish a ready-made one: FraudNovaFilter.php. It needs no Composer and no extra libraries, only PHP's curl extension.

The heart of the file is short. Keitaro hands the filter the click and the value you typed into the filter, and the filter answers one question: is this click risky?

class fraudnova extends AbstractFilter
{
    public function isPass(StreamFilter $filter, RawClick $rawClick)
    {
        $risky = self::isRisky(
            (string) $rawClick->getIpString(),
            $rawClick->getUserAgent(),
            $rawClick->getLanguage(),
            self::thresholdFrom($filter->getPayload())
        );

        return $filter->getMode() == StreamFilter::ACCEPT ? $risky : !$risky;
    }
}

That is an excerpt; the full file adds the check itself. It sends the visitor's IP, User-Agent and language to GET /api/v1/check, and treats the click as risky when the fraud_score is at or above your threshold, or when the result says proxy, vpn, tor or bot_status. The value you type into the filter is the threshold: a whole number from 1 to 100, with 75 used when you leave it empty or type anything else.

Three details keep it safe to run on live traffic:

  • A per-IP cache. The verdict for each IP is saved in the server's temp directory for a day, so a visitor who clicks ten times costs you one credit, not ten.
  • A 2-second timeout. The curl call gives up after 2 seconds.
  • It fails open. If the check cannot run for any reason (no credits, a rate limit, a timeout, a network error), the click passes as if it were clean. A good visitor is never sent away because a check did not happen.

Installing it

  1. Copy the file to your Keitaro server as /var/www/keitaro/var/filters/fraudnova.php.
  2. Add your FraudNova API key as the filter's README explains. Keys start with fn_ and are created under Dashboard, API keys.
  3. In Keitaro, open your campaign and add the new filter to the stream that sends traffic to your offer.
  4. Set the filter's mode to Reject and its value to 75.
  5. Place the stream for your safe page below it, since Keitaro works through streams in order.

In Reject mode a risky click does not pass the filter (the excerpt's last line), so it skips your offer stream and goes on to the safe-page stream below. Accept mode does the opposite: only risky clicks pass.

What to know before you rely on it

Keitaro's documentation explains how to write a custom filter, but it does not describe making outbound HTTP calls from inside one. The filter does exactly that, so a slow answer could hold a click for a moment. The 2-second timeout bounds that risk, the cache means most repeat clicks never wait at all, and the fail-open rule means a slow or failed check never blocks a visitor. Test it on a small stream first.

Option B: the redirect gate

If you would rather not put code inside Keitaro, or you run more than one tracker, use the gate. It is a small script you host on your own server, in the tracker gate folder of our examples repo. There is a PHP version (php/gate.php, which needs PHP 8.2 and Composer) and a Node.js version.

The gate reads the visitor's real connection IP, User-Agent and Accept-Language from the request itself, never from a query parameter, so nobody can fake a clean verdict by adding ?ip= to the link. It checks the IP, then sends the visitor on with a 302 redirect to either your money page or your safe page. It uses the same rules as the filter: block at a fraud_score of 75 or above, or on proxy, vpn, tor or bot_status. You can change the threshold and the flags, turn on active_vpn, and limit traffic to a list of allowed_countries. It also caches each verdict per IP for 24 hours, waits at most 2 seconds for an answer, and lets the click through if the check fails.

Setting it up in Keitaro

In your offer stream, use the gate as the landing page or offer URL:

https://gate.example.com/gate.php?clickid={subid}&route=default

{subid} is Keitaro's own token: Keitaro replaces it with the click's id before the visitor arrives, and tokens like this work in any Keitaro URL. The gate receives that value as the clickid parameter and appends the incoming query string when it redirects, so clickid travels on to your money page. In the gate's own config, a {clickid} placeholder in a destination URL is filled with that same value.

Your money page stays as it was. Its offer link still goes back through Keitaro as usual, so conversions are attributed to the right click.

Report blocked clicks back to Keitaro

A blocked click never reaches your offer, so the gate can tell Keitaro about each one. Set report_url in the gate's config to your Keitaro postback, copied from Settings, Postback URL, with the status set to trash:

https://TRACKER/POSTBACK-KEY/postback?subid={clickid}&status=trash

The gate calls this once for every blocked click, with {clickid} filled in, and never for an allowed one. trash is one of Keitaro's standard statuses (so is rejected), so your reports can show how many clicks each source lost to the filter.

Choosing a threshold

75 is where the high-risk band starts (0–39 is clean, 40–74 suspicious, 75–100 high risk), and it is a sensible start for most offers. If a bad click is expensive, for example on a finance or insurance offer, try 60 or 65. If you buy cheap, high-volume traffic and only want to cut the worst of it, try 85. The flags matter as much as the number: many affiliate networks reject proxy and VPN traffic whatever its score. Our guide to fraud score thresholds explains how to tune the number from your own results.

What it costs

Every check is 1 credit, with no subscription. Because both the filter and the gate cache each verdict per IP for a day, you pay 1 credit per new visitor IP per day, not per click. New accounts get 25 free credits once the email is verified, which is enough to test a stream. Each API key has a rate limit and each account has a cap on checks running at the same time; both are listed in the API docs, and higher limits are available on request.

Next step

Take an IP from a recent click and run it through the free IP checker to see which signals come back. Then create an account for your API key, install the filter or the gate on one stream, and compare that stream's conversion rate with the rest of your campaign after a few days.

Try it free

Run one IP proxy check right now — no account, no card.

Try the free IP proxy checker — no signup See the Proxy & VPN detection API

Also read