From 42afb5114a2b2119d1db68c1ddd48aed6f161dd5 Mon Sep 17 00:00:00 2001
From: Letha <letha@mondoo.com>
Date: Mon, 7 Oct 2024 19:49:04 -0700
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=84=20=20Add=20long-form=20CLI=20help?=
 =?UTF-8?q?=20for=20a=20bunch=20of=20providers=20(#4724)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Add long-form help for a bunch of providers

* Change per @tas50 review

* Change per @tas50 review
---
 providers/ipmi/config/config.go   | 11 ++++++++---
 providers/mondoo/config/config.go | 14 +++++++++++---
 providers/okta/config/config.go   | 18 +++++++++++++-----
 providers/opcua/config/config.go  |  9 +++++----
 providers/shodan/config/config.go | 14 +++++++++++---
 5 files changed, 48 insertions(+), 18 deletions(-)

diff --git a/providers/ipmi/config/config.go b/providers/ipmi/config/config.go
index be629f922..d73c858c8 100644
--- a/providers/ipmi/config/config.go
+++ b/providers/ipmi/config/config.go
@@ -17,11 +17,16 @@ var Config = plugin.Provider{
 	Connectors: []plugin.Connector{
 		{
 			Name:  "ipmi",
-			Use:   "ipmi user@host",
+			Use:   "ipmi USER@HOST",
 			Short: "an IPMI interface",
-			Long: `ipmi is designed for querying resources via the Intelligent Platform Management Interface (IPMI).
-IPMI provides management and monitoring capabilities  independently of the host system's CPU,
+			Long: `Use the ipmi provider to query resources using the Intelligent Platform Management Interface (IPMI).
+
+IPMI provides management and monitoring capabilities independently of the host system's CPU,
 firmware (BIOS or UEFI), and operating system.
+
+Examples:
+  cnquery shell ipmi <user@host>
+	cnspec scan ipmi <user@host>
 `,
 			MinArgs:   1,
 			MaxArgs:   1,
diff --git a/providers/mondoo/config/config.go b/providers/mondoo/config/config.go
index 2ffbe577a..5b92ebb00 100644
--- a/providers/mondoo/config/config.go
+++ b/providers/mondoo/config/config.go
@@ -15,9 +15,17 @@ var Config = plugin.Provider{
 	ConnectionTypes: []string{provider.DefaultConnectionType},
 	Connectors: []plugin.Connector{
 		{
-			Name:      "mondoo",
-			Use:       "mondoo",
-			Short:     "Mondoo Platform",
+			Name:  "mondoo",
+			Use:   "mondoo",
+			Short: "Mondoo Platform",
+			Long: `Use the mondoo provider to query resources in Mondoo Platform.
+
+To query Mondoo Platform from a workstation, the workstation must be registered with Mondoo Platform. To learn how to register a workstation, read https://mondoo.com/docs/cnspec/cnspec-adv-install/registration/. 
+
+Examples:
+  cnquery shell mondoo
+	cnspec scan mondoo
+`,
 			MinArgs:   0,
 			MaxArgs:   4,
 			Discovery: []string{},
diff --git a/providers/okta/config/config.go b/providers/okta/config/config.go
index 589b29b12..385b2721b 100644
--- a/providers/okta/config/config.go
+++ b/providers/okta/config/config.go
@@ -16,22 +16,30 @@ var Config = plugin.Provider{
 	ConnectionTypes: []string{provider.ConnectionType},
 	Connectors: []plugin.Connector{
 		{
-			Name:      "okta",
-			Use:       "okta",
-			Short:     "an Okta organization",
+			Name:  "okta",
+			Use:   "okta",
+			Short: "an Okta organization",
+			Long: `Use the okta provider to query resources in an Okta organization.
+
+To query an Okta organization, you need the organization's domain and an API token to access that domain. To learn how, read https://mondoo.com/docs/cnquery/saas/okta/.
+
+Examples:
+  cnquery shell okta -organization <okta-domain> -token <api-token>
+	cnspec scan okta -organization <okta-domain> -token <api-token>
+`,
 			Discovery: []string{},
 			Flags: []plugin.Flag{
 				{
 					Long:    "organization",
 					Type:    plugin.FlagType_String,
 					Default: "",
-					Desc:    "The Okta organization to scan",
+					Desc:    "The domain of the Okta organization to scan",
 				},
 				{
 					Long:    "token",
 					Type:    plugin.FlagType_String,
 					Default: "",
-					Desc:    "Okta access token",
+					Desc:    "Access token for the Okta organization",
 				},
 			},
 		},
diff --git a/providers/opcua/config/config.go b/providers/opcua/config/config.go
index b1483d493..3a5c88fad 100644
--- a/providers/opcua/config/config.go
+++ b/providers/opcua/config/config.go
@@ -18,11 +18,12 @@ var Config = plugin.Provider{
 			Name:  "opcua",
 			Use:   "opcua [--endpoint <endpoint>]",
 			Short: "an OPC UA device",
-			Long: `opcua is designed for querying resources on an OPC UA (Open Platform 
-Communications Unified Architecture) server, a protocol facilitating machine-to-machine communications within 
-the realm of industrial automation.
-`,
+			Long: `Use the opcua provider to query resources on an Open Platform 
+Communications Unified Architecture (OPC UA) server or device. OPC UA is a protocol facilitating machine-to-machine communications within the realm of industrial automation.
 
+Example:
+  cnquery shell opcua --endpoint opc.tcp://<host>:<port>
+`,
 			Discovery: []string{},
 			Flags: []plugin.Flag{
 				{
diff --git a/providers/shodan/config/config.go b/providers/shodan/config/config.go
index 6d02d888b..67199423a 100644
--- a/providers/shodan/config/config.go
+++ b/providers/shodan/config/config.go
@@ -17,9 +17,17 @@ var Config = plugin.Provider{
 	ConnectionTypes: []string{provider.DefaultConnectionType},
 	Connectors: []plugin.Connector{
 		{
-			Name:    "shodan",
-			Use:     "shodan",
-			Short:   "a Shodan account",
+			Name:  "shodan",
+			Use:   "shodan",
+			Short: "a Shodan account",
+			Long: `Use the shodan provider to query domain and IP security information in the Shodan search engine. 
+
+If you set the SHODAN_TOKEN environment variable, you can omit the token flag.
+
+Examples:
+  cnquery shell shodan --token <api-token>
+	cnquery shell shodan --networks <ip-range> --discover hosts
+`,
 			MinArgs: 0,
 			MaxArgs: 2,
 			Discovery: []string{