flashcatcloud · UlricQin · Sep 5, 2026 · Sep 5, 2026
diff --git a/en/monitors/targets/configure-targets.mdx b/en/monitors/targets/configure-targets.mdx
@@ -8,7 +8,7 @@ The installation package includes a default `agent.yaml`. If you only need to on
 
 ## Basic configuration example
 
-The following configuration is suitable for first-time onboarding:
+The following configuration requires monit-agent `v0.3.0` or later. Upgrade the Agent before adding `unknown_command_policy`; older versions do not recognize this field and fail to load the configuration.
 
 ```yaml
 locator_mappings: {}
@@ -51,6 +51,7 @@ host:
 
   shell_exec:
     enabled: true
+    unknown_command_policy: require_approval
     default_max_lines: 200
     cat_max_file_size: 20971520
     user_allow_list: []
@@ -116,18 +117,40 @@ Recommendations:
 host:
   shell_exec:
     enabled: true
+    unknown_command_policy: require_approval
     default_max_lines: 200
     cat_max_file_size: 20971520
     user_allow_list: []
 ```
 
+### Unknown command policy
+
+`host.shell_exec.unknown_command_policy` determines how commands that do not pass automatic safety rules, but meet the existing syntax and execution requirements, receive authorization. These "unknown commands" can include unrecognized read-only operations as well as operations that modify data or affect services.
+
+| Command category | `require_approval` (default) | `allow` |
+|---|---|---|
+| Known-safe operations | Execute automatically | Execute automatically |
+| Operations that match a permanent-deny rule | Reject | Reject |
+| Unknown operations | Execute after local root approval | Execute directly, without an approval session |
+
+Omitting the field or setting it to an empty string uses `require_approval`, preserving the existing approval behavior. The only valid values are `require_approval` and `allow`. Incorrect capitalization or spelling fails configuration validation.
+
+You can set this policy only in the Agent's local `agent.yaml`, not through the console or tool call parameters. It affects only `shell.exec`; it does not grant write access to database or middleware diagnostic tools, or override `enabled: false` or `disabled_tools`.
+
+<Warning>
+Setting the policy to `allow` authorizes unknown commands to execute directly with the permissions of the account running the Agent. This includes `docker exec` and `kubectl exec`, which previously required approval. Their actual access depends on that account's container runtime permissions and Kubernetes credentials.
+
+Unknown commands can modify or delete data, access sensitive information, affect services, or invoke other programs. A compromised control plane can also use these capabilities. The Agent still enforces permanent-deny rules, syntax checks, timeouts, and output limits, but these rules cannot identify every indirect dangerous behavior of an unknown program.
+</Warning>
+
 Recommendations:
 
