From b50f987c37946dcee4579f5c6ce67e496734c12f Mon Sep 17 00:00:00 2001 From: Salim Afiune Maya Date: Mon, 27 Apr 2020 02:46:23 -0600 Subject: [PATCH] docs(cli): func comments and cmd style updates Signed-off-by: Salim Afiune Maya --- README.md | 2 +- cli/cmd/api.go | 1 + cli/cmd/cli_state.go | 44 +++++++++++++++++-------------- cli/cmd/cli_update_cmd.go | 2 ++ cli/cmd/cli_update_cmd_windows.go | 2 ++ cli/cmd/event.go | 6 +++-- cli/cmd/outputs.go | 2 +- cli/cmd/version.go | 7 +++-- cli/cmd/vulnerability.go | 15 ++++++----- 9 files changed, 48 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 5b0755bec..7846dd24b 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ C:\> iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubus Look at the [cli/](cli/) folder for more documentation. -## API Client ([`api`](api/)) +## Lacework API Client ([`api`](api/)) A Golang API client for interacting with the [Lacework API](https://support.lacework.com/hc/en-us/categories/360002496114-Lacework-API-). diff --git a/cli/cmd/api.go b/cli/cmd/api.go index 91ca4cac2..e47f98234 100644 --- a/cli/cmd/api.go +++ b/cli/cmd/api.go @@ -56,6 +56,7 @@ For a complete list of available API endpoints visit: ) func init() { + // add the api command rootCmd.AddCommand(apiCmd) apiCmd.Flags().StringVarP(&apiData, diff --git a/cli/cmd/cli_state.go b/cli/cmd/cli_state.go index 1ed48e4d1..27b77c4bc 100644 --- a/cli/cmd/cli_state.go +++ b/cli/cmd/cli_state.go @@ -130,7 +130,7 @@ func (c *cliState) VerifySettings() error { // NonInteractive turns off interactive mode, that is, no progress bars and spinners func (c *cliState) NonInteractive() { - cli.Log.Info("turning off interactive mode") + c.Log.Info("turning off interactive mode") c.nonInteractive = true } @@ -138,7 +138,7 @@ func (c *cliState) NonInteractive() { // into the cli state, make sure to run StopSpinner when you are done processing func (c *cliState) StartProgress(suffix string) { if c.nonInteractive { - cli.Log.Debugw("skipping spinner", + c.Log.Debugw("skipping spinner", "noninteractive", c.nonInteractive, "action", "start_progress", ) @@ -146,21 +146,21 @@ func (c *cliState) StartProgress(suffix string) { } // humans like spinners (^.^) - if cli.HumanOutput() { + if c.HumanOutput() { // make sure there is not a spinner already running - cli.StopProgress() + c.StopProgress() - cli.Log.Debug("starting spinner") - cli.spinner = spinner.New(spinner.CharSets[9], 100*time.Millisecond) - cli.spinner.Suffix = suffix - cli.spinner.Start() + c.Log.Debug("starting spinner") + c.spinner = spinner.New(spinner.CharSets[9], 100*time.Millisecond) + c.spinner.Suffix = suffix + c.spinner.Start() } } // StopProgress stops the running progress spinner, if any func (c *cliState) StopProgress() { if c.nonInteractive { - cli.Log.Debugw("skipping spinner", + c.Log.Debugw("skipping spinner", "noninteractive", c.nonInteractive, "action", "stop_progress", ) @@ -168,31 +168,35 @@ func (c *cliState) StopProgress() { } // humans like spinners (^.^) - if cli.HumanOutput() { - if cli.spinner != nil { - cli.Log.Debug("stopping spinner") - cli.spinner.Stop() - cli.spinner = nil + if c.HumanOutput() { + if c.spinner != nil { + c.Log.Debug("stopping spinner") + c.spinner.Stop() + c.spinner = nil } } } +// EnableJSONOutput enables the cli to display JSON output func (c *cliState) EnableJSONOutput() { - cli.Log.Info("switch output to json format") - cli.jsonOutput = true + c.Log.Info("switch output to json format") + c.jsonOutput = true } +// EnableJSONOutput enables the cli to display human readable output func (c *cliState) EnableHumanOutput() { - cli.Log.Info("switch output to human format") - cli.jsonOutput = false + c.Log.Info("switch output to human format") + c.jsonOutput = false } +// JSONOutput returns true if the cli is configured to display JSON output func (c *cliState) JSONOutput() bool { - return cli.jsonOutput + return c.jsonOutput } +// HumanOutput returns true if the cli is configured to siplay human readable output func (c *cliState) HumanOutput() bool { - return !cli.jsonOutput + return !c.jsonOutput } // loadStateFromViper loads parameters and environment variables diff --git a/cli/cmd/cli_update_cmd.go b/cli/cmd/cli_update_cmd.go index 7feb36cae..ffa311b90 100644 --- a/cli/cmd/cli_update_cmd.go +++ b/cli/cmd/cli_update_cmd.go @@ -19,6 +19,8 @@ package cmd +// UpdateCommand returns the command that a user should run to update the cli +// to the latest available version (unix specific command) func (c *cliState) UpdateCommand() string { return ` $ curl https://raw.githubusercontent.com/lacework/go-sdk/master/cli/install.sh | sudo bash diff --git a/cli/cmd/cli_update_cmd_windows.go b/cli/cmd/cli_update_cmd_windows.go index c87f56007..36b8bcdae 100644 --- a/cli/cmd/cli_update_cmd_windows.go +++ b/cli/cmd/cli_update_cmd_windows.go @@ -18,6 +18,8 @@ package cmd +// UpdateCommand returns the command that a user should run to update the cli +// to the latest available version (windows specific command) func (c *cliState) UpdateCommand() string { return ` C:\> Set-ExecutionPolicy Bypass -Scope Process -Force diff --git a/cli/cmd/event.go b/cli/cmd/event.go index 578064a18..40ac0b736 100644 --- a/cli/cmd/event.go +++ b/cli/cmd/event.go @@ -41,8 +41,10 @@ var ( eventListCmd = &cobra.Command{ Use: "list", Short: "list all events from a date range (default last 7 days)", - Long: `List all events from a data range, by default it displays the last -7 days, but you can specify a different time range.`, + Long: ` +List all events from a time range, by default this command displays the +events from the last 7 days, but it is possible to specify a different +time range.`, Args: cobra.NoArgs, RunE: func(_ *cobra.Command, _ []string) error { lacework, err := api.NewClient(cli.Account, diff --git a/cli/cmd/outputs.go b/cli/cmd/outputs.go index 40f9a602f..1cea00ecf 100644 --- a/cli/cmd/outputs.go +++ b/cli/cmd/outputs.go @@ -44,7 +44,7 @@ func (c *cliState) OutputHuman(format string, a ...interface{}) { } } -// OutputJSONString just like OutputJSON but passing a JSON string +// OutputJSONString is just like OutputJSON but from a JSON string func (c *cliState) OutputJSONString(s string) error { pretty, err := c.JsonF.Format([]byte(s)) if err != nil { diff --git a/cli/cmd/version.go b/cli/cmd/version.go index fb5ddbf06..6cdfcf629 100644 --- a/cli/cmd/version.go +++ b/cli/cmd/version.go @@ -44,8 +44,11 @@ var ( versionCmd = &cobra.Command{ Use: "version", Short: "print the Lacework CLI version", - Long: `Prints out the installed version of the Lacework CLI and checks for newer -versions available for update.`, + Long: ` +Prints out the installed version of the Lacework CLI and checks for newer +versions available for update. + +Set the environment variable 'LW_UPDATES_DISABLE=1' to avoid checking for updates.`, Args: cobra.NoArgs, Run: func(_ *cobra.Command, _ []string) { if cli.JSONOutput() { diff --git a/cli/cmd/vulnerability.go b/cli/cmd/vulnerability.go index abe76b41a..98e3e36ec 100644 --- a/cli/cmd/vulnerability.go +++ b/cli/cmd/vulnerability.go @@ -69,7 +69,7 @@ Then navigate to Settings > Integrations > Container Registry.`, // vulScanCmd represents the scan sub-command inside the vulnerability command vulScanCmd = &cobra.Command{ Use: "scan", - Short: "Manage on-demand vulnerability scans", + Short: "manage on-demand vulnerability scans", Long: `Request on-demand vulnerability scans and view the generated report. NOTE: Scans can take up to 15 minutes to return results.`, @@ -78,13 +78,13 @@ NOTE: Scans can take up to 15 minutes to return results.`, // vulScanRunCmd represents the run sub-command inside the scan vulnerability command vulScanRunCmd = &cobra.Command{ Use: "run ", - Short: "Request an on-demand vulnerability scan", - Long: `Request an on-demand vulnerability scan + Short: "request an on-demand vulnerability scan", + Long: `Request an on-demand vulnerability scan. Arguments: - container registry where the container image is published + container registry where the container image has been published repository name that contains the container image - either the tag or the image ID to scan (image_id format: sha256:1ee...1d3b)`, + either a tag or an image ID to scan (image_id format: sha256:1ee...1d3b)`, Args: cobra.ExactArgs(3), RunE: func(_ *cobra.Command, args []string) error { lacework, err := api.NewClient(cli.Account, @@ -139,7 +139,8 @@ Arguments: // vulScanShowCmd represents the show sub-command inside the scan vulnerability command vulScanShowCmd = &cobra.Command{ Use: "show ", - Short: "Return data about an on-demand vulnerability scan", + Short: "return results about an on-demand vulnerability scan", + Long: "Return results about an on-demand vulnerability scan.", Args: cobra.ExactArgs(1), RunE: func(_ *cobra.Command, args []string) error { lacework, err := api.NewClient(cli.Account, @@ -185,7 +186,7 @@ Arguments: // vulReportCmd represents the report sub-command inside the vulnerability command vulReportCmd = &cobra.Command{ Use: "report ", - Short: "Show vulnerability reports of a container image", + Short: "show vulnerability reports of a container image", Long: `Review vulnerability reports from container image scans that run previously either by the preriodic scan mechanism that Lacework runs every hour, or a requested on-demand vulnerability scan.