Skip to main content
verifyngo evaluates a list of rules for every incoming request. The first rule that matches decides the action. If no rule matches, default_action applies (defaults to challenge). Rules can match on the URL path, the User-Agent header, or a client IP address or CIDR range. The three actions are allow (pass the request through to the upstream), challenge (serve a CAPTCHA), and deny (block the request immediately).

​
Inline rules (config.json)

You can define rules directly in config.json under the rules array. Each rule has a match object and an action string.
​
string
A regular expression matched against the request URL path. The rule fires when the path matches.
​
string
A regular expression matched against the User-Agent header. The rule fires when the header matches.
​
array of strings
A list of IP addresses or CIDR ranges. The rule fires when the client IP falls within any of the listed ranges.
​
string
required
What to do when the rule matches. One of allow, challenge, or deny.
Rules are first-match-wins and are evaluated from top to bottom. Put more specific rules before broader ones to avoid an early rule shadowing a later one.

​
Plain-text rules file

For larger rule sets, or when you want to update rules without restarting verifyngo, set rules_file in config.json to a path and create a .txt file there. verifyngo watches the file and picks up any edits within about 10 seconds.
Each line in the file follows the format <action> <type> <pattern>. Here is the full example from rules.txt.example:
The three match types are:
  • path — matches the request URL path using the pattern as a regular expression.
  • ua — matches the User-Agent header using the pattern as a regular expression.
  • cidr — matches the client IP against a single CIDR range (or a bare IP address).
Lines starting with # are treated as comments and skipped. Empty lines are also ignored.
Use the rules file for rules you change often. You don’t need to restart verifyngo — it picks up changes to the file automatically within about 10 seconds.

​
YAML policy file

For more advanced matching, set policy_file in config.json to a YAML file path. The policy file lets you define named network groups and write expressive conditions that can match on path, user agent, HTTP method, IP address, request headers, and more.
A policy file has three top-level sections:
  • networks — named groups of IP ranges or ASNs that you can reference in rule conditions.
  • conditions — named, reusable expressions you can reference inside rules.
  • rules — the list of rules to evaluate, each with a name, action, and one or more conditions.
Conditions can use the following variables:
  • path — the request URL path.
  • userAgent — the User-Agent header value.
  • method — the HTTP method (e.g. GET, POST).
  • ip — the client IP address as a string.
  • headers["Header-Name"] — any request header value.
Available functions in condition expressions:
  • matches(value, "regex") — true if the value matches the regular expression.
  • contains(value, "substring") — true if the value contains the substring.
  • startsWith(value, "prefix") — true if the value starts with the prefix.
  • network(ip, "group_name") — true if the IP falls within the named network group.
When policy_file is set, verifyngo uses the policy file exclusively and ignores both rules and rules_file. Like the plain-text rules file, the policy file is reloaded automatically within about 10 seconds whenever it changes on disk.