Add long-form help for gcp, k8s, network, os, terraform, vcd, vsphere (…

…#5124) * Add long-form help for gcp, k8s, network, os, terraform, vcd, vsphere * fix filesystem * fixes per @tas50 review
mondoohq · Jan 28, 2025 · 985236b · 985236b
1 parent 1e7d128
commit 985236b
Show file tree

Hide file tree

Showing 7 changed files with 142 additions and 43 deletions.
diff --git a/providers/gcp/config/config.go b/providers/gcp/config/config.go
@@ -21,9 +21,22 @@ var Config = plugin.Provider{
 	},
 	Connectors: []plugin.Connector{
 		{
-			Name:    "gcp",
-			Use:     "gcp",
-			Short:   "a Google Cloud project or folder",
+			Name:  "gcp",
+			Use:   "gcp",
+			Short: "a Google Cloud project or folder",
+			Long: `Use the gcp provider to query resources within Google Cloud Platform (GCP), including databases, services, instances, containers, and more.
+
+Examples without logging into and configuring GCP:
+  cnquery shell gcp org <ORGANIZATION-ID> --credentials-path <PATH-TO-YOUR-SERVICE-ACCT>
+  cnspec scan gcp project <PROJECT-ID> --credentials-path <PATH-TO-YOUR-SERVICE-ACCT>
+
+Note:
+  If you log into GCP and configure the project you want to query or scan, you can omit credentials. To learn how, read https://mondoo.com/docs/cnspec/cloud/gcp/.
+
+Examples with the GCP project configured:
+  cnspec scan gcp folder <FOLDER-ID>
+  cnquery shell gcp project
+`,
 			MaxArgs: 2,
 			Discovery: []string{
 				resources.DiscoveryOrganization,

diff --git a/providers/k8s/config/config.go b/providers/k8s/config/config.go
@@ -21,6 +21,16 @@ var Config = plugin.Provider{
 			Aliases: []string{"kubernetes"},
 			Use:     "k8s (optional MANIFEST path)",
 			Short:   "a Kubernetes cluster or local manifest file(s)",
+			Long: `Use the k8s provider to query Kubernetes resources, including clusters, pods, services, containers, manifests, and more.
+
+Requirement:
+  To query or scan a Kubernetes cluster, you must install kubectl on your workstation. To learn how, read https://kubernetes.io/docs/tasks/tools/. 
+
+Examples:
+  cnquery shell k8s
+  cnspec scan k8s
+  cnspec <MANIFEST-FILE>
+`,
 			MinArgs: 0,
 			MaxArgs: 1,
 			Discovery: []string{

diff --git a/providers/network/config/config.go b/providers/network/config/config.go
@@ -30,9 +30,18 @@ var Config = plugin.Provider{
 	},
 	Connectors: []plugin.Connector{
 		{
-			Name:      "host",
-			Use:       "host HOST",
-			Short:     "a remote host",
+			Name:  "host",
+			Use:   "host HOST",
+			Short: "a remote HTTP or HTTPS host",
+			Long: `Use the host provider to query remote HTTP or HTTPS hosts. 
+
+Examples:
+  cnquery shell host <YOUR-DOMAIN-OR-IP>
+  cnspec scan host <YOUR-DOMAIN-OR-IP>
+
+Note:
+  If you don't provide a protocol, Mondoo assumes HTTPS.
+`,
 			MinArgs:   1,
 			MaxArgs:   1,
 			Discovery: []string{},

diff --git a/providers/os/config/config.go b/providers/os/config/config.go
@@ -32,9 +32,16 @@ var Config = plugin.Provider{
 	},
 	Connectors: []plugin.Connector{
 		{
-			Name:    "local",
-			Use:     "local",
-			Short:   "your local system",
+			Name:  "local",
+			Use:   "local",
+			Short: "your local system",
+			Long: `Use the local provider to query your local system. This is the default provider. There's no need to specify local in a command.  
+
+Examples:
+  cnquery shell
+  cnspec scan
+	cnspec scan -o json > FILENAME.json
+`,
 			MinArgs: 0,
 			MaxArgs: 0,
 			Discovery: []string{
@@ -59,9 +66,15 @@ var Config = plugin.Provider{
 			},
 		},
 		{
-			Name:    "ssh",
-			Use:     "ssh user@host",
-			Short:   "a remote system via SSH",
+			Name:  "ssh",
+			Use:   "ssh user@host",
+			Short: "a remote system via SSH",
+			Long: `Use the ssh provider to query remote systems using SSH.  
+
+Examples:
+  cnspec scan ssh USER@IP-ADDRESS --ask-pass
+  cnquery shell ssh USER@IP-ADDRESS --ask-pass
+`,
 			MinArgs: 1,
 			MaxArgs: 1,
 			Flags: []plugin.Flag{
@@ -110,9 +123,15 @@ var Config = plugin.Provider{
 			},
 		},
 		{
-			Name:    "winrm",
-			Use:     "winrm user@host",
-			Short:   "a remote system via WinRM",
+			Name:  "winrm",
+			Use:   "winrm user@host",
+			Short: "a remote system via WinRM",
+			Long: `Use the winrm provider to query remote systems using WinRM.  
+
+Examples:
+  cnspec scan winrm USER@HOST --ask-pass
+  cnquery shell winrm USER@HOST --ask-pass
+`,
 			MinArgs: 1,
 			MaxArgs: 1,
 			Flags: []plugin.Flag{
@@ -147,9 +166,15 @@ var Config = plugin.Provider{
 			},
 		},
 		{
-			Name:    "vagrant",
-			Use:     "vagrant host",
-			Short:   "a Vagrant host",
+			Name:  "vagrant",
+			Use:   "vagrant host",
+			Short: "a Vagrant host",
+			Long: `Use the vagrant provider to query Vagrant virtual machines.  
+
+Examples:
+  cnspec scan vagrant HOST
+  cnquery shell vagrant HOST
+`,
 			MinArgs: 1,
 			MaxArgs: 1,
 			Flags: []plugin.Flag{
@@ -169,9 +194,15 @@ var Config = plugin.Provider{
 			},
 		},
 		{
-			Name:    "container",
-			Use:     "container",
-			Short:   "a running container or container image",
+			Name:  "container",
+			Use:   "container",
+			Short: "a running container or container image",
+			Long: `Use the container provider to query running containers or container images.  
+
+Examples:
+  cnspec scan container ubuntu:latest
+  cnquery shell container ubuntu:latest
+`,
 			MinArgs: 1,
 			MaxArgs: 2,
 			Discovery: []string{
@@ -197,7 +228,7 @@ var Config = plugin.Provider{
 					Long:    "disable-cache",
 					Type:    plugin.FlagType_Bool,
 					Default: "false",
-					Desc:    "Disable the in-memory cache for images. WARNING: This will slow down scans significantly.",
+					Desc:    "Disable the in-memory cache for images. WARNING: This significantly slows scans.",
 				},
 				{
 					Long:    "container-proxy",
@@ -208,9 +239,19 @@ var Config = plugin.Provider{
 			},
 		},
 		{
-			Name:    "docker",
-			Use:     "docker",
-			Short:   "a running Docker container or Docker image",
+			Name:  "docker",
+			Use:   "docker",
+			Short: "a running Docker container, Docker image, or Dockerfile",
+			Long: `Use the docker provider to query running Docker containers or container images in public or private container registries using their registry name. Or scan a Dockerfile by specifying its path. 
+
+Examples:
+  cnspec scan docker <DOCKER-CONTAINER-ID>
+	cnspec scan docker file <FILEPATH>
+  cnspec scan docker ubuntu:latest
+  cnspec scan docker elastic/elasticsearch:7.2.0
+  cnspec scan docker gcr.io/google-containers/ubuntu:22.04
+  cnspec scan docker registry.access.redhat.com/ubi8/ubi
+`,
 			MinArgs: 1,
 			MaxArgs: 2,
 			Discovery: []string{
@@ -236,7 +277,7 @@ var Config = plugin.Provider{
 					Long:    "disable-cache",
 					Type:    plugin.FlagType_Bool,
 					Default: "false",
-					Desc:    "Disable the in-memory cache for images. WARNING: This will slow down scans significantly",
+					Desc:    "Disable the in-memory cache for images. WARNING: This significantly slows scans.",
 				},
 				{
 					Long:    "container-proxy",
@@ -251,6 +292,12 @@ var Config = plugin.Provider{
 			Aliases: []string{"fs"},
 			Use:     "filesystem PATH [flags]",
 			Short:   "a mounted file system target",
+			Long: `Use the filesystem provider to query mounted file systems. 
+
+Examples:
+  cnspec scan filesystem <MOUNT-PATH-TO-FILE-SYSTEM>
+	cnquery shell fs <MOUNT-PATH-TO-FILE-SYSTEM>
+`,
 			MinArgs: 0,
 			MaxArgs: 1,
 			Flags: []plugin.Flag{
@@ -264,34 +311,40 @@ var Config = plugin.Provider{
 			},
 		},
 		{
-			Name:    "device",
-			Use:     "device",
-			Short:   "a block device target",
+			Name:  "device",
+			Use:   "device",
+			Short: "a block device target",
+			Long: `Use the device provider to query block devices. 
+
+Examples:
+  cnspec scan device --lun <LOGICAL-UNIT-NUMBER>
+	cnquery shell device --device-name <NAME-OF-LINUX-DEVICE>
+`,
 			MinArgs: 0,
 			MaxArgs: 0,
 			Flags: []plugin.Flag{
 				{
 					Long:   "lun",
 					Type:   plugin.FlagType_String,
-					Desc:   "The logical unit number of the block device that should be scanned. Do not use together with --device-name or --serial-number",
+					Desc:   "The logical unit number of the block device. Do not use with --device-name or --serial-number",
 					Option: plugin.FlagOption_Hidden,
 				},
 				{
 					Long:   "device-name",
 					Type:   plugin.FlagType_String,
-					Desc:   "The target device to scan, e.g. /dev/sda. Supported only for Linux scanning. Do not use together with --lun or --serial-number",
+					Desc:   "The target device, e.g., /dev/sda. Supported only for Linux scanning. Do not use together with --lun or --serial-number",
 					Option: plugin.FlagOption_Hidden | plugin.FlagOption_Deprecated,
 				},
 				{
 					Long:   "device-names",
 					Type:   plugin.FlagType_List,
-					Desc:   "The target devices to scan, e.g. /dev/sda. Supported only for Linux scanning. Do not use together with --lun or --serial-number",
+					Desc:   "The target devices, e.g., /dev/sda. Supported only for Linux scanning. Do not use together with --lun or --serial-number",
 					Option: plugin.FlagOption_Hidden,
 				},
 				{
 					Long:   "serial-number",
 					Type:   plugin.FlagType_String,
-					Desc:   "The serial number of the block device that should be scanned. Supported only for Windows scanning. Do not use together with --device-name or --lun",
+					Desc:   "The serial number of the block device. Supported only for Windows scanning. Do not use together with --device-name or --lun",
 					Option: plugin.FlagOption_Hidden,
 				},
 				{

diff --git a/providers/terraform/config/config.go b/providers/terraform/config/config.go
@@ -21,10 +21,16 @@ var Config = plugin.Provider{
 	},
 	Connectors: []plugin.Connector{
 		{
-			Name:      "terraform",
-			Aliases:   []string{},
-			Use:       "terraform PATH",
-			Short:     "a Terraform HCL file or directory",
+			Name:    "terraform",
+			Aliases: []string{},
+			Use:     "terraform PATH",
+			Short:   "a Terraform HCL file or directory",
+			Long: `Use the terraform provider to query Terraform HCL files and directories. 
+
+Examples:
+  cnspec scan terraform <PATH-TO-HCL-FILE>
+	cnquery shell terraform <PATH-TO-DIRECTORY>
+`,
 			MinArgs:   1,
 			MaxArgs:   2,
 			Discovery: []string{},

diff --git a/providers/vcd/config/config.go b/providers/vcd/config/config.go
@@ -18,31 +18,33 @@ var Config = plugin.Provider{
 			Name:  "vcd",
 			Use:   "vcd [--user <user>] [--host <host>] [--organization <organization>] [--ask-pass] [--password <password>]",
 			Short: "a VMware Cloud Director installation",
-			Long: `vcd is designed for querying resources within for a VMware Cloud Director environment. VMware's 
-vCloud Director (vCD), a platform that facilitates the operation and management of virtual resources within
-a multi-tenant cloud environment.
+			Long: `Use the vcd provider to query resources in a VMware Cloud Director environment. The VMware Cloud Director platform facilitates the operation and management of virtual resources within a multi-tenant cloud environment.
+
+			Examples:
+			  cnquery shell vcd --user <USER-NAME> --host <HOST-NAME> --ask-pass
+				cnspec scan vcd --user <USER-NAME> --host <HOST-NAME> --password <PASSWORD>
 `,
 			Discovery: []string{},
 			Flags: []plugin.Flag{
 				{
 					Long:    "user",
 					Type:    plugin.FlagType_String,
 					Default: "",
-					Desc:    "vCloud Director user",
+					Desc:    "Cloud Director user",
 					Option:  plugin.FlagOption_Required,
 				},
 				{
 					Long:    "host",
 					Type:    plugin.FlagType_String,
 					Default: "",
-					Desc:    "vCloud Director host",
+					Desc:    "Cloud Director host",
 					Option:  plugin.FlagOption_Required,
 				},
 				{
 					Long:    "organization",
 					Type:    plugin.FlagType_String,
 					Default: "",
-					Desc:    "vCloud Director Organization (optional)",
+					Desc:    "Cloud Director Organization (optional)",
 				},
 				{
 					Long:        "ask-pass",

diff --git a/providers/vsphere/config/config.go b/providers/vsphere/config/config.go
@@ -20,6 +20,12 @@ var Config = plugin.Provider{
 			Name:  "vsphere",
 			Use:   "vsphere user@host",
 			Short: "a VMware vSphere installation",
+			Long: `Use the vsphere provider to query VMware vSphere installations. 
+
+Examples:
+  cnspec scan vsphere <USER>@<HOST> --askpass
+	cnquery shell vsphere <USER>@<HOST> --password <YOUR-PASSWORD>
+`,
 			Discovery: []string{
 				resources.DiscoveryApi,
 				resources.DiscoveryInstances,