Session Rules

Session Rules automate token management across testing sessions. Instead of manually updating Authorization headers or cookies every time a session expires, you define rules that extract tokens from responses and inject them into subsequent requests automatically.

🔗The Problem

Penetration tests often last hours. Session tokens expire. Every time you need to re-authenticate, you interrupt your workflow. Session Rules solve this by detecting expiration, triggering a re-authentication macro, and propagating new tokens forward without manual intervention.

🔗Rule Structure

Each session rule contains:

  • name – a label for the rule
  • scope – a scope pattern limiting which URLs this rule applies to (host wildcard, URL prefix, or regex)
  • validation – optional configuration for detecting invalid sessions
  • reauth_macro – optional UUID of a macro to execute when the session expires
  • token_updates – list of extraction + injection pairs (where to find the token, where to put it)
  • enabled / priority – toggle and ordering; higher priority rules are evaluated first

🔗Detecting Session Expiry

Validation checks detect when a session is no longer valid:

  • StatusCode – response status is in a given list (e.g., [401, 403]); the most common check
  • ResponseContains – response body contains a string (e.g., "session expired")
  • ResponseNotContains – response body no longer contains an expected string (e.g., "authenticated")
  • HeaderContains – a specific header contains a pattern
  • Regex – a regex matches the response

One check type is active per rule.

🔗Token Sources

Where to extract a token from the response:

  • ResponseBody(regex) – regex with one capture group; the captured group is the token
  • ResponseHeader(header_name, regex) – token extracted from a response header using a regex
  • Cookie(cookie_name) – token is the value of a Set-Cookie header with the given name

🔗Token Targets

Where to inject the extracted token into subsequent requests:

  • RequestHeader(header_name) – sets the value of the named request header
  • Cookie(cookie_name) – sets the value of the named cookie in the Cookie header
  • QueryParam(param_name) – sets the value of a URL query parameter

🔗Built-in Presets

Four preset rules cover the most common patterns:

JWT Bearer auth – detects 401/403 as invalid, extracts access_token from JSON response body, injects into Authorization header as Bearer <token>.

Cookie-based session – detects 302/401/403, extracts the named cookie from Set-Cookie, injects into Cookie header.

CSRF token – extracts the CSRF token from a hidden input field (<input name="_csrf" value="...">), injects into the named request header.

OAuth2 refresh – detects 401, triggers the macro to get a new access token, extracts both access_token and refresh_token from the response body.

🔗How It Works

The session plugin hooks into the proxy pipeline:

  • On response – extracts tokens from every matching response and caches them in memory. If a response indicates session expiry, the plugin flags the macro for execution.
  • On request – if cached tokens exist, injects them into outgoing requests matching the rule scope.

Both auto-extract and auto-inject are enabled by default and can be disabled independently.

Cached tokens are held in a thread-safe map keyed by token name. Each new extraction overwrites the previous value, so token rotation is handled transparently.

🔗Configuration Example

{
  "rules": [
    {
      "name": "API Auth",
      "scope": {"pattern": "*.api.example.com", "target": "host"},
      "validation": {
        "check_type": {"type": "StatusCode", "value": [401]}
      },
      "reauth_macro": "uuid-of-login-macro",
      "token_updates": [
        {
          "token_name": "access_token",
          "source": {"type": "ResponseBody", "regex": "\"access_token\":\"([^\"]+)\""},
          "target": {"type": "RequestHeader", "name": "Authorization"}
        }
      ],
      "enabled": true,
      "priority": 100
    }
  ],
  "auto_extract": true,
  "auto_inject": true
}

🔗MCP Tool

session – session and authentication management.

Actions:

  • tokens – list currently cached tokens
  • status – session manager status
  • list_macros – list login macros
  • create_macro – create a new login macro
  • get_macro – get a specific macro
  • delete_macro – remove a macro
  • execute_macro – run a macro manually
  • refresh – force token refresh

For full macro lifecycle (record, edit, replay multi-step sequences) and rule management with triggers (Always / StatusCode / BodyContains / HeaderContains / Interval), see the macros MCP tool which exposes:

  • list_macros, get_macro, create_macro (from flow_ids), update_macro, delete_macro, run_macro, test_macro
  • list_rules, create_rule, update_rule, delete_rule, enable_rule, disable_rule