Orravo Spam Shield v1.0.0

Requirements

• WordPress 6.0 or newer
• PHP 8.0 or newer with the mbstring extension
• One of: Contact Form 7, WPForms, Gravity Forms, OForms, Fluent Forms (or no form plugin at all if you only need the REST API)
• Optional: iconv for the disposable-domain Punycode normaliser

From WordPress admin

The six layers

Honeypot

Spam Shield injects a single hidden field, oss_hp, into every supported form. The field is wrapped in a position:absolute;left:-9999px div and labelled Leave this field empty (configurable). Bots fill it because they fill every input. Real users never see it.

If JavaScript is enabled, the field is additionally cleared on submit so even an autofill manager that pre-fills it will be neutralised. The server-side check still wins: a non-empty value is always a 1.0 honeypot score.

Timing

PHP// Hidden field added to each form on render
<input type="hidden" name="oss_ts"
       value="1748716800.eyJ0Ijox..." />

// Server-side check on submit:
//   1. Decode payload, verify HMAC signature
//   2. Compute now() - rendered_at
//   3. If delta < min_seconds (default 1.5)  -> bot-like
//      If delta > max_seconds (default 5400) -> stale form
//   4. Otherwise: 0.0 contribution

Rate limiting

Implemented as a sliding-window counter in oss_rate_log. Two buckets are maintained per IP: one for the last 5 minutes (burst), one for the last hour (sustained). Burst limit defaults to 5; sustained limit defaults to 30. Once a limit is exceeded, the score contribution goes to 1.0 and the offending IP receives a 60-second cool-down (configurable).

PHP// Read current bucket counts
[ $burst, $sustained ] = OSS_Rate::counts_for_ip( '203.0.113.5' );

// Programmatic reset
OSS_Rate::reset( '203.0.113.5' );

Geo blocking

Spam Shield ships with the MaxMind GeoLite2 Country database (CC BY-SA 4.0). IP-to-country resolution happens in PHP via the bundled geoip2/geoip2 reader. No external API call. The database is refreshed monthly via the oss_refresh_geoip cron event (defaults off; opt in if you want auto-updates).

Two modes: deny list (default; block specific countries) or allow list (only listed countries can submit; everything else blocked). Allow list mode is for forms that should only accept submissions from a single country or region.

Disposable email

The disposable-domain list lives in oss_disposable_domains (~12,000 entries). It is refreshed daily from a community-maintained JSON feed; you can pin to a specific revision or disable auto-refresh entirely. The email's domain is normalised (Punycode-decoded, lower-cased, MX-less subdomains trimmed) before lookup.

PHP// Programmatic check
if ( OSS_Disposable::is_disposable( 'foo@10minutemail.com' ) ) {
    // ...
}

// Add or remove a domain
OSS_Disposable::add( 'tempbox.net' );
OSS_Disposable::remove( 'mailinator.com' );

Decision tree

• 1Run every enabled layer. Each returns a partial_score in [0, 1] and a reason string.
• 2Compute total = sum(partial * weight) / sum(weight_of_triggered_layers). Untriggered layers do not dilute.
• 3If total >= block_threshold (default 0.85): Block. The form returns a generic validation error; the entry is not stored.
• 4If total >= spam_threshold (default 0.6): Spam. The submission is stored but flagged; notifications can be suppressed.
• 5Otherwise: Clean. The submission flows through to the form plugin normally.
• 6The decision and per-layer scores are written to oss_log.

Decision actions

Layer weights

Weights are configurable under Spam Shield → Scoring → Weights. Setting a layer's weight to 0 effectively disables its contribution while keeping the layer running (useful for evaluating without blocking).

PHP// Filter weights at runtime
add_filter( 'oss_layer_weights', function( array $w ): array {
    $w['rate']  = 0.50;   // be aggressive about repeated submissions
    $w['geo']   = 0.10;   // be soft about geo (we run global outreach)
    return $w;
} );

// Filter the final decision (last word)
add_filter( 'oss_decision', function( string $decision, array $context ): string {
    // Always trust an authenticated user with edit_posts
    if ( is_user_logged_in() && current_user_can( 'edit_posts' ) ) {
        return 'clean';
    }
    return $decision;
}, 10, 2 );

Built-in

Custom forms

PHP// Pipe a custom form through Spam Shield
$decision = OSS_Score::evaluate([
    'form_id'  => 'my-custom-form',
    'fields'   => $_POST,        // raw input
    'email'    => $_POST['email'] ?? '',
    'ip'       => OSS_Helpers::client_ip(),
    'user_agent' => $_SERVER['HTTP_USER_AGENT'] ?? '',
    'request_uri'=> $_SERVER['REQUEST_URI'] ?? '',
]);

if ( $decision['decision'] === 'block' ) {
    wp_die( 'Submission blocked.', '', [ 'response' => 403 ] );
}

if ( $decision['decision'] === 'spam' ) {
    // Quietly silence notifications; still store the entry
    $is_spam = true;
}

// Log it (Spam Shield logs automatically when called via integrations;
// log manually for custom forms)
OSS_Log::insert( $decision );

Supported entry types

Auto-population

After three Block decisions for the same IP within an hour, Spam Shield can auto-add that IP to the IP blocklist with a 24-hour TTL. Disable auto-population under Blocklists → Behaviour if you want full manual control. Auto-added rows are labelled with source='auto' and a reason string so they are distinguishable from manual entries.

PHP// Programmatic
OSS_Blocklist::add( 'ip',       '198.51.100.0/24', [ 'source' => 'manual', 'note' => 'sustained scraping' ] );
OSS_Blocklist::add( 'email',    '*@throwaway.example' );
OSS_Blocklist::add( 'keyword',  '/(viagra|cialis|tramadol)/i' );

// Add with TTL
OSS_Blocklist::add( 'ip', '203.0.113.5', [ 'expires_at' => time() + DAY_IN_SECONDS ] );

// Check
$blocked = OSS_Blocklist::matches([
    'ip'    => '203.0.113.5',
    'email' => 'foo@example.com',
    'body'  => 'message body to scan for keyword matches',
]); // returns [ 'matched' => bool, 'type' => ..., 'rule' => ... ]

Endpoints

Test a payload

cURLcurl -X POST https://example.com/wp-json/orravo-spam/v1/test \
  -H 'Content-Type: application/json' \
  -H 'X-WP-Nonce: <rest-nonce>' \
  -d '{
    "email":      "foo@10minutemail.com",
    "ip":         "203.0.113.5",
    "body":       "Buy viagra cheap online click here",
    "user_agent": "Mozilla/5.0",
    "rendered_at":1748716800
  }'

# Response
{
  "decision":  "block",
  "score":     0.92,
  "layers": {
    "honeypot":   { "score": 0.0,  "reason": "ok" },
    "timing":     { "score": 0.3,  "reason": "submitted in 0.4s" },
    "rate":       { "score": 0.0,  "reason": "ok" },
    "geo":        { "score": 0.0,  "reason": "ok" },
    "disposable": { "score": 1.0,  "reason": "10minutemail.com" },
    "blocklist":  { "score": 1.0,  "reason": "keyword: viagra" }
  }
}

Filter reference