This is an automated email from the ASF dual-hosted git repository.
Aias00 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/shenyu-website.git
The following commit(s) were added to refs/heads/main by this push:
new 8ee4cb03d4c docs: add security model document. (#1127)
8ee4cb03d4c is described below
commit 8ee4cb03d4c7e3685ca35ad01fdddf6c99838eff
Author: wy471x <[email protected]>
AuthorDate: Thu Jul 16 16:23:57 2026 +0800
docs: add security model document. (#1127)
* docs: add security model document.
* docs: add security model document and add zh version.
---
docs/help/_category_.json | 4 +
docs/help/security-model/_category_.json | 4 +
docs/help/security-model/security-model.md | 130 +++++++++++++++++++++
.../zh/docusaurus-plugin-content-docs/current.json | 4 +
.../current/help/_category_.json | 4 +
.../current/help/security-model/_category_.json | 4 +
.../current/help/security-model/security-model.md | 130 +++++++++++++++++++++
.../version-2.7.1.json | 4 +
.../version-2.7.1/help/_category_.json | 4 +
.../help/security-model/_category_.json | 4 +
.../help/security-model/security-model.md | 130 +++++++++++++++++++++
versioned_docs/version-2.7.1/help/_category_.json | 4 +
.../help/security-model/_category_.json | 4 +
.../help/security-model/security-model.md | 130 +++++++++++++++++++++
14 files changed, 560 insertions(+)
diff --git a/docs/help/_category_.json b/docs/help/_category_.json
new file mode 100644
index 00000000000..55f1ed2f29b
--- /dev/null
+++ b/docs/help/_category_.json
@@ -0,0 +1,4 @@
+{
+ "label": "Help",
+ "position": 9
+}
diff --git a/docs/help/security-model/_category_.json
b/docs/help/security-model/_category_.json
new file mode 100644
index 00000000000..51a7517afe5
--- /dev/null
+++ b/docs/help/security-model/_category_.json
@@ -0,0 +1,4 @@
+{
+ "label": "Security Model",
+ "position": 1
+}
diff --git a/docs/help/security-model/security-model.md
b/docs/help/security-model/security-model.md
new file mode 100644
index 00000000000..2c15ebb8550
--- /dev/null
+++ b/docs/help/security-model/security-model.md
@@ -0,0 +1,130 @@
+---
+title: Security Model
+keywords: ["Security Model", "Trust Boundaries", "Vulnerability Scope"]
+description: Apache ShenYu security model defining trust boundaries,
deployment controls, and vulnerability scope
+---
+
+# Apache ShenYu Security Model
+
+This document defines the security model and trust boundaries of Apache
ShenYu. It is intended for:
+
+- **Operators**: understand required deployment controls and security
assumptions.
+- **Security researchers**: determine whether a reported behavior falls within
ShenYu's intended trust boundaries.
+- **ASF Security team**: triage incoming vulnerability reports against this
model.
+
+Reports about behavior that violates this model are in scope. Reports about
behavior that assumes a boundary explicitly excluded by this model are out of
scope.
+
+---
+
+## 1. Deployment Boundary
+
+**The Admin service (shenyu-admin) is designed to operate within a trusted
internal network.**
+
+The Admin port (default: `9095`) must **not** be exposed to the public
internet. The Admin service binds to `0.0.0.0` by default for convenience in
containerized and internal-network deployments; this is not an indication that
it is safe for external exposure.
+
+Operators are responsible for:
+
+- Placing the Admin service behind a firewall or private VPC.
+- Using network-level access controls (security groups, ingress rules, VPN) to
restrict access to the Admin port.
+- Optionally binding the Admin server to a specific internal address in
production.
+
+Exposing the Admin port to the public internet is a deployment
misconfiguration, not a vulnerability in ShenYu.
+
+## 2. Authentication Boundary
+
+**All authenticated Admin users are fully trusted. Account provisioning is the
security boundary.**
+
+The Admin service uses Apache Shiro for authentication. Once a user is
authenticated (via username/password, LDAP, or other configured mechanisms),
they are considered a trusted operator of the ShenYu deployment.
+
+The security boundary is:
+
+- **Account creation and credential management** — only authorized personnel
should be able to provision Admin accounts.
+- **Credential storage** — passwords and secrets stored by ShenYu (e.g., in
the database) must be protected.
+
+Actions performed by an authenticated Admin user (including any user with a
valid login) are not security vulnerabilities. If an attacker can authenticate,
the deployment is already compromised.
+
+## 3. RBAC Model
+
+**`@RequiresPermissions` controls UI feature visibility, not security
isolation between authenticated Admin users.**
+
+ShenYu implements a role-based access control (RBAC) system using Apache Shiro
annotations (`@RequiresPermissions`). This system is designed to:
+
+- Simplify the Admin UI by showing each user only the features relevant to
their role.
+- Prevent accidental misconfiguration by limiting which users can modify
specific resources (plugins, rules, selectors, etc.).
+
+RBAC in ShenYu is **not** a hard security boundary. It does **not** protect
against:
+
+- A malicious authenticated user intentionally escalating privileges.
+- A user discovering or invoking API endpoints they are not assigned to
through means other than the Admin UI.
+- Cross-tenant isolation between Admin users of the same deployment.
+
+**All authenticated Admin users share the same trust domain.** If you require
strict isolation between operators, deploy separate ShenYu Admin instances.
+
+## 4. WebSocket Sync Channel
+
+**The `/websocket` endpoint is intentionally unauthenticated and must be
protected by network-level access controls.**
+
+The Admin service exposes a WebSocket endpoint at `/websocket` for Gateway
(bootstrap) instances to receive real-time configuration updates. This endpoint
is explicitly excluded from Shiro authentication (see `shenyu.shiro.white-list`
in `application.yml`).
+
+Because the Gateway must connect to this endpoint to synchronize plugin,
selector, and rule data, the WebSocket channel operates without authentication
at the application layer. The security of this channel depends entirely on:
+
+- **Network isolation**: the `/websocket` endpoint must only be reachable by
Gateway instances within the trusted internal network.
+- **Firewall rules**: block external access to the Admin port, which also
protects the WebSocket endpoint.
+
+Anyone who can reach the `/websocket` endpoint can receive the full
configuration state of the Gateway, including plugin rules, upstream service
addresses, and authentication keys. This is by design: within the trusted
network, the Gateway is a legitimate consumer of this data.
+
+## 5. Control Plane vs. Data Plane
+
+**Admin (control plane) and Gateway (data plane) are separate trust domains.**
+
+| Component | Role | Trust Level |
+|---|---|---|
+| shenyu-admin | Control plane — manages configuration, plugins, rules,
metadata | Trusted internal only |
+| shenyu-bootstrap | Data plane — handles live traffic routing, rate limiting,
auth | Exposed to traffic (internet-facing or DMZ) |
+
+Key implications:
+
+- The Gateway does **not** trust the Admin implicitly for runtime traffic
decisions. The Gateway enforces its own authentication, rate limiting, and
routing rules against incoming requests.
+- Compromise of the Admin does **not** directly compromise traffic flowing
through the Gateway, but it does allow an attacker to modify Gateway
configuration (add/remove plugins, modify routing rules, etc.).
+- Compromise of the Gateway does **not** grant access to the Admin or its
database.
+- The WebSocket sync channel (`/websocket`) is the bridge between these trust
domains and must be protected as described in Section 4.
+
+## 6. Database Security
+
+**The database is trusted infrastructure. Database compromise is an
independent security event outside ShenYu's software threat model.**
+
+ShenYu stores configuration, user credentials, plugin data, and metadata in a
database (H2 for development, MySQL/PostgreSQL for production).
+
+ShenYu assumes:
+
+- The database is deployed in a secured environment with access controls
independent of ShenYu.
+- Database credentials used by ShenYu are protected and not exposed.
+- The database network port is not exposed to untrusted networks.
+
+If an attacker gains direct access to the database (e.g., via SQL injection in
a separate application, stolen credentials, or network misconfiguration), they
can read or modify all ShenYu state. This is an infrastructure-level
compromise, not a vulnerability in ShenYu's application logic.
+
+## 7. Scope Summary
+
+**In scope** (report to [[email protected]](mailto:[email protected])):
+
+- Unauthenticated remote code execution.
+- Authentication bypass allowing access without valid credentials.
+- Gateway (bootstrap) request-handling vulnerabilities exploitable through
crafted HTTP traffic.
+- Plugin-level vulnerabilities that allow bypassing Gateway-enforced
authentication or rate limiting.
+- Injection attacks (SQL, command, template) reachable through unauthenticated
Gateway request paths.
+
+**Out of scope** (deployment or infrastructure concerns):
+
+- Actions performed by an authenticated Admin user.
+- Misuse of features by an authenticated Admin user (e.g., an Admin user
modifying rules they are not "supposed" to access via RBAC).
+- Exposure of the Admin port or WebSocket endpoint to untrusted networks.
+- Direct database access by an attacker with database credentials.
+- Vulnerabilities in third-party infrastructure (LDAP servers, databases,
Kubernetes clusters) used alongside ShenYu.
+
+---
+
+## References
+
+- [Apache ShenYu Website](https://shenyu.apache.org/)
+- [Security Vulnerability Reporting](https://www.apache.org/security/)
+- [Apache Project Maturity
Model](https://community.apache.org/apache-way/apache-project-maturity-model.html)
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current.json
b/i18n/zh/docusaurus-plugin-content-docs/current.json
index 222e9aa0236..112569eb475 100755
--- a/i18n/zh/docusaurus-plugin-content-docs/current.json
+++ b/i18n/zh/docusaurus-plugin-content-docs/current.json
@@ -110,5 +110,9 @@
"sidebar.tutorialSidebar.category.Benchmark Test": {
"message": "基准测试",
"description": "ShenYu Benchmark Test"
+ },
+ "sidebar.tutorialSidebar.category.Help": {
+ "message": "帮助",
+ "description": "The label for category 'Help' in sidebar 'tutorialSidebar'"
}
}
diff --git
a/i18n/zh/docusaurus-plugin-content-docs/current/help/_category_.json
b/i18n/zh/docusaurus-plugin-content-docs/current/help/_category_.json
new file mode 100644
index 00000000000..670a29a17ea
--- /dev/null
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/help/_category_.json
@@ -0,0 +1,4 @@
+{
+ "label": "帮助",
+ "position": 9
+}
diff --git
a/i18n/zh/docusaurus-plugin-content-docs/current/help/security-model/_category_.json
b/i18n/zh/docusaurus-plugin-content-docs/current/help/security-model/_category_.json
new file mode 100644
index 00000000000..bd7a9f33c2c
--- /dev/null
+++
b/i18n/zh/docusaurus-plugin-content-docs/current/help/security-model/_category_.json
@@ -0,0 +1,4 @@
+{
+ "label": "安全模型",
+ "position": 1
+}
diff --git
a/i18n/zh/docusaurus-plugin-content-docs/current/help/security-model/security-model.md
b/i18n/zh/docusaurus-plugin-content-docs/current/help/security-model/security-model.md
new file mode 100644
index 00000000000..3b4660dd64e
--- /dev/null
+++
b/i18n/zh/docusaurus-plugin-content-docs/current/help/security-model/security-model.md
@@ -0,0 +1,130 @@
+---
+title: 安全模型
+keywords: ["安全模型", "信任边界", "漏洞范围"]
+description: Apache ShenYu 安全模型，定义信任边界、部署控制和漏洞范围
+---
+
+# Apache ShenYu 安全模型
+
+本文档定义了 Apache ShenYu 的安全模型和信任边界，适用于：
+
+- **运维人员**：了解所需的部署控制措施和安全假设。
+- **安全研究人员**：判断某个报告的行为是否在 ShenYu 的预期信任边界内。
+- **ASF 安全团队**：根据本模型对收到的漏洞报告进行分诊。
+
+违反本模型的行为报告属于有效范围。假设了本模型明确排除的边界的行为报告则不在范围内。
+
+---
+
+## 1. 部署边界
+
+**Admin 服务（shenyu-admin）设计用于在受信任的内部网络中运行。**
+
+Admin 端口（默认：`9095`）**不得**暴露到公共互联网。Admin 服务默认绑定到
`0.0.0.0`，是为了方便容器化和内部网络部署；这并不意味着它对外部暴露是安全的。
+
+运维人员负责：
+
+- 将 Admin 服务放置于防火墙或私有 VPC 之后。
+- 使用网络级访问控制（安全组、入站规则、VPN）限制对 Admin 端口的访问。
+- 在生产环境中，可选择将 Admin 服务器绑定到特定的内部地址。
+
+将 Admin 端口暴露到公共互联网是部署配置错误，而非 ShenYu 的漏洞。
+
+## 2. 认证边界
+
+**所有已认证的 Admin 用户都是完全受信任的。账号管理是安全边界。**
+
+Admin 服务使用 Apache Shiro 进行认证。一旦用户通过认证（通过用户名/密码、LDAP 或其他配置的机制），他们就被视为 ShenYu
部署的受信任操作者。
+
+安全边界在于：
+
+- **账号创建和凭证管理** — 只有授权人员才能创建 Admin 账号。
+- **凭证存储** — ShenYu 存储的密码和密钥（例如在数据库中）必须受到保护。
+
+已认证的 Admin 用户（包括任何拥有有效登录凭据的用户）执行的操作不属于安全漏洞。如果攻击者能够认证，则部署已经被攻破。
+
+## 3. RBAC 模型
+
+**`@RequiresPermissions` 控制的是 UI 功能的可见性，而非已认证 Admin 用户之间的安全隔离。**
+
+ShenYu 使用 Apache Shiro
注解（`@RequiresPermissions`）实现了基于角色的访问控制（RBAC）系统。该系统的设计目标是：
+
+- 简化 Admin 界面，仅向每个用户展示与其角色相关的功能。
+- 通过限制哪些用户可以修改特定资源（插件、规则、选择器等），防止意外误配置。
+
+ShenYu 中的 RBAC **不是**硬安全边界。它**不能**防护：
+
+- 恶意的已认证用户故意提升权限。
+- 用户通过 Admin UI 以外的方式发现或调用未被分配的 API 端点。
+- 同一部署的 Admin 用户之间的跨租户隔离。
+
+**所有已认证的 Admin 用户共享同一信任域。** 如果需要操作者之间的严格隔离，请部署独立的 ShenYu Admin 实例。
+
+## 4. WebSocket 同步通道
+
+**`/websocket` 端点是有意不进行认证的，必须通过网络级访问控制来保护。**
+
+Admin 服务在 `/websocket` 暴露一个 WebSocket 端点，供
Gateway（bootstrap）实例接收实时配置更新。该端点被明确排除在 Shiro 认证之外（参见 `application.yml` 中的
`shenyu.shiro.white-list`）。
+
+由于 Gateway 必须连接到此端点以同步插件、选择器和规则数据，WebSocket 通道在应用层没有认证机制。此通道的安全性完全取决于：
+
+- **网络隔离**：`/websocket` 端点只能被受信任内部网络中的 Gateway 实例访问。
+- **防火墙规则**：阻止外部访问 Admin 端口，同时也就保护了 WebSocket 端点。
+
+任何能够访问 `/websocket` 端点的人都可以接收 Gateway
的完整配置状态，包括插件规则、上游服务地址和认证密钥。这是有意为之：在受信任网络内，Gateway 是这些数据的合法消费者。
+
+## 5. 控制面与数据面
+
+**Admin（控制面）和 Gateway（数据面）属于不同的信任域。**
+
+| 组件 | 角色 | 信任级别 |
+|---|---|---|
+| shenyu-admin | 控制面 — 管理配置、插件、规则、元数据 | 仅限受信任的内部网络 |
+| shenyu-bootstrap | 数据面 — 处理实时流量路由、限流、认证 | 对流量暴露（面向互联网或 DMZ） |
+
+关键含义：
+
+- Gateway **不会**隐式信任 Admin 来做运行时的流量决策。Gateway 会针对入站请求执行自己的认证、限流和路由规则。
+- Admin 被攻破**不会**直接危及流经 Gateway 的流量，但会允许攻击者修改 Gateway 的配置（添加/删除插件、修改路由规则等）。
+- Gateway 被攻破**不会**授予对 Admin 或其数据库的访问权限。
+- WebSocket 同步通道（`/websocket`）是这两个信任域之间的桥梁，必须按照第 4 节所述进行保护。
+
+## 6. 数据库安全
+
+**数据库是受信任的基础设施。数据库被攻破是一个独立的安全事件，不在 ShenYu 的软件威胁模型范围内。**
+
+ShenYu 将配置、用户凭证、插件数据和元数据存储在数据库中（开发环境使用 H2，生产环境使用 MySQL/PostgreSQL）。
+
+ShenYu 假设：
+
+- 数据库部署在安全环境中，具有独立于 ShenYu 的访问控制。
+- ShenYu 使用的数据库凭证受到保护且不对外暴露。
+- 数据库网络端口不暴露给不受信任的网络。
+
+如果攻击者获得对数据库的直接访问权限（例如通过其他应用程序的 SQL 注入、凭证泄露或网络配置错误），他们可以读取或修改所有 ShenYu
状态。这是基础设施层面的安全事件，而非 ShenYu 应用程序逻辑中的漏洞。
+
+## 7. 范围总结
+
+**在范围内**（请报告至 [[email protected]](mailto:[email protected])）：
+
+- 未经认证的远程代码执行。
+- 允许无需有效凭证即可访问的认证绕过。
+- Gateway（bootstrap）请求处理漏洞，可通过构造的 HTTP 流量利用。
+- 允许绕过 Gateway 强制执行的认证或限流的插件级漏洞。
+- 通过未经认证的 Gateway 请求路径可到达的注入攻击（SQL、命令、模板）。
+
+**不在范围内**（部署或基础设施问题）：
+
+- 已认证的 Admin 用户执行的操作。
+- 已认证的 Admin 用户对功能的误用（例如，Admin 用户修改了通过 RBAC 他们"不应该"访问的规则）。
+- Admin 端口或 WebSocket 端点暴露给不受信任的网络。
+- 拥有数据库凭证的攻击者直接访问数据库。
+- 与 ShenYu 一起使用的第三方基础设施（LDAP 服务器、数据库、Kubernetes 集群）中的漏洞。
+
+---
+
+## 参考资料
+
+- [Apache ShenYu 官网](https://shenyu.apache.org/)
+- [安全漏洞报告](https://www.apache.org/security/)
+- [Apache
项目成熟度模型](https://community.apache.org/apache-way/apache-project-maturity-model.html)
diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.7.1.json
b/i18n/zh/docusaurus-plugin-content-docs/version-2.7.1.json
index 636a972a6ff..a1cd13f2bfd 100755
--- a/i18n/zh/docusaurus-plugin-content-docs/version-2.7.1.json
+++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.7.1.json
@@ -77,5 +77,9 @@
"description": "ShenYu Benchmark Test"
+ },
+ "sidebar.tutorialSidebar.category.Help": {
+ "message": "帮助",
+ "description": "The label for category 'Help' in sidebar 'tutorialSidebar'"
}
}
diff --git
a/i18n/zh/docusaurus-plugin-content-docs/version-2.7.1/help/_category_.json
b/i18n/zh/docusaurus-plugin-content-docs/version-2.7.1/help/_category_.json
new file mode 100644
index 00000000000..670a29a17ea
--- /dev/null
+++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.7.1/help/_category_.json
@@ -0,0 +1,4 @@
+{
+ "label": "帮助",
+ "position": 9
+}
diff --git
a/i18n/zh/docusaurus-plugin-content-docs/version-2.7.1/help/security-model/_category_.json
b/i18n/zh/docusaurus-plugin-content-docs/version-2.7.1/help/security-model/_category_.json
new file mode 100644
index 00000000000..bd7a9f33c2c
--- /dev/null
+++
b/i18n/zh/docusaurus-plugin-content-docs/version-2.7.1/help/security-model/_category_.json
@@ -0,0 +1,4 @@
+{
+ "label": "安全模型",
+ "position": 1
+}
diff --git
a/i18n/zh/docusaurus-plugin-content-docs/version-2.7.1/help/security-model/security-model.md
b/i18n/zh/docusaurus-plugin-content-docs/version-2.7.1/help/security-model/security-model.md
new file mode 100644
index 00000000000..3b4660dd64e
--- /dev/null
+++
b/i18n/zh/docusaurus-plugin-content-docs/version-2.7.1/help/security-model/security-model.md
@@ -0,0 +1,130 @@
+---
+title: 安全模型
+keywords: ["安全模型", "信任边界", "漏洞范围"]
+description: Apache ShenYu 安全模型，定义信任边界、部署控制和漏洞范围
+---
+
+# Apache ShenYu 安全模型
+
+本文档定义了 Apache ShenYu 的安全模型和信任边界，适用于：
+
+- **运维人员**：了解所需的部署控制措施和安全假设。
+- **安全研究人员**：判断某个报告的行为是否在 ShenYu 的预期信任边界内。
+- **ASF 安全团队**：根据本模型对收到的漏洞报告进行分诊。
+
+违反本模型的行为报告属于有效范围。假设了本模型明确排除的边界的行为报告则不在范围内。
+
+---
+
+## 1. 部署边界
+
+**Admin 服务（shenyu-admin）设计用于在受信任的内部网络中运行。**
+
+Admin 端口（默认：`9095`）**不得**暴露到公共互联网。Admin 服务默认绑定到
`0.0.0.0`，是为了方便容器化和内部网络部署；这并不意味着它对外部暴露是安全的。
+
+运维人员负责：
+
+- 将 Admin 服务放置于防火墙或私有 VPC 之后。
+- 使用网络级访问控制（安全组、入站规则、VPN）限制对 Admin 端口的访问。
+- 在生产环境中，可选择将 Admin 服务器绑定到特定的内部地址。
+
+将 Admin 端口暴露到公共互联网是部署配置错误，而非 ShenYu 的漏洞。
+
+## 2. 认证边界
+
+**所有已认证的 Admin 用户都是完全受信任的。账号管理是安全边界。**
+
+Admin 服务使用 Apache Shiro 进行认证。一旦用户通过认证（通过用户名/密码、LDAP 或其他配置的机制），他们就被视为 ShenYu
部署的受信任操作者。
+
+安全边界在于：
+
+- **账号创建和凭证管理** — 只有授权人员才能创建 Admin 账号。
+- **凭证存储** — ShenYu 存储的密码和密钥（例如在数据库中）必须受到保护。
+
+已认证的 Admin 用户（包括任何拥有有效登录凭据的用户）执行的操作不属于安全漏洞。如果攻击者能够认证，则部署已经被攻破。
+
+## 3. RBAC 模型
+
+**`@RequiresPermissions` 控制的是 UI 功能的可见性，而非已认证 Admin 用户之间的安全隔离。**
+
+ShenYu 使用 Apache Shiro
注解（`@RequiresPermissions`）实现了基于角色的访问控制（RBAC）系统。该系统的设计目标是：
+
+- 简化 Admin 界面，仅向每个用户展示与其角色相关的功能。
+- 通过限制哪些用户可以修改特定资源（插件、规则、选择器等），防止意外误配置。
+
+ShenYu 中的 RBAC **不是**硬安全边界。它**不能**防护：
+
+- 恶意的已认证用户故意提升权限。
+- 用户通过 Admin UI 以外的方式发现或调用未被分配的 API 端点。
+- 同一部署的 Admin 用户之间的跨租户隔离。
+
+**所有已认证的 Admin 用户共享同一信任域。** 如果需要操作者之间的严格隔离，请部署独立的 ShenYu Admin 实例。
+
+## 4. WebSocket 同步通道
+
+**`/websocket` 端点是有意不进行认证的，必须通过网络级访问控制来保护。**
+
+Admin 服务在 `/websocket` 暴露一个 WebSocket 端点，供
Gateway（bootstrap）实例接收实时配置更新。该端点被明确排除在 Shiro 认证之外（参见 `application.yml` 中的
`shenyu.shiro.white-list`）。
+
+由于 Gateway 必须连接到此端点以同步插件、选择器和规则数据，WebSocket 通道在应用层没有认证机制。此通道的安全性完全取决于：
+
+- **网络隔离**：`/websocket` 端点只能被受信任内部网络中的 Gateway 实例访问。
+- **防火墙规则**：阻止外部访问 Admin 端口，同时也就保护了 WebSocket 端点。
+
+任何能够访问 `/websocket` 端点的人都可以接收 Gateway
的完整配置状态，包括插件规则、上游服务地址和认证密钥。这是有意为之：在受信任网络内，Gateway 是这些数据的合法消费者。
+
+## 5. 控制面与数据面
+
+**Admin（控制面）和 Gateway（数据面）属于不同的信任域。**
+
+| 组件 | 角色 | 信任级别 |
+|---|---|---|
+| shenyu-admin | 控制面 — 管理配置、插件、规则、元数据 | 仅限受信任的内部网络 |
+| shenyu-bootstrap | 数据面 — 处理实时流量路由、限流、认证 | 对流量暴露（面向互联网或 DMZ） |
+
+关键含义：
+
+- Gateway **不会**隐式信任 Admin 来做运行时的流量决策。Gateway 会针对入站请求执行自己的认证、限流和路由规则。
+- Admin 被攻破**不会**直接危及流经 Gateway 的流量，但会允许攻击者修改 Gateway 的配置（添加/删除插件、修改路由规则等）。
+- Gateway 被攻破**不会**授予对 Admin 或其数据库的访问权限。
+- WebSocket 同步通道（`/websocket`）是这两个信任域之间的桥梁，必须按照第 4 节所述进行保护。
+
+## 6. 数据库安全
+
+**数据库是受信任的基础设施。数据库被攻破是一个独立的安全事件，不在 ShenYu 的软件威胁模型范围内。**
+
+ShenYu 将配置、用户凭证、插件数据和元数据存储在数据库中（开发环境使用 H2，生产环境使用 MySQL/PostgreSQL）。
+
+ShenYu 假设：
+
+- 数据库部署在安全环境中，具有独立于 ShenYu 的访问控制。
+- ShenYu 使用的数据库凭证受到保护且不对外暴露。
+- 数据库网络端口不暴露给不受信任的网络。
+
+如果攻击者获得对数据库的直接访问权限（例如通过其他应用程序的 SQL 注入、凭证泄露或网络配置错误），他们可以读取或修改所有 ShenYu
状态。这是基础设施层面的安全事件，而非 ShenYu 应用程序逻辑中的漏洞。
+
+## 7. 范围总结
+
+**在范围内**（请报告至 [[email protected]](mailto:[email protected])）：
+
+- 未经认证的远程代码执行。
+- 允许无需有效凭证即可访问的认证绕过。
+- Gateway（bootstrap）请求处理漏洞，可通过构造的 HTTP 流量利用。
+- 允许绕过 Gateway 强制执行的认证或限流的插件级漏洞。
+- 通过未经认证的 Gateway 请求路径可到达的注入攻击（SQL、命令、模板）。
+
+**不在范围内**（部署或基础设施问题）：
+
+- 已认证的 Admin 用户执行的操作。
+- 已认证的 Admin 用户对功能的误用（例如，Admin 用户修改了通过 RBAC 他们"不应该"访问的规则）。
+- Admin 端口或 WebSocket 端点暴露给不受信任的网络。
+- 拥有数据库凭证的攻击者直接访问数据库。
+- 与 ShenYu 一起使用的第三方基础设施（LDAP 服务器、数据库、Kubernetes 集群）中的漏洞。
+
+---
+
+## 参考资料
+
+- [Apache ShenYu 官网](https://shenyu.apache.org/)
+- [安全漏洞报告](https://www.apache.org/security/)
+- [Apache
项目成熟度模型](https://community.apache.org/apache-way/apache-project-maturity-model.html)
diff --git a/versioned_docs/version-2.7.1/help/_category_.json
b/versioned_docs/version-2.7.1/help/_category_.json
new file mode 100644
index 00000000000..55f1ed2f29b
--- /dev/null
+++ b/versioned_docs/version-2.7.1/help/_category_.json
@@ -0,0 +1,4 @@
+{
+ "label": "Help",
+ "position": 9
+}
diff --git a/versioned_docs/version-2.7.1/help/security-model/_category_.json
b/versioned_docs/version-2.7.1/help/security-model/_category_.json
new file mode 100644
index 00000000000..51a7517afe5
--- /dev/null
+++ b/versioned_docs/version-2.7.1/help/security-model/_category_.json
@@ -0,0 +1,4 @@
+{
+ "label": "Security Model",
+ "position": 1
+}
diff --git a/versioned_docs/version-2.7.1/help/security-model/security-model.md
b/versioned_docs/version-2.7.1/help/security-model/security-model.md
new file mode 100644
index 00000000000..2c15ebb8550
--- /dev/null
+++ b/versioned_docs/version-2.7.1/help/security-model/security-model.md
@@ -0,0 +1,130 @@
+---
+title: Security Model
+keywords: ["Security Model", "Trust Boundaries", "Vulnerability Scope"]
+description: Apache ShenYu security model defining trust boundaries,
deployment controls, and vulnerability scope
+---
+
+# Apache ShenYu Security Model
+
+This document defines the security model and trust boundaries of Apache
ShenYu. It is intended for:
+
+- **Operators**: understand required deployment controls and security
assumptions.
+- **Security researchers**: determine whether a reported behavior falls within
ShenYu's intended trust boundaries.
+- **ASF Security team**: triage incoming vulnerability reports against this
model.
+
+Reports about behavior that violates this model are in scope. Reports about
behavior that assumes a boundary explicitly excluded by this model are out of
scope.
+
+---
+
+## 1. Deployment Boundary
+
+**The Admin service (shenyu-admin) is designed to operate within a trusted
internal network.**
+
+The Admin port (default: `9095`) must **not** be exposed to the public
internet. The Admin service binds to `0.0.0.0` by default for convenience in
containerized and internal-network deployments; this is not an indication that
it is safe for external exposure.
+
+Operators are responsible for:
+
+- Placing the Admin service behind a firewall or private VPC.
+- Using network-level access controls (security groups, ingress rules, VPN) to
restrict access to the Admin port.
+- Optionally binding the Admin server to a specific internal address in
production.
+
+Exposing the Admin port to the public internet is a deployment
misconfiguration, not a vulnerability in ShenYu.
+
+## 2. Authentication Boundary
+
+**All authenticated Admin users are fully trusted. Account provisioning is the
security boundary.**
+
+The Admin service uses Apache Shiro for authentication. Once a user is
authenticated (via username/password, LDAP, or other configured mechanisms),
they are considered a trusted operator of the ShenYu deployment.
+
+The security boundary is:
+
+- **Account creation and credential management** — only authorized personnel
should be able to provision Admin accounts.
+- **Credential storage** — passwords and secrets stored by ShenYu (e.g., in
the database) must be protected.
+
+Actions performed by an authenticated Admin user (including any user with a
valid login) are not security vulnerabilities. If an attacker can authenticate,
the deployment is already compromised.
+
+## 3. RBAC Model
+
+**`@RequiresPermissions` controls UI feature visibility, not security
isolation between authenticated Admin users.**
+
+ShenYu implements a role-based access control (RBAC) system using Apache Shiro
annotations (`@RequiresPermissions`). This system is designed to:
+
+- Simplify the Admin UI by showing each user only the features relevant to
their role.
+- Prevent accidental misconfiguration by limiting which users can modify
specific resources (plugins, rules, selectors, etc.).
+
+RBAC in ShenYu is **not** a hard security boundary. It does **not** protect
against:
+
+- A malicious authenticated user intentionally escalating privileges.
+- A user discovering or invoking API endpoints they are not assigned to
through means other than the Admin UI.
+- Cross-tenant isolation between Admin users of the same deployment.
+
+**All authenticated Admin users share the same trust domain.** If you require
strict isolation between operators, deploy separate ShenYu Admin instances.
+
+## 4. WebSocket Sync Channel
+
+**The `/websocket` endpoint is intentionally unauthenticated and must be
protected by network-level access controls.**
+
+The Admin service exposes a WebSocket endpoint at `/websocket` for Gateway
(bootstrap) instances to receive real-time configuration updates. This endpoint
is explicitly excluded from Shiro authentication (see `shenyu.shiro.white-list`
in `application.yml`).
+
+Because the Gateway must connect to this endpoint to synchronize plugin,
selector, and rule data, the WebSocket channel operates without authentication
at the application layer. The security of this channel depends entirely on:
+
+- **Network isolation**: the `/websocket` endpoint must only be reachable by
Gateway instances within the trusted internal network.
+- **Firewall rules**: block external access to the Admin port, which also
protects the WebSocket endpoint.
+
+Anyone who can reach the `/websocket` endpoint can receive the full
configuration state of the Gateway, including plugin rules, upstream service
addresses, and authentication keys. This is by design: within the trusted
network, the Gateway is a legitimate consumer of this data.
+
+## 5. Control Plane vs. Data Plane
+
+**Admin (control plane) and Gateway (data plane) are separate trust domains.**
+
+| Component | Role | Trust Level |
+|---|---|---|
+| shenyu-admin | Control plane — manages configuration, plugins, rules,
metadata | Trusted internal only |
+| shenyu-bootstrap | Data plane — handles live traffic routing, rate limiting,
auth | Exposed to traffic (internet-facing or DMZ) |
+
+Key implications:
+
+- The Gateway does **not** trust the Admin implicitly for runtime traffic
decisions. The Gateway enforces its own authentication, rate limiting, and
routing rules against incoming requests.
+- Compromise of the Admin does **not** directly compromise traffic flowing
through the Gateway, but it does allow an attacker to modify Gateway
configuration (add/remove plugins, modify routing rules, etc.).
+- Compromise of the Gateway does **not** grant access to the Admin or its
database.
+- The WebSocket sync channel (`/websocket`) is the bridge between these trust
domains and must be protected as described in Section 4.
+
+## 6. Database Security
+
+**The database is trusted infrastructure. Database compromise is an
independent security event outside ShenYu's software threat model.**
+
+ShenYu stores configuration, user credentials, plugin data, and metadata in a
database (H2 for development, MySQL/PostgreSQL for production).
+
+ShenYu assumes:
+
+- The database is deployed in a secured environment with access controls
independent of ShenYu.
+- Database credentials used by ShenYu are protected and not exposed.
+- The database network port is not exposed to untrusted networks.
+
+If an attacker gains direct access to the database (e.g., via SQL injection in
a separate application, stolen credentials, or network misconfiguration), they
can read or modify all ShenYu state. This is an infrastructure-level
compromise, not a vulnerability in ShenYu's application logic.
+
+## 7. Scope Summary
+
+**In scope** (report to [[email protected]](mailto:[email protected])):
+
+- Unauthenticated remote code execution.
+- Authentication bypass allowing access without valid credentials.
+- Gateway (bootstrap) request-handling vulnerabilities exploitable through
crafted HTTP traffic.
+- Plugin-level vulnerabilities that allow bypassing Gateway-enforced
authentication or rate limiting.
+- Injection attacks (SQL, command, template) reachable through unauthenticated
Gateway request paths.
+
+**Out of scope** (deployment or infrastructure concerns):
+
+- Actions performed by an authenticated Admin user.
+- Misuse of features by an authenticated Admin user (e.g., an Admin user
modifying rules they are not "supposed" to access via RBAC).
+- Exposure of the Admin port or WebSocket endpoint to untrusted networks.
+- Direct database access by an attacker with database credentials.
+- Vulnerabilities in third-party infrastructure (LDAP servers, databases,
Kubernetes clusters) used alongside ShenYu.
+
+---
+
+## References
+
+- [Apache ShenYu Website](https://shenyu.apache.org/)
+- [Security Vulnerability Reporting](https://www.apache.org/security/)
+- [Apache Project Maturity
Model](https://community.apache.org/apache-way/apache-project-maturity-model.html)
