Skip to the content
Documentation
Help Start
Reading in:
  • German: 9,110 of 9,110 pages
About the help in other languages
All help pages

Request shield: configuration reference

Every way to configure the request shield (exp_request_shield) in one place - where its configuration lives, the constants in config.php, requestshield.ini, the cronjob part, the files on disk, the rule file format, the…

Download as PDF

Address: https://doc.exponential.earth/learninminutes/exphelp/viewer/help/request-shield/configuration-reference.md

On this page

Request shield: configuration reference

This page lists everything that configures the request shield (the extension exp_request_shield, which bundles the request-shield library): the few settings outside the rule files, the rule file format, every rule line and every set key with its default, and every rule the extension ships for Exponential. It is a reference to look things up in. For worked, copy-paste examples read the cookbook; for installing the shield, the setup guide.

The tables follow request-shield 0.4.0, the version bundled with exp_request_shield 0.0.1.x. On the server, php extension/exp_request_shield/bin/request-shield vocabulary prints the rule words of the installed version.

Contents

  1. Where the configuration lives
  2. The main rule file and the constants
  3. requestshield.ini and the cronjob part
  4. Files on disk
  5. The rule file format
  6. The order a request is checked in
  7. Every rule line
  8. Every set key
  9. The shipped Exponential rules
  10. The built-in rule sets
  11. The expect line
  12. The log line
  13. The installation's own requests
  14. Related pages

Where the configuration lives

The shield runs before the kernel starts, so it never reads an INI file. Its configuration is in these places:

