jiazhizhong/higress
1
0
Fork 0
mirror of https://github.com/alibaba/higress.git synced 2026-03-02 23:51:11 +08:00
Code Issues Packages Projects Releases Wiki Activity

update plugins doc (#1305)

Browse Source
This commit is contained in:
澄潭
2024-09-12 21:48:40 +08:00
committed by GitHub
parent 0f9113ed82
commit c7c4ae1da2
80 changed files with 7373 additions and 2368 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
plugins/wasm-cpp/extensions/request_block/README.md
View File

@@ -1,11 +1,18 @@
<p>
<a href="README_EN.md"> English </a> | 中文
</p>
---
title: 请求屏蔽
keywords: [higress,request block]
description: 请求屏蔽插件配置参考
---
# 功能说明
## 功能说明
`request-block`插件实现了基于 URL、请求头等特征屏蔽 HTTP 请求，可以用于防护部分站点资源不对外部暴露
# 配置字段
## 运行属性
插件执行阶段：`鉴权阶段`
插件执行优先级：`320`
## 配置字段
| 名称 | 数据类型 | 填写要求 | 默认值 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
@@ -16,9 +23,9 @@
| blocked_message | string | 选填 | - | 配置请求被屏蔽时返回的 HTTP 应答 Body |
| case_sensitive | bool | 选填 | true | 配置匹配时是否区分大小写，默认区分 |
# 配置示例
## 配置示例
## 屏蔽请求 url 路径
### 屏蔽请求 url 路径
```yaml
block_urls:
- swagger.html
@@ -33,7 +40,7 @@ curl http://example.com?foo=Bar
curl http://exmaple.com/Swagger.html
```
## 屏蔽请求 header
### 屏蔽请求 header
```yaml
block_headers:
- example-key
@@ -47,7 +54,7 @@ curl http://example.com -H 'example-key: 123'
curl http://exmaple.com -H 'my-header: example-value'
```
## 屏蔽请求 body
### 屏蔽请求 body
```yaml
block_bodies:
- "hello world"
@@ -61,30 +68,8 @@ curl http://example.com -d 'Hello World'
curl http://exmaple.com -d 'hello world'
```
## 对特定路由或域名开启
```yaml
# 使用 _rules_ 字段进行细粒度规则配置
_rules_:
# 规则一：按路由名称匹配生效
- _match_route_:
- route-a
- route-b
block_bodies:
- "hello world"
# 规则二：按域名匹配生效
- _match_domain_:
- "*.example.com"
- test.com
block_urls:
- "swagger.html"
block_bodies:
- "hello world"
```
此例 `_match_route_` 中指定的 `route-a` 和 `route-b` 即在创建网关路由时填写的路由名称，当匹配到这两个路由时，将使用此段配置；
此例 `_match_domain_` 中指定的 `*.example.com` 和 `test.com` 用于匹配请求的域名，当发现域名匹配时，将使用此段配置；
配置的匹配生效顺序，将按照 `_rules_` 下规则的排列顺序，匹配第一个规则后生效对应配置，后续规则将被忽略。
# 请求 Body 大小限制
## 请求 Body 大小限制
当配置了 `block_bodies` 时，仅支持小于 32 MB 的请求 Body 进行匹配。若请求 Body 大于此限制，并且不存在匹配到的 `block_urls` 和 `block_headers` 项时，不会对该请求执行屏蔽操作
当配置了 `block_bodies` 时，若请求 Body 超过全局配置 DownstreamConnectionBufferLimits，将返回 `413 Payload Too Large`

80
plugins/wasm-cpp/extensions/request_block/README_EN.md
View File

@@ -1,24 +1,28 @@
<p>
English | <a href="README.md">中文</a>
</p>
---
title: Request Blocking
keywords: [higress,request block]
description: Request blocking plugin configuration reference
---
## Function Description
The `request-block` plugin implements HTTP request blocking based on features such as URL, request headers, etc. It can be used to protect certain site resources from being exposed to the outside.
# Description
`request-block` plugin implements a request blocking function based on request characteristics such as URL and request header. It can be used to protect internal resources from unauthorized access.
## Running Attributes
Plugin Execution Stage: `Authentication Stage`
# Configuration Fields
Plugin Execution Priority: `320`
| Name | Type | Requirement | Default Value | Description |
| -------- | -------- | -------- | -------- | -------- |
| block_urls | array of string | Optional. Choose one from following: `block_urls`, `block_headers`, `block_bodies` | - | HTTP URLs to be blocked. |
| block_headers | array of string | Optional. Choose one from following: `block_urls`, `block_headers`, `block_bodies` | - | HTTP request headers to be blocked. |
| block_bodies | array of string | Optional. Choose one from following: `block_urls` ,`block_headers`, `block_bodies` | - | HTTP request bodies to be blocked. |
| blocked_code | number | Optional | 403 | HTTP response status code to be sent when corresponding request is blocked. |
| blocked_message | string | Optional | - | HTTP response body to be sent when corresponding request is blocked. |
| case_sensitive | bool | Optional | true | Whether to use case-senstive comparison when matching. Enabled by default. |
## Configuration Fields
| Name | Data Type | Fill Requirement | Default Value | Description |
|--------------------|--------------------|---------------------------------------------------------|---------------|------------------------------------------------------------|
| block_urls | array of string | Optional, at least one of `block_urls`, `block_headers`, `block_bodies` must be filled | - | Configure strings for matching URLs that need to be blocked |
| block_headers | array of string | Optional, at least one of `block_urls`, `block_headers`, `block_bodies` must be filled | - | Configure strings for matching request headers that need to be blocked |
| block_bodies | array of string | Optional, at least one of `block_urls`, `block_headers`, `block_bodies` must be filled | - | Configure strings for matching request bodies that need to be blocked |
| blocked_code | number | Optional | 403 | Configure the HTTP status code returned when a request is blocked |
| blocked_message | string | Optional | - | Configure the HTTP response body returned when a request is blocked |
| case_sensitive | bool | Optional | true | Configure whether matching is case-sensitive, default is case-sensitive |
# Configuration Samples
## Block Specific Request URLs
## Configuration Example
### Blocking Request URL Paths
```yaml
block_urls:
- swagger.html
@@ -26,65 +30,39 @@ block_urls:
case_sensitive: false
```
According to the configuration above, following requests will be blocked:
Based on this configuration, the following requests will be denied access:
```bash
curl http://example.com?foo=Bar
curl http://exmaple.com/Swagger.html
```
## Block Specific Request Headers
### Blocking Request Headers
```yaml
block_headers:
- example-key
- example-value
```
According to the configuration above, following requests will be blocked:
Based on this configuration, the following requests will be denied access:
```bash
curl http://example.com -H 'example-key: 123'
curl http://exmaple.com -H 'my-header: example-value'
```
## Block Specific Request Bodies
### Blocking Request Bodies
```yaml
block_bodies:
- "hello world"
case_sensitive: false
```
According to the configuration above, following requests will be blocked:
Based on this configuration, the following requests will be denied access:
```bash
curl http://example.com -d 'Hello World'
curl http://exmaple.com -d 'hello world'
```
## Only Enable for Specific Routes or Domains
```yaml
# Use _rules_ field for fine-grained rule configurations
_rules_:
# Rule 1: Match by route name
- _match_route_:
- route-a
- route-b
block_bodies:
- "hello world"
# Rule 2: Match by domain
- _match_domain_:
- "*.example.com"
- test.com
block_urls:
- "swagger.html"
block_bodies:
- "hello world"
```
In the rule sample of `_match_route_`, `route-a` and `route-b` are the route names provided when creating a new gateway route. When the current route names matches the configuration, the rule following shall be applied.
In the rule sample of `_match_domain_`, `*.example.com` and `test.com` are the domain names used for request matching. When the current domain name matches the configuration, the rule following shall be applied.
All rules shall be checked following the order of items in the `_rules_` field, The first matched rule will be applied. All remained will be ignored.
## Request Body Size Limit
When `block_bodies` is configured, only request bodies smaller than 32 MB are supported for matching. If the request body exceeds this limit and there are no matching `block_urls` or `block_headers`, the blocking operation will not be executed for that request.
# Maximum Request Body Size Limitation
When `block_bodies` is configured, body matching shall only be performed when its size is smaller than 32MB. If not, and no `block_urls` or `block_headers` configuration is matched, the request won't be blocked.
When `block_bodies` is configured, if the size of request body exceeds the global configuration of DownstreamConnectionBufferLimits, a ``413 Payload Too Large`` response will be returned.
When `block_bodies` is configured and the request body exceeds the global configuration DownstreamConnectionBufferLimits, it will return `413 Payload Too Large`.