-- Keep `enabled: true` when AI-SRE needs live host diagnostics. Only controlled shell commands can be executed.
-- If a command is occasionally blocked, local root can [approve that command](/en/monitors/targets/install-agent#approve-a-blocked-shell-command).
+- Set `enabled: true` when AI-SRE needs live host diagnostics, and keep the default `require_approval` policy.
+- When you need to confirm unknown commands individually, have local root [approve each command](/en/monitors/targets/install-agent#approve-a-blocked-shell-command).
 - For a command that needs to run repeatedly, add the complete command to `user_allow_list` only after confirming that it is safe, read-only, and does not expose sensitive information.
+- Choose `allow` only if you accept the risks of executing unknown commands directly. It does not restrict write operations to a separate allowlist.
 
-Neither human approval nor `user_allow_list` can allow high-risk operations such as shutdown, reboot, system destruction, or reading sensitive credentials.
+Commands that match permanent-deny rules cannot be enabled through human approval, `user_allow_list`, or `allow`.
 
 To urgently disable a tool, use `tool_policy.disabled_tools`:
 
@@ -137,7 +160,7 @@ tool_policy:
     - shell.exec
 ```
 
-After changing `shell_exec.enabled` or `tool_policy.disabled_tools`, send SIGHUP to reload the configuration. The change takes effect without restarting the Agent.
+After changing `shell_exec.enabled`, `shell_exec.unknown_command_policy`, or `tool_policy.disabled_tools`, send SIGHUP to reload the configuration without restarting the Agent. Policy changes apply to new calls; commands already running or awaiting approval retain their original behavior. See [Reload configuration and verify onboarding](/en/monitors/targets/reload-and-verify#change-the-unknown-command-policy).
 
 ## MySQL
 

diff --git a/en/monitors/targets/install-agent.mdx b/en/monitors/targets/install-agent.mdx
@@ -12,7 +12,7 @@ Prepare the following information before installation:
 
 | Item | Description |
 |---|---|
-| Agent package download URL | `https://static.flashcat.cloud/monitagent/monitagent-v0.1.6-linux-amd64.tar.gz`. For ARM CPUs, replace `amd64` with `arm64`. |
+| Agent package download URL | `https://static.flashcat.cloud/monitagent/monitagent-v0.3.0-linux-amd64.tar.gz`. For ARM CPUs, replace `amd64` with `arm64`. |
 | Edge address | For example, `ws://edge.example.com:6868` or `wss://edge.example.com:6868`. Edge version must be `>= v0.47.0`. View the Edge list and installation method [here](https://console.flashcat.cloud/monit/engine/list). |
 | Local host object address | Use the current host's fixed private IP or DNS name, such as `10.0.1.12`. If omitted, the Agent uses the IP address associated with the local default route. |
 | Read-only accounts for databases and middleware | To diagnose MySQL, Redis, PostgreSQL, MongoDB, Kafka, Elasticsearch, and other services, prepare read-only accounts and credentials in advance. |
@@ -21,14 +21,14 @@ The Edge address must include a protocol prefix. Supported protocols are `ws://`
 
 ## Install monit-agent
 
-The following steps use Linux as an example.
+The following steps use the monit-agent `v0.3.0` Linux package.
 
 ```bash
 sudo mkdir -p /opt/monit-agent
 cd /opt/monit-agent
 
-sudo curl -sfLO "https://static.flashcat.cloud/monitagent/monitagent-v0.1.6-linux-amd64.tar.gz"
-sudo tar -xzf monitagent-v0.1.6-linux-amd64.tar.gz --strip-components=1
+sudo curl -sfLO "https://static.flashcat.cloud/monitagent/monitagent-v0.3.0-linux-amd64.tar.gz"
+sudo tar -xzf monitagent-v0.3.0-linux-amd64.tar.gz --strip-components=1
 sudo chmod +x ./monitagent
 ```
 
@@ -129,17 +129,21 @@ sudo journalctl -u monitagent -f
 If you modify the Edge address, Basic Auth, TLS parameters, or `hostLocator`, restart the Agent. After modifying `agent.yaml`, send SIGHUP to reload the configuration:
 
 ```bash
-sudo systemctl kill -s HUP monitagent
+sudo systemctl kill --kill-who=main -s HUP monitagent
 ```
 
 ## Approve a blocked Shell command
 
-`shell.exec` automatically runs read-only diagnostic commands that meet its built-in safety rules. If a command does not pass the automatic rules but you have confirmed that it is appropriate for the current machine, sign in to the Linux host running the Agent and open an approval session as root:
+`shell.exec` automatically runs read-only diagnostic commands that meet its built-in safety rules. The approval steps below apply to the default `host.shell_exec.unknown_command_policy: require_approval` setting. With `allow`, unknown commands execute directly without an approval session. Read [Unknown command policy and risks](/en/monitors/targets/configure-targets#unknown-command-policy) before choosing a policy.
+
+Under the default policy, if a command does not pass automatic rules, does not match a permanent-deny rule, and you have confirmed that it is appropriate for the current machine, sign in to the Linux host running the Agent and open an approval session as root:
 
 ```bash
 sudo /opt/monit-agent/monitagent shell-approval
 ```
 
+Without an approval session, the Agent returns `approval_unavailable` and does not execute unknown commands. After opening a session, submit the diagnostic request again.
+
 After the session connects, it displays a waiting status. When commands need approval, the terminal shows only the commands and a ten-second countdown:
 
 - Press Enter to approve every command in the current batch.
@@ -154,7 +158,7 @@ Only one approval session can be active for an Agent. To take over an existing s
 sudo /opt/monit-agent/monitagent shell-approval --replace
 ```
 
-Only root can open or replace a session. Pending commands are rejected if the Agent restarts or the session disconnects, and you must open a new session after a restart. High-risk operations such as shutdown, reboot, system destruction, or reading sensitive credentials cannot be enabled through human approval.
+Only root can open or replace a session. Pending commands are rejected if the Agent restarts or the session disconnects, and you must open a new session after a restart. Commands that match permanent-deny rules cannot be enabled through human approval.
 
 ## Next step
 

diff --git a/en/monitors/targets/reload-and-verify.mdx b/en/monitors/targets/reload-and-verify.mdx
@@ -11,12 +11,13 @@ Different `monit-agent` configuration changes take effect in different ways. Thi
 | Change | How it takes effect |
 |---|---|
 | Host collection, tool switches, MySQL, Redis, PostgreSQL, MongoDB, Kafka, Elasticsearch, and other configurations in `agent.yaml` | Send SIGHUP to reload |
+| `host.shell_exec.unknown_command_policy` (available in monit-agent `v0.3.0` and later) | Send SIGHUP to reload |
 | Edge address, Basic Auth, TLS, `hostLocator`, audit directory | Restart the Agent |
 
-Send SIGHUP:
+Send SIGHUP to the Agent's main process:
 
 ```bash
-sudo systemctl kill -s HUP monitagent
+sudo systemctl kill --kill-who=main -s HUP monitagent
 ```
 
 Restart the service:
@@ -31,6 +32,24 @@ If you only add or adjust object configuration in `agent.yaml`, use SIGHUP reloa
 
 After changing tool switches, a successful reload updates the diagnostic tools currently available from the Agent. No restart is required.
 
+## Change the unknown command policy
+
+After editing `host.shell_exec.unknown_command_policy` in `agent.yaml`, send SIGHUP to the Agent's main process. The Agent reloads and validates the configuration. New calls use the new policy after a successful reload. If validation fails, the Agent keeps the previous configuration and logs the reason. Editing the file alone does not trigger a reload.
+
+- Change from `require_approval` to `allow`: newly submitted unknown commands no longer require approval. Commands already awaiting approval must still complete their original approval process.
+- Change from `allow` to `require_approval`: newly submitted unknown commands require approval. Commands already running are not terminated, and completed writes are not rolled back.
+- Known-safe operations continue to execute automatically. Operations that match permanent-deny rules remain blocked.
+
+See [Unknown command policy](/en/monitors/targets/configure-targets#unknown-command-policy) for the policy values and risks. To check whether the reload succeeded, view the logs:
+
+```bash
+sudo journalctl -u monitagent -n 100
+```
+
+<Note>
+Upgrade to monit-agent `v0.3.0` or later before adding this field. Older versions do not recognize `unknown_command_policy`. Before rolling back to an older version, remove the field or restore the previous configuration; otherwise, the Agent cannot load it.
+</Note>
+
 ## Verify successful onboarding
 
 After the Agent starts, a host object usually appears on the monitoring object page within a few seconds.

diff --git a/zh/monitors/targets/configure-targets.mdx b/zh/monitors/targets/configure-targets.mdx
@@ -8,7 +8,7 @@ keywords: ["agent.yaml", "MySQL", "Redis", "PostgreSQL", "MongoDB", "Kafka", "El
 
 ## 基础配置示例
 
-下面是一个适合首次接入的基础配置：
+下面的基础配置适用于 monit-agent `v0.3.0` 或以上版本。使用 `unknown_command_policy` 前，请先升级 Agent；旧版本不识别该字段，会导致配置加载失败。
 
 ```yaml
 locator_mappings: {}
@@ -51,6 +51,7 @@ host:
 
   shell_exec:
     enabled: true
+    unknown_command_policy: require_approval
     default_max_lines: 200
     cat_max_file_size: 20971520
     user_allow_list: []
@@ -116,18 +117,40 @@ locator_mappings:
 host:
   shell_exec:
     enabled: true
+    unknown_command_policy: require_approval
     default_max_lines: 200
     cat_max_file_size: 20971520
     user_allow_list: []
 ```
 
+### 未知命令策略
+
+`host.shell_exec.unknown_command_policy` 控制未通过自动安全规则、但满足现有语法和执行限制的命令如何获得执行授权。这类“未知命令”既可能是未收录的只读操作，也可能修改数据或影响服务。
+
+| 命令分类 | `require_approval`（默认） | `allow` |
+|---|---|---|
+| 已知安全操作 | 自动执行 | 自动执行 |
+| 命中永久拒绝规则的操作 | 拒绝执行 | 拒绝执行 |
+| 未知操作 | 本机 root 审批后执行 | 直接执行，无需审批会话 |
+
+省略该字段或将其设为空字符串时，使用 `require_approval`，保持原有审批行为。只有 `require_approval` 和 `allow` 是合法值；大小写或拼写错误会导致配置校验失败。
+
+你只能在 Agent 本地的 `agent.yaml` 中设置该策略，不能通过控制台或工具调用参数切换。它只影响 `shell.exec`，不会开启数据库、中间件等其他诊断工具的写权限，也不会覆盖 `enabled: false` 或 `disabled_tools`。
+
+<Warning>
+将策略设置为 `allow`，表示授权未知命令以 Agent 的运行账号权限直接执行。这也包括原本需要审批的 `docker exec`、`kubectl exec`，实际可访问范围取决于该账号的容器运行时权限和 Kubernetes 凭据。
+
+未知命令可能修改或删除数据、访问敏感信息、影响服务或调用其他程序；中心端被攻破时也可能利用这些能力。Agent 仍执行永久拒绝规则、语法检查、超时和输出限制，但这些规则不能完备识别任意未知程序的间接危险行为。
+</Warning>
+
 建议：
 
-- 需要 AI-SRE 做主机现场诊断时，保持 `enabled: true`。只有受控的 shell 才能执行，放心开启。
-- 命令偶尔被拦截时，可以由本机 root [人工审批该命令](/zh/monitors/targets/install-agent#人工审批被拦截的-shell-命令)。
+- 需要 AI-SRE 做主机现场诊断时，设置 `enabled: true`，并保留默认的 `require_approval` 策略。
+- 未知命令需要逐条确认时，由本机 root [人工审批该命令](/zh/monitors/targets/install-agent#人工审批被拦截的-shell-命令)。
 - 对于需要长期重复使用的命令，确认其安全、只读且不会输出敏感信息后，再将完整命令添加到 `user_allow_list`。
+- 只有在接受未知命令直接执行的风险时，才将策略改为 `allow`。它不提供一份限定写操作范围的白名单。
 
-人工审批和 `user_allow_list` 都不能放开关机、重启、破坏系统或读取敏感凭据等高危操作。
+命中永久拒绝规则的命令，不能通过人工审批、`user_allow_list` 或 `allow` 放开。
 
 如需紧急禁用某个工具，可以使用 `tool_policy.disabled_tools`：
 
@@ -137,7 +160,7 @@ tool_policy:
     - shell.exec
 ```
 
-修改 `shell_exec.enabled` 或 `tool_policy.disabled_tools` 后，发送 SIGHUP reload 即可生效，无需重启 Agent。
+修改 `shell_exec.enabled`、`shell_exec.unknown_command_policy` 或 `tool_policy.disabled_tools` 后，发送 SIGHUP reload 即可生效，无需重启 Agent。策略切换对新调用生效；已开始执行或等待审批的命令保持原行为，详见[配置生效与接入验证](/zh/monitors/targets/reload-and-verify#切换未知命令策略)。
 
 ## MySQL
 

diff --git a/zh/monitors/targets/install-agent.mdx b/zh/monitors/targets/install-agent.mdx
@@ -12,7 +12,7 @@ keywords: ["monit-agent", "Agent 安装", "Edge 地址", "系统服务", "监控
 
 | 准备项 | 说明 |
 |---|---|
-| Agent 安装包下载地址 | `https://static.flashcat.cloud/monitagent/monitagent-v0.1.6-linux-amd64.tar.gz`。如果是 arm 的 CPU，则把 `amd64` 换成 `arm64`。 |
+| Agent 安装包下载地址 | `https://static.flashcat.cloud/monitagent/monitagent-v0.3.0-linux-amd64.tar.gz`。如果是 arm 的 CPU，则把 `amd64` 换成 `arm64`。 |
 | Edge 地址 | 例如 `ws://edge.example.com:6868` 或 `wss://edge.example.com:6868`。Edge 版本需要 `>= v0.47.0`，Edge 列表和安装方法[点此查看](https://console.flashcat.cloud/monit/engine/list)。 |
 | 本机对象地址 | 建议使用当前主机的固定内网 IP 或 DNS 名称，例如 `10.0.1.12`。不指定的话默认会使用本机默认路由对应的 IP。 |
 | 数据库/中间件只读账号 | 如需诊断 MySQL、Redis、PostgreSQL、MongoDB、Kafka、Elasticsearch 等服务，需提前准备对应的只读账号和凭据。 |
@@ -21,14 +21,14 @@ Edge 地址必须带协议前缀，支持 `ws://`、`wss://`、`http://`、`http
 
 ## 安装 monit-agent
 
-以下步骤以 Linux 为例。
+以下步骤以 monit-agent `v0.3.0` 的 Linux 安装包为例。
 
 ```bash
 sudo mkdir -p /opt/monit-agent
 cd /opt/monit-agent
 
-sudo curl -sfLO "https://static.flashcat.cloud/monitagent/monitagent-v0.1.6-linux-amd64.tar.gz"
-sudo tar -xzf monitagent-v0.1.6-linux-amd64.tar.gz --strip-components=1
+sudo curl -sfLO "https://static.flashcat.cloud/monitagent/monitagent-v0.3.0-linux-amd64.tar.gz"
+sudo tar -xzf monitagent-v0.3.0-linux-amd64.tar.gz --strip-components=1
 sudo chmod +x ./monitagent
 ```
 
@@ -129,17 +129,21 @@ sudo journalctl -u monitagent -f
 如果修改了 Edge 地址、Basic Auth、TLS 参数或 `hostLocator`，需要重启 Agent。修改 `agent.yaml` 后，可以发送 SIGHUP 让 Agent 重新加载配置：
 
 ```bash
-sudo systemctl kill -s HUP monitagent
+sudo systemctl kill --kill-who=main -s HUP monitagent
 ```
 
 ## 人工审批被拦截的 Shell 命令
 
-`shell.exec` 会自动执行符合内置安全规则的只读诊断命令。如果某条命令未通过自动规则，但你确认它可以在当前机器上执行，可以提前登录 Agent 所在的 Linux 主机，用 root 打开审批会话：
+`shell.exec` 会自动执行符合内置安全规则的只读诊断命令。以下审批步骤适用于默认的 `host.shell_exec.unknown_command_policy: require_approval`。如果你设置为 `allow`，未知命令会直接执行，无需打开审批会话；选择前请阅读[未知命令策略及风险说明](/zh/monitors/targets/configure-targets#未知命令策略)。
+
+在默认策略下，如果某条命令未通过自动规则、没有命中永久拒绝规则，并且你确认它可以在当前机器上执行，可以提前登录 Agent 所在的 Linux 主机，用 root 打开审批会话：
 
 ```bash
 sudo /opt/monit-agent/monitagent shell-approval
 ```
 
+如果未打开审批会话，Agent 返回 `approval_unavailable`，不执行未知命令。打开会话后，请重新发起诊断调用。
+
 审批会话连接成功后会显示等待提示。出现待审批命令时，终端只展示命令本身和 10 秒倒计时：
 
 - 按回车批准当前批次中的全部命令。
@@ -154,7 +158,7 @@ sudo /opt/monit-agent/monitagent shell-approval
 sudo /opt/monit-agent/monitagent shell-approval --replace
 ```
 
-只有 root 可以打开或接管会话。Agent 重启或会话断开时，待审批命令会被拒绝；重启后需要重新打开会话。关机、重启、破坏系统或读取敏感凭据等高危操作不能通过人工审批放开。
+只有 root 可以打开或接管会话。Agent 重启或会话断开时，待审批命令会被拒绝；重启后需要重新打开会话。命中永久拒绝规则的命令不能通过人工审批放开。
 
 ## 下一步