Regex gate

The regex gate matches one configured part of the current request. It can inspect the body, path, query, or selected header values. It returns audit-safe findings with type regex_match.

Choose what to scan with scan.kind, then choose what to do with scan.action.kind. This example replaces matches in the request body:

name: customer-identifiers
kind: regex
scan:
  kind: body
  action:
    kind: replace
    template: '[{entity}]'
pattern_catalog:
  entities:
    - name: customer-id
      rules:
        - name: customer-id-rule
          pattern: '\bCUST-[0-9]{8}\b'
          confidence: high

The body is decoded as strict UTF-8. Path and query scans use the exact text in the request model. A header scan matches each selected header value on its own; a match cannot span two values. Header names are case-insensitive:

name: labeled-headers
kind: regex
scan:
  kind: header
  names: [x-customer-note, x-request-label]
  action:
    kind: deny
pattern_catalog: patterns.yaml

The header scan sees the current request snapshot, including validated header mutations from earlier gates. The regex gate does not return header mutations itself. OpenShell permits writes only in the x-openshell-middleware- namespace, so a general regex replacement cannot rewrite arbitrary selected headers. A custom gate can return supported header writes or removals when it declares the GateCapability.MUTATE_HEADERS capability.

A catalog can be inline or in a relative .yaml or .yml file. Relative paths resolve from the Egress Gate process working directory, not from the policy file. Use an inline catalog when the process does not have a stable working directory. The gate rejects absolute paths, path traversal, symlinks, YAML aliases, duplicate keys, invalid body UTF-8, unsafe patterns, and oversized catalogs.

Each entity has a stable, bounded name and one or more rules. Rule confidence is low, medium, or high. Optional flags are ignore_case, multiline, dot_all, and ascii. Do not use named capture groups or inline flags. Patterns must produce non-empty matches. Findings include overlapping detections. Replacement uses deterministic, non-overlapping matches.

Actions

detect and deny work with every scan kind. replace exists only in the body scan schema. It cannot be configured for a path, query, or header scan. This structure keeps unsupported combinations out of generated schemas and editor suggestions. OpenShell middleware results cannot rewrite a request path or query. Header replacement is not part of the built-in gate.

The replace action owns its template. It returns a body replacement even when there is no match. This preserves the operator's explicit intent to replace the current body. Invalid body UTF-8 is a stable body_encoding_invalid service failure.

The regex gate does not edit the body in place. It returns the replacement in RequestMutations. The pipeline processor uses it to build the next immutable HttpRequest snapshot. If the pipeline allows the request, Egress Gate includes the replacement in the final mutations returned to the OpenShell supervisor.

Replacement templates contain literal text and the {entity} field only. Output size is projected before rendering and is bounded by the advertised OpenShell body limit.

Scan reference

Configure another regex gate when different request parts need different catalogs or actions. Keeping one scan per gate makes matches, findings, and replacement offsets unambiguous.