This is an automated email from the ASF dual-hosted git repository.
vgalaxies pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/hugegraph-doc.git
The following commit(s) were added to refs/heads/master by this push:
new ecc56229 docs(sec): enhance security warnings for gremlin execution
(#457)
ecc56229 is described below
commit ecc562291dd406bb900eacf711baba33924dc564
Author: imbajin <[email protected]>
AuthorDate: Fri Apr 17 09:48:13 2026 +0800
docs(sec): enhance security warnings for gremlin execution (#457)
Co-authored-by: Copilot <[email protected]>
---
content/cn/docs/clients/restful-api/gremlin.md | 5 +++++
content/cn/docs/config/config-authentication.md | 7 +++++--
content/cn/docs/guides/security.md | 8 ++++++++
content/cn/docs/quickstart/hugegraph/hugegraph-server.md | 2 +-
content/cn/docs/quickstart/toolchain/hugegraph-hubble.md | 2 ++
content/en/docs/clients/restful-api/gremlin.md | 5 +++++
content/en/docs/config/config-authentication.md | 8 +++++---
content/en/docs/guides/security.md | 8 ++++++++
content/en/docs/quickstart/hugegraph/hugegraph-server.md | 2 +-
content/en/docs/quickstart/toolchain/hugegraph-hubble.md | 2 ++
content/en/docs/quickstart/toolchain/hugegraph-tools.md | 2 ++
11 files changed, 44 insertions(+), 7 deletions(-)
diff --git a/content/cn/docs/clients/restful-api/gremlin.md
b/content/cn/docs/clients/restful-api/gremlin.md
index ab22c1cf..52642f56 100644
--- a/content/cn/docs/clients/restful-api/gremlin.md
+++ b/content/cn/docs/clients/restful-api/gremlin.md
@@ -7,6 +7,11 @@ description: "Gremlin（图查询语言）REST 接口:通过 HTTP 接口执行 G
### 8.1 Gremlin
+> ⚠️ **SEC 提醒：生产环境下安全使用原生查询接口**
+>
+> 图查询语言 (如 Gremlin/Cypher)
本身的灵活性会带来一些潜在的安全隐患。为了保障核心安全，**请避免直接在公网环境暴露任何相关的原生查询接口**。
+> 在必须对内暴露的生产场景中，必须开启 **[鉴权体系 (Auth)](/cn/docs/config/config-authentication/)**
并结合 **IP 白名单**作为双重保障机制，严格控制用户执行权限。同时建议结合 Audit Log (审计日志) 来审计具体执行的语句，以及采用
**[容器环境
(Docker/K8s)](/cn/docs/quickstart/hugegraph/hugegraph-server/#31-使用-docker-容器-便于测试)**
部署以提升系统级的安全隔离。
+
#### 8.1.1 向 HugeGraphServer 发送 gremlin 语句（GET），同步执行
##### Params
diff --git a/content/cn/docs/config/config-authentication.md
b/content/cn/docs/config/config-authentication.md
index fef92032..f5e33c7f 100644
--- a/content/cn/docs/config/config-authentication.md
+++ b/content/cn/docs/config/config-authentication.md
@@ -24,8 +24,11 @@ user(name=xx) -belong-> group(name=xx) -access(read)->
target(graph=graph1, reso
### 配置用户认证
-HugeGraph 目前默认**未启用**用户认证功能，需通过修改配置文件来启用该功能。(Note: 如果在生产环境/外网使用,
-请使用 **Java11** 版本 + 开启权限避免安全相关隐患)
+HugeGraph 目前默认**未启用**用户认证功能，需通过修改配置文件来启用该功能。
+
+> ⚠️ **SEC 提醒：图查询语言 (Gremlin/Cypher) 的安全性**
+>
+> 出于图查询语言的灵活性可能带来的潜在系统安全隐患，**请避免直接在公网/外网环境暴露任何查询相关接口**。在实际生产部署时，请以此处的
**[鉴权认证体系](/cn/docs/config/config-authentication/)** 结合 **IP 白名单**
为安全双重保障机制，同时建议开启 Audit Log (审计日志) 以精准定位用户执行的具体查询语句。鉴于 Server 的无状态特性，整体架构上强烈推荐采用
**[容器化环境
(Docker/K8s)](/cn/docs/quickstart/hugegraph/hugegraph-server/#31-使用-docker-容器-便于测试)**
部署，以极低成本有效隔离底层系统的安全风险。
目前已内置实现了`StandardAuthenticator`模式，该模式支持多用户认证与细粒度权限控制。此外，开发者可以自定义实现`HugeAuthenticator`接口来对接自身的权限系统。
diff --git a/content/cn/docs/guides/security.md
b/content/cn/docs/guides/security.md
index 9a0a77dc..9c25ae8e 100644
--- a/content/cn/docs/guides/security.md
+++ b/content/cn/docs/guides/security.md
@@ -6,6 +6,14 @@ weight: 7
## 报告 Apache HugeGraph 的安全问题
+> ⚠️ **SEC 提醒：致漏洞研究人员关于图查询语言的说明**
+>
+> 鉴于图查询语言 (如 Gremlin/Cypher) 本身在解析与执行上的灵活性，HugeGraph 推荐在生产环境依赖 **"[Auth
(配置鉴权)](/cn/docs/config/config-authentication/) + IP 白名单 + Audit Log (审计日志)"**
机制来践行最小权限原则。同时由于 Server 节点基本是无状态的，**所有生产环境均明确建议使用[容器环境
(Docker/K8s)](/cn/docs/quickstart/hugegraph/hugegraph-server/#31-使用-docker-容器-便于测试)
进行隔离部署**。
+>
+> 近期社区已收到较多关于图查询语言灵活性的安全反馈。在 HugeGraph 安全体系整体重构完成前，对于在**不启用或跳过 Auth
系统/避开授权身份**的前提下执行 DSL 查询的情况，此类已知风险将**不再单独视为新漏洞**进行处理。
+>
+> 但是，如果在**已开启 Auth 系统**的环境中，仍能以**匿名或未授权身份访问**并进行漏洞利用，或者成功**绕过 IP 白名单 /
逃逸容器**造成严重越权或底层系统破坏，我们仍然将其视为高危安全漏洞，非常欢迎您随时向我们反馈！
+
遵循 ASF 的规范，HugeGraph 社区对**解决修复**项目中的安全问题保持非常积极和开放的态度。
我们强烈建议用户首先向我们的独立安全邮件列表报告此类问题，相关详细的流程规范请参考 [ASF
SEC](https://www.apache.org/security/committers.html) 守则。
diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md
b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md
index 8ecc4a08..2be45ba4 100644
--- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md
+++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md
@@ -34,7 +34,7 @@ Core 模块是 Tinkerpop 接口的实现，Backend 模块用于管理数据存
- 方式 3：源码编译
- 方式 4：使用 tools 工具部署 (Outdated)
-**注意**：生产环境或对公网暴露的环境必须使用 Java 11，并开启 [Auth
权限认证](/cn/docs/config/config-authentication/)，否则存在安全风险。
+> ⚠️ **SEC 提醒**：由于图查询语言 (如 Gremlin/Cypher)
的高度灵活性，直接暴露原生查询接口会带来潜在的安全隐患，因此**请避免直接在公网环境中暴露任何查询相关接口**。生产环境中务必开启 **[鉴权体系
(Auth)](/cn/docs/config/config-authentication/)** 配合 **IP 白名单** 构成双重保障机制，同时建议辅以
Audit Log (审计日志) 追踪具体查询语句。推荐整体采用 **[容器化环境
(Docker/K8s)](#31-使用-docker-容器-便于测试)** 进行部署以获得更好的系统级安全隔离。
#### 3.1 使用 Docker 容器 (便于**测试**)
<!-- 3.1 is linked by another place. if change 3.1's title, please check -->
diff --git a/content/cn/docs/quickstart/toolchain/hugegraph-hubble.md
b/content/cn/docs/quickstart/toolchain/hugegraph-hubble.md
index 51adbc0b..add0f97d 100644
--- a/content/cn/docs/quickstart/toolchain/hugegraph-hubble.md
+++ b/content/cn/docs/quickstart/toolchain/hugegraph-hubble.md
@@ -402,6 +402,8 @@ HugeGraph 支持 Apache TinkerPop3 的图遍历查询语言 Gremlin，Gremlin
Gremlin 查询后，下方为图结果展示区域，提供 3 种图结果展示方式，分别为：【图模式】、【表格模式】、【Json 模式】。
+> ⚠️ **SEC 提醒**：Hubble 允许在网页端直接输入并执行 Gremlin 原生查询语句，这赋予了使用者较高的操作权限。**请避免将
Hubble 服务暴露在公网环境**，建议在使用时确保图数据库服务端已开启 **[鉴权体系
(Auth)](/cn/docs/config/config-authentication/)** 并配合 **IP
白名单**进行严格的权限控制，防止未授权访问或恶意代码执行风险。
+
支持缩放、居中、全屏、导出等操作。
【图模式】
diff --git a/content/en/docs/clients/restful-api/gremlin.md
b/content/en/docs/clients/restful-api/gremlin.md
index ccd72686..3b348e7c 100644
--- a/content/en/docs/clients/restful-api/gremlin.md
+++ b/content/en/docs/clients/restful-api/gremlin.md
@@ -7,6 +7,11 @@ description: "Gremlin REST API: Execute Gremlin graph
traversal language scripts
### 8.1 Gremlin
+> ⚠️ **SEC Reminder: Safe Usage of Native Query Endpoints in Production
Environments**
+>
+> The flexibility of Graph Query Languages (such as Gremlin/Cypher) inherently
introduces certain potential security risks. To ensure core security, **please
avoid exposing any related native query endpoints directly to the public
network**.
+> In production scenarios where internal exposure is required, you must enable
the **[Authentication System (Auth)](/docs/config/config-authentication/)**
combined with an **IP Whitelist** as a dual-security mechanism to strictly
control user execution permissions. Additionally, it is advised to use an Audit
Log to audit the specific statements executed and to adopt **[Containerized
Deployment
(Docker/K8s)](/docs/quickstart/hugegraph/hugegraph-server/#31-use-docker-container-convenient-f
[...]
+
#### 8.1.1 Sending a gremlin statement (GET) to HugeGraphServer for
synchronous execution
##### Params
diff --git a/content/en/docs/config/config-authentication.md
b/content/en/docs/config/config-authentication.md
index e00c8a41..eb01cf94 100644
--- a/content/en/docs/config/config-authentication.md
+++ b/content/en/docs/config/config-authentication.md
@@ -24,9 +24,11 @@ user(name=xx) -belong-> group(name=xx) -access(read)->
target(graph=graph1, reso
### Configure User Authentication
-By default, HugeGraph does **not enable** user authentication, and it needs to
be enabled by
-modifying the configuration file (Note: If used in a production environment or
over the internet,
-please use a **Java11** version and enable **auth-system** to avoid security
risks.)
+By default, HugeGraph does **not enable** user authentication, and it needs to
be enabled by modifying the configuration file.
+
+> ⚠️ **SEC Reminder: Security of Graph Query Languages (Gremlin/Cypher)**
+>
+> Due to potential system security risks brought about by the flexibility of
graph query languages, **please avoid exposing any query-related endpoints
directly to public/external network environments**. In actual production
deployments, please use the **[Authentication
System](/docs/config/config-authentication/)** outlined here combined with an
**IP Whitelist** as a dual-security mechanism, and we recommend enabling Audit
Logs to pinpoint the exact queries executed by users. Given the [...]
You need to modify the configuration file to enable this feature. HugeGraph
provides built-in authentication mode: `StandardAuthenticator`. This mode
supports multi-user authentication and fine-grained permission control.
Additionally, developers can implement their own `HugeAuthenticator` interface
to integrate with their existing authentication systems.
diff --git a/content/en/docs/guides/security.md
b/content/en/docs/guides/security.md
index 4ce21102..b4852b90 100644
--- a/content/en/docs/guides/security.md
+++ b/content/en/docs/guides/security.md
@@ -6,6 +6,14 @@ weight: 7
## Reporting New Security Problems with Apache HugeGraph
+> ⚠️ **SEC Reminder: Notice to Vulnerability Researchers Regarding Graph Query
Languages**
+>
+> Given the inherent parsing and execution flexibility of graph query
languages (like Gremlin/Cypher), HugeGraph strongly recommends relying on the
**"[Auth (Authentication)](/docs/config/config-authentication/) + IP Whitelist
+ Audit Log"** mechanism in production environments to adhere to the Principle
of Least Privilege. Furthermore, since Server nodes are essentially stateless,
**it is explicitly advised to use [Containerized Environments
(Docker/K8s)](/docs/quickstart/hugegraph/huge [...]
+>
+> Recently, the community has received numerous security reports concerning
the flexibility of graph queries. Until the overall HugeGraph security
architecture is fully refactored, known situations involving the execution of
DSL queries with **Auth disabled or skipped, or by using an anonymous or
unauthorized identity** will **no longer be treated individually as new
vulnerabilities**.
+>
+> However, if a vulnerability can still be exploited in an environment where
the **Auth system is enabled** by accessing it with an **anonymous or
unauthorized identity**, or if one successfully **bypasses the IP whitelist /
escapes the container** causing severe unauthorized access or underlying system
destruction, we still consider this a high-risk security vulnerability and
highly encourage you to report it to us at any time!
+
Adhering to the specifications of ASF, the HugeGraph community maintains a
highly proactive and open attitude towards addressing security issues in the
**remediation** projects.
We strongly recommend that users first report such issues to our dedicated
security email list, with detailed procedures specified in the [ASF
SEC](https://www.apache.org/security/committers.html) code of conduct.
diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md
b/content/en/docs/quickstart/hugegraph/hugegraph-server.md
index 84469f08..4197acbb 100644
--- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md
+++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md
@@ -33,7 +33,7 @@ There are four ways to deploy HugeGraph-Server components:
- Method 3: Source code compilation
- Method 4: One-click deployment
-**Note:** For production environments or environments exposed to the public
network, you must use Java 11 and enable [Auth
authentication](/docs/config/config-authentication/) to avoid security risks.
+> ⚠️ **SEC Reminder**: Due to the high flexibility of graph query languages
(like Gremlin/Cypher), exposing native query endpoints directly presents
potential security risks. Therefore, **please avoid exposing any query-related
endpoints directly in public network environments**. In production
environments, it is imperative to enable the **[Authentication System
(Auth)](/docs/config/config-authentication/)** combined with an **IP
Whitelist** to establish a dual assurance mechanism, along [...]
#### 3.1 Use Docker container (Convenient for Test/Dev)
diff --git a/content/en/docs/quickstart/toolchain/hugegraph-hubble.md
b/content/en/docs/quickstart/toolchain/hugegraph-hubble.md
index 2746ea77..8d04d5e9 100644
--- a/content/en/docs/quickstart/toolchain/hugegraph-hubble.md
+++ b/content/en/docs/quickstart/toolchain/hugegraph-hubble.md
@@ -409,6 +409,8 @@ HugeGraph supports Gremlin, a graph traversal query
language of Apache TinkerPop
After Gremlin query, below is the graph result display area, which provides 3
kinds of graph result display modes: [Graph Mode], [Table Mode], [Json Mode].
+> ⚠️ **SEC Reminder**: Hubble allows the direct input and execution of native
Gremlin query statements on the web interface, which grants users relatively
high operational privileges. **Please avoid exposing the Hubble service to
public network environments**. It is recommended to ensure that the graph
database server has enabled the **[Authentication System
(Auth)](/docs/config/config-authentication/)** combined with an **IP
Whitelist** for strict permission control when in use, prevent [...]
+
Support zoom, center, full screen, export and other operations.
【Picture Mode】
diff --git a/content/en/docs/quickstart/toolchain/hugegraph-tools.md
b/content/en/docs/quickstart/toolchain/hugegraph-tools.md
index 3ebb3543..cd6deda0 100644
--- a/content/en/docs/quickstart/toolchain/hugegraph-tools.md
+++ b/content/en/docs/quickstart/toolchain/hugegraph-tools.md
@@ -142,6 +142,8 @@ Another way is to set the environment variable in the
bin/hugegraph script:
##### 3.5 Gremlin Type，gremlin-execute and gremlin-schedule
+> ⚠️ **SEC Reminder**: The execution of Gremlin depends on the actual logic of
the statements, which may involve scenarios such as large-scale data
modification and high-risk system calls with potential implicit hazards. Please
use this tool **only in secure and trusted network environments**. It is
imperative to configure and secure **HugeGraph-Server** with the
**[Authentication System (Auth)](/docs/config/config-authentication/)** and an
**IP Whitelist** to restrict execution requests [...]
+
- gremlin-execute, send Gremlin statements to HugeGraph-Server to execute
query or modification operations, execute synchronously, and return results
after completion
- --file or -f, specify the script file to execute, UTF-8 encoding, mutually
exclusive with --script
- --script or -s, specifies the script string to execute, mutually exclusive
with --file
