cgxsh 1.0.2b1

Description:

cgxsh 1.0.2b1

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.