cgxsh 1.0.2b1

Command-line access to the controller-based CloudGenix ION Troubleshooting Toolkit.

cgxsh (Preview)

CloudGeniX SHell (cgxsh)

Command-line access to the controller-based CloudGenix ION Troubleshooting Toolkit.

WARNING

As of 6/2023, Using username/password for controller login is DEPRECATED. This method has not been removed from cgxsh as of version 1.0.2b1. This may still function for specific legacy customers/accounts.

Please switch to AUTH_TOKEN controller login as soon as possible. A future update will add support for Prisma SASE TSG/Service Accounts, which will be the recommended authentication mode for future use.

Synopsis

The cgxsh application is designed to allow a CloudGenix customer to replace a lot of the device-specific troubleshooting traditionally performed via SSH with a cloud-based connectivity model.

This utility attempts to behave "ssh-like", but there are fundamental differences.

This utility should support Windows (Win 10 or higher) and Mac/Linux systems.

Requirements

• Active CloudGenix Account
• Python >=3.10
• CloudGenix IONs running 5.2.1+ Software
• Python modules:
  • cloudgenix - https://github.com/CloudGenix/sdk-python
  • websockets - https://websockets.readthedocs.io/en/stable/
  • fuzzywuzzy - https://github.com/seatgeek/fuzzywuzzy/
  • pyyaml - https://pyyaml.org/wiki/PyYAMLDocumentation
  • tabulate - https://github.com/astanin/python-tabulate
  • cryptography - https://github.com/pyca/cryptography

Installation

• Via PIP as simple as pip install cgxsh

Commands/Features

cgxsh

• SSH-replacement console utility using CloudGenix Cloud Controller
• Simple commandline use: cgxsh "Portland ION"
• Interactive session by default, but specific commands and exit support too: cgxsh "Portland ION" "set paging off" "dump lldp all"
• Multi-tenant ESP/MSP support: cgxsh "Device_name"@"Tenant_Name"
• Configuration file with Multi-tenant support and optional Encryption to store credential(s)
• Fuzzy matching:

  edwards-mbp-pro:cgxsh aaron$ cgxsh "Portland ION"
  No match for Portland ION, best guesses:
    1) Portland Sales Office ION, (86%)
    2) ION2K-A, (54%)
    3) ION2K-B, (54%)
    4) DHL-1, (36%)
    5) MAD-7K-1, (36%)
    6) MAD-7K-2, (36%)
    7) MAN-3K-1, (36%)
  Select a number, or any other key to exit: 1
  

• Escape command menu for operations while connected:

  Portland Sales Office ION#  
  
  cgxsh> ?
  Commands are:
      send            Send special characters (help send for more)
      sdkdebug        Enable/Disable API/WebSocket debug messages (help sdkdebug for more)
      verbosity       Change cgxsh message verbosity (help verbosity for more)
      sessions        View active Toolkit Websocket Sessions (help sessions for more)
      sessions_kill   View and kill/close active Toolkit Websocket Sessions (help sessions_kill for more)
      quit            Close the connection and exit.
      close           Close the connection and exit.
      exit            Close the connection and exit.
      help            Additional help on sub commands. eg: help <command>
      
      Pressing <enter> on empty command line will return you to session.
      
  cgxsh> 
  

cgxsh_generic_ws

• Generic CloudGenix Websocket client to manage and experiment with Subscriptions.
• CloudGenix-required keepalive handling
• JSON output formatting.

cgxsh_create_defaultconfig

• Creates default cgxsh config (in $HOME/.cgxsh/config.yml)

cgxsh_edit_config

• Launches editor to edit cgxsh config.
  • Mac/Linux: Default /usr/bin/vi
  • Windows: Default notepad.exe
• Handles decryption/re-encryption of configuration, if encrypted.

cgxsh_decrypt_config

• Allows for decryption cgxsh configuration, if desired.

cgxsh_encrypt_config

• Encrypts cgxsh configuration, if not already encrypted.

License

MIT

Version