WhereWhat it configuresWho changes it
The rule files (settings/request-shield/*.rules)everything the shield decides: hosts, paths, methods, budgets, the browser check, the log, the modeyou, on the server; the mode also from the administration
Constants in config.phpwhich rule file, which directories, the shield switched offyou, before the hook line
var/request-shield/PAUSEDthe shield paused while the file existsPause / Switch on in the administration, or touch / remove
settings/override/requestshield.ini.append.phponly the administration pages (the dashboard's period, the log's page size)you
settings/override/cronjob.ini.append.phpwhen the daily cronjob part requestshield runsyou

The main rule file and the constants

The shield reads one main rule file, which includes the others. It is the first of:

OrderFileWhen
1the file named by EXP_REQUEST_SHIELD_RULESthe constant is defined in config.php before the hook line
2settings/request-shield/request-shield.rulesthe site has its own file (recommended)
3extension/exp_request_shield/rules/request-shield.rulesthe extension's default, replaced by every update

php extension/exp_request_shield/bin/request-shield rules prints the file in use and where it comes from; the dashboard's setup box says the same.

The constants, defined in config.php before the hook line, only when the default does not fit:

ConstantDefaultEffect
EXP_REQUEST_SHIELD_RULESsee abovethe main rule file, an absolute path
EXP_REQUEST_SHIELD_ROOTtwo levels above the extensionthe installation's root
EXP_REQUEST_SHIELD_VAR<root>/var/request-shieldwhere the compiled settings (cache/), PAUSED, the backups of mode switches and the key for own requests (cache/self.key) live
EXP_REQUEST_SHIELD_DISABLEDnot definedtrue: the hook does nothing at all (restart Velocity after changing it)
// config.php, above the hook line: a rule file kept outside the installation
define( 'EXP_REQUEST_SHIELD_RULES', '/etc/exponential/www.example.org/request-shield.rules' );

if ( is_file( __DIR__ . '/extension/exp_request_shield/bootstrap/hook.php' ) )
    require __DIR__ . '/extension/exp_request_shield/bootstrap/hook.php';

requestshield.ini and the cronjob part

requestshield.ini holds only settings of the administration pages. Override them in settings/override/requestshield.ini.append.php:

[AdminSettings]DefaultEffect
DashboardHours24the hours the dashboard sums up and draws, 1 to 168
DashboardRecent15the newest log lines on the dashboard
LogHours[]1, 6, 24, 72, 168the periods offered on the log page
LogPageSize50log lines per page
ShowRuleTextenabledshow the text of the rule files on the rules page (disabled hides it, for example when a rule file names office addresses)

The extension also brings the cronjob part requestshield, scheduled daily at 04:23 (CrontabSchedule_requestshield=23 4 * * * in its cronjob.ini.append.php). It runs request-shield feeds update (the public blocklists the rules name with feed) and request-shield crawlers update (the address lists search engines and AI crawlers publish), so that blocklists and crawler verification stay current. Run it as the site's user; the kernel's crontab installer writes it into that user's crontab. Until the first run, feed rules decide nothing.

Files on disk

PathWhatWritten by
extension/exp_request_shield/lib/requestshield/the library (and php74/, the same files for PHP 7.4)the package
extension/exp_request_shield/rules/the shipped rule filesthe package, replaced by every update
settings/request-shield/the site's main rule file and its copies of exponential*.rulesyou, or the first mode switch in the administration
var/request-shield/cache/the compiled settings; self.key, the key of the installation's own requeststhe shield
var/request-shield/store/counters (without APCu), the secret of the pass cookie, lists, feeds, statisticsthe shield (path from set store-dir)
var/request-shield/log/shield.logone line per decision, rotated at log-max-sizethe shield (path from set log)
var/request-shield/backup/the previous rule file of each mode switchthe administration
var/request-shield/PAUSEDpauses the shield while it existsyou, or Pause
var/log/requestshield.logevery switch made in the administration, with the user's loginthe administration

All of var/request-shield/ must be writable by the user the site's PHP runs as, and must never be served by the web server (a standard Exponential virtual host refuses var/ except the storage paths it serves on purpose). Files the shield makes are 0600 and folders 0700 unless set file-mode and set dir-mode say otherwise. Run the command line as the site's user (sudo -u <web user> php extension/exp_request_shield/bin/request-shield ...), or files made by root will be unreadable for the site.

The rule file format

ids SITE                                          # this file's rule IDs start with SITE-
version 2026-11-15.1                              # shown by check and on the rules page

include exponential-admin-uri.rules               # another file, relative to this one

[SITE-OLD] block /old/**                          # a rule with an ID; the comment is its description
expect GET /old/page   404                        # an example, decided by "request-shield test"
expect GET /oldies     answered                   # a near miss that must pass
  • One rule per line: a word, then values separated by spaces. # starts a comment at the start of a line or after a space (\# is a literal #). The comment after a rule is its description, shown on the rules pages and when an example fails.

  • [ID] before a rule names it: letters, digits, -, _, .. The log, trace and the dashboard name the rule by it (rule=SITE-OLD). A rule without an ID is named by file and line (request-shield.rules:12). An ID used twice is an error. [ID@n] is a revision; as a reference (unblock [SCAN-BACKUP@1]) it names the revision you reviewed, and check warns when a library update changes that rule.

  • ids <PREFIX> [required] at the top: every ID in the file must start with <PREFIX>-; required makes an ID mandatory for every rule.

  • include <file or glob> reads further files, relative to the including file. An include may not leave its directory with ..: this is why the site's main file has copies of exponential*.rules next to it. include @name reads a built-in set (@wordpress, @tracking, ...).

  • Paths are simple patterns, matched against the path without the query:

    PatternMatchesDoes not match
    /wp-admin/**/wp-admin, /wp-admin/x/y.php/wp-adminx
    /page/*/page/about (* stays in one segment)/page/a/b
    *.sql/dump.sql, /a/b/dump.sql (no leading /: anywhere)/dump.sqlx
    **/admin/**/admin, /shop/admin/x (in any directory)/administrator
    /file?.txt/file1.txt (? is one character)/file12.txt

    regex switches the rest of the line to regular expressions without delimiters (block regex (?i)^/(phpmyadmin|adminer)); (?i) makes one case-insensitive. Every pattern is compiled when the files are read, so a broken one is an error then, never a silent miss. URI siteaccesses stand in front of the path (/ger/content/search): write **/content/search or a regex with (/[a-z0-9_]+)? in front where they matter.

  • none as the first value empties a list first, defaults included (exempt none 192.0.2.1).

  • match <paths> { ... } groups the rules of one area: inside, rules apply to those paths only, and a limit counts only the requests there. match regex ... { } takes a regular expression.

  • site <names> { ... } adds rules for some websites (host names, *.example.org, default). The website is picked by the web server's server name (set site-from server-name, the default), so a visitor cannot choose another website's rules with a Host header. After the first site block, only further site blocks, include, ids and version may follow, and server-wide lines (trust, store-dir, secret, ban, feed, set recheck ...) may not stand inside one. Use absolute paths for store-dir and log in a file with site blocks.

  • Later lines win for set keys: put the site's own settings after the include of the shipped rules, which set a mode, a store and a log of their own.

  • Changes need no restart. Every server notices a changed rule file within recheck seconds (10 by default) and compiles it again. A file with a mistake never takes the site down: the last good settings stay in force (or, at the very first compile, the shield lets everything through) and PHP's error log names the file and line once a minute.

The order a request is checked in

request-shield trace <main.rules> "GET https://www.example.org/path" shows these steps for one request, each with its result; the first refusal ends the request:

#StepRule lines that decide it
1Kept outdeny, the deny list
2Public listsfeed
3Bannedban
4Kind of requestmethod
5Sizeset max-uri, max-query-parameters, max-header-bytes
6Disguised addressbuilt in: encodings, .., paths out of the website's folder
7Website namehost
8Addresses only attackers ask forblock, unblock, the built-in scanner paths
9Where forms may be sentallow
10Where forms come frompost-origin
11Areas for certain visitorsrestrict
12Known crawlerscrawlers, crawler
13Known parametersquery
14Attack patternsblock query, block header, @attacks
15May a cache keep the answer?cache-path, cache-query, cache-ignore
16Pace (one line per budget)limit, no-limit
17Browser checkchallenge, challenge-exempt, api-path

An exempt address skips the budgets and the browser check, but blocked paths and attack patterns still refuse it. A request with a valid X-Exp-Self signature (the installation's own request) skips the shield entirely.

Every rule line

Defaults are those of the library; where the shipped Exponential rules set something else, the column "Shipped" says so.

LineDefaultShippedEffect
host <names>any hostnot set: write it in the site's filethe site's host names; a request for any other name gets 404
trust <addresses or ranges>nobodynot setwho may send X-Forwarded-For, -Proto and -Host: the load balancer, reverse proxy or CDN. From anyone else these headers are removed before the site runs. X-Forwarded-For is read right to left up to the first address no trusted proxy vouches for
method <METHODS>GET HEAD POST OPTIONSadds PUT PATCH DELETE (admin rules)the methods allowed at all; any other: 405
allow <METHODS> <paths>everywhereEXP-POST, EXP-ADMIN-POST, EXP-ADMIN-SPAthose methods only at those paths, anywhere else 405. Several allow lines for one method add up
restrict <paths> to <addresses or ranges>openSITE-DASH (/rs/**)only those addresses may open the paths, others 403. In monitor mode a restrict refuses nobody
block <paths>the built-in scanner and devtools pathsEXP-SYSVIEW, EXP-MODULES, EXP-INTERNAL, EXP-INI, EXP-VIEWPARAMS404 before the site sees the request
unblock <pattern> / unblock [ID] / unblock @settakes a block back: one pattern, one rule, a whole set
unblock [<ID>] at <paths> [for <addresses>]EXP-SYSVIEW-OK, EXP-DOWNLOAD, EXP-ADMIN-SYSa block lifted at some paths only (and only for some addresses)
block query|header <Name>|headers|anywhere <regex>@attacksan attack pattern in the query or the headers: 403. Values are decoded and normalized first. Form bodies are not looked at
query <name> <type> ... [at <paths>]EXP-SEARCH-Q, EXP-ADMIN-Qthe query parameters the site takes and their types: int, number, word, id, list, text, any or /regex/; * for every name. Only text values and unknown parameters are scanned for attacks
query strictoffmonitor (EXP-STRICT)any parameter no query line names: 404
query drop [at <paths>]offunknown parameters are removed instead, the request goes on without them (GET and HEAD)
cache-path <paths>anywhat a cache may keep
cache-query <names>anynone (EXP-CACHE-Q)the parameters a cached address may have; a request with others is answered but never kept (allow-uncached)
cache-ignore <names> / cache-ignore @trackingparameters no cache key holds, removed before the cache and the site run
limit <name> <n>/<unit> [challenge-at <n>] [on-demand] [on-exceeded challenge] [at <paths>]requests 600/minno-limit requests; EXP-PACE, EXP-IMAGES, EXP-SEARCHESa budget per visitor (an IPv4 address or an IPv6 /64). Units s, sec, min, hour, day, also 20/10s. Past challenge-at the browser check; past the limit 429 with Retry-After, or with on-exceeded challenge the check that, once solved, starts the counter again. at <paths> or a match block: only requests there count. Each budget needs its own name
no-limit <name>requestsswitches a budget off, the default one too
challenge [<METHODS>] <paths> [max-age <duration>]EXP-LOGIN, EXP-FORMS, EXP-ADMIN-CHECKalways the browser check there, once per pass; max-age 15m: a pass from the last 15 minutes. With methods first, only those (challenge POST **: every form sent)
challenge-exempt <paths>never the browser check there (feeds, webhooks, APIs for programs); budgets past their limit answer 429 instead
api-path <paths>EXP-API, EXP-ADMIN-BGa check there comes as JSON (429 with the header Request-Shield-Challenge), never as a page. Requests that ask for JSON or are a page's background fetch get JSON anyway
post-origin same [missing check|allow|refuse] [except <paths>]offEXP-ORIGIN, EXP-ORIGIN-Xforms (POST, PUT, PATCH, DELETE) only from the website's own pages: Origin, else Referer; another website 403; neither header: the browser check (missing check, the default)
post-origin except <paths>EXP-ORIGIN-Xpaths left out (payment callbacks, webhooks)
backend <paths>EXP-ADMIN-AREAthe editors' area, counted apart in the statistics
exempt <addresses or ranges> [until <day>[T<hh:mm>]]127.0.0.1 ::1never counted and never checked; still refused for blocked paths and attack patterns
deny <addresses or ranges> [until <day>[T<hh:mm>]]403 before every other check
feed <name> [<url> | from <file>] deny|check|count|ban-signal <n> [at <paths>]spamhaus-drop deny, feodo denya public blocklist, fetched by the cronjob part; above the site blocks
ban after <n> <signal> in <time> for <time>monitor (EXP-BAN: 10 refusals in 10 minutes, 1 hour)a visitor past <n> signals (refusals, limits, checks, or a budget's name) is answered only 429 for a while; repeated bans grow (ban-growth, ban-max)
crawlers <kind> allow|check|blockallowall four kinds allowwhat verified crawlers get, by kind: search, ai-search, ai-user, ai-training. allow: never the browser check (only the budgets, answered with a pause); check: like any visitor; block: 403
crawler <ID> allow|check|blockthe same for one crawler (CRAWL-GPTBOT, ...)
crawler <kind> ua /<pattern>/ [dns <suffixes>] [ranges <lists>]a crawler of your own, verified by DNS or an address list
monitor <rule>EXP-BAN, EXP-STRICTbefore block, restrict, allow, limit, challenge, ban, feed, query strict: the rule is logged as it would decide (monitor-...), not enforced
replace [<ID>] <rule>swaps a rule in one line, keeping its ID and its count in the log. Write the replacement complete: a rule from inside a match block needs its at <paths> (or its own match block), or it counts everywhere
expect ...about 150an example for request-shield test, see below
match <paths> { ... } / site <names> { ... }see the format
ids, version, includesee the format
dashboard-access "<principal>"|* sha256:<hash> [until <day>]who may open the library's own pages below /rs with a token (request-shield access-token); keep it in a file only the owner can read
stats-group "<name>" <websites>, stats-skip <paths>statistics per customer; paths not counted when they pass
plugin <class> [from <file>]a plugin told about every decision
set <key> <value>see every set key

Every set key

${NAME} in a value is an environment variable, ${NAME:-default} with a default.

KeyDefaultShippedEffect
modeenforceenforceoff (nothing is decided), monitor (everything logged as it would be decided, nobody refused), enforce, strict (enforce, and the rules marked strict)
recheck10 (seconds)how often the rule files are checked for changes; 0: on every request
storeautowhere counters live: auto (APCu when usable, else files), apcu, file, memory. Use file under Velocity and with several PHP-FPM pools, so all workers share one count
store-dir.request-shield/store next to the main filevar/request-shield/storecounters without APCu, the secret, lists, feeds, statistics. Relative to the rule file
secretmade in store-dirthe key of the pass cookie, at least 32 characters. Several servers behind one load balancer need the same one: set secret ${SHIELD_SECRET}
pass-ttl1h2h (admin host: 8h)how long a solved browser check lasts
solution-ttl5mhow long a solution may take to come back
difficulty-min, difficulty-max50000, 500000the work of the browser check; doubled per solve within an hour, up to the maximum
cookie, solution-cookiersp, rssthe cookie names
bind-user-agentonthe pass holds only for the browser it was solved in
debug-headeroffon: every answer carries X-RS: <decision>; rule=<ID> (for testing; switch it off again)
strip-untrusted-forwardedonremoves X-Forwarded-* from $_SERVER when the sender is not trusted
search-enginesonoff: no crawler is recognized
crawler-verifybothranges (only the published address lists, no DNS on the request path), dns, both
dns-lookups30 a minuteDNS lookups to verify crawlers, all requests together; 0: none
app-challengeoffon: the site may ask for the check with the response header X-RS-Check: 1
ipv6-prefix64the IPv6 prefix one visitor is counted under
max-uri, max-query-parameters, max-header-bytes4096, 64, 16384size limits; past them the request is refused before the site runs
languageautothe language of the shield's own pages: the visitor's browser language among those there are texts for (English and German built in), or a code
text.<key>, text.<lang>.<key>your own texts for the check page and the error pages (set text.en.title One moment, please)
homenone/where the shield's own pages link to, "To the home page"
challenge-logoa shieldan SVG file of your own in the middle of the check page
error-pagethe shield's pagea page of your own for a status: set error-page 404 errors/404.html, 4xx for all; placeholders {status} {title} {text} {wait} {home} {lang} {reference}
widget-path, widget-difficultyoff, 25000the browser check inside a form, solved while the visitor types
lognonevar/request-shield/log/shield.logthe log file; without it the dashboard's chart stays empty
log-levelstopflagstop: refused, slowed, checked; flag: also requests let through uncached (unknown parameters, POSTs) and solved checks; all: every request (briefly only); off
log-ipmaskedmasked: the visitor's network (IPv4 /24, IPv6 /48), never one person's address; full: the address (personal data: say so in the privacy notice)
log-max-size10Mthen one rotation to shield.log.1
file-mode, dir-mode0600, 0700the modes of what the shield writes; for a group: 0640 / 02750
statsoffoffthe library's statistics below /rs/stats/ (on, or parts)
dashboard-path/rswhere the library's own pages live
dashboard-session8hhow long a token login to those pages lasts
api, api-write, api-originson, off, noneapi offthe JSON API below /rs/api/v1
live, live-keepoff, 1hthe live view with full addresses (APCu or files)
lists-dir<store-dir>/listswhere allow.rules and deny.rules of the command line live
feeds-max-age3dan older fetched blocklist is not used
ban-growth, ban-max, ban-keep2, 1d, memoryeach ban within a day this many times as long, at most this long; file: bans survive a restart of APCu
site-fromserver-namewhich name picks a site block: the web server's server name, or host (the Host header)
cache-unknown-queryuncacheda parameter cache-query does not name: uncached, or hit-only
http-cache, http-cache-*offthe library's own HTTP cache; Exponential sites use the kernel's HTTP cache instead
stats-hours, stats-days, stats-months, stats-flush, stats-hosts, stats-depth, stats-slow, stats-path, crawler-log*details of the statistics

The library's own reference has each with a longer explanation: settings.

The shipped Exponential rules

The default main file includes exponential-admin-uri.rules, which includes exponential.rules. Every rule has an ID; change one in the site's main file with replace [ID] ..., take it back with unblock [ID] or no-limit <name>, and never edit the copies, so they can be refreshed.

The frontend (exponential.rules):

IDRuleWhat it does
(settings)include @tracking @attacks @devtools, set pass-ttl 2h, set home /marketing parameters known, attack patterns refused, build files and debug pages refused
EXP-SYSVIEWblock regex (?i)/content/view(/|$)/content/view/..., pages by node number, 404 in the frontend
EXP-SYSVIEW-OKunblock [EXP-SYSVIEW] at **/content/view/sitemap/* **/content/view/tagcloud/*the sitemap and the tag cloud stay open
EXP-MODULESblock regex (?i)^(/(ger|eng))?/(setup|class|section|role|...|pdf)(/|$)admin modules, 404 in the frontend; name your URI siteaccesses instead of ger|eng
EXP-INTERNALblock regex ^/(settings|kernel|lib|bin|autoload|cronjobs|update|tests|doc|var/[^/]+/(cache|log))(/|$)the installation's own folders
EXP-INIblock *.ini *.ini.append *.ini.append.php *.tplsettings and template sources, anywhere
EXP-DOWNLOADunblock [SCAN-BACKUP@1] at **/content/download/** /var/*/storage/**uploaded archives (.zip, .sql ...) stay downloadable
EXP-VIEWPARAMSblock regex (?i)/\((offset|limit|year|month|day)\)/(?![0-9]{1,6}(/|$))view parameters must be numbers up to 6 digits
EXP-POSTallow POST **/user/login **/content/action ... /api/**POST only where Exponential takes a form; add your extensions' modules
EXP-LOGINchallenge **/user/login **/user/register **/user/forgotpassword **/user/password/** max-age 15mthe login and registration: the browser check first
EXP-FORMSchallenge **/content/action **/content/tipafriend/** **/comment/add/** **/newsletter/subscribe/** max-age 30mcontact forms, comments, newsletter
EXP-ORIGINpost-origin sameforms only from the website's own pages
EXP-ORIGIN-Xpost-origin except **/paypal/notify_url/** **/xrowpaypal/notify/**payment callbacks
EXP-APIapi-path **/ezjscore/** /api/**ezjscore calls and the REST API get a check as JSON
EXP-SEARCHESlimit searches 10/min on-exceeded challenge (in match regex (?i)/content/(advanced)?search(/|$))ten searches a minute, then the check
EXP-SEARCH-Qquery SearchText text ... SearchDate /-1|[1-5]/ ...the search form's parameters and their types
EXP-CACHE-Qcache-query nonea cache keeps addresses without a query only
EXP-SEARCH-CHECKchallenge **/content/search **/content/advancedsearch max-age 1hcommented out: take the # away while a search is attacked
EXP-PACElimit pages 300/min challenge-at 120 on-exceeded challenge at regex ^(?!...images...)the pace: the check past 120 pages a minute and again past 300, image addresses left out
EXP-IMAGESlimit images 3000/min on-exceeded challenge at regex ^(...content/image/|/index_image.php|...storage/images...)image aliases made on demand: 3000 a minute
EXP-BANmonitor ban after 10 refusals in 10m for 1ha scanner an hour off the site; watched only
EXP-STRICTmonitor query strictunknown query parameters: 404; watched only

The admin as /admin (exponential-admin-uri.rules): EXP-ADMIN-BG (api-path /admin/user/megamenu/**), the method line with PUT PATCH DELETE, EXP-ADMIN-SPA (allow PUT PATCH DELETE /admin/explayouts_ui_api/**, the layout editor), and in match /admin/**: EXP-ADMIN-SYS (system URLs and admin modules open), EXP-ADMIN-POST (allow POST), EXP-ADMIN-CHECK (challenge: the browser check once per pass), EXP-ADMIN-AREA (backend), EXP-ADMIN-Q (query * text) and the commented EXP-ADMIN-NET (restrict to <office>).

The admin on a host of its own (exponential-admin-host.rules): the same as EXP-AH-* rules in site admin.example.org { ... }, with set pass-ttl 8h for editors.

The default main file (request-shield.rules): SITE-ADMIN-* for the other admin siteaccesses (/adminui, /editor, /admin2 to /admin4l, /admintest_*), include @wordpress, the crawlers lines, the two feed lines, the paths below var/request-shield/, set stats off, SITE-DASH (restrict /rs/** to 127.0.0.1 ::1) and set api off.

The built-in rule sets

SetIDsRead
scannersSCAN-HIDDEN, SCAN-BACKUP, SCAN-TEST, SCAN-DBTOOL, SCAN-CGI, SCAN-CONFIG, SCAN-SECRETS, SCAN-KEYSalways (unblock @scanners takes them back)
devtoolsDEV-BUILD, DEV-APPCONFIG, DEV-DEBUG, DEV-APIDOCS, DEV-SOURCEalways
crawlersCRAWL-GOOGLE, CRAWL-GPTBOT, ...always: the known crawlers and their address lists
@wordpressWP-FOLDERS, WP-SCRIPTSinclude @wordpress: /wp-admin, /wp-login.php, xmlrpc.php ... 404
@trackingTRACK-UTM, TRACK-GOOGLE, TRACK-META, ...include @tracking: utm_*, gclid, fbclid ... are known parameters
@attacksATK-SQL-*, ATK-XSS-*, ATK-LFI, ATK-JNDI, ...include @attacks: attack patterns in the query and headers, 403

The expect line

expect <METHOD> <address> <outcome> [by <ID>] [from <address>] [with pass] [times <n>] [ua "<User-Agent>"] [header <Name>:<value>]...
PartMeaning
<address>a path with its query, or a full URL when the host matters (https://admin.example.org/...), encoded as a browser sends it
passesanswered, and a cache may keep it
uncachedanswered, never kept
answeredeither: the site answers (for near misses that must not be refused)
checkthe browser check (page or JSON)
json-checkthe check as JSON only
403, 404, 405, 429 ...refused with that status
by <ID>the rule that must decide; without it, the last rule with an ID above the line in the same file
from <address>the visitor's address; default 198.51.100.7
with passthe visitor holds a solved check
times <n>sent n times in a row; the outcome is the last one's
ua "...", header Name:valuea User-Agent, extra headers (several allowed)

php extension/exp_request_shield/bin/request-shield test <main.rules> decides every example on a fresh store in memory: nothing is counted, logged or sent. Rules marked monitor and set mode monitor are tested as enforced, so the examples can be written before a rule is switched on (--as-written tests them as they are). --only=<ID> tests one rule; --junit=<file> writes a report for CI. Exit code 0: all pass; 1: one fails; 2: a mistake in the files.

The log line

2026-11-15T10:32:48+00:00 198.51.100.0/24 challenge 429 "always" rule=EXP-LOGIN "GET https://www.example.org/user/login" "Mozilla/5.0 ..."
2026-11-15T10:34:33+00:00 203.0.113.0/24 reject 404 "blocked path" rule=EXP-MODULES "GET https://www.example.org/setup/info" "curl/8.5"
2026-11-15T10:35:02+00:00 198.51.100.0/24 allow-uncached 200 "challenge solved" "GET https://www.example.org/user/login" "Mozilla/5.0 ..."

The fields: time, the visitor's network (or address with log-ip full), the decision, the status, the reason, then optional rule=, claimed= (a crawler name that was not verified), wait= (seconds of a pause), ref= (the reference shown on the error page), the request with its full address, and the User-Agent.

DecisionMeaningDashboard group
rejectrefused (403, 404, 405, 414 ...)refused
throttlea pause, 429 with Retry-After (a budget past its limit, a ban)refused
challengethe browser check was sent (429 is the status of the check page; a real browser solves it by itself)checked
allow-uncachedlet through, but no cache may keep it (POSTs, unknown parameters, a solved check)other
monitor-...what a watched rule, or monitor mode, would have done; the visitor got inwatched

The installation's own requests

Since exp_request_shield 0.0.1.5, requests the installation sends to its own pages (Setup > Preload sites, the address checks after an upgrade, static publishing) carry a signature and pass the shield before it runs:

  • The header is X-Exp-Self: <unix time>.<signature>, the signature an HMAC-SHA256 over the time, the method, the host (without port) and the path with its query, made with var/request-shield/cache/self.key (64 hexadecimal characters, readable by the site's user only, made on first use).
  • It holds for 120 seconds and only for the address and method it was made for. Anyone else's request is decided as always; the key never leaves the server.
  • PHP code of the installation makes one with expRequestShield::selfHeader( $url, $method ), which returns the header line or null (no key, or an address without a host). The class needs nothing from the kernel. See the cookbook.
  • The kernel's preloader (expPreloadRunner) and the upgrade's smoke check send it whenever the extension is installed (Exponential 6.0.15 from 2026-11-14 on).

Something wrong on this page? Report an error

Documentation license

This documentation is free documentation, licensed under the GNU Free Documentation License 1.3 or later.

Exponential Copyright © 1998-2026 Exponential Foundation and 7x