Skip to main content

Custom rules

Custom rules allow you to perform actions against visitor requests using logical expressions in VerifiedVisitors.

For example, you can configure a rule which serves CAPTCHA to all requests for a set of paths from likely-automated traffic.

A rule is comprised of a logical expression and an action. When processing a web request, the rule's expression is evaluated within the context of the request, and if found to match, the specified action is executed.

A site may have more than one rule configured. Rules are evaluated sequentially in priority order, stopping when a rule expression matches the request context.

Request Context / Fields

Rules are evaluated against a request context - a set of values derived from the web request currently being processed along with further enrichments and data about the visitor.

Expressions can target the following fields:

Standard Fields

FieldTypeDescriptionExample
asnnumberAS Number associated with the IP.64496
country_codestringThe 2-letter country code associated with the IP.GB
hoststringThe hostname used in the request URI.www.verifiedvisitors.com
ipstringThe client IP address.198.51.100.3
uristringThe request URI path and query./some/path?qk=a_value
uri.pathstringThe request URI path./some/path
uri.querystringThe request URI query.?qk=a_value
user_agentstringThe user-agent header value.Mozilla/5.0 Example/25.0
headers.refererstringThe referer header value.www.verifiedvisitors.com

Dynamic Fields

FieldTypeDescriptionExample
automatedbooleanWhether the visitor is considered automated or not.true
bot_servicebooleanWhether the visitor matches a known bot service.true
bot_service.idnumberThe ID of the bot service, if matching.101
path.tagstringThe path tag key, if matching.login
path.tag.idnumberThe path tag ID, if matching.42
vv.visitor.eventsstring[]List of detection events which contributed to the visitor score.['detection-automated-fp', 'detection-automated-ua']
vv.visitor.scorenumberLikelihood that a visitor is autoamrted or human. This is an integer value ranging from -2 to 2.

A score of -2 indicates a high probability that a visitor is automated.

A score of -1 indicates a moderate probability that a visitor is automated.

A score of 0 and above indicates that a visitor is unlikely to be automated.
-1
labelsstring[]List of customer-provided labels.['key:value']

Expressions

A rule expression is comprised of a set of comparison clauses joined with logical operators, represented as a tree using JSON.

For example, the expression automated = true AND uri.path = '/login' is represented by:

{
"op": "and",
"items": [
{ "op": "eq", "lhs": "automated", "rhs": true },
{ "op": "eq", "lhs": "uri.path", "rhs": "/login" }
]
}

Logical Clauses

The following logical clauses are supported:

OperatorStructureEvaluation
and{ "op": "and", "items": CLAUSES[] }Expression is true if all items are true.
or{ "op": "or", "items": CLAUSES[] }Expression is true if any item is true.
not{ "op": "not", "item": CLAUSE }Expression is true if item is false.

Comparison Clauses

Comparison clauses all take the form:

{ "op": OPERATOR, "lhs": FIELD, "rhs": VALUE}

Note that the LHS and RHS types must match. For example, if the type of the LHS field is a string, then so must be the RHS value. Similarly, comparisons involving arrays must have matching item types.

The following comparison clauses are supported:

OperatorLHS typesRHS typesExpression
eqLiteralsLiterals'ip' EQ '198.51.100.3'
containsArraysLiterals'vv.visitor.events' CONTAINS 'detection-automated-fp'
intersectsArraysArrays'vv.visitor.events' INTERSECTS ['detection-automated-fp', 'detection-automated-ua']
inLiteralsArrays'country_code' IN [ 'GB', 'US' ]
matchstringstring'user_agent' MATCH '.*Chrome.*', where RHS is a RegExp.

Actions

When a rule's expression is matched, the corresponding action is issued as a response.

Actions are executed by the system processing web requests, and typically generate the appropriate response according to the resulting action.

The following actions are supported:

ActionKeyEffect
AllowallowExplicitly allow the request through. This can be useful to allow specific requests as an exception to other rules.
BlockblockBlock the request completely.
CAPTCHAcaptchaServe a CAPTCHA challenge.
This challenge is passed once the visitor solves an interactive challenge.

Cookies and JavaScript are required on the client-side for visitors to pass this challenge.
JavaScript Challengejs_challengeServe a non-interactive challenge or CAPTCHA as a fallback.
This challenge is passed as soon as VerifiedVisitors has learned more about the visitor via the web agent script, and does not require the visitor to be classed as non-automated.

This is most useful when used in conjunction with higher-priority rules targeting automated visitors.

Cookies and JavaScript are required on the client-side for visitors to pass this challenge.

Examples

Serve CAPTCHA to automated traffic visiting a login page

Action: 'captcha'
Expression:
{
"op": "and",
"items": [
{ "op": "eq", "lhs": "automated", "rhs": true },
{ "op": "eq", "lhs": "uri.path", "rhs": "/login" }
]
}

Block definitely automated traffic except for specific IPs and verified bot services

Action: 'block'
Expression:
"expression": {
"op": "and",
"items": [
{ "op": "eq", "lhs": "vv.visitor.score", "rhs": -2 },
{ "op": "eq", "lhs": "bot_service", "rhs": false },
{
"op": "not",
"item": {
"op": "in",
"lhs": "ip",
"rhs": ["198.51.100.3", "198.51.103.1"]
}
}
]
}

Allow a specific IP by exception using rule priorities

Action: 'allow'
Priority: 0
Expression:
{
"action": "allow",
"priority": 0,
"expression": { "op": "eq", "lhs": "ip", "rhs": "198.51.103.1" }
}

Action: 'allow'
Priority: 1
Expression:
{
"action": "block",
"priority": 1,
"expression": { "op": "eq", "lhs": "vv.visitor.score", "rhs": -2 }
}

Require JS/fingerprinting telemetry and block automated visitors

This configuration requires all non-automated visitors to run a client-side script (improving automation detection rates for first-time visitors) before being allowed through, catching any automated visitors with a higher priority rule.

Action: 'block'
Priority: 0
Expression:
{
"op": "and",
"items": [
{ "op": "eq", "lhs": "automated", "rhs": true },
{ "op": "eq", "lhs": "bot_service", "rhs": false }
]
}

Action: 'js_challenge'
Priority: 1
Expression:
{
"op": "and",
"items": [
{ "op": "eq", "lhs": "automated", "rhs": false },
{ "op": "eq", "lhs": "bot_service", "rhs": false }
]
}

Target a segment of traffic using customer labels

The labels field in the /verifyVisitor API call can be used to set custom metadata for requests, which can be targeted by a rule expression.

Action: 'block'
Expression:
{
"op": "and",
"items": [
{ "op": "contains", "lhs": "labels", "rhs": "group:test-group" }
]
}