教程四:远程执行运维命令

场景与前置条件

你手上有几台开发板或测试机,它们跑着 anet daemon。你想从网络的另一端触发 "重启业务进程"、"读最近 200 行日志"、"烧一版固件"这类操作,并拿回回显, 而且这份权限要能随时收回,不需要重启被控端。

这就是 shell 模块的用途。它是套件里唯一一个在宿主机上执行命令的模块, 因此它的默认状态与其它模块相反:不装、不配、不列名单,三者缺一都执行不了。

开始之前需要:

• 两台机器(或同一台机器上的两个身份,见本页末尾的"本机排练")。 一台是被控端,要装 shell 变体;一台是调用端,装默认版即可。
• 两台都能出站访问同一个 hub。本页用官方 hub https://hub.agentnetwork.org.cn。
• 被控端的 ~/.anet/config.json 你能编辑,并且有 sudo(名单文件放在 /etc/anet 下)。

apt-get update && apt-get install -y curl ca-certificates procps

三道闸门

shell 模块的授权被拆成三个互相独立的决定。任何一道没过,命令都不会执行。

三道之外还有两个默认关闭的开关,后面会分别说明:

• allow_arbitrary —— 是否开放 shell.exec(执行调用方给的任意命令)。默认 false。
• allow_local —— 是否放行不带调用方身份的调用。默认 false。

第一道之所以做成加法 tag(默认不在),而其余九个由构建标签管辖的子系统都是减法 tag (默认在、-tags no_<name> 去掉),原因是两个方向出错的代价不对称:减法 tag 写错,后果是 某人想去掉的模块没去掉;加法 tag 写错,后果是命令执行能力进了所有没要过它的构建。 需要靠"记得去掉"来保护的人,恰好是没听说过这个 tag 的人。

判据是符号数,方向与减法 tag 相反,由 CI 的 optin job 两个方向都验:

go build -o /tmp/a ./cmd/anet             && go tool nm /tmp/a | grep -c module/shell   # 必须 0
go build -tags shell -o /tmp/b ./cmd/anet && go tool nm /tmp/b | grep -c module/shell   # 必须 > 0

动手:从零到一次远程执行

curl -fsSL https://agentnetwork.org.cn/install.sh | sh -s -- --shell \
  --hub https://hub.agentnetwork.org.cn \
  --name $(hostname)

anet version

anet 0.1.7 (commit …, built …)
modules: anetlink,blackboard,cas,mcp,org,p2p,service,shell,taskboard,x402

modules: anetlink,blackboard,cas,mcp,org,p2p,service,taskboard,x402

strings "$(command -v anet)" | grep -c 'shell\.run@'     # 默认版 0,shell 版 1
go tool nm "$(command -v anet)" | grep -c module/shell    # 默认版 0,shell 版 > 0(需装 Go)

module "shell" is configured but not compiled into this build (it needs -tags shell, which the default build does not use)

{
  "modules": {
    "shell": {
      "commands": {
        "uptime":      { "run": "uptime", "description": "负载与运行时长" },
        "disk":        { "run": "df -h" },
        "tail-log":    { "run": "journalctl -u myapp -n 200 --no-pager" },
        "restart-app": { "run": "systemctl restart myapp", "description": "重启业务进程" },
        "flash":       { "run": "/opt/tools/flash.sh", "args": true, "timeout_s": 600 }
      },
      "allow_file": "/etc/anet/shell-allow",
      "timeout_s": 60,
      "max_output_bytes": 65536
    }
  }
}

sudo mkdir -p /etc/anet
sudo touch /etc/anet/shell-allow
sudo chown "$USER" /etc/anet/shell-allow   # daemon 以谁的身份跑,就要能读它
sudo chmod 600 /etc/anet/shell-allow

anet stop && anet up

anet hub-register https://hub.agentnetwork.org.cn --name $(hostname)

anet shell: no caller is allowed — set allow or allow_file, or this module will refuse every call

anet delegate <被控端AID> --capability shell.run@uptime
anet results

{
  "capability": "shell.run@uptime",
  "status": "UNAVAILABLE",
  "verifiable": false,
  "message": "this node does not accept commands from bafyrei……"
}

anet status

anet status | grep -o 'bafyrei[a-z0-9]*' | head -1

echo '# 我的笔记本,2026-09-03 加' | sudo tee -a /etc/anet/shell-allow
echo 'bafyrei……调用端的AID'      | sudo tee -a /etc/anet/shell-allow

anet delegate <被控端AID> --capability shell.run@uptime
anet results

{
  "capability": "shell.run@uptime",
  "status": "OK",
  "verifiable": true,
  "metrics": { "duration_ms": 12, "exit_code": 0, "output_bytes": 68 },
  "evidence": {
    "auth_trust": 0,
    "latency_ms": 12,
    "native_ack": true,
    "observed_state": " 14:22:31 up 6 days,  3:11,  1 user,  load average: 0.08, 0.12, 0.09",
    "protocol": "shell",
    "requested": "shell.run@uptime",
    "verify_trust": 2
  }
}

anet delegate <被控端AID> --capability shell.run@flash --args '{"argv":["--image","/tmp/fw.bin"]}'

