Define advanced traffic rules with YAML

Use a YAML policy file to define named network groups from ASNs, CIDRs, or remote URLs and write flexible, expressive per-rule conditions.

The YAML policy file gives you more advanced traffic control than inline rules or the plain-text rules file. To enable it, set policy_file in config.json to the path of your YAML file. When policy_file is set, it takes priority over rules_file and any inline rules defined in config.json which also allows for hot reload (where you do not have to restart verifyngo for changes to take effect), unlike the other files, which don’t have that capability.

Structure of a policy file

A policy file has up to three top-level keys:

• networks — named groups of IP ranges (required if your rules use remoteAddress.network(...)).
• conditions — reusable named condition groups (optional).
• rules — the ordered list of rules to evaluate (required).

Below is the example policy from examples/policy.yaml:

networks:
  huawei-cloud:
    - asn: 136907
    - asn: 55990
    - asn: 138915

  alibaba-cloud:
    - asn: 24429
    - asn: 134963

  cloudflare-v4:
    - url: https://www.cloudflare.com/ips-v4

  private-nets:
    - prefixes:
        - 10.0.0.0/8
        - 172.16.0.0/12
        - 192.168.0.0/16

rules:
  - name: allow-home
    conditions:
      - 'path == "/"'
    action: allow

  - name: allow-private
    conditions:
      - 'remoteAddress.network("private-nets")'
    action: pass

  - name: undesired-networks
    conditions:
      - 'remoteAddress.network("huawei-cloud") || remoteAddress.network("alibaba-cloud") || remoteAddress.network("cloudflare-v4")'
    action: drop

  - name: always-protected
    conditions:
      - 'path == "/sensitive-path"'
    action: check

Defining networks

The networks section maps a name to one or more source entries. verifyngo resolves all entries at startup and builds a fast lookup table for checking IPs at request time. You can mix source types within the same group.

Source	Description
asn: <number>	Fetches the ASN’s announced prefixes from RADb whois at startup.
cidr: "x.x.x.x/y"	Adds a single explicit CIDR range (or bare IP).
prefixes: [...]	Adds a list of explicit CIDR ranges.
url: "https://..."	Fetches a list of CIDRs from a remote URL (one per line by default).
file: "/path/to/file"	Reads CIDRs from a local file (one per line).

For url and file sources you can add a jq-path key to extract CIDRs from a JSON response, or a regex key with a named capture group called prefix to extract CIDRs from arbitrary text.

networks:
  cloudflare-v4:
    - url: https://www.cloudflare.com/ips-v4

  bad-asns:
    - asn: 136907
    - asn: 55990

  private-nets:
    - prefixes:
        - 10.0.0.0/8
        - 172.16.0.0/12
        - 192.168.0.0/16

Writing rules

Each rule in the rules list has a name, one or more conditions, and an action. Rules are evaluated top to bottom; the first matching rule wins. If no rule matches, default_action from config.json applies.

Available actions are allow / pass (let the request through), challenge / check (serve a CAPTCHA), and deny / drop (block immediately). The paired words are aliases for the same behaviour.

rules:
  - name: allow-private
    conditions:
      - 'remoteAddress.network("private-nets")'
    action: pass

  - name: block-bad-asns
    conditions:
      - 'remoteAddress.network("bad-asns")'
    action: deny

  - name: always-challenge-sensitive
    conditions:
      - 'path == "/admin"'
    action: challenge

When a rule has more than one condition, all conditions must be true for the rule to match (logical AND).

Condition variables

These variables are available in every condition expression:

• path — the request URL path string (e.g. "/blog/post-1").
• userAgent — the value of the User-Agent request header.
• method — the HTTP method (GET, POST, etc.).
• ip — the client IP address as a string.
• headers["Header-Name"] — the value of any request header, accessed by its exact name.
• remoteAddress.network("name") — evaluates to true if the client IP is a member of the named network group.

Condition functions

Three helper functions are available for string matching:

• contains(str, substr) — true if str contains substr.
• startsWith(str, prefix) — true if str starts with prefix.
• matches(str, regex) — true if str matches the regular expression regex.

You can also call these as methods: userAgent.contains("bot"), path.startsWith("/api"), path.matches("^/post/[0-9]+").

Named condition groups

If the same set of conditions appears in multiple rules, define it once under conditions and reference it in rules using ($name). When a rule contains a ($name) reference, verifyngo expands the group inline and OR-joins the individual expressions within it before applying the rule’s AND logic.

conditions:
  is-bot-ua:
    - 'userAgent.contains("bot")'
    - 'userAgent.contains("crawler")'

rules:
  - name: block-bots
    conditions:
      - '($is-bot-ua)'
    action: deny

Hot-reload applies to the policy file too. verifyngo watches the file and picks up any changes within about 10 seconds — no restart required.