host-bash

name	host_bash
description	设备上跑只读 shell 命令做诊断探索（沙箱化 / read-only policy）
when_to_use	当结构化工具（host_load / host_processes / host_find_large_files / query_logql / query_promql） 不够用、需要灵活的 shell 一行 / pipe 时使用。**只读**：写操作（rm / mv / chmod / systemctl restart 等） 会被边端 cmdpolicy 沙箱拒掉。 典型场景： • 复杂条件的 ps / grep / awk / sed pipe（"找 cpu top 10 + 名字含 nginx 的"） • iptables -L / ip addr / tc qdisc show / mount 等只读运维查询 • systemctl status / cat / list-units / is-active（不能 restart / stop） • journalctl / dmesg 配合 grep / awk 做日志快速定位 • find / du / stat 配合 sort / head 做文件系统下钻 • 网络探测 nc -z / curl --head / dig / ping（host 在 operator allowlist 内） 明确不要用于： • 重启服务 → 用 host_restart_service（mutating，走 reviewer） • 改文件 / 改配置 → 不支持（也不应让 LLM 自主改） • 简单单一动作 → 用结构化工具更省 token： - 看 cpu/mem 用 get_host_load - 看进程列表用 get_host_processes - 找大文件用 host_find_large_files - 看磁盘占用用 host_du_summary **被沙箱拒绝时（response.allowed=false）读 reason，按提示改命令重试**。 常见拒绝：sed -i / find -delete / shell 嵌套 ($()/`) / redirect (> >>) / systemctl restart / 任何 ClassDenied 二进制（rm / bash / python / ...）。
metadata	{"os":["linux"],"requires":{"bins":["ps","grep","awk","sed","find","du","stat","ls","cat","head","tail","wc","sort","uniq"]},"ongrid":{"scope":"edge","edge_runtime":"subprocess","edge_capabilities":["[Truncated]"],"activation":{"mode":"always"},"min_ongrid_version":">=0.7.30"}}

[能力: host_bash]

本工具在目标设备上运行单条 shell 命令或 pipe 管道，由边端 internal/edgeagent/cmdpolicy 沙箱 做策略校验。v1 是 read-only policy，写操作一律被拒。

调用规则

host_bash(device_id=<num>, cmd="<command>")

• device_id 必填：与 @-mention chip 和 Prom device_id label 一致
• cmd 必填：单条命令或单层 pipe；不支持 ; && || $() <() > >> 反引号 / heredoc
• timeout_seconds 可选：默认 30s，最大 300s

允许的命令分类

分类	示例 binary	备注
文件系统读	ls / cat / head / tail / find / du / stat / grep / awk / sed / wc	sed -i / find -delete / awk system() 拒
系统状态读	ps / df / free / uptime / iostat / vmstat / lsof / ss / netstat / dmesg / journalctl	journalctl --rotate / --vacuum-* 拒
网络配置读	iptables -L / ip addr / tc qdisc show / mount -l / crontab -l	iptables -A / ip addr add / mount /a /b 拒
OVS 探测	ovs-vsctl show / list-br / get / find / list；ovs-ofctl dump-flows / dump-ports / show；ovs-dpctl show；ovs-appctl fdb/show / lacp/show 等	add-br / del-br / set / add-flow / del-flows 全拒
nftables / conntrack	nft list ruleset / list table；conntrack -L / -S / -G / -E；ipset list；ethtool -i <iface>	nft add/delete/flush；conntrack -F / -D；ethtool -K/-G/-s 全拒
eBPF 只读	bpftool prog show / map dump / btf dump / net show / link show / iter list / feature probe	bpftool prog load / attach；map create / update 全拒（要写 BPF 走 Layer-3 preset）
网络命名空间	ip netns list / identify / pids；ip netns（裸= list）	ip netns exec / add / del 拒（exec 会重入沙箱）。深入 inspect 走 host_netns_inspect skill（未上）
服务状态读	systemctl status / cat / list-units / is-active	systemctl restart / stop / start 拒（用 host_restart_service）
网络探测	nc -z / curl --head / dig / host / ping / traceroute	curl -o / wget / nc -e/-l 拒；目标 host 须在 operator allowlist 内

推荐套路（诊断 / 探索）

问"哪个进程吃 cpu"：

host_bash(device_id=N, cmd="ps aux --sort=-%cpu | head -10")

问"nginx 最近一小时报错了哪些"：

host_bash(device_id=N, cmd="journalctl -u nginx --since '1 hour ago' | grep -i error | head -50")

问"看下 /var 哪些子目录占用最大"（也可以用 host_du_summary）：

host_bash(device_id=N, cmd="du -sh /var/* | sort -rh | head -10")

问"iptables 当前规则"：

host_bash(device_id=N, cmd="iptables -L -n")

问"哪个端口开着"：

host_bash(device_id=N, cmd="ss -tlnp")

不要做的事

• 不要尝试 redirect 写文件（> /tmp/x）—— 沙箱拒
• 不要尝试用 bash -c 套子壳 —— bash / sh / zsh / dash 整个 ClassDenied
• 不要尝试 sed -i —— 用 sed 看就行，改文件不在本工具职责
• 不要尝试 systemctl restart —— 用 host_restart_service skill（带 reviewer 二审）
• 被拒后不要重试同一条命令 —— 读 response.reason，调整命令再发
• 不要用本工具替代结构化查询 —— 简单 cpu/mem/进程查询用 get_host_load / get_host_processes

v1 实现说明

• Policy = cmdpolicy.DefaultReadOnly()，operator 可在 /etc/ongrid-edge/bash-policy.yaml 扩展或收紧（替换某个 binary 的 matchers / 缩短 path allowlist / 改 timeout / 加 network allowlist）
• 网络出站默认全拒（network_host_allowlist=[]），operator 显式添加 CIDR 或 hostname suffix 才放行
• Path allowlist 默认 /var /opt /home /tmp /srv /data（与 host_files 共享同一份）
• stdout cap 64 KiB / stderr cap 16 KiB / 默认 timeout 30s / 单段 argv ≤32