From e4ac43de11f0280f458200df7adc2866cffe45c1 Mon Sep 17 00:00:00 2001 From: misterpantz Date: Mon, 27 Jan 2025 15:33:03 -0800 Subject: [PATCH] Add long-form help for gcp, k8s, network, os, terraform, vcd, vsphere --- providers/gcp/config/config.go | 19 ++++- providers/k8s/config/config.go | 10 +++ providers/network/config/config.go | 15 +++- providers/os/config/config.go | 107 ++++++++++++++++++++------- providers/terraform/config/config.go | 14 +++- providers/vcd/config/config.go | 14 ++-- providers/vsphere/config/config.go | 6 ++ 7 files changed, 142 insertions(+), 43 deletions(-) diff --git a/providers/gcp/config/config.go b/providers/gcp/config/config.go index 9c9a87d9c0..9d0a0daba8 100644 --- 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 --credentials-path + cnspec scan gcp project --credentials-path + +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 + cnquery shell gcp project +`, MaxArgs: 2, Discovery: []string{ resources.DiscoveryOrganization, diff --git a/providers/k8s/config/config.go b/providers/k8s/config/config.go index 8b2deb80f3..f9d42cb209 100644 --- 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 +`, MinArgs: 0, MaxArgs: 1, Discovery: []string{ diff --git a/providers/network/config/config.go b/providers/network/config/config.go index 860487407e..dfbc845b8e 100644 --- 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 host", + Long: `Use the host provider to query remote hosts. + +Examples: + cnquery shell host + cnspec scan host + +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 index 1de16e8d45..aa19b5c8d3 100644 --- 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 vagrant 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 + cnspec scan docker file + 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 --path + cnquery shell fs --path +`, 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 + cnquery shell device --device-name +`, 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 index dbe539fc23..0d4871e9d0 100644 --- 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 + cnquery shell terraform +`, MinArgs: 1, MaxArgs: 2, Discovery: []string{}, diff --git a/providers/vcd/config/config.go b/providers/vcd/config/config.go index 2a89e60233..68aba05e8c 100644 --- a/providers/vcd/config/config.go +++ b/providers/vcd/config/config.go @@ -18,9 +18,11 @@ var Config = plugin.Provider{ Name: "vcd", Use: "vcd [--user ] [--host ] [--organization ] [--ask-pass] [--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 --host --ask-pass + cnspec scan vcd --user --host --password `, Discovery: []string{}, Flags: []plugin.Flag{ @@ -28,21 +30,21 @@ a multi-tenant cloud environment. 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 index df98d8621c..1007129ee7 100644 --- 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 @ --askpass + cnquery shell vsphere @ --password +`, Discovery: []string{ resources.DiscoveryApi, resources.DiscoveryInstances,