Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/achetronic/request-validator

External Authz for Envoy to allow or deny requests based on CEL expressions. Body included.
https://github.com/achetronic/request-validator

cel envoy ext-authz istio

Last synced: 23 days ago
JSON representation

External Authz for Envoy to allow or deny requests based on CEL expressions. Body included.

Awesome Lists containing this project

README 

          
# request-validator



A lightweight Envoy and Istio **ext-authz** service that allows or denies requests using simple YAML rules written in [CEL (Common Expression Language)](https://github.com/google/cel-spec).



This service is built for complex authorization scenarios that standard Istio `AuthorizationPolicy` cannot handle, such as:



- Inspecting the request body (JSON or YAML).

- Mixing IP networks (CIDRs) and JWT claims with request payload values.

- Validating OAuth `redirect_uris`.

- Blocking specific paths during certain hours.

- Any other custom validation that goes beyond basic method, path, and header matching.



## Two ways to configure policies



You can drive the engine in two complementary ways, and you can mix them freely:



1. **Declarative YAML**. A policy file checked into Git, typically mounted into the pod as a `ConfigMap`. This is your source of truth and what code review enforces.

2. **Admin API at runtime**. A small CRUD HTTP API on a separate port that lets you upsert and delete groups, facts, defaults and logging without redeploying. Useful for emergency blocks, A/B experiments, and any change that needs to happen in seconds.



Both paths feed the same evaluator. The YAML is the declarative floor; the admin API overlays it per key. There is no separate "YAML mode" or "API mode": every replica always serves the same effective policy, computed as `MergeFromYAML(yaml, admin_overlay)`.



### How the merge works



| Section    | Behaviour                                                                                      |

| ---------- | ---------------------------------------------------------------------------------------------- |

| `groups`   | Keyed by `name`. API entry replaces the YAML entry with the same name; new names are appended. |

| `facts`    | Same as `groups`: per-name overlay.                                                            |

| `defaults` | Per-field overlay. Fields present in the API replace YAML; absent fields keep the YAML value.  |

| `logging`  | Same per-field overlay as `defaults`.                                                          |



Deleting an admin entry (`DELETE /api/v1/groups/foo`) restores the YAML entry of the same name if there was one. So you can ship a guard-rail policy in Git and let operators add tactical rules on top without losing the base.



You can always inspect what is actually being evaluated with `GET /api/v1/config`, which returns the merged result with a `source: "yaml" | "api"` flag on each group.



### Hot reload



Whatever changes (the YAML file on disk, the admin overlay in the state store, or both) every replica rebuilds atomically:



| Trigger                                                    | Path                                              |

| ---------------------------------------------------------- | ------------------------------------------------- |

| Edit the YAML (`kubectl edit cm request-validator-policy`) | fsnotify picks it up within ~200 ms               |

| `kill -HUP 1` (fallback for NFS / FUSE)                    | manual reload                                     |

| Admin API `PUT` / `DELETE`                                 | leader commits, every replica's informer rebuilds |



A reload that fails to parse, validate, compile or fetch URL facts is rejected; the previously installed policy keeps serving traffic. Fail-closed by design.



### Writes go to the leader, reads work anywhere



In multi-replica deployments the admin API uses a Kubernetes `Lease` (`request-validator-leader`) to elect one writer at a time. A write that lands on a follower is transparently proxied to the current leader over an internal HTTP hop, and the leader's response is streamed back to the client. There is no redirect on the wire: the client cannot tell which replica handled the request, and it does not need any direct access to individual pods. Reads are served locally by every replica from its informer cache, with sub-second convergence after a write.



## Quick Tour



Here is a simple policy that allows POST requests to a Keycloak Dynamic Client Registration endpoint, but only if the request comes from an internal private IP range:



```yaml

defaults:

  action: deny



groups:

  - name: dcr-internal

    action: allow

    rules:

      - name: from-internal-cidr

        match: |

          request.method == 'POST' &&

          request.path.startsWith('/realms/mcp/clients-registrations') &&

          inCIDR(request.remoteIp, ['10.0.0.0/8'])

```



How it works:



- **`defaults.action`**: The default action when no rules match. We set this to `deny` to ensure unmatched requests are blocked.

- **`groups`**: Logical collections of rules that share a verdict (like `action: allow`).

- **`rules`**: Individual checks. The `match` field contains a CEL expression that must return a boolean. If it evaluates to `true`, the rule matches and the group's action is applied.

- **`inCIDR`**: A helper function provided by request-validator to easily check IP ranges.



The rest of this guide covers more advanced features and examples.



## Examples



### 1. Limit Admin Access to Office IP and Working Hours



```yaml

groups:

  - name: admin-business-hours

    action: allow

    rules:

      - name: office-during-the-day

        match: |

          request.path.startsWith('/admin') &&

          inCIDR(request.remoteIp, ['203.0.113.0/24']) &&

          now().getHours('UTC') >= 7 &&

          now().getHours('UTC') < 19

```



The `now()` function returns the current time. You can use standard CEL accessors like `getHours`, `getDayOfWeek`, or `getMonth` to enforce schedules without external dependencies.



### 2. Require a Header on Webhook Paths



```yaml

groups:

  - name: webhook-needs-signature

    action: allow

    rules:

      - name: signed-with-x-hub-signature

        match: |

          request.path.startsWith('/hooks/github') &&

          has('x-hub-signature-256', request.headers) &&

          request.header['x-hub-signature-256'].startsWith('sha256=')

```



The `has()` helper checks if a header exists and is not empty. You can then access its values directly via `request.header`.



### 3. Block Specific Realms on Public Domains



```yaml

groups:

  - name: keep-master-realm-private

    action: deny

    rules:

      - name: no-master-on-public-hosts

        match: |

          request.host in ['auth.example-1.com', 'auth.example-2.com'] &&

          request.path.startsWith('/realms/master')

```



Declaring a group with `action: deny` makes it easy to write and read explicit blocklists.



### 4. Validate JSON Request Bodies



This is a powerful feature that Istio's built-in policies cannot do. Here, we only allow Keycloak client registrations if all listed `redirect_uris` belong to trusted domains:



```yaml

groups:

  - name: dcr-trusted-redirects

    action: allow

    match: |

      request.method == 'POST' &&

      request.path.matches('^/realms/mcp/clients-registrations(/.*)?$') &&

      request.body.jsonOk

    rules:

      - name: antigravity

        match: |

          request.body.json.redirect_uris.all(u,

            u.startsWith('https://antigravity.google/'))



      - name: chatgpt

        match: |

          request.body.json.redirect_uris.all(u,

            u.matches('^https://([a-z0-9-]+\\.)?openai\\.com/.+$'))

```



The group-level `match` serves as a pre-filter. If it is a POST to the registration endpoint with valid JSON, we then evaluate the individual rules.



### 5. Multi-factor Checks (Defense in Depth)



If you want a group to require multiple rules to pass before allowing access, set the group `mode` to `all`:



```yaml

groups:

  - name: admin-defence-in-depth

    action: allow

    mode: all

    match: |

      request.path.startsWith('/admin')

    rules:

      - name: from-internal-network

        match: inCIDR(request.remoteIp, ['10.0.0.0/8', '192.168.0.0/16'])

      - name: has-admin-claim

        match: request.header['x-user-groups'].contains('platform-admins')

      - name: no-debug-header

        match: '!has("x-debug", request.headers)'

```



In `all` mode, every single rule must evaluate to `true`. If even one fails, the group denies the request.



For a comprehensive real-world policy, take a look at [`examples/policy.yaml`](examples/policy.yaml).



### 6. Push a Tactical Block via the Admin API



So far every example has lived in the YAML file. Here is the same shape pushed at runtime through the admin API, useful for an incident response when there is no time for a redeploy:



```bash

TOKEN=$(kubectl -n request-validator get secret request-validator-admin \

  -o jsonpath='{.data.token}' | base64 -d)



curl -sLf -X PUT \

  -H "Authorization: Bearer $TOKEN" \

  -H "Content-Type: application/json" \

  -d '{

    "priority": -100,

    "action": "deny",

    "rules": [

      { "name": "block-bad-ip",

        "match": "request.remoteIp == \"203.0.113.5\"" }

    ]

  }' \

  "http://request-validator.request-validator.svc:8081/api/v1/groups/incident-2026-05-19"

```



The body is the exact same shape you would write inside `groups:` in the YAML; the wire format and the on-disk format are intentionally identical. `priority: -100` makes the group win against the YAML allow-lists. You can hit any pod (or the Service in front of them); if the pod that receives the request is not the current leader it proxies the write internally and you still get the leader's response back. Reverting the change is a `DELETE` against the same URL; the YAML floor takes over again without a deploy.



## How Policy Evaluation Works



The engine evaluates groups sequentially in the order they are defined. The first group that matches and produces a verdict determines the outcome. If no group produces a verdict, the default action (`defaults.action`) is applied.



You can customize this flow using several properties:



- **`priority`**: Assign an integer (e.g., `priority: -100`) to run a group earlier. Groups with lower priority values run first. This is useful for placing global blocklists before allowlist groups.

- **`match` (Group level)**: A filter that decides if the group should look at the request. If false, the group is skipped.

- **`mode`**: Controls how rules inside the group are evaluated:

  - `firstMatch` (default): The first rule that evaluates to `true` wins.

  - `all`: All rules must evaluate to `true`.

- **`action` (Rule level)**: You can override the group action on a specific rule.

- **`fallthrough`**: By default, if a rule does not match, the engine moves to the next rule. You can set `fallthrough: allow` or `fallthrough: deny` to immediately stop group evaluation with that verdict.

- **`dryRun`**: Set to `true` to test rules in production. The engine evaluates and logs the decision, but will not block the request.



## Available Request Fields in CEL



Every CEL expression has access to two top-level objects: `request` and `facts`.



| Field                      | Type                        | Description                                        |

| :------------------------- | :-------------------------- | :------------------------------------------------- |

| `request.method`           | `string`                    | HTTP method (GET, POST, etc.)                      |

| `request.scheme`           | `string`                    | http or https (extracted from X-Forwarded-Proto)   |

| `request.host`             | `string`                    | Request authority (host without port)              |

| `request.path`             | `string`                    | URL path                                           |

| `request.remoteIp`         | `string`                    | Client IP (from X-Forwarded-For or remote address) |

| `request.headers`          | `map>` | All headers with lowercased keys                   |

| `request.header`           | `map`       | First value of each header                         |

| `request.queries`          | `map>` | All query parameters                               |

| `request.query`            | `map`       | First value of each query parameter                |

| `request.body.raw`         | `string`                    | Raw request body (up to `defaults.maxBodyBytes`)   |

| `request.body.size`        | `int`                       | Body size in bytes                                 |

| `request.body.contentType` | `string`                    | Content-Type header shortcut                       |

| `request.body.json`        | `dyn`                       | Parsed JSON object, or `{}` if not JSON            |

| `request.body.jsonOk`      | `bool`                      | True if the body is valid JSON                     |

| `request.body.yaml`        | `dyn`                       | Parsed YAML object, or `{}` if not YAML            |

| `request.body.yamlOk`      | `bool`                      | True if the body is valid YAML                     |



_Note: For the body to be available, you must configure Envoy/Istio to forward request bodies (see the Istio configuration section below)._



## Facts: Dynamic and External Data



If you have dynamic data that changes frequently (such as IP blocks published by third parties or lists of active customers), you can load them dynamically as `facts` instead of hardcoding them into your YAML policy.



You define facts at the top level of your policy and reference them in CEL using `facts.`.



There are three sources for facts:



| Method  | Source                                        | CEL Type                      |

| :------ | :-------------------------------------------- | :---------------------------- |

| `value` | Defined inline in your YAML policy            | The declared YAML type        |

| `file`  | Read from a local file path on startup/reload | String (file content)         |

| `url`   | Fetched periodically over HTTP                | String (latest response body) |



Example configuration:



```yaml

facts:

  - name: internalCidrs

    method: value

    value:

      - 10.0.0.0/8

      - 192.168.0.0/16



  - name: trustedClients

    method: file

    file:

      path: /etc/policy/lists/trusted-clients.yaml



  - name: chatgptFeed

    method: url

    url:

      address: https://openai.com/chatgpt-actions.json

      interval: 10m

      timeout: 15s

      headers:

        Authorization: "Bearer $TOKEN"

```



To use them in your CEL rules:



```cel

inCIDR(request.remoteIp, facts.internalCidrs)

```



For facts loaded as raw strings, you can parse them on the fly in CEL:



```cel

inCIDR(request.remoteIp, parseJSON(facts.chatgptFeed).prefixes.map(p, p.ipv4Prefix))

```



The `parseJSON` and `parseYAML` helpers return `{}` if the input is empty or invalid, ensuring your rules do not crash if a fetch fails. It is usually a good idea to protect your rules by checking if the fact is available first:



```yaml

match: |

  request.path.startsWith('/api') &&

  facts.chatgptFeed != null && facts.chatgptFeed != ""

```



_Note on reliability: If the initial fetch of a URL fact fails during startup, the policy is rejected. If a subsequent background refresh fails, request-validator will log a warning but continue to use the last successfully fetched data. This prevents temporary network issues from blocking requests._



## Logging



`request-validator` writes structured JSON logs for decisions and internal events. You can configure logging directly in your policy:



```yaml

logging:

  level: info # debug | info | warn | error

  format: json # json | console

  logBody: false # include the request body in logs (opt-in)

  redactReveal: 6 # show only the first N characters of redacted values

  excludeHeaders: # completely exclude these headers from logs

    - cookie

    - set-cookie

  redactHeaders: # mask these header values

    - authorization

    - proxy-authorization

    - x-api-key

    - x-auth-token

  redactQueryParams: # mask these query parameters

    - access_token

    - id_token

    - code

```



The CLI flags `--log-level` and `--log-format` can be used to override these settings without updating the YAML policy.



An example log entry in JSON:



```json

{

  "time": "2026-05-19T12:14:59.845Z",

  "level": "INFO",

  "msg": "request decided",

  "decision": "allow",

  "rule": "dcr-trusted-redirects/antigravity",

  "reason": "matched",

  "dry_run": false,

  "duration_ms": 0.31,

  "request": {

    "method": "POST",

    "host": "auth.example-1.com",

    "path": "/realms/mcp/clients-registrations",

    "query": "code=***&debug=1",

    "remote_ip": "203.0.113.5",

    "headers": {

      "content-type": "application/json",

      "authorization": "Bearer*********************************",

      "x-api-key": "***"

    },

    "body": { "size": 48, "content_type": "application/json" }

  }

}

```



The `console` format outputs values as plain `key=value` lines, which is highly readable when using `kubectl logs -f` during local development.



## CEL Function Reference



On top of the standard CEL functions and libraries (`ext.Strings()`, `ext.Encoders()`, `ext.Lists()`, `ext.Sets()`, `ext.Math()`, `ext.Bindings()`), the service registers the following custom helper functions.



### Network Functions



- `inCIDR(ip, cidrs)`: Returns `true` if `ip` is in any of the listed CIDR ranges. Supports both IPv4 and IPv6. Plain IPs are automatically treated as `/32` or `/128`.

- `ipFamily(ip)`: Returns `"ipv4"`, `"ipv6"`, or `""` if invalid.

- `isPrivateIP(ip)`: Returns `true` if the IP is in private ranges (RFC1918, RFC4193, or link-local).

- `isLoopbackIP(ip)`: Returns `true` if the IP is a loopback address (`127.0.0.0/8` or `::1`).

- `parseURL(url)`: Parses a URL string and returns a map with `scheme`, `host`, `port`, `path`, `query`, `fragment`, `username`, and `password`.



### Glob Matching



- `glob(string, pattern)`: Evaluates a glob pattern. `*` matches anything except slashes, `**` matches everything recursively, `?` matches a single character, and `[abc]` matches character classes.

- `globAny(string, patterns)`: Returns `true` if any of the glob patterns match.



### Encoding and Security



- `sha256Hex(string)`: Returns the SHA-256 hash of a string as a lowercase hex string.

- `parseJWTUnverified(token)`: Parses a JWT token and returns a map containing `{header, payload}`. It **does not** verify the signature. Use this only if signature validation is handled by another gateway layer.



### Time



- `now()`: Returns the current UTC timestamp. You can call CEL accessors like `.getHours()`, `.getDayOfWeek()`, or `.getMonth()` on the result.



### Structured Parsing



- `parseJSON(string)`: Parses JSON. Returns `{}` on empty, null, or invalid input.

- `parseYAML(string)`: Parses YAML. Returns `{}` on empty, null, or invalid input.

- `jsonPath(object, expression)`: Evaluates a lightweight JSONPath expression (e.g., `$.a.b[*]`, `$..name`, `$[0]`).



### HTTP Conveniences



- `has(name, map)`: Returns `true` if the key exists in the map and has a non-empty value.

- `firstOr(map, name, default)`: Returns the first value of a key, or the default value if it is empty or missing.



## Deployment and Operation



### Running Locally



To run request-validator locally with the included example:



```bash

go run ./cmd \

  --config examples/policy.yaml \

  --log-level debug --log-format console \

  --no-kubernetes

```



The `--no-kubernetes` flag tells the service to run in standalone, in-memory mode without attempting to contact a Kubernetes cluster.



### Deploying to Kubernetes



An official OCI image is available at: `ghcr.io/achetronic/request-validator:`.



A ready-to-go deployment setup is located in [`examples/kubernetes/`](examples/kubernetes/). Pick `manifests/` for plain `kubectl` / kustomize, or `helm/` for the bjw-s app-template chart:



```bash

# Create the namespace and admin secret

kubectl create namespace request-validator

kubectl -n request-validator create secret generic request-validator-admin \

  --from-literal=token=$(openssl rand -hex 32)



# Deploy the manifests (plain kubectl + kustomize)

kubectl apply -k examples/kubernetes/manifests/



# …or with Helm (bjw-s app-template 5.0.1)

helm repo add bjw-s https://bjw-s-labs.github.io/helm-charts

helm upgrade --install request-validator bjw-s/app-template \

  --version 5.0.1 -n request-validator \

  -f examples/kubernetes/helm/values.yaml

```



This sets up a Deployment with 2 replicas, RBAC permissions, a ConfigMap for the policy, a Service, and a PodDisruptionBudget.



### Ports and Endpoints



The service exposes two ports:



#### 1. ext-authz port (Default: `8080`)



This is the port Envoy talks to.



- `/`: The ext-authz validation endpoint.

- `/healthz`: Liveness probe.

- `/readyz`: Readiness probe (becomes healthy once a policy is successfully loaded).

- `/metrics`: Prometheus metrics.



#### 2. admin port (Default: `8081`)



Exposes a CRUD API to modify policies at runtime. Disabled if `--admin-token-file` is not provided.



- `GET/PUT/DELETE /api/v1/groups[/{name}]`: Manage policy groups.

- `GET/PUT/DELETE /api/v1/facts[/{name}]`: Manage facts.

- `GET/PUT/DELETE /api/v1/defaults`: Override global configuration defaults.

- `GET/PUT/DELETE /api/v1/logging`: Manage logging rules.

- `GET /api/v1/config`: View the merged running configuration.

- `GET /api/v1/cluster`: Details about the leader and cluster state.

- `GET /api/v1/openapi.json`: OpenAPI 3.1 specification.



All admin requests must include an `Authorization: Bearer ` header, using the token defined in the admin token file.



### Hot Reloads and Multi-Replica Mode



These are covered in detail under [Two Ways to Configure Policies](#two-ways-to-configure-policies):

file changes propagate via fsnotify (or `SIGHUP` as fallback), admin

API writes go to the elected leader and fan out to every replica's

informer cache, and failed reloads keep the previous policy live.



### Diagnostic Headers



Every decision returned by request-validator includes headers to help you debug and inspect evaluation results:



- `x-rv-result`: The verdict (`allow` or `deny`).

- `x-rv-rule`: The rule that matched, formatted as `group/rule` (or ``).

- `x-rv-reason`: A short, human-readable explanation.

- `x-rv-dry-run`: `true` if the rule was executed in dry-run mode.



## Integration with Istio



To integrate the service with Istio, apply these two configurations:



### 1. Register the Extension Provider in MeshConfig



Add request-validator as an extension provider in your Istio installation settings (usually in the `istio-system` namespace's `istio` ConfigMap):



```yaml

meshConfig:

  extensionProviders:

    - name: request-validator

      envoyExtAuthzHttp:

        service: request-validator..svc.cluster.local

        port: 8080

        failOpen: false

        timeout: 2s

        includeRequestBodyInCheck:

          maxRequestBytes: 1048576

          allowPartialMessage: false

        headersToDownstreamOnDeny:

          [content-type, x-rv-result, x-rv-rule, x-rv-reason, x-rv-dry-run]

        headersToUpstreamOnAllow:

          [x-rv-result, x-rv-rule, x-rv-reason, x-rv-dry-run]

        includeRequestHeadersInCheck:

          - authorization

          - content-type

          - cookie

          - x-api-key

          - x-user-groups

          - x-forwarded-for

          - x-forwarded-proto

```



### 2. Configure an AuthorizationPolicy



Create a CUSTOM policy to route matching traffic to the validator:



```yaml

apiVersion: security.istio.io/v1

kind: AuthorizationPolicy

metadata:

  name: keycloak-dcr-ext-authz

  namespace: keycloak

spec:

  selector:

    matchLabels:

      app.kubernetes.io/name: keycloak

  action: CUSTOM

  provider:

    name: request-validator

  rules:

    - to:

        - operation:

            hosts: [auth.example-1.com, auth.example-2.com]

            paths:

              - /realms/*/clients-registrations

              - /realms/*/clients-registrations/*

```



For advanced use cases, such as passing all request headers without listing them individually, see the EnvoyFilter examples in [`examples/config-for-istio.yaml`](examples/config-for-istio.yaml).



## License



Apache-2.0.