> For the complete documentation index, see [llms.txt](https://docs.digitalapi.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalapi.ai/api-gateway/plugin-reference/plugins-security.md).
# Security plugins
Plugins in this category protect the gateway against malicious traffic: bot detection, payload size limits, CORS enforcement, WAF-style rule sets. They run early in the request chain so bad traffic is rejected before downstream plugins or upstream calls. The catalogue ships 9 Security plugins.
{% hint style="info" %}
**In this category:** [`consumer-restriction`](#consumer-restriction), [`cors`](#cors), [`csrf`](#csrf), [`ip-restriction`](#ip-restriction), [`log-data-mask`](#log-data-mask), [`public-api`](#public-api), [`referer-restriction`](#referer-restriction), [`ua-restriction`](#ua-restriction), [`uri-blocker`](#uri-blocker)
{% endhint %}
### `consumer-restriction`
The `consumer-restriction` Plugin allows users to configure access restrictions on Consumer, Route, API, or Consumer Group.
{% hint style="info" %}
**Priority** `2400` · **Category** Security
{% endhint %}
Configuration and details
| Name | Type | Required | Default | Valid values | Description |
| ---------------------------- | -------------- | -------- | -------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| type | string | False | consumer\_name | \["consumer\_name", "consumer\_group\_id", "service\_id", "route\_id"] | Type of object to base the restriction on. |
| whitelist | array\[string] | True | | | List of objects to whitelist. Has a higher priority than `allowed_by_methods`. |
| blacklist | array\[string] | True | | | List of objects to blacklist. Has a higher priority than `whitelist`. |
| rejected\_code | integer | False | 403 | \[200,...] | HTTP status code returned when the request is rejected. |
| rejected\_msg | string | False | | | Message returned when the request is rejected. |
| allowed\_by\_methods | array\[object] | False | | | List of allowed configurations for Consumer settings, including a username of the Consumer and a list of allowed HTTP methods. |
| allowed\_by\_methods.user | string | False | | | A username for a Consumer. |
| allowed\_by\_methods.methods | array\[string] | False | | \["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE", "PURGE"] | List of allowed HTTP methods for a Consumer. |
**Sample configuration**
Whitelist named Consumers (only these Consumers may call the API):
```json
{
"consumer-restriction": {
"whitelist": ["jack", "alice"]
}
}
```
Blacklist named Consumers (block these, allow everyone else):
```json
{
"consumer-restriction": {
"blacklist": ["bob"]
}
}
```
Restrict by route with a custom rejection code and message:
```json
{
"consumer-restriction": {
"type": "route_id",
"whitelist": ["orders-api", "billing-api"],
"rejected_code": 401,
"rejected_msg": "You are not allowed to access this route"
}
}
```
Per-Consumer allowed methods:
```json
{
"consumer-restriction": {
"allowed_by_methods": [
{
"user": "jack",
"methods": ["GET", "POST"]
},
{
"user": "alice",
"methods": ["GET"]
}
]
}
}
```
### `cors`
The `cors` Plugins lets you enable [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) easily.
{% hint style="info" %}
**Priority** `4000` · **Category** Security
{% endhint %}
Configuration and details
| Name | Type | Required | Default | Description |
| ---------------------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| allow\_origins | string | False | "\*" | Origins to allow CORS. Use the `scheme://host:port` format. For example, `https://somedomain.com:8081`. If you have multiple origins, use a `,` to list them. If `allow_credential` is set to `false`, you can enable CORS for all origins by using `*`. If `allow_credential` is set to `true`, you can forcefully allow CORS on all origins by using `**` but it will pose some security issues. |
| allow\_methods | string | False | "\*" | Request methods to enable CORS on. For example `GET`, `POST`. Use `,` to add multiple methods. If `allow_credential` is set to `false`, you can enable CORS for all methods by using `*`. If `allow_credential` is set to `true`, you can forcefully allow CORS on all methods by using `**` but it will pose some security issues. |
| allow\_headers | string | False | "\*" | Headers in the request allowed when accessing a cross-origin resource. Use `,` to add multiple headers. If `allow_credential` is set to `false`, you can enable CORS for all request headers by using `*`. If `allow_credential` is set to `true`, you can forcefully allow CORS on all request headers by using `**` but it will pose some security issues. |
| expose\_headers | string | False | | Headers in the response allowed when accessing a cross-origin resource. Use `,` to add multiple headers. If `allow_credential` is set to `false`, you can enable CORS for all response headers by using `*`. If not specified, the plugin will not modify the `Access-Control-Expose-Headers header`. See [Access-Control-Expose-Headers - MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Expose-Headers) for more details. |
| max\_age | integer | False | 5 | Maximum time in seconds the result is cached. If the time is within this limit, the browser will check the cached result. Set to `-1` to disable caching. Note that the maximum value is browser dependent. See [Access-Control-Max-Age](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age#Directives) for more details. |
| allow\_credential | boolean | False | false | When set to `true`, allows requests to include credentials like cookies. According to CORS specification, if you set this to `true`, you cannot use '\*' to allow all for the other attributes. |
| allow\_origins\_by\_regex | array | False | nil | Regex to match origins that allow CORS. For example, `[".*\.test.com$"]` can match all subdomains of `test.com`. When set to specified range, only domains in this range will be allowed, no matter what `allow_origins` is. |
| allow\_origins\_by\_metadata | array | False | nil | Origins to enable CORS referenced from `allow_origins` set in the Plugin metadata. For example, if `"allow_origins": {"EXAMPLE": "https://example.com"}` is set in the Plugin metadata, then `["EXAMPLE"]` can be used to allow CORS on the origin `https://example.com`. |
| Name | Type | Required | Default | Description |
| --------------------------------- | ------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| timing\_allow\_origins | string | False | nil | Origin to allow to access the resource timing information. See [Timing-Allow-Origin](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Timing-Allow-Origin). Use the `scheme://host:port` format. For example, `https://somedomain.com:8081`. If you have multiple origins, use a `,` to list them. |
| timing\_allow\_origins\_by\_regex | array | False | nil | Regex to match with origin for enabling access to the resource timing information. For example, `[".*\.test.com"]` can match all subdomain of `test.com`. When set to specified range, only domains in this range will be allowed, no matter what `timing_allow_origins` is. |
**Sample configuration**
Minimal (allow CORS from a single origin):
```json
{
"cors": {
"allow_origins": "https://app.example.com"
}
}
```
Credentials enabled (cookies allowed, so origins, methods, and headers must be listed explicitly, not `*`):
```json
{
"cors": {
"allow_origins": "https://app.example.com",
"allow_methods": "GET,POST,PUT,DELETE",
"allow_headers": "Authorization,Content-Type",
"allow_credential": true,
"max_age": 3600
}
}
```
Match origins by regex (all subdomains of `example.com`):
```json
{
"cors": {
"allow_origins_by_regex": [".*\\.example\\.com$"],
"allow_methods": "GET,POST",
"expose_headers": "X-Request-Id"
}
}
```
### `csrf`
The `csrf` Plugin can be used to protect your API against [CSRF attacks](https://en.wikipedia.org/wiki/Cross-site_request_forgery) using the [Double Submit Cookie](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Double_Submit_Cookie) method.
{% hint style="info" %}
**Priority** `2980` · **Category** Security · **Required** `key`
{% endhint %}
Configuration and details
This Plugin considers the `GET`, `HEAD` and `OPTIONS` methods to be safe operations (`safe-methods`) and such requests are not checked for interception by an attacker. Other methods are termed as `unsafe-methods`.
| Name | Type | Required | Default | Description |
| ------- | ------ | -------- | ------------------ | ------------------------------------------------------------------------------------------- |
| name | string | False | `helix-csrf-token` | Name of the token in the generated cookie. |
| expires | number | False | `7200` | Expiration time in seconds of the CSRF cookie. Set to `0` to skip checking expiration time. |
| key | string | True | | Secret key used to encrypt the cookie. |
**Sample configuration**
Minimal (only the required signing key):
```json
{
"csrf": {
"key": "my-csrf-signing-secret"
}
}
```
Custom cookie name and expiry:
```json
{
"csrf": {
"key": "my-csrf-signing-secret",
"name": "x-csrf-token",
"expires": 3600
}
}
```
### `ip-restriction`
The `ip-restriction` Plugin supports restricting access to upstream resources by IP addresses, through either configuring a whitelist or blacklist of IP addresses. Restricting IP to resources helps prevent unauthorized access and harden API security.
{% hint style="info" %}
**Priority** `3000` · **Category** Security
{% endhint %}
Configuration and details
| Name | Type | Required | Default | Valid values | Description |
| -------------- | -------------- | -------- | -------------------------------- | ------------ | ---------------------------------------------------------------------- |
| whitelist | array\[string] | False | | | List of IPs or CIDR ranges to whitelist. |
| blacklist | array\[string] | False | | | List of IPs or CIDR ranges to blacklist. |
| message | string | False | "Your IP address is not allowed" | \[1, 1024] | Message returned when the IP address is not allowed access. |
| response\_code | integer | False | 403 | \[403, 404] | HTTP response code returned when the IP address is not allowed access. |
**Sample configuration**
Whitelist IPs and CIDR ranges (only these may connect):
```json
{
"ip-restriction": {
"whitelist": ["10.0.0.0/8", "192.168.1.100"]
}
}
```
Blacklist IPs (block these, allow everyone else) with a custom message and code:
```json
{
"ip-restriction": {
"blacklist": ["203.0.113.0/24"],
"message": "Access from your IP address is blocked",
"response_code": 404
}
}
```
### `log-data-mask`
The `log-data-mask` Plugin defines rules to mask or remove sensitive data from request and response data before they are written to access logs. The plugin runs in the log phase and stores its configuration under `ctx.helix.` (default `log_data_mask`) so that logging plugins can resolve and apply the masking rules.
{% hint style="info" %}
**Priority** `999` · **Category** Security
{% endhint %}
Configuration and details
At least one of `request` or `response` must be configured. Each is an array of masking rules with the fields below.
| Name | Type | Required | Default | Valid values | Description |
| -------------- | -------------- | ----------- | --------------- | ------------ | --------------------------------------------------------------- |
| request | array\[object] | Conditional | | | Masking rules applied to the logged request data. |
| response | array\[object] | Conditional | | | Masking rules applied to the logged response data. |
| ctx\_namespace | string | False | `log_data_mask` | | Namespace under `ctx.helix` where the masking config is stored. |
**Rule fields (per entry in `request` or `response`)**
| Name | Type | Required | Valid values | Description |
| ------------ | ------ | ----------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| action | string | True | \["remove","replace","regex"] | `remove` drops the field from the log, `replace` substitutes a fixed value, `regex` applies a pattern substitution. |
| name | string | True | | Name of the query parameter, header, or body field the rule targets. |
| type | string | True | \["query","header","body"] | Where the field lives. |
| value | string | Conditional | | Replacement value. Required for the `replace` and `regex` actions. |
| regex | string | Conditional | | Pattern to match. Required for the `regex` action. |
| body\_format | string | False | \["json","urlencoded"] | Body encoding, for rules of type `body`. |
**Sample configuration**
Minimal (remove a sensitive header from logged request data):
```json
{
"log-data-mask": {
"request": [
{
"action": "remove",
"type": "header",
"name": "Authorization"
}
]
}
}
```
Replace a query parameter with a fixed value:
```json
{
"log-data-mask": {
"request": [
{
"action": "replace",
"type": "query",
"name": "api_key",
"value": "***MASKED***"
}
]
}
}
```
Regex-mask a JSON body field in the response and use a custom namespace:
```json
{
"log-data-mask": {
"ctx_namespace": "log_data_mask",
"response": [
{
"action": "regex",
"type": "body",
"name": "card_number",
"regex": "\\d(?=\\d{4})",
"value": "*",
"body_format": "json"
}
]
}
}
```
### `public-api`
The `public-api` Plugin exposes an internal API endpoint, making it publicly accessible. One of the primary use cases of this Plugin is to expose internal endpoints created by other Plugins.
{% hint style="info" %}
**Priority** `501` · **Category** Security
{% endhint %}
Configuration and details
| Name | Type | Required | Default | Valid Values | Description |
| ---- | ------ | -------- | ------- | ------------ | --------------------------------------------------------------------- |
| uri | string | False | | | Internal endpoint to expose. If not configured, expose the Route URI. |
**Sample configuration**
Expose the Route URI (no fields set):
```json
{
"public-api": {}
}
```
Expose a specific internal endpoint:
```json
{
"public-api": {
"uri": "/internal/jwt/sign"
}
}
```
### `referer-restriction`
The `referer-restriction` Plugin can be used to restrict access to an API or a Route by whitelisting/blacklisting the `Referer` request header.
{% hint style="info" %}
**Priority** `2990` · **Category** Security
{% endhint %}
Configuration and details
| Name | Type | Required | Default | Valid values | Description |
| --------------- | -------------- | -------- | ---------------------------------- | ------------ | ------------------------------------------------------------------------------------------------- |
| whitelist | array\[string] | False | | | List of hostnames to whitelist. A hostname can start with `*` for wildcard. |
| blacklist | array\[string] | False | | | List of hostnames to blacklist. A hostname can start with `*` for wildcard. |
| message | string | False | "Your referer host is not allowed" | \[1, 1024] | Message returned when access is not allowed. |
| bypass\_missing | boolean | False | false | | When set to `true`, bypasses the check when the `Referer` request header is missing or malformed. |
**Sample configuration**
Whitelist referer hosts (wildcards allowed):
```json
{
"referer-restriction": {
"whitelist": ["example.com", "*.example.com"]
}
}
```
Blacklist referer hosts and bypass the check when the header is missing:
```json
{
"referer-restriction": {
"blacklist": ["malicious.com"],
"bypass_missing": true,
"message": "Requests from your site are not allowed"
}
}
```
### `ua-restriction`
The `ua-restriction` Plugin supports restricting access to upstream resources through either configuring an allowlist or denylist of user agents. A common use case is to prevent web crawlers from overloading the upstream resources and causing service degradation.
{% hint style="info" %}
**Priority** `2999` · **Category** Security
{% endhint %}
Configuration and details
| Name | Type | Required | Default | Valid values | Description |
| --------------- | -------------- | -------- | ------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| bypass\_missing | boolean | False | false | | If true, bypass the user agent restriction check when the `User-Agent` header is missing. |
| allowlist | array\[string] | False | | | List of user agents to allow. Support regular expressions. At least one of the `allowlist` and `denylist` should be configured, but they cannot be configured at the same time. |
| denylist | array\[string] | False | | | List of user agents to deny. Support regular expressions. At least one of the `allowlist` and `denylist` should be configured, but they cannot be configured at the same time. |
| message | string | False | "Not allowed" | | Message returned when the user agent is denied access. |
**Sample configuration**
Allowlist user agents (only matching agents may access, regex supported):
```json
{
"ua-restriction": {
"allowlist": ["Mozilla/5.0.*", "MyMobileApp/.*"]
}
}
```
Denylist user agents (block crawlers) and bypass when the header is missing:
```json
{
"ua-restriction": {
"denylist": ["(Googlebot|bingbot)", ".*[Bb]ot.*"],
"bypass_missing": true,
"message": "Crawlers are not allowed"
}
}
```
### `uri-blocker`
The `uri-blocker` Plugin intercepts user requests with a set of `block_rules`.
{% hint style="info" %}
**Priority** `2900` · **Category** Security · **Required** `block_rules`
{% endhint %}
Configuration and details
| Name | Type | Required | Default | Valid values | Description |
| ----------------- | -------------- | -------- | ------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| block\_rules | array\[string] | True | | | List of regex filter rules. If the request URI hits any one of the rules, the response code is set to the `rejected_code` and the user request is terminated. For example, `["root.exe", "root.m+"]`. |
| rejected\_code | integer | False | 403 | \[200, ...] | HTTP status code returned when the request URI hits any of the `block_rules`. |
| rejected\_msg | string | False | | non-empty | HTTP response body returned when the request URI hits any of the `block_rules`. |
| case\_insensitive | boolean | False | false | | When set to `true`, ignores the case when matching request URI. |
**Sample configuration**
Minimal (block requests whose URI matches any rule):
```json
{
"uri-blocker": {
"block_rules": ["root.exe", "root.m+"]
}
}
```
Case-insensitive matching with a custom rejection code and body:
```json
{
"uri-blocker": {
"block_rules": ["/admin", "\\.php$"],
"rejected_code": 404,
"rejected_msg": "This resource is not available",
"case_insensitive": true
}
}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.digitalapi.ai/api-gateway/plugin-reference/plugins-security.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.