feat: Auto docs generation for the Lacework CLI (#616)

* feat: add headers to CLI documentation * chore: ran make generate-docs * docs: add line after injecting headers * docs(cli): multiple style corrections * feat(cli): add docs command to auto generate docs * docs: Updating support links to docs.lacework.com * docs: remove title from markdown files * docs: last updates before releasing Signed-off-by: Salim Afiune Maya <[email protected]> Co-authored-by: Ben Radstone <[email protected]>
lacework · Nov 18, 2021 · 81b7fdb · 81b7fdb
1 parent 432104f
commit 81b7fdb
Show file tree

Hide file tree

Showing 116 changed files with 755 additions and 288 deletions.
diff --git a/cli/cmd/access_token.go b/cli/cmd/access_token.go
@@ -34,7 +34,7 @@ var (
 	// accessTokenCmd represents the access-token command
 	accessTokenCmd = &cobra.Command{
 		Use:   "access-token",
-		Short: "generate temporary API access tokens",
+		Short: "Generate temporary API access tokens",
 		Long: `Generates a temporary API access token that can be used to access the
 Lacework API. The token will be valid for the duration that you specify.`,
 		Args: cobra.NoArgs,

diff --git a/cli/cmd/account.go b/cli/cmd/account.go
@@ -27,7 +27,7 @@ var (
 	accountCmd = &cobra.Command{
 		Use:     "account",
 		Aliases: []string{"accounts", "acc"},
-		Short:   "manage accounts in an organization (org admins only)",
+		Short:   "Manage accounts in an organization (org admins only)",
 		Long: `Manage accounts inside your Lacework organization.
 
 An organization can contain multiple accounts so you can also manage components
@@ -37,15 +37,15 @@ and can easily switch between them.
 
 To enroll your Lacework account in an organization follow the documentation:
 
-  https://support.lacework.com/hc/en-us/articles/360041727394-Organization-Overview
+  https://docs.lacework.com/organization-overview
     `,
 	}
 
 	// accountListCmd represents the list command inside the account command
 	accountListCmd = &cobra.Command{
 		Use:     "list",
 		Aliases: []string{"ls"},
-		Short:   "list all accounts",
+		Short:   "List all accounts",
 		Long:    `List all accounts in your organization.`,
 		Args:    cobra.NoArgs,
 		RunE: func(_ *cobra.Command, _ []string) error {

diff --git a/cli/cmd/agent.go b/cli/cmd/agent.go
@@ -48,7 +48,7 @@ var (
 
 	agentCmd = &cobra.Command{
 		Use:   "agent",
-		Short: "manage Lacework agents",
+		Short: "Manage Lacework agents",
 		Long: `Manage agents and agent access tokens in your account.
 
 To analyze application, host, and user behavior, Lacework uses a lightweight agent,
@@ -57,13 +57,13 @@ agent requires minimal system resources and runs on most 64-bit Linux distributi
 
 For a complete list of supported operating systems, visit:
 
-    https://support.lacework.com/hc/en-us/articles/360005230014-Supported-Operating-Systems`,
+  https://docs.lacework.com/supported-operating-systems`,
 	}
 
 	agentTokenCmd = &cobra.Command{
 		Use:     "token",
 		Aliases: []string{"tokens"},
-		Short:   "manage agent access tokens",
+		Short:   "Manage agent access tokens",
 		Long: `Manage agent access tokens in your account.
 
 Agent tokens should be treated as secret and not published. A token uniquely identifies
@@ -74,52 +74,49 @@ complete, the old token can safely be disabled without interrupting Lacework ser
 
 	agentTokenListCmd = &cobra.Command{
 		Use:   "list",
-		Short: "list all agent access tokens",
-		Long:  `List all agent access tokens.`,
+		Short: "List all agent access tokens",
 		Args:  cobra.NoArgs,
 		RunE:  listAgentTokens,
 	}
 
 	agentTokenCreateCmd = &cobra.Command{
 		Use:   "create <name> [description]",
-		Short: "create a new agent access token",
-		Long:  `Create a new agent access token.`,
+		Short: "Create a new agent access token",
 		Args:  cobra.RangeArgs(1, 2),
 		RunE:  createAgentToken,
 	}
 
 	agentTokenShowCmd = &cobra.Command{
 		Use:   "show <token>",
-		Short: "show details about an agent access token",
-		Long:  `Show details about an agent access token.`,
+		Short: "Show details about an agent access token",
 		Args:  cobra.ExactArgs(1),
 		RunE:  showAgentToken,
 	}
 
 	agentTokenUpdateCmd = &cobra.Command{
 		Use:   "update <token>",
-		Short: "update an agent access token",
+		Short: "Update an agent access token",
 		Long: `Update an agent access token.
 
 To update the token name and description:
 
-    $ lacework agent token update <token> --name dev --description "k8s deployment for dev"
+    lacework agent token update <token> --name dev --description "k8s deployment for dev"
 
 To disable a token:
 
-    $ lacework agent token update <token> --disable
+    lacework agent token update <token> --disable
 
 To enable a token:
 
-    $ lacework agent token update <token> --enable`,
+    lacework agent token update <token> --enable`,
 		Args: cobra.ExactArgs(1),
 		RunE: updateAgentToken,
 	}
 
 	// TODO hidden for now
 	agentListCmd = &cobra.Command{
 		Use:    "list",
-		Short:  "list all hosts with a running agent",
+		Short:  "List all hosts with a running agent",
 		Long:   `List all hosts that have a running agent in your environment`,
 		Hidden: true,
 		RunE:   listAgents,
@@ -128,7 +125,7 @@ To enable a token:
 	// TODO hidden for now
 	agentGenerateCmd = &cobra.Command{
 		Use:    "generate",
-		Short:  "generate agent deployment scripts",
+		Short:  "Generate agent deployment scripts",
 		Long:   `TBA`,
 		Hidden: true,
 		RunE: func(_ *cobra.Command, _ []string) error {
@@ -138,7 +135,7 @@ To enable a token:
 
 	agentInstallCmd = &cobra.Command{
 		Use:   "install <[user@]host[:port]>",
-		Short: "install the datacollector agent on a remote host",
+		Short: "Install the datacollector agent on a remote host",
 		Args:  cobra.ExactArgs(1),
 		Long: `For single host installation of the Lacework agent via Secure Shell (SSH).
 
@@ -147,21 +144,21 @@ launched to help gather the necessary authentication information to access the r
 
 To authenticate to the remote host with a username and password.
 
-    $ lacework agent install <host> --ssh_username <your-user> --ssh_password <secret>
+    lacework agent install <host> --ssh_username <your-user> --ssh_password <secret>
 
 To authenticate to the remote host with an identity file instead.
 
-    $ lacework agent install <user@host> -i /path/to/your/key
+    lacework agent install <user@host> -i /path/to/your/key
 
 To provide an agent access token of your choice, use the command 'lacework agent token list',
 select a token and pass it to the '--token' flag.
 
-    $ lacework agent install <user@host> -i /path/to/your/key --token <token>
+    lacework agent install <user@host> -i /path/to/your/key --token <token>
 
 To authenticate to the remote host on a non-standard SSH port use the '--ssh_port' flag or
 pass it directly via the argument.
 
-    $ lacework agent install <user@host:port>
+    lacework agent install <user@host:port>
     `,
 		RunE: installRemoteAgent,
 	}

diff --git a/cli/cmd/alert_rules.go b/cli/cmd/alert_rules.go
@@ -37,9 +37,11 @@ var (
 	alertRulesCommand = &cobra.Command{
 		Use:     "alert-rule",
 		Aliases: []string{"alert-rules", "ar"},
-		Short:   "manage alert rules",
+		Short:   "Manage alert rules",
 		Long: `Manage alert rules to route events to the appropriate people or tools.		
+
 An alert rule has three parts:
+
   1. Alert channel(s) that should receive the event notification
   2. Event severity and categories to include
   3. Resource group(s) containing the subset of your environment to consider
@@ -50,7 +52,7 @@ An alert rule has three parts:
 	alertRulesListCommand = &cobra.Command{
 		Use:     "list",
 		Aliases: []string{"ls"},
-		Short:   "list all alert rules",
+		Short:   "List all alert rules",
 		Long:    "List all alert rules configured in your Lacework account.",
 		Args:    cobra.NoArgs,
 		RunE: func(_ *cobra.Command, _ []string) error {
@@ -90,7 +92,7 @@ Then navigate to Settings > Alert Rules.
 	// show command is used to retrieve a lacework alert rule by resource id
 	alertRulesShowCommand = &cobra.Command{
 		Use:   "show",
-		Short: "show an alert rule by id",
+		Short: "Show an alert rule by id",
 		Long:  "Show a single alert rule by it's ID.",
 		Args:  cobra.ExactArgs(1),
 		RunE: func(_ *cobra.Command, args []string) error {
@@ -119,7 +121,7 @@ Then navigate to Settings > Alert Rules.
 	// delete command is used to remove a lacework alert rule by resource id
 	alertRulesDeleteCommand = &cobra.Command{
 		Use:   "delete",
-		Short: "delete a alert rule",
+		Short: "Delete a alert rule",
 		Long:  "Delete a single alert rule by it's ID.",
 		Args:  cobra.ExactArgs(1),
 		RunE: func(_ *cobra.Command, args []string) error {
@@ -135,8 +137,7 @@ Then navigate to Settings > Alert Rules.
 	// create command is used to create a new lacework alert rule
 	alertRulesCreateCommand = &cobra.Command{
 		Use:   "create",
-		Short: "create a new alert rule",
-		Long:  "Creates a new single alert rule.",
+		Short: "Create a new alert rule",
 		RunE: func(_ *cobra.Command, args []string) error {
 			if !cli.InteractiveMode() {
 				return errors.New("interactive mode is disabled")

diff --git a/cli/cmd/api.go b/cli/cmd/api.go
@@ -38,10 +38,10 @@ var (
 	// apiCmd represents the api command
 	apiCmd = &cobra.Command{
 		Use:   "api <method> <path>",
-		Short: "helper to call Lacework's API",
+		Short: "Helper to call Lacework's API",
 		Long: `Use this command as a helper to call any available Lacework API v1 & v2 endpoint.
 
-== For APIv1 ==
+### For APIv1
 
 To list all integrations configured in your account:
 
@@ -51,7 +51,7 @@ For a complete list of available API v1 endpoints visit:
 
     https://<ACCOUNT>.lacework.net/api/v1/external/docs
 
-== For APIv2 ==
+### For APIv2
 
 To list all available Lacework schema types:
 

diff --git a/cli/cmd/compliance.go b/cli/cmd/compliance.go
@@ -63,7 +63,7 @@ var (
 	complianceCmd = &cobra.Command{
 		Use:     "compliance",
 		Aliases: []string{"comp"},
-		Short:   "manage compliance reports",
+		Short:   "Manage compliance reports",
 		Long: `Manage compliance reports for Google, Azure, or AWS cloud providers.
 
 Lacework cloud security platform provides continuous Compliance monitoring against
@@ -72,7 +72,7 @@ HIPAA benchmark standards.
 
 Get started by integrating one or more cloud accounts using the command:
 
-    $ lacework integration create
+    lacework integration create
 
 If you prefer to configure the integration via the WebUI, log in to your account at:
 
@@ -82,89 +82,89 @@ Then navigate to Settings > Integrations > Cloud Accounts.
 
 Use the following command to list all available integrations in your account:
 
-    $ lacework integrations list
+    lacework integrations list
 `,
 	}
 
 	// complianceAzureCmd represents the azure sub-command inside the compliance command
 	complianceAzureCmd = &cobra.Command{
 		Use:     "azure",
 		Aliases: []string{"az"},
-		Short:   "compliance for Azure Cloud",
+		Short:   "Compliance for Azure Cloud",
 		Long: `Manage compliance reports for Azure Cloud.
 
 To list all Azure Tenants configured in your account:
 
-    $ lacework compliance azure list-tenants
+    lacework compliance azure list-tenants
 
 To list all Azure Subscriptions from a Tenant, use the command:
 
-    $ lacework compliance azure list-subscriptions <tenant_id>
+    lacework compliance azure list-subscriptions <tenant_id>
 
 To get the latest Azure compliance assessment report, use the command:
 
-    $ lacework compliance azure get-report <tenant_id> <subscriptions_id>
+    lacework compliance azure get-report <tenant_id> <subscriptions_id>
 
 These reports run on a regular schedule, typically once a day.
 
 To run an ad-hoc compliance assessment use the command:
 
-    $ lacework compliance azure run-assessment <tenant_id>
+    lacework compliance azure run-assessment <tenant_id>
 `,
 	}
 
 	// complianceGcpCmd represents the gcp sub-command inside the compliance command
 	complianceGcpCmd = &cobra.Command{
 		Use:     "google",
 		Aliases: []string{"gcp"},
-		Short:   "compliance for Google Cloud",
+		Short:   "Compliance for Google Cloud",
 		Long: `Manage compliance reports for Google Cloud.
 
 To get the latest GCP compliance assessment report, use the command:
 
-    $ lacework compliance gcp get-report <organization_id> <project_id>
+    lacework compliance gcp get-report <organization_id> <project_id>
 
 These reports run on a regular schedule, typically once a day.
 
 To find out which GCP organizations/projects are connected to your
 Lacework account, use the following command:
 
-    $ lacework integrations list --type GCP_CFG
+    lacework integrations list --type GCP_CFG
 
 Then, choose one integration, copy the GUID and visualize its details
 using the command:
 
-    $ lacework integration show <int_guid>
+    lacework integration show <int_guid>
 
 To list all GCP projects from an organization, use the command:
 
-    $ lacework compliance gcp list-projects <organization_id>
+    lacework compliance gcp list-projects <organization_id>
 
 To run an ad-hoc compliance assessment use the command:
 
-    $ lacework compliance gcp run-assessment <org_or_project_id>
+    lacework compliance gcp run-assessment <org_or_project_id>
 `,
 	}
 
 	// complianceAwsCmd represents the aws sub-command inside the compliance command
 	complianceAwsCmd = &cobra.Command{
 		Use:   "aws",
-		Short: "compliance for AWS",
+		Short: "Compliance for AWS",
 		Long: `Manage compliance reports for Amazon Web Services (AWS).
 
 To list all AWS accounts configured in your account:
 
-    $ lacework compliance aws list-accounts
+    lacework compliance aws list-accounts
 
 To get the latest AWS compliance assessment report:
 
-    $ lacework compliance aws get-report <account_id>
+    lacework compliance aws get-report <account_id>
 
 These reports run on a regular schedule, typically once a day.
 
 To run an ad-hoc compliance assessment:
 
-    $ lacework compliance aws run-assessment <account_id>
+    lacework compliance aws run-assessment <account_id>
 `,
 	}
 )