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: user@email.com
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  aaron@cloudgenix.com      1h36m12s  active   1576618422757015099992703857847609972162
      2  Portland Sales Office ION  otheruser@cloudgenix.com  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.

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
cgxsh_lib		cgxsh_lib
LICENSE		LICENSE
README.md		README.md
cgxsh.py		cgxsh.py
cgxsh_create_defaultconfig.py		cgxsh_create_defaultconfig.py
cgxsh_decrypt_config.py		cgxsh_decrypt_config.py
cgxsh_edit_config.py		cgxsh_edit_config.py
cgxsh_encrypt_config.py		cgxsh_encrypt_config.py
cgxsh_generic_ws.py		cgxsh_generic_ws.py
requirements.txt		requirements.txt
setup.cfg		setup.cfg
setup.py		setup.py

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

cgxsh (Preview)

WARNING

Synopsis

Requirements

Installation

Commands/Features

cgxsh

cgxsh_generic_ws

cgxsh_create_defaultconfig

cgxsh_edit_config

cgxsh_decrypt_config

cgxsh_encrypt_config

License

Version

(Optional) Environment Variables

Usage info and examples.

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

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

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

Managing connected cgxsh/web toolkit users to the current ION

Encrypting a clear-text configuration.

Default config.yml template

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

Command-line arguments

cgxsh

cgxsh_generic_ws

cgxsh_edit_config

cgxsh_edit_config

About

Releases 1

Packages

Languages

License

ebob9/cgxsh

Folders and files

Latest commit

History

Repository files navigation

cgxsh (Preview)

WARNING

Synopsis

Requirements

Installation

Commands/Features

cgxsh

cgxsh_generic_ws

cgxsh_create_defaultconfig

cgxsh_edit_config

cgxsh_decrypt_config

cgxsh_encrypt_config

License

Version

(Optional) Environment Variables

Usage info and examples.

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

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

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

Managing connected cgxsh/web toolkit users to the current ION

Encrypting a clear-text configuration.

Default config.yml template

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

Command-line arguments

cgxsh

cgxsh_generic_ws

cgxsh_edit_config

cgxsh_edit_config

About

Resources

License

Stars

Watchers

Forks

Releases 1

Packages 0

Languages

Packages