From f30a9de01da9094265667da2a1fbfc7df5036677 Mon Sep 17 00:00:00 2001
From: RuoJi6 <79234113+RuoJi6@users.noreply.github.com>
Date: Mon, 17 Aug 2026 15:50:32 +0800
Subject: [PATCH] feat(hitl): expand safe read-only tool allowlist (#258)

---
 config.example.yaml               |  2 +-
 docs/en-US/hitl-best-practices.md | 12 ++++++++++--
 docs/zh-CN/hitl-best-practices.md | 12 ++++++++++--
 3 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/config.example.yaml b/config.example.yaml
index 787fa01f..eb67d4f1 100644
--- a/config.example.yaml
+++ b/config.example.yaml
@@ -146,7 +146,7 @@ hitl:
   # 已决策审计日志保留天数（与 MCP 监控一致；省略默认 90；0 表示不自动清理）
   retention_days: 90
   # 按你环境里的真实工具名增删（与侧栏一致、小写不敏感）；不需要全局免审批可改为 []
-  tool_whitelist: [read_file, list_dir, glob, grep, tool_search, upsert_project_fact, get_project_fact]
+  tool_whitelist: [read_file, ls, list_dir, glob, grep, tool_search, upsert_project_fact, get_project_fact, list_project_facts, search_project_facts, list_vulnerabilities, get_vulnerability, get_asset, query_assets, list_knowledge_risk_types, get_tool_execution, wait_tool_execution, batch_task_list, batch_task_get, asm_list_resources, manage_webshell_list, c2_event, c2_file]
   # audit_agent_prompt: |  # 审批模式；留空使用内置默认，可在「人机协同」页编辑
   # audit_agent_prompt_review_edit: |  # 审查编辑模式；留空使用内置默认
 
diff --git a/docs/en-US/hitl-best-practices.md b/docs/en-US/hitl-best-practices.md
index baf4f18b..39e7f5f6 100644
--- a/docs/en-US/hitl-best-practices.md
+++ b/docs/en-US/hitl-best-practices.md
@@ -25,7 +25,7 @@ hitl:
     api_key: ""
     model: "" # set a small model here; blank reuses the default AI channel model
   retention_days: 90
-  tool_whitelist: [read_file, list_dir, glob, grep, tool_search]
+  tool_whitelist: [read_file, ls, glob, grep, tool_search, get_project_fact, list_project_facts, search_project_facts, list_vulnerabilities, get_vulnerability, get_asset, query_assets, list_knowledge_risk_types, get_tool_execution, wait_tool_execution, batch_task_list, batch_task_get, asm_list_resources, manage_webshell_list, c2_event, c2_file]
 ```
 
 `audit_model` supports partial configuration. Empty fields inherit from the resolved default AI channel, so the common setup is to fill only `model` and run approvals on a cheaper small model.
@@ -91,10 +91,16 @@ In review-edit mode, you may narrow paths, targets, or command arguments before
 Allowlisted tools skip approval, so keep the list stable and low-risk. Recommended examples:
 
 - `read_file`
-- `list_dir`
+- `ls`
 - `glob`
 - `grep`
 - `tool_search`
+- Project and vulnerability reads: `get_project_fact`, `list_project_facts`, `search_project_facts`, `list_vulnerabilities`, `get_vulnerability`
+- Asset and knowledge-metadata reads: `get_asset`, `query_assets`, `list_knowledge_risk_types`
+- Execution and task-state reads: `get_tool_execution`, `wait_tool_execution`, `batch_task_list`, `batch_task_get`
+- Local management-metadata reads: `asm_list_resources`, `manage_webshell_list`, `c2_event`, `c2_file`
+
+These built-in MCP reads remain constrained by RBAC and resource scope; the allowlist only bypasses HITL approval and does not grant additional access. `list_dir` is effective only when that is the actual tool name; the Eino filesystem directory-listing tool is named `ls`.
 
 Avoid globally allowlisting:
 
@@ -102,6 +108,8 @@ Avoid globally allowlisting:
 - File write/delete tools
 - C2 task tools
 - WebShell command execution tools
+- Nominally read-only tools that send requests to a target or external service, such as `webshell_file_read`, `webshell_file_list`, `search_knowledge_base`, and remote ASM task queries
+- Multiplexed tools whose actions include both reads and writes, such as `c2_session`, `c2_listener`, `c2_profile`, and `c2_task_manage`
 
 ## Mode Selection
 
diff --git a/docs/zh-CN/hitl-best-practices.md b/docs/zh-CN/hitl-best-practices.md
index 90c496ef..763ceabf 100644
--- a/docs/zh-CN/hitl-best-practices.md
+++ b/docs/zh-CN/hitl-best-practices.md
@@ -25,7 +25,7 @@ hitl:
     api_key: ""
     model: "" # 可填小模型；留空复用默认 AI 通道的模型
   retention_days: 90
-  tool_whitelist: [read_file, list_dir, glob, grep, tool_search]
+  tool_whitelist: [read_file, ls, glob, grep, tool_search, get_project_fact, list_project_facts, search_project_facts, list_vulnerabilities, get_vulnerability, get_asset, query_assets, list_knowledge_risk_types, get_tool_execution, wait_tool_execution, batch_task_list, batch_task_get, asm_list_resources, manage_webshell_list, c2_event, c2_file]
 ```
 
 `audit_model` 的字段可以只填一部分。空字段会自动继承默认 AI 通道解析后的模型配置，因此常见做法是只填 `model`，让审计 Agent 使用更便宜的小模型。
@@ -91,10 +91,16 @@ hitl:
 白名单工具会跳过审批，因此要保守维护。推荐放：
 
 - `read_file`
-- `list_dir`
+- `ls`
 - `glob`
 - `grep`
 - `tool_search`
+- 项目与漏洞查询：`get_project_fact`、`list_project_facts`、`search_project_facts`、`list_vulnerabilities`、`get_vulnerability`
+- 资产与知识元数据查询：`get_asset`、`query_assets`、`list_knowledge_risk_types`
+- 执行与任务状态查询：`get_tool_execution`、`wait_tool_execution`、`batch_task_list`、`batch_task_get`
+- 本地管理元数据查询：`asm_list_resources`、`manage_webshell_list`、`c2_event`、`c2_file`
+
+上述内置 MCP 查询仍受 RBAC 和资源范围约束；白名单只跳过 HITL 审批，不扩大访问权限。`list_dir` 仅在实际工具名为该值时有效；Eino 文件系统的目录列表工具名是 `ls`。
 
 不建议直接全局白名单：
 
@@ -102,6 +108,8 @@ hitl:
 - 文件写入/删除工具
 - C2 任务工具
 - WebShell 命令执行工具
+- 会向目标或外部服务发起请求的“只读”工具，例如 `webshell_file_read`、`webshell_file_list`、`search_knowledge_base` 和 ASM 远程任务查询
+- 同一工具名同时包含读写 action 的复合工具，例如 `c2_session`、`c2_listener`、`c2_profile`、`c2_task_manage`
 
 ## 模式选择