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

Field	Type	Description	Example
asn	number	AS Number associated with the IP.	64496
country_code	string	The 2-letter country code associated with the IP.	GB
host	string	The hostname used in the request URI.	www.verifiedvisitors.com
ip	string	The client IP address.	198.51.100.3
method	string	The request method.	POST
uri	string	The request URI path and query.	/some/path?qk=a_value
uri.path	string	The request URI path.	/some/path
uri.query	string	The request URI query.	?qk=a_value
user_agent	string	The user-agent header value.	Mozilla/5.0 Example/25.0
headers.referer	string	The referer header value.	www.verifiedvisitors.com
net_types	string[]	Network type. Supported Values: "proxy", "hosting", "mobile"	['mobile']

Dynamic Fields

Field	Type	Description	Example
automated	boolean	Whether the visitor is considered automated or not.	true
bot_service	boolean	Whether the visitor matches a known bot service.	true
bot_service.id	number	The ID of the bot service, if matching.	101
path.tag	string	The path tag key, if matching.	login
path.tag.id	number	The path tag ID, if matching.	42
vv.visitor.events	string[]	List of detection events which contributed to the visitor score.	['detection-automated-fp', 'detection-automated-ua']
vv.visitor.score	number	Likelihood 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
labels	string[]	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:

Operator	Structure	Evaluation
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:

Operator	LHS types	RHS types	Expression
eq	Literals	Literals	'ip' EQ '198.51.100.3'
contains	Arrays	Literals	'vv.visitor.events' CONTAINS 'detection-automated-fp'
intersects	Arrays	Arrays	'vv.visitor.events' INTERSECTS ['detection-automated-fp', 'detection-automated-ua']
in	Literals	Arrays	'country_code' IN [ 'GB', 'US' ]
match	string	string	'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:

Action	Key	Effect
Allow	allow	Explicitly allow the request through. This can be useful to allow specific requests as an exception to other rules.
Block	block	Block the request completely.
CAPTCHA	captcha	Serve 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 Challenge	js_challenge	Serve 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.

Percentage Rollouts

Percentage rollouts allow for gradual rollouts of access control rules. When configured, the rule will only take affect for the specified percentage of visitors.

Each visitor is assigned a number between 0 and 1 based on a hash of the visitor and rule IDs. If the number is less than the percentage specified, then the visitor skips this rule, and the next rule in the chain is evaluated.

This method ensures that a given rule will apply consistently to all requests from a particular visitor.

Rate Limiting Rules

Rules with a rate limiter configured only apply their action for requests which match the rule expression and exceed the set rate limit.

Rate limiting rules track request counts by the given tracking properties using a leaky bucket algorithm. Each rule has its own counter and therefore counts are not shared between rules, however a request may be processed by more than one rate limiting rule.

When a request is processed by a rate limiting rule, the rule's expression is evaluated first. If the request doesn't match the expression, the rate limiter's counter is not updated.

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" }
    ]
}