# Under Attack Mode (UAM)

# Overview

Under Attack Mode (UAM) is a WebShield feature that lets a server administrator put one or more domains (optionally scoped to specific URL paths) "under attack". While a domain is under attack, every matching HTTP request is first served a lightweight JavaScript splash challenge instead of being passed straight to the site:

• Regular browsers solve the challenge transparently and receive a clearance cookie (its lifetime is configurable per rule); subsequent requests carrying a valid cookie flow through normally.
• Simple bots that cannot run the challenge never reach the application.

UAM is a server-wide administrator feature. It is distinct from the per-IP GreyList / Anti-bot Challenge: UAM decisions are keyed on the request's (domain, path) and are configured explicitly by the administrator, rather than being driven by the state of an IP list.

# How it works

• A domain is placed under attack by creating a UAM rule. A rule pairs a domain (optionally narrowed to a path-set) with the clearance-cookie lifetime to grant once a visitor solves the challenge.
• When a request matches an active rule, WebShield returns the JS splash challenge and does not forward the request to the backend until the visitor passes.
• UAM is fail-open: if the feature is disabled, the request has no Host, the rule store cannot be read, or no active rule matches, the request simply proceeds through the normal WebShield flow. UAM never blocks a request outright — it only inserts a challenge.
• The feature is gated behind a single on/off toggle that is off by default, and all UAM state is stored on the server itself.

# Prerequisites

• WebShield version >= 1.45.0 installed and running in an environment where UAM is available (see the note above). The core rule commands and the service toggle have been available since 1.44.2; the per-rule challenge-cookie lifetime and the uam test command described below were added in 1.45.0.
• Root access to the server. UAM is managed with the imunify360-wsctl uam command, which must be run as root.

# Enabling and disabling UAM

UAM is off by default. Enable the feature before creating rules — while it is disabled, all rule and counter commands fail with a service_disabled error.

imunify360-wsctl uam settings service            # show the current {enabled} state
imunify360-wsctl uam settings service enable      # turn UAM on, server-wide
imunify360-wsctl uam settings service disable     # turn UAM off

Disabling the feature stops all challenges immediately; your rules are preserved and take effect again when you re-enable it.

# Managing rules

A rule is created from a small JSON payload. The fields are:

A new rule is active as soon as it is created.

# Put a whole domain under attack; re-challenge visitors after 1 hour:
imunify360-wsctl uam add '{"domain":"shop.example.com","cookie_ttl":"1h","label":"Black Friday"}'

# Scope the rule to specific paths (see "Path scoping" below):
imunify360-wsctl uam add '{"domain":"shop.example.com","cookie_ttl":"30m","paths":{"mode":"include","matchers":[{"value":"/checkout","condition":"prefix"}]}}'

List the current rules (a table by default, --json for raw output, --domain to filter by exact domain):

imunify360-wsctl uam list
imunify360-wsctl uam list --domain shop.example.com --json

The table shows ID ACTIVE DOMAIN COOKIE_TTL LABEL. The ID is a positive integer assigned by WebShield when the rule is created; you use it to edit or delete the rule.

imunify360-wsctl uam list
ID  ACTIVE  DOMAIN            COOKIE_TTL  LABEL
7   true    shop.example.com  1h          Black Friday

Edit a rule with a partial JSON payload — only active, cookie_ttl, label, and paths can be changed. Temporarily pausing a rule is done by setting active to false:

imunify360-wsctl uam edit 7 '{"active":false}'       # pause the rule (keep it for later)
imunify360-wsctl uam edit 7 '{"cookie_ttl":"2h"}'    # change the clearance-cookie lifetime
imunify360-wsctl uam edit 7 '{"label":"BF sale"}'    # rename
imunify360-wsctl uam edit 7 '{"paths":null}'         # clear paths -> back to whole-domain

Delete a rule by ID. Delete is idempotent — deleting an ID that no longer exists still succeeds:

imunify360-wsctl uam delete 7

# Path scoping

By default a rule covers the whole domain. Add a paths block to challenge only some URLs. The block has a mode and a list of matchers:

• mode: "include" — the matchers list the paths that are under attack. A request is challenged only if it matches one of them.
• mode: "exclude" — the matchers list exceptions. A matching request is let through; everything else on the domain is challenged.

Each matcher is {"value": "...", "condition": "..."}, where condition is one of equals, prefix, suffix, or contains. A rule may hold between 1 and 32 matchers, and a request matches the block if it satisfies any of them.

# Only challenge /api and everything under /checkout:
imunify360-wsctl uam add '{"domain":"shop.example.com","paths":{"mode":"include","matchers":[{"value":"/api","condition":"equals"},{"value":"/checkout","condition":"prefix"}]}}'

# Challenge the whole domain EXCEPT the health-check endpoint:
imunify360-wsctl uam add '{"domain":"shop.example.com","paths":{"mode":"exclude","matchers":[{"value":"/healthz","condition":"equals"}]}}'

# Testing which rule matches a URL

uam test checks whether a given URL would be challenged, using the exact same matching as live traffic. It is the quickest way to verify a rule's path scoping without generating real requests.

imunify360-wsctl uam test example.com/path          # scheme optional; host required
imunify360-wsctl uam test https://shop.example.com/api?x=1

The scheme is optional, the host is required, and both the path and the query string are significant (only a trailing #fragment is ignored, and an empty path is treated as /). When a rule matches, the command prints that rule as JSON; otherwise it prints No matching rule:

imunify360-wsctl uam test shop.example.com/checkout
[
  {
    "id": 7,
    "owner": "admin",
    "active": true,
    "label": "Black Friday",
    "domain": "shop.example.com",
    "cookie_ttl": "1h",
    "paths": {
      "mode": "include",
      "matchers": [
        {
          "value": "/checkout",
          "condition": "prefix"
        }
      ]
    }
  }
]

# Monitoring challenges

Each challenge served for a rule is counted. Use counters to see which rules are actively challenging traffic, busiest first:

imunify360-wsctl uam counters                       # all rules with hits today, busiest first
imunify360-wsctl uam counters --since 24h           # a rolling window instead of "today"
imunify360-wsctl uam counters shop.example.com      # filter by exact domain
imunify360-wsctl uam counters 7                      # filter by rule id

The single optional argument is auto-detected: a positive integer is treated as a rule ID, anything else as an exact domain. The --since window is one of today (default), 1h, 4h, 24h, 4d, or 7d. Output columns are ID ACTIVE DOMAIN HITS LABEL. Only rules with at least one challenge in the window are listed, and challenge counts are retained for 7 days.

imunify360-wsctl uam counters
ID  ACTIVE  DOMAIN            HITS  LABEL
7   true    shop.example.com  1523  Black Friday