Docs

Sucuri

Sucuri

Sucuri exposes a single POST endpoint (https://waf.sucuri.net/api?v2) that dispatches on the a (action) parameter. The reference for each action lives in docs/okf/services/sucuri/ — pulled directly from the Sucuri API panel.

Endpoint

  • URL: ENV['SUCURI_API_URL'] (production: https://waf.sucuri.net/api?v2)
  • Method: POST (form-encoded body)
  • Auth on every request:
    • k — API key (ENV['SUCURI_API_KEY'] or per-app apps.sucuri_api_key)
    • s — MD5 hexdigest of the domain (omitted for add_site)
  • Dispatch: action selected by a=<action_name>

Response envelope

All v2 responses share one JSON shape — see response-format.

json { "status": boolean, "messages": []string, "action": string, "request_time": timestamp, "verbose": boolean, "output": []object }

status: 1 = success, status: 0 = error (with details in messages).

Rate limiting

Default per API key: 12 requests/minute, 60 requests/hour. Exceeding returns HTTP 429 with Retry-After. Headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset on every response.

Our handling: - Sync web requests (timeout ≤ 29s): re-raise 429 immediately — we can’t afford sleep 30 under Heroku’s 30s request cap. - Async workers (timeout > 29s): retry up to 3× with 30s sleep.

Client-side conventions

  • Domain normalization: we strip leading www. and *. before sending; Sucuri normalizes the rest to the apex. See sucuri-apex-normalization.
  • Array params: some actions need duplicated keys (block_from_posting[]=AF&block_from_posting[]=AD). Sucuri.platform expands Ruby array values into duplicate keys.
  • Audit-trail format: 'bad': intentional — see audit-trails.
  • User-agent sanitization: (, ), ,, + are stripped before sending so DB stays in sync with Sucuri’s server-side strip.

API reference (per action)

Reference Actions covered
response-format Common envelope + rate limit headers
show-settings show_settings
advanced-settings update_setting (every settable field — origin, security, performance, geo, dirs, UA/referer/cookie/method, 2FA)
allow-block-ip allowlist_ip, delete_allowlist_ip, blocklist_ip, delete_blocklist_ip
add-delete-site add_site, delete_site
add-ssl-certificate add_certificate
clear-cache clear_cache (full + per-file)
audit-trails audit_trails
protected-pages protected_pages, update_setting (protected_pages, protected_page_item[], protected_page_remove[])
reports-settings email_reports_settings

The Sucuri panel also has Request Generator and Bulk Request Generator — interactive UI for composing requests, not standalone API reference. Not included here.

Mapping Sucuri class methods to actions

Method Action Reference
Sucuri.add_site/3 add_site add-delete-site
Sucuri.delete_site/2 delete_site add-delete-site
Sucuri.show_settings/4 show_settings show-settings
Sucuri.add_certificate/5 add_certificate add-ssl-certificate
Sucuri.clear_cache/2, clear_path_cache/3 clear_cache clear-cache
Sucuri.new_internal_ip/4, delete_internal_ip/4 update_setting advanced-settings
Sucuri.whitelist_dir/5, remove_whitelist_dir/5 update_setting advanced-settings (allowlist_dir)
Sucuri.blacklist_dir/5, remove_blacklist_dir/5 update_setting advanced-settings (blocklist_dir)
Sucuri.noncache_dir/5, remove_noncache_dir/5 update_setting advanced-settings
Sucuri.ahttp_method_list/3, remove_ahttp_method_list/3 update_setting advanced-settings
Sucuri.block_cookie/3, remove_block_cookie/3 update_setting advanced-settings
Sucuri.block_useragent/3, remove_block_useragent/3 update_setting advanced-settings
Sucuri.block_referer/3, remove_block_referer/3 update_setting advanced-settings
Sucuri.block_from_posting/3, block_from_viewing/3 (+ removes) update_setting advanced-settings
Sucuri.add_whitelist_ip/2, delete_whitelist_ip/2 allowlist_ip / delete_allowlist_ip allow-block-ip
Sucuri.protected_pages/4, get_protected_pages/2 protected_pages protected-pages
Sucuri.add_protected_page/5, remove_protected_page/4 update_setting protected-pages
Sucuri.audit_trails/8, logs/7 audit_trails audit-trails
Sucuri.email_reports_settings/2 email_reports_settings reports-settings
Sucuri.change_setting/5 (toggles for forwardquerystrings_mode, block_attacker_country, ids_monitoring) update_setting advanced-settings
Sucuri.set_ssl_sni_tls_option/4 update_setting advanced-settings
Sucuri.verify_key/2 show_settings show-settings

Known quirks (project-specific)

  • Sucuri apex normalization — *.example.com, www.example.com, example.com collapse to one Sucuri site.
  • waf-metrics is blocked-only — audit_trails only emits block events.
  • Sucuri time zones — Sucuri uses US Eastern, we use UTC.
  • Log shipping ingestion — primary log feed is pushed by Sucuri to POST /api/v1/logs, not pulled via audit_trails.
  • allowlist_dir (alias of whitelist_dir) accepts pattern=matches; both whitelist_* and allowlist_* field names work. The in-code comment claiming otherwise is stale.