Version	Build	Changes
1.0.2	b1	Support for Python 3.10+, Websockets 12.0+ (Github issue #3)
1.0.1	b1	Fix for Github issues #1 and #2
1.0.0	b1	Initial Release
0.0.1	b1	Placeholder for future release.

(Optional) Environment Variables

• AUTH_TOKEN or X_AUTH_TOKEN: CloudGenix Controller Authentication Token (overrides configuration files)
• CGXSH_CONFIG_PASSWORD: Password for loading encrypted cgxsh configuration.

Usage info and examples.

Connecting to an ION with fuzzy name match and no configuration info saved

cgxsh \<ION name or ID>

edwards-mbp-pro:cgxsh aaron$ cgxsh "Portland ION"
controller login: [e-mail]
controller password: 

No match for Portland ION, best guesses:
  1) Portland Sales Office ION, (86%)
  2) ION2K-A, (54%)
  3) ION2K-B, (54%)
  4) MAN-3K-1, (36%)
  5) MAD-7K-2, (36%)
  6) MAD-7K-1, (36%)
  7) DHL-1, (36%)
Select a number, or any other key to exit: 1
Connecting to Portland Sales Office ION (15608897741660166).
Connected to 15608897741660166.
Escape character is '^]'.
ec2683ee-0d9c-8a64-3467-55121bb8a672 login: aaron
Password: 
Last login: Tue Dec 17 22:47:18 UTC 2019 on pts/0
 
Portland Sales Office ION# dump standingalarms 

Code		:	NETWORK_VPNPEER_UNREACHABLE
Ident		:	15608901339660208
Severity	:	minor
Raised		:	2019-12-12 20:54:44.834 +0000 UTC (122h6m8.469335222s ago)
Correlation ID	:	F70lP6T9
 vpn_link_id	:	15608901339570207
 al_id		:	15608896659530120

Portland Sales Office ION#  

Connecting to an ION with exact name match and controller/device configuration in config file

cgxsh \<ION name or ID>

edwards-mbp-pro:cgxsh aaron$ cgxsh "Portland Sales Office ION"
Connecting to Portland Sales Office ION (15608897741660166).
Connected to 15608897741660166.
Escape character is '^]'.

Last login: Tue Dec 17 22:52:46 UTC 2019 on pts/0
 
Portland Sales Office ION# dump standingalarms

Code		:	NETWORK_VPNPEER_UNREACHABLE
Ident		:	15608901339660208
Severity	:	minor
Raised		:	2019-12-12 20:54:44.834 +0000 UTC (122h6m8.469335222s ago)
Correlation ID	:	F70lP6T9
 vpn_link_id	:	15608901339570207
 al_id		:	15608896659530120

Portland Sales Office ION#  

Connecting to an ION on a sub-tenant via an ESP/MSP account with saved per-sub-tenant configurations

cgxsh \<ION name or ID>

edwards-mbp-pro:cgxsh aaron$ cgxsh "Portland Sales Office ION"@MyCustomerClientZ 
No match for MyCustomerClientZ, best guesses:
  1) MyCustomerClientA, (90%)
  2) CustomerClientB, (22%)
  3) CustomerClientC, (22%)
  4) CustomerClientD, (22%)
  5) CustomerClientE, (22%)
  6) CustomerClientF, (22%)
Select a number, or any other key to exit: 1

Connecting to Client MyCustomerClientA (MyCustomerClient_canonicalname).
Connecting to Portland Sales Office ION (15608897741660166).
Connected to 15608897741660166.
Escape character is '^]'.

Last login: Tue Dec 17 22:52:46 UTC 2019 on pts/0
 
Portland Sales Office ION# dump standingalarms

Code		:	NETWORK_VPNPEER_UNREACHABLE
Ident		:	15608901339660208
Severity	:	minor
Raised		:	2019-12-12 20:54:44.834 +0000 UTC (122h6m8.469335222s ago)
Correlation ID	:	F70lP6T9
 vpn_link_id	:	15608901339570207
 al_id		:	15608896659530120

Portland Sales Office ION#  

Managing connected cgxsh/web toolkit users to the current ION

