Merge pull request #261 from Axonius/feature/cli_update_settings_docs…

…_example

Adding examples for modifying settings using the CLI.

docs/main/usage_cli/common_examples/settings.rst

@@ -0,0 +1,16 @@
+.. include:: /main/.special.rst
+
+.. _settings_ex:
+
+Settings Examples
+###############################################
+
+These examples show the various ways that settings commands can be used. The examples
+only show individual options being used for the most part, but you can combine any
+number of these options to have the commands create powerful queries for you.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   settings_examples/ex*

docs/main/usage_cli/common_examples/settings_examples/ex1.rst

@@ -0,0 +1,76 @@
+.. include:: /main/.special.rst
+
+Viewing Sections and Sub-Sections
+###############################################
+
+There are a lot of settings that can be configured for the Axonius platform.
+These are seperated into three groups: ``settings-global``, ``settings-gui`` and `settings-lifecycle``.
+Inside of each group, settings are split further into sections and sub-sections. So before we can work
+with settings, we have to know what sections and sub-sections there are.
+
+In this example we are going to take a look at how to find the sections and sub-sections contained in
+the ``settings-global`` group.
+
+The simplest way to view all sections and sub-sections is to ask for everything and use a program to
+filter down what is returned.
+
+.. code:: shell
+
+    $ axonshell system settings-global get | grep "Section Name"
+
+    - Section Name: 'global_ssl'
+    - Section Name: 'certificate_verify_settings'
+    - Section Name: 'ssl_trust_settings'
+    - Section Name: 'csr_settings'
+    - Section Name: 'proxy_settings'
+    - Section Name: 'external_system_url_settings'
+    - Section Name: 'password_policy_settings'
+    - Section Name: 'password_reset_password'
+    - Section Name: 'password_brute_force_protection'
+    - Section Name: 'password_expiration_settings'
+    - Section Name: 'vault_settings'
+    --- Sub Section Name: 'akeyless_vault'
+    --- Sub Section Name: 'aws_secrets_manager_vault'
+    --- Sub Section Name: 'azure_key_vault'
+    --- Sub Section Name: 'beyond_trust_vault'
+    --- Sub Section Name: 'beyond_trust_password_safe_vault'
+    --- Sub Section Name: 'clickstudios_passwordstate_vault'
+    --- Sub Section Name: 'cyberark_vault'
+    --- Sub Section Name: 'gcp_secret_manager'
+    --- Sub Section Name: 'hashicorp_vault'
+    --- Sub Section Name: 'manageengine_pam360_vault'
+    --- Sub Section Name: 'thycotic_secret_server_vault'
+    - Section Name: 'email_settings'
+    --- Sub Section Name: 'smtpAuth'
+    --- Sub Section Name: 'oauthAuth'
+    - Section Name: 'syslog_settings'
+    - Section Name: 'https_log_settings'
+    - Section Name: 'opsgenie_settings'
+    - Section Name: 'jira_settings'
+    - Section Name: 'notifications_settings'
+    --- Sub Section Name: 'notifications_disk_space_percentage'
+    --- Sub Section Name: 'notifications_disk_space_gb'
+    - Section Name: 'correlation_settings'
+    --- Sub Section Name: 'correlation_devices_global_config'
+    --- Sub Section Name: 'correlation_devices_adapters_config'
+    --- Sub Section Name: 'correlation_users_global_config'
+    - Section Name: 'correlation_schedule'
+    - Section Name: 'reports_scheduler'
+    - Section Name: 'static_analysis_settings'
+    --- Sub Section Name: 'nvd_proxy_settings'
+    --- Sub Section Name: 'device_location_mapping'
+    --- Sub Section Name: 'mac_address_enrichment'
+    --- Sub Section Name: 'enrichment_settings'
+    - Section Name: 'aggregation_settings'
+    - Section Name: 'vulnerabilities_settings'
+    - Section Name: 'cache_settings'
+    - Section Name: 'refresh_rate'
+    - Section Name: 'getting_started_checklist'
+    - Section Name: 'data_sync_settings'
+    --- Sub Section Name: 'aws_s3_settings'
+    --- Sub Section Name: 'azure_storage_settings'
+    --- Sub Section Name: 'smb_settings'
+    --- Sub Section Name: 'ssh_settings'
+    - Section Name: 'api_settings'
+    - Section Name: 'restrict_permission_assignment'
+    - Section Name: 'export_csv_settings'

docs/main/usage_cli/common_examples/settings_examples/ex2.rst

@@ -0,0 +1,161 @@
+.. include:: /main/.special.rst
+
+Viewing Section and Sub-Section Values
+###############################################
+
+Now that we know how to see all the sections and sub-sections we can work with. Lets take a
+look at one and see how it is currently configured. For this example, lets take a look at
+``email_settings``. This section contains sub-sections for ``smtpAuth`` and oauthAuth``.
+
+.. code:: shell
+
+    $ axonshell system settings-global get | grep "Section Name"
+
+    ...
+    - Section Name: 'email_settings'
+    --- Sub Section Name: 'smtpAuth'
+    --- Sub Section Name: 'oauthAuth'
+    ...
+
+To take a look at how it is currently configured, we can run another simple command that will output
+the current settings in ``text`` format.
+
+.. code:: shell
+
+    $ axonshell system settings-global get-section --section "email_settings"
+
+    - Section Name: 'email_settings'
+    - Section Title: Global Settings: Email Settings
+
+        Name: enabled
+        Title: Send emails
+        Type: 'bool'
+        Value: enabled=True
+
+        Name: smtpHost
+        Title: Email host
+        Type: 'string'
+        Value: smtpHost='services.axonius.lan'
+
+        Name: smtpPort
+        Title: Port
+        Type: 'integer'
+        Value: smtpPort=25
+
+        Name: conditional
+        Title: SMTP Authentication type
+        Type: 'string'
+        Value: conditional='smtpAuth'
+
+        Name: smtpAuth
+        Title: Smtpauth
+        Type: 'array'
+        Value: smtpAuth={'smtpPassword': None, 'smtpUser': None}
+
+        Name: oauthAuth
+        Title: Oauthauth
+        Type: 'array'
+        Value: oauthAuth={'smtpAuthEmail': None, 'smtpClientID': None, 'smtpClientSecret': None, 'smtpRefreshToken': None, 'smtpoAuthURL': None}
+
+        Name: use_ssl
+        Title: Use SSL for connection
+        Type: 'string'
+        Value: use_ssl='Unencrypted'
+
+        Name: ca_file
+        Title: CA file
+        Type: 'file'
+        Value: ca_file=None
+
+        Name: cert_file
+        Title: Certificate file
+        Type: 'file'
+        Value: cert_file=None
+
+        Name: private_key
+        Title: Private key file
+        Type: 'file'
+        Value: private_key=None
+
+        Name: sender_address
+        Title: Sender address
+        Type: 'string'
+        Value: sender_address=None
+
+        Name: compress_email_attachments
+        Title: Compress email attachments
+        Type: 'bool'
+        Value: compress_email_attachments=False
+
+    --- Sub Section Name: 'smtpAuth'
+    --- Sub Section Title: Global Settings: Email Settings: Smtpauth
+
+          Name: smtpUser
+          Title: User name
+          Type: 'string'
+          Value: smtpUser=None
+
+          Name: smtpPassword
+          Title: Password
+          Type: 'string'
+          Value: smtpPassword=None
+
+    --- Sub Section Name: 'oauthAuth'
+    --- Sub Section Title: Global Settings: Email Settings: Oauthauth
+
+          Name: smtpAuthEmail
+          Title: OAuth authentication email
+          Type: 'string'
+          Value: smtpAuthEmail=None
+
+          Name: smtpClientID
+          Title: OAuth client ID
+          Type: 'string'
+          Value: smtpClientID=None
+
+          Name: smtpClientSecret
+          Title: OAuth client secret
+          Type: 'string'
+          Value: smtpClientSecret=None
+
+          Name: smtpRefreshToken
+          Title: OAuth refresh token
+          Type: 'string'
+          Value: smtpRefreshToken=None
+
+          Name: smtpoAuthURL
+          Title: OAuth URL
+          Type: 'string'
+          Value: smtpoAuthURL=None
+
+Like most of our commands, we provide multiple formats to work with the data in. By default viewing settings defaults
+to ``text`` mode as stated above but we can easily change that.
+
+.. code:: shell
+
+    $ axonshell system settings-global get-section --section "email_settings" \
+      --export-format json-config
+
+    {
+      "ca_file": null,
+      "cert_file": null,
+      "compress_email_attachments": false,
+      "conditional": "smtpAuth",
+      "enabled": false,
+      "oauthAuth": {
+        "smtpAuthEmail": null,
+        "smtpClientID": null,
+        "smtpClientSecret": null,
+        "smtpRefreshToken": null,
+        "smtpoAuthURL": null
+      },
+      "private_key": null,
+      "sender_address": "system@axonius.com",
+      "smtpAuth": {
+        "smtpPassword": null,
+        "smtpUser": null
+      },
+      "smtpHost": null,
+      "smtpPort": null,
+      "use_ssl": "Unencrypted"
+    }

docs/main/usage_cli/common_examples/settings_examples/ex3.rst

@@ -0,0 +1,111 @@
+.. include:: /main/.special.rst
+
+Modifying Values
+###############################################
+
+Viewing settings is all well and good but modifying settings is even better.
+You are able to modify full sections at once or individual sub-sections. In both cases they can
+be updated via either command line parameters or using a json file. The related commands are ``update-section``,
+``update-section-from-json``, ``update-sub-section`` and ``update-sub-section-from-json`` as seen here.
+
+.. code:: shell
+
+    $ axonshell system settings-global --help
+
+    Usage: axonshell system settings-global [OPTIONS] COMMAND [ARGS]...
+
+      Group: Global Settings.
+
+    Options:
+      --help  Show this message and exit.
+
+    Commands:
+      configure-destroy             Enable or disable dangerous API endpoints.
+      get                           Get all settings.
+      get-section                   Get settings for a section.
+      get-sub-section               Get settings for a subsection.
+      update-section                Update a section from arguments.
+      update-section-from-json      Update a section from a JSON file.
+      update-sub-section            Update a subsection from arguments.
+      update-sub-section-from-json  Update a subsection from a JSON file.
+
+If you are looking to update a section or sub-section using only command line parameters, one of the commands
+you could use would be the ``update-sub-section`` command.
+
+.. code:: shell
+
+    $ axonshell system settings-global update-sub-section --help
+
+    Usage: axonshell system settings-global update-sub-section
+               [OPTIONS]
+
+      Update a subsection from arguments.
+
+    Options:
+      -u, --url URL                   URL of an Axonius instance  [env var:
+                                      AX_URL; required]
+      -k, --key KEY                   API Key (or username if credentials=True) of
+                                      user in an Axonius instance  [env var:
+                                      AX_KEY; required]
+      -s, --secret SECRET             API Secret (or password if credentials=True)
+                                      of user in an Axonius instance  [env var:
+                                      AX_SECRET; required]
+      -xf, --export-format [json-full|json-config|str]
+                                      Format of to export data in  [env var:
+                                      AX_EXPORT_FORMAT; default: str]
+      -se, --section TEXT             Settings section internal name (not title)
+                                      [env var: AX_SECTION; required]
+      -sb, --sub-section TEXT         Settings sub section internal name (not
+                                      title)  [env var: AX_SUB_SECTION; required]
+      -c, --config SPLIT_EQUALS       Configuration keys in the form of key=value
+                                      (multiples)  [env var: AX_CONFIG]
+      --help                          Show this message and exit.
+
+An example might look like this:
+
+.. code:: shell
+
+    $ axonshell system settings-global update-sub-section --section "email_settings" \
+    --config "sender_address=no-reply@yourdomain.com"
+
+To update a section or sub-section using json from a file you could use the ``update-sub-section-json`` command.
+
+.. code:: shell
+
+    $ axonshell system settings-global update-sub-section-from-json --help
+
+    Usage: axonshell system settings-global update-sub-section-from-json
+               [OPTIONS]
+
+      Update a subsection from a JSON file.
+
+    Options:
+      -u, --url URL                   URL of an Axonius instance  [env var:
+                                      AX_URL; required]
+      -k, --key KEY                   API Key (or username if credentials=True) of
+                                      user in an Axonius instance  [env var:
+                                      AX_KEY; required]
+      -s, --secret SECRET             API Secret (or password if credentials=True)
+                                      of user in an Axonius instance  [env var:
+                                      AX_SECRET; required]
+      -xf, --export-format [json-full|json-config|str]
+                                      Format of to export data in  [env var:
+                                      AX_EXPORT_FORMAT; default: str]
+      -se, --section TEXT             Settings section internal name (not title)
+                                      [env var: AX_SECTION; required]
+      -sb, --sub-section TEXT         Settings sub section internal name (not
+                                      title)  [env var: AX_SUB_SECTION; required]
+      -if, --input-file FILENAME      File to read (from path or piped via STDIN)
+                                      [env var: AX_INPUT_FILE; default: -]
+      --help                          Show this message and exit.
+
+Using what you learned from the previous chapter, you could get the config for a sub-section in ``json-config`` format
+and save it in a file. Then update that file to the desired configuration. So if you wanted to update the sub-section
+``smtpAuth`` it would look something like this:
+
+.. code:: shell
+
+    $ axonshell system settings-global update-sub-section-from-json --section "email_settings" \
+    --sub-section "smtpAuth" --input-file "./smtp_auth_settings.json"
+
+Where ``smtp_auth_settings.json`` would be a file containing the json object you wanted to set that sub-section to.

docs/main/usage_cli/common_examples/settings_examples/notes.rst

@@ -0,0 +1,7 @@
+.. include:: /main/.special.rst
+
+Notes
+==========================================
+
+.. note::
+