# 撤一个调用方
sudo sed -i '/bafyrei……调用端的AID/d' /etc/anet/shell-allow
 
# 或者一次性全撤
sudo rm /etc/anet/shell-allow

anet hub-leave
anet stop

配置字段全表

以下字段全部来自 ANet/module/shell/shell.go 的 Config 与 Command 结构。

命令名的限制:不能为空,不能含空格、制表符、@ 或 / —— 因为它会成为能力 id shell.run@<name> 的一部分。run 不能是空白。

关于 allow_local:CallerAID 的零值就是空字符串。把"空"当作"本机、可信"意味着 将来任何一处新调用点漏填这个字段,都会静默绕过整份名单。默认拒绝让同一个疏忽 表现为一次看得见的拒绝,而不是一次看不见的放行。它需要自己的开关,这个开关默认关。

这个模块暴露哪些能力

能力列表是排序后通告的,所以卡片上的顺序跨重启稳定 —— 一份自己会重排的列表会让每张卡 看起来都变过。

allow_arbitrary 关着时,shell.exec 既不出现在能力卡上,也不接受按名调用。开着时, daemon 启动会打一行明确的警告到 ~/.anet/daemon.log:

anet shell: allow_arbitrary is ON — an allowed caller can run any command as the user this daemon runs as

行为约定

这一节的每一条都是实现行为,不是建议;标注了 daemon 的那条不在模块里。

• 不提权。 命令以 daemon 自己的用户身份运行。本模块不调 sudo、不 setuid。 要 root 就要让 daemon 以 root 运行 —— 那是安装期的决定,写在 unit 文件里、看得见, 不是这个模块能授予的东西。以非 root 身份跑 systemctl restart 这类命令,能不能做成 完全取决于该用户的权限;做不成时退出码与 stderr 原样回给调用方。(systemctl、 journalctl 在非 root 下的具体失败形态与目标机器的 polkit 配置有关,本页没有实测。)

• 参数不会变成命令。 args: true 时,调用方给的 argv 每一个元素被单引号包裹 (内嵌单引号转义为 '\'')后追加到命令行末尾。命令行归运营者,参数归网络, 两者不能混成一个东西。argv 不是字符串列表时,这次调用直接报错,不执行。

• 没声明 args 却带了 argv,是错误而不是忽略。 静默丢掉参数意味着执行了 一件与调用方所要求的不同的事,然后报成功。

• args 里出现别的键,同样是错误。 shell.run@<name> 只认 argv 这一个键, shell.exec 只认 command 与 dir;别的键一律拒绝并点名:

  shell: uptime: unknown argument "arguments" (this call takes: argv)

  这条补的是同一个漏洞的一般情形:把 argv 写成 args 或 arguments 的调用方, 参数被丢掉、命令照跑、结果报 OK —— 一次没按要求做却自称成功的执行。

• 超时杀整个进程组。 命令跑在自己的进程组里,超时时 SIGKILL 发给整个组。 只杀 shell 会把它启动的子进程(一次构建、一次烧录、一个循环)留在机器上, 而没有任何句柄能再找到它们。

• 逃出进程组的子进程最多再等 3 秒。 有些命令会自己 setsid,它们持有的输出管道 会让这次等待永远不结束。WaitDelay 把这个等待封顶,而不是让一次调用永久挂起。

• 回显有上限,截断时写明。 超过 max_output_bytes 的部分被截断,并在输出末尾追加 一行 [output truncated at <N> bytes],不静默截。超限之后的写入仍然被接收(丢弃), 这样命令不会因为管道关闭而被 EPIPE 打死 —— 否则"输出太多"会伪装成"命令崩了"。

• 诚实效果状态。 退出码 0 → OK;非 0 → FAILED,message 是 exit <码>, stderr 在 evidence.observed_state 里;超时被杀 → FAILED,message 是 killed after <超时>。不会出现"被杀了但报 OK、输出为空"这种组合。 命令根本没能启动(exec 失败)走的是另一条路径:模块不构造效果,而是返回错误 shell: start: …;daemon 把 provider 返回的错误统一记成 FAILED,message 就是 这句错误文本。所以调用方两种情况都看到 FAILED,区别在于没能启动的那次不带 metrics.exit_code、也不带 evidence —— 本节点没有退出状态可报。

• verify_trust 是 2(V2),不是 4。 本节点读回了退出码和这条命令打印的内容, 这是它观察到的;命令声称的那件事在世界上是否真的发生了,它没有观察到。

• 每次执行、以及名单判定产生的每次拒绝,都在应答前上证据链。

有一种拒绝不写事件:名单文件存在但读不了。此时本节点连"谁在名单上"都答不出来, 它回 UNAVAILABLE 并且不落记录(module/shell/provider.go 的 Invoke), 所以"谁在敲门"的复查看不到这一类。

被拒的记录是更值得留的那一条:名单外的 AID 只会出现在这里,而拒绝如果不留痕, 想复查"谁在敲门"的运营者就没有东西可查。查看方式:

anet evidence --type anet.shell.refused --limit 20
anet evidence --type anet.shell.command --limit 20

