docs: add limactl help yq concept guide to explain yqlib limitations

cmd/limactl/editflags/editflags.go

@@ -68,7 +68,7 @@ func RegisterEdit(cmd *cobra.Command, commentPrefix string) {
 
 	flags.Bool("rosetta", false, commentPrefix+"Enable Rosetta (for vz instances)")
 
-	flags.StringArray("set", []string{}, commentPrefix+"Modify the template inplace, using yq syntax. Can be passed multiple times.")
+	flags.StringArray("set", []string{}, commentPrefix+"Modify the template inplace, using yq syntax. Can be passed multiple times. See 'limactl help yq-restrictions' for limitations.")
 	flags.StringArray("param", []string{}, commentPrefix+"Set a template parameter, e.g. name=value. Can be passed multiple times.")
 
 	flags.Uint16("ssh-port", 0, commentPrefix+"SSH port (0 for random)") // colima-compatible

cmd/limactl/main.go

@@ -210,6 +210,7 @@ func newApp() *cobra.Command {
 		newCloneCommand(),
 		newRenameCommand(),
 		newWatchCommand(),
+		newYQRestrictionsHelpCommand(),
 	)
 	addPluginCommands(rootCmd)
 

cmd/limactl/start.go

@@ -57,6 +57,7 @@ func newCreateCommand() *cobra.Command {
 
   To create an instance "default" with yq expressions:
   $ limactl create --set='.cpus = 2 | .memory = "2GiB"'
+  Note: Some yq operators are restricted. See 'limactl help yq-restrictions'.
 
   To create an instance "default" with a template parameter:
   $ limactl create --name=default --param containerdSnapshotter=false template:docker

cmd/limactl/yq_restrictions.go

@@ -0,0 +1,35 @@
+// SPDX-FileCopyrightText: Copyright The Lima Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package main
+
+import (
+	"github.com/spf13/cobra"
+)
+
+func newYQRestrictionsHelpCommand() *cobra.Command {
+	return &cobra.Command{
+		Use:   "yq-restrictions",
+		Short: "Restrictions on yq expressions in Lima",
+		Long: `Lima uses yq (v4) syntax for the --set flag and provision mode "yq".
+
+Lima embeds yqlib (https://github.com/mikefarah/yq) as a library and
+disables several operators to prevent template expressions from reading
+the host environment or executing arbitrary commands:
+
+  Disabled by Lima:
+    - env, envOp        (environment variable access)
+    - load, load_str    (arbitrary file reads)
+
+  Disabled by yqlib default:
+    - system            (arbitrary command execution)
+
+These restrictions exist because --set expressions and provision.yq
+expressions may come from untrusted template files. Allowing them to
+access environment variables, read files, or execute commands on the
+host would be a security risk.
+
+For full yq v4 expression syntax, see:
+  https://mikefarah.gitbook.io/yq/`,
+	}
+}

hack/bats/tests/yq.bats

@@ -47,3 +47,8 @@ load "../helpers/load"
     run_e -1 limactl yq -n --security-disable-env-ops 'env(FOO)'
     assert_stderr "Error: env operations have been disabled"
 }
+
+@test 'yq multi-call command has system operations disabled by default' {
+    run -1 limactl yq -n 'system("echo hello")'
+    assert_output --partial "system operations are disabled"
+}