Press escape char (CTRL-]) during cgxsh session

Portland Sales Office ION#  

cgxsh> ?
Commands are:
    send            Send special characters (help send for more)
    sdkdebug        Enable/Disable API/WebSocket debug messages (help sdkdebug for more)
    verbosity       Change cgxsh message verbosity (help verbosity for more)
    sessions        View active Toolkit Websocket Sessions (help sessions for more)
    sessions_kill   View and kill/close active Toolkit Websocket Sessions (help sessions_kill for more)
    quit            Close the connection and exit.
    close           Close the connection and exit.
    exit            Close the connection and exit.
    help            Additional help on sub commands. eg: help <command>
    
    Pressing <enter> on empty command line will return you to session.
    
cgxsh> sessions_kill element
Toolkit Sessions:
  Index  Element                    Operator                  Age       State                                  Session ID
-------  -------------------------  ------------------------  --------  -------  ----------------------------------------
      1  Portland Sales Office ION  [e-mail]      1h36m12s  active   1576618422757015099992703857847609972162
      2  Portland Sales Office ION  [e-mail]  9m9s      active   1576623645452007700007702497325448497534
Total: 2
Enter Index to remove (range for multiple (eg. 1,3,5-10), or x to exit: 2
Planning to end the following sessions (index): 2.
Confirm? (y/n): y
Ended session 2 to Portland Sales Office ION.

cgxsh> 
Portland Sales Office ION# 

Encrypting a clear-text configuration.

edwards-mbp-pro:cgxsh aaron$ cgxsh_encrypt_config 
Enter password to encrypt file: 
Confirm file encryption password: 
Saving encrypted configuration: Done.
edwards-mbp-pro:cgxsh aaron$ 

Default config.yml template

---
type: cgxsh
version: 1.0

# This section allows you to specify a default AUTH_TOKEN, DEVICE_USER and DEVICE_PASSWORD. These will be used
# by default if others are not specified.
#
# For Controller authentication, AUTH_TOKEN is used first (if present.) If no AUTH_TOKEN, CONTROLLER_USER and 
# CONTROLLER_PASSWORD are used. If those are missing or fail, login will be prompted.
# 
# If the DEVICE_USER or DEVICE_PASSWORD fails, you will be prompted to finish logging in when connecting to the device.

DEFAULT:
    AUTH_TOKEN:
    CONTROLLER_USER:
    CONTROLLER_PASSWORD:
    DEVICE_USER: 
    DEVICE_PASSWORD: 

# If you have a CloudGenix MSP/ESP portal account, you can specify the device access credentials on a per-client
# basis. If the client name is not an exact match, the credentials will not be used.
#
# Note: MSP/ESP client attachment requires DEFAULT: CONTROLLER_USERNAME/CONTROLLER_PASSOWRD. AUTH_TOKENs cannot be used. 

ESP:
  "Example Client1 Name Match":
    DEVICE_USER:
    DEVICE_PASSWORD: 
    
  "Example Client2 Name Match":
    DEVICE_USER:
    DEVICE_PASSWORD: 

Subscribe to generic websocket to get push config change messages (element, site in this example)

cgxsh_generic_ws

edwards-mbp-pro:cgxsh aaron$ cgxsh_generic_ws
Connected.
> { "type": "PUT", "uri": "/v2.0/api/tenants/10006/subscriptions", "body": {"type": "config_change", "subscriptions": [{"resource_key": "elements"},{"resource_key": "sites"}] }}
< {
      "type": "PUT",
      "uri": "/v2.0/api/tenants/10006/subscriptions",
      "body": {
          "id": "15766253860930016",
          "_etag": 1,
          "_content_length": 0,
          "_schema": 0,
          "_created_on_utc": 15766253860930016,
          "_updated_on_utc": 15766253860930016,
          "_status_code": "200",
          "_message_id": "1576625386053000499998772050152704482435",
          "_request_id": "1576625386053000399991149536419934892671",
          "subscriptions": [
              {
                  "resource_key": "elements"
              },
              {
                  "resource_key": "sites"
              }
          ],
          "type": "config_change"
      }
  }

subsequent time later when configuration change on element occurs..

< {
      "id": "15766254376560072",
      "_created_on_utc": 15766254376560072,
      "_updated_on_utc": 15766254376560072,
      "_message_id": "1576625437641018399996760510275758800343",
      "_request_id": "1576625437641018299992839389780516744938",
      "operator_id": "15713488339050031",
      "operator_tenant_id": "10006",
      "esp_tenant_id": "123",
      "request_id": "1576625437588017700003942214959372913327",
      "source_ip": "96.64.220.253",
      "resource_key": "elements",
      "resource_id": "15608897741660166",
      "resource_etag": 1728,
      "resource_version": "v2.3",
      "request_type": "PUT",
      "request_uri": "/v2.3/api/tenants/10006/elements/15608897741660166",
      "request_body": {
          "_etag": 1727,
          "_schema": 0,
          "id": "15608897741660166",
          "site_id": "15608896590040129",
          "name": "Portland Sales Office ION",
          "description": null,
          "tags": [
              "SNOW-high"
          ],
          "sw_obj": null,
          "cluster_insertion_mode": null,
          "cluster_member_id": null,
          "l3_direct_private_wan_forwarding": true,
          "l3_lan_forwarding": true,
          "vpn_to_vpn_forwarding": false,
          "network_policysetstack_id": null,
          "priority_policysetstack_id": null,
          "nat_policysetstack_id": null,
          "spoke_ha_config": null
      },
      "response_code": 200,
      "response_body": {
          "id": "15608897741660166",
          "_etag": 1728,
          "_content_length": "0",
          "_schema": 0,
          "_created_on_utc": 15608897741660166,
          "_updated_on_utc": 15766254376080179,
          "_status_code": "200",
          "_request_id": "1576625437588017700003942214959372913327",
          "_debug": null,
          "_info": null,
          "_warning": null,
          "_error": null,
          "tenant_id": "10006",
          "site_id": "15608896590040129",
          "software_version": "5.2.1-a85",
          "hw_id": "ec2683ee-0d9c-8a64-3467-55121bb8a672",
          "serial_number": "ec2683ee-0d9c-8a64-3467-55121bb8a672",
          "model_name": "ion 3102v",
          "name": "Portland Sales Office ION",
          "description": null,
          "role": "SPOKE",
          "state": "bound",
          "allowed_roles": [
              "HUB",
              "SPOKE"
          ],
          "cluster_insertion_mode": null,
          "cluster_member_id": null,
          "l3_direct_private_wan_forwarding": true,
          "l3_lan_forwarding": true,
          "connected": true,
          "admin_action": null,
          "deployment_op": null,
          "network_policysetstack_id": null,
          "priority_policysetstack_id": null,
          "spoke_ha_config": null,
          "tags": [
              "SNOW-high"
          ],
          "nat_policysetstack_id": null,
          "vpn_to_vpn_forwarding": false
      },
      "time_ms": 52,
      "request_content_length": 439,
      "response_content_length": 0,
      "request_ts": 1576625437588,
      "response_ts": 1576625437640
  }
> 

Command-line arguments

cgxsh

usage: cgxsh [-h] [--controller-email CONTROLLER_EMAIL]
             [--controller-password CONTROLLER_PASSWORD]
             [--device-user DEVICE_USER] [--device-password DEVICE_PASSWORD]
             [--noexit] [--controller CONTROLLER] [--insecure] [--noregion]
             [--override-host-header FORCE_HOST] [--verbosity VERBOSITY]
             [--sdkdebug SDKDEBUG]
             element[@client] ...

cgxsh (1.0.0b1)

optional arguments:
  -h, --help            show this help message and exit

cgxsh_args:
  CGXSH Arguments

  --controller-email CONTROLLER_EMAIL, -E CONTROLLER_EMAIL
                        Use this email for controller login.
  --controller-password CONTROLLER_PASSWORD
                        Use this password for controller login. NOT
                        RECOMMENDED - Password will likely be stored in shell
                        history.
  --device-user DEVICE_USER
                        Use this user to login to the Element Toolkit.
  --device-password DEVICE_PASSWORD
                        Use this password to login to the Element Toolkit. NOT
                        RECOMMENDED - Password will likely be stored in shell
                        history.
  --noexit              If using commands, do not exit after running commands.
                        Maintain interactive shell.
  element[@client]      Element name or ID to connect to. If connecting as
                        ESP/MSP account, @client name or ID is required.
  commands              (Optional) Strings of space-separated Toolkit commands
                        to run. Example: "set paging off" "dump lldp all"

Controller Options:
  These options change how the program connects to the CloudGenix Controller

  --controller CONTROLLER, -C CONTROLLER
                        Override Controller API URI. Default:
                        https://api.elcapitan.cloudgenix.com
  --insecure, -I        Do not verify API SSL certificate
  --noregion, -NR       Ignore Region-based redirection.
  --override-host-header FORCE_HOST, -OH FORCE_HOST
                        Force Host Header on API requests.

Debug:
  These options enable debugging output

  --verbosity VERBOSITY, -V VERBOSITY
                        CGXSH client verbosity.
  --sdkdebug SDKDEBUG, -D SDKDEBUG
                        Enable CloudGenix SDK Debug output, levels 0-3

cgxsh_generic_ws

usage: cgxsh_generic_ws [-h] [--no-format] [--show-keepalives]
                        [--controller-email CONTROLLER_EMAIL]
                        [--controller-password CONTROLLER_PASSWORD]
                        [--controller CONTROLLER] [--insecure] [--noregion]
                        [--override-host-header FORCE_HOST]
                        [--verbosity VERBOSITY] [--sdkdebug SDKDEBUG]
                        [[@client]]

cgxsh_generic_ws (1.0.0b1)

optional arguments:
  -h, --help            show this help message and exit

cgxsh_generic_ws args:
  CGXSH Generic WebSocket Client Arguments

  --no-format, -NF      Disable output pretty-printing/formatting.
  --show-keepalives     Show background keepalive messages
  --controller-email CONTROLLER_EMAIL, -E CONTROLLER_EMAIL
                        Use this email for controller login.
  --controller-password CONTROLLER_PASSWORD
                        Use this password for controller login. NOT
                        RECOMMENDED - Password will likely be stored in shell
                        history.
  [@client]             If connecting as ESP/MSP account, @client name or ID
                        is required.

Controller Options:
  These options change how the program connects to the CloudGenix Controller

  --controller CONTROLLER, -C CONTROLLER
                        Override Controller API URI. Default:
                        https://api.elcapitan.cloudgenix.com
  --insecure, -I        Do not verify API SSL certificate
  --noregion, -NR       Ignore Region-based redirection.
  --override-host-header FORCE_HOST, -OH FORCE_HOST
                        Force Host Header on API requests.

Debug:
  These options enable debugging output

  --verbosity VERBOSITY, -V VERBOSITY
                        CGXSH Generic WebSocket Client verbosity.
  --sdkdebug SDKDEBUG, -D SDKDEBUG
                        Enable CloudGenix SDK Debug output, levels 0-3

cgxsh_edit_config

usage: cgxsh_edit_config [-h] [--editor EDITOR]

cgxsh_edit_config (1.0.0b1)

optional arguments:
  -h, --help            show this help message and exit

cgxsh_edit_config:
  CGXSH Edit Configuration Arguments

  --editor EDITOR, -E EDITOR
                        Use this program to edit configuration. Editor must
                        supportfilename as first argument. Default:
                        /usr/bin/vi

cgxsh_edit_config

usage: cgxsh_decrypt_config [-h] [--force FORCE]

cgxsh_decrypt_config (1.0.0b1)

optional arguments:
  -h, --help            show this help message and exit

cgxsh_decrypt_config:
  CGXSH Decrypt Configuration Arguments

  --force FORCE, -F FORCE
                        Export configurations to alternate file. Don't verify
                        contents after decryption. Must specify filename to
                        decrypt contents into, since config may be corrupt.
                        Valid password is still required.