开机自启:User= 决定命令以谁的身份执行

anet up 起的进程不跨重启。真机上用 systemd:

sudo tee /etc/systemd/system/anet.service >/dev/null <<EOF
[Unit]
Description=ANet daemon
After=network-online.target
Wants=network-online.target
 
[Service]
Type=simple
User=$USER
Environment=ANET_DATA_DIR=$HOME/.anet
ExecStart=$HOME/.local/bin/anet daemon
Restart=on-failure
RestartSec=5
 
[Install]
WantedBy=multi-user.target
EOF
 
anet stop
sudo systemctl daemon-reload
sudo systemctl enable --now anet
systemctl status anet --no-pager

User= 决定命令以谁的身份执行。User=你自己 的 daemon 只能跑你自己能跑的东西; 要跑 root 级运维命令,就要把 User= 设成 root,并把 ANET_DATA_DIR 改到 /root/.anet。

已知取舍

四条,都是有意选的,写在这里是因为它们各自有代价。

一 · run 经 shell 执行,运营者写进去的内容不受任何限制。 这样运营者可以直接写平时敲的命令(管道、重定向、&&),代价是 run 里的内容 没有任何校验。这条线划在"运营者写的"和"网络传来的"之间,只有后者是被引号隔离的那一侧。 不接受这个取舍的话,把命令包成脚本、run 只写脚本路径 —— 代价是配置文件不再显示 这台机器实际会做什么。

二 · 命令名会进 hub 目录。 节点向 hub 通告的是它实际会应答的能力 id,所以 shell.run@restart-app 这类名字对 任何能浏览目录的人可见。这不给出访问权(名单仍然拦着),但确实公开了这台机器 可以被要求做什么。不希望公开的命令,名字就不要带信息。

三 · shell.list 只把名单条数回给远程调用方,不回 AID 列表。 一个被接受的调用方不该顺带拿到本节点信任的其余机器名单 —— 那会把"一个被接受的调用方" 变成"一份其他运营者的通讯录"。本机调用(CallerAID 为空,需要 allow_local)拿到 完整列表,那是运营者在读自己的配置。

四 · 回显会落到本节点的证据链上,尽管 shell 模块自己没写它。

• 位置:ANet/internal/daemon/capability.go 的 deliverCapabilityResult, 写入 anet.capability.effect 事件时带上了 evidence,其中包含 observed_state。
• 行为:ANet/module/shell/provider.go 写的 anet.shell.command 事件不含回显, 但 daemon 在交付能力结果时写的那条事件含。
• 影响:命令打印的任何内容(可能包括日志里的敏感串)会留在被控端的 ~/.anet/evidence.ael.jsonl 里。ANet/docs/SHELL-zh.md 里"回显本身不入链" 这句只对模块自己写的那条事件成立,对整条链不成立。
• 发现方式:为本页核对源码时,对照两处 RecordEvidence / ledger.Append 调用点。

排查

节点自己的日志在 ~/.anet/daemon.log,也可以 anet logs 100。

这一页背后验过什么

ANet/scripts/joint-shell.sh 起一个 hub 加两个 daemon,provider 用 -tags shell 构建,跨进程走真实委派路径。脚本里有 19 处 ok 断言点,最后一处就是"未服务的能力 是否作答";这条修好之后一次完整运行打印的是 19 passed。它验的是单元测试验不了的那些:

• 名单文件不存在时拒绝,走的是真实网络路径而不是构造出来的 provider.Call。
• 名单上的调用方能在另一台机器上执行命令,且以 daemon 的用户身份执行(不是 root)。
• 到达模块的 CallerAID 是验签后的身份,不是调用方自称的值。 这是关键的一条:整套授权都压在这个字段上,而单元测试断言的是测试文件自己写进去的值。 只有真委派能证明这件事,脚本靠"provider 的证据链里记着 requester 的 AID"来验。
• 参数里的 shell 元字符(hi; id、&& id、$(id))原样作为文本回来,没有被执行。
• 非零退出回 FAILED 且 stderr 完整。
• 删掉名单行后下一次调用即被拒(不重启),加回后即恢复,拒绝记录上了链。
• shell.exec 在 allow_arbitrary 关闭时不出现在 hub 目录里,按名调用也不执行。

本机排练(可选)

不想动两台机器的话,可以在一台机器上用两个身份排练,但要注意: 两个身份共用同一个二进制,所以被控端那个身份要生效,这个二进制必须是 shell 变体。

anet id new board          # 建一个新身份并后台启动;数据目录 ~/.anet/ids/board
anet id ls                 # 看 AID、控制口、数据目录

anet id new 会立刻把这个身份起起来,而它此时还没有 modules.shell。所以顺序是: 把 modules.shell 写进 ~/.anet/ids/board/config.json(名单里填默认身份的 AID), 再 anet --id board stop && anet --id board up 让配置生效,然后 anet --id board hub-register <hub-url> --name board 把能力清单折进注册。 之后用 anet --id board <cmd> 操作被控端、用裸 anet <cmd> 操作调用端。 委派仍然走 hub 中继,两个身份都要 hub-register。

接下来