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`
`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`

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.

Examples

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

Custom rules

Request Context / Fields​

Standard Fields​

Dynamic Fields​

Expressions​

Logical Clauses​

Comparison Clauses​

Actions​

Examples​

Serve CAPTCHA to automated traffic visiting a login page​

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

Allow a specific IP by exception using rule priorities​

Require JS/fingerprinting telemetry and block automated visitors​

Target a segment of traffic using customer labels​