企业官网建设流程全解析

如何用 yq 的 system 操作符调用外部命令并正确启用安全开关

【免费下载链接】yqyq is a portable command-line YAML, JSON, XML, CSV, TOML, HCL and properties processor项目地址: https://gitcode.com/GitHub_Trending/yq/yq

在 yq 表达式中需要引用外部命令的输出时（例如把某个命令的结果写进字段值），可以使用system操作符。它被设计为默认关闭：不显式传入--security-enable-system-operator时，表达式会直接报错而不会执行任何命令。这篇文章基于 yq 官方文档 system-operators 说明如何正确启用这个开关、按文档语法调用命令，以及启用后对其他安全开关产生的影响。

system 操作符的默认状态：禁用并报错

system操作符的语法是system("命令"; "参数")：

• 命令字符串（必填）；
• 参数可以是单个值，也可以是参数数组，用;与命令分隔（可选）。

该操作符默认处于禁用状态。与--security-disable-env-ops、--security-disable-file-ops的行为一致，禁用时不会运行命令，而是直接返回错误。文档给出的禁用示例：对sample.yml（内容如下）执行

yq '.country = system("/usr/bin/echo"; "test")' sample.yml

country: Australia

会得到错误：

Error: system operations are disabled, use --security-enable-system-operator to enable

看到这个报错就说明操作符处于禁用状态，需要加上安全开关。

启用安全开关并调用命令

启用方式是给 yq 命令加上--security-enable-system-operator标志。

带参数调用

使用同一个sample.yml（country: Australia）：

yq --security-enable-system-operator '.country = system("/usr/bin/echo"; "test")' sample.yml

文档示例输出：

country: test

命令的标准输出（去掉末尾换行）被作为字符串赋给了.country字段。

不带参数调用

省略分号和参数即可不传额外参数。对内容为a: hello的文件执行：

yq --security-enable-system-operator '.a = system("/usr/bin/echo")' sample.yml

文档示例输出：

a: ""

即没有参数时echo无输出，字段被赋为空字符串。

传多个参数（可选分支）

文档说明参数可以是一个数组。yq 的测试用例（operator_system_test.go）展示了数组写法，对内容为a: hello的文件执行：

yq --security-enable-system-operator '.a = system("/usr/bin/echo"; ["foo", "bar"])' sample.yml

测试中的预期结果为a: foo bar。

数据流向：节点值进 stdin，stdout 出结果

文档对数据流的定义是：

• 当前匹配节点的取值会被序列化后，通过stdin传给外部命令；
• 命令的stdout（去掉末尾换行）作为字符串返回，成为表达式中的值。

因此外部命令内部可以用cat等方式读到 yq 传入的节点值，再决定输出内容。

文档给出的通用用法形式为：

yq --security-enable-system-operator --null-input '.field = system("command"; "arg1")'

其中command与arg1是占位写法，需要替换为你实际要执行的命令和参数；--null-input表示不读取输入文件，直接求值表达式，适合从零创建文档。

启用 system 后对其他安全开关的影响

文档给出了明确的安全警告：启用system后，它可以通过外部命令复现env和load操作符的功能。也就是说，如果同时使用了--security-disable-env-ops（禁用 env 相关操作）和--security-disable-file-ops（禁用 load 等文件相关操作），启用system会实际抵消（override）这两个禁用开关的效果。

在只读场景处理不受信任的表达式时，这一点需要在安全边界上单独考虑：即使已经禁用了 env 和 file 操作，只要表达式中出现system且开关被打开，就能借助外部命令间接读取环境或文件。

结果核对方式

按文档可以直接核对的三类结果：

1. 开关未启用：命令不执行，输出固定错误信息Error: system operations are disabled, use --security-enable-system-operator to enable；
2. 开关已启用、命令成功：stdout（去末尾换行）被写入目标字段，如country: test；
3. 开关已启用、命令无参数输出：字段被赋为空字符串，如a: ""。

以上输出均为文档示例结果。完整实现可参考 operator_system.go，标志--security-enable-system-operator在 root.go 中注册，与另外两个安全标志并列。

【免费下载链接】yqyq is a portable command-line YAML, JSON, XML, CSV, TOML, HCL and properties processor项目地址: https://gitcode.com/GitHub_Trending/yq/yq