> 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:** [`chaitin-waf`](#chaitin-waf), [`consumer-restriction`](#consumer-restriction), [`cors`](#cors), [`csrf`](#csrf), [`ip-restriction`](#ip-restriction), [`public-api`](#public-api), [`referer-restriction`](#referer-restriction), [`ua-restriction`](#ua-restriction), [`uri-blocker`](#uri-blocker)
{% endhint %}
### `chaitin-waf`
The `chaitin-waf` Plugin integrates with the Chaitin WAF (SafeLine) service to provide advanced detection and prevention of web-based threats, enhancing application security and protecting sensitive user data.
{% hint style="info" %}
**Priority** `2700` · **Category** Security
{% endhint %}
Configuration and details
| Name | Type | Required | Default | Valid values | Description |
| -------------------------- | -------------- | -------- | ------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| mode | string | false | block | `off`, `monitor`, `block` | Mode to determine how the Plugin behaves for matched requests. In `off` mode, WAF checks are skipped. In `monitor` mode, requests with potential threats are logged but not blocked. In `block` mode, requests with threats are blocked as determined by the WAF service. |
| match | array\[object] | false | | | An array of matching rules. The Plugin uses these rules to decide whether to perform a WAF check on a request. If the list is empty, all requests are processed. |
| match.vars | array\[array] | false | | | An array of one or more matching conditions in the form of lua-resty-expr to conditionally execute the plugin. |
| append\_waf\_resp\_header | boolean | false | true | | If true, add response headers `X-AILIX-CHAITIN-WAF`, `X-AILIX-CHAITIN-WAF-TIME`, `X-AILIX-CHAITIN-WAF-ACTION`, and `X-AILIX-CHAITIN-WAF-STATUS`. |
| append\_waf\_debug\_header | boolean | false | false | | If true, add debugging headers `X-AILIX-CHAITIN-WAF-ERROR` and `X-AILIX-CHAITIN-WAF-SERVER` to the response. Effective only when `append_waf_resp_header` is `true`. |
| config | object | false | | | Chaitin WAF service configurations. These settings override the corresponding metadata defaults when specified. |
| config.connect\_timeout | integer | false | 1000 | | The connection timeout to the WAF service, in milliseconds. |
| config.send\_timeout | integer | false | 1000 | | The sending timeout for transmitting data to the WAF service, in milliseconds. |
| config.read\_timeout | integer | false | 1000 | | The reading timeout for receiving data from the WAF service, in milliseconds. |
| config.req\_body\_size | integer | false | 1024 | | The maximum allowed request body size, in KB. |
| config.keepalive\_size | integer | false | 256 | | The maximum number of idle connections to the WAF detection service that can be maintained concurrently. |
| config.keepalive\_timeout | integer | false | 60000 | | The idle connection timeout for the WAF service, in milliseconds. |
| config.real\_client\_ip | boolean | false | true | | If true, the client IP is obtained from the `X-Forwarded-For` header. If false, the Plugin uses the client IP from the connection. |
### `consumer-restriction`
The `consumer-restriction` Plugin allows users to configure access restrictions on Consumer, Route, Service, 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. |
### `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. |
### `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 | `ailix-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. |
### `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. |
### `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. |
### `referer-restriction`
The `referer-restriction` Plugin can be used to restrict access to a Service 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. |
### `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. |
### `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. |
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
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 optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.