XMC NBI DeviceLister (Go)

DeviceLister uses the GraphQL-based API provided by the Northbound Interface (NBI) of Extreme Management Center (XMC; formerly known as NetSight) to fetch and display a list of all devices. The list includes the following pieces of information for each device:

• up/down (as +/- and text)
• IP address
• vendor and model
• system name or nick name

The tool is intended to provide a quick overview of the managed devices and to serve as a starting point for other tools.

Branches

This project uses two defined branches:

• master is the primary development branch. Code within master may be broken at any time.
• stable is reserved for code that compiles without errors and is tested. Track stable if you just want to use the software.

Other branches, for example for developing specific features, may be created and deleted at any time.

Dependencies

This tool uses Go modules to handle dependencies.

Running / Compiling

Use go run ./... to run the tool directly or go build -o DeviceLister ./... to compile a binary. Prebuilt binaries may be available as artifacts from the GitLab CI/CD pipeline for tagged releases.

Tested with go1.15.

Usage

DeviceLister --help:

Usage: ./DeviceLister [options]

Available options:
  -h, --host string     XMC Hostname / IP
      --port uint       HTTP port where XMC is listening (default 8443)
      --path string     Path where XMC is reachable
      --timeout uint    Timeout for HTTP(S) connections (default 5)
      --nohttps         Use HTTP instead of HTTPS
      --insecurehttps   Do not validate HTTPS certificates
  -u, --userid string   Client ID (OAuth) or username (Basic Auth) for authentication
  -s, --secret string   Client Secret (OAuth) or password (Basic Auth) for authentication
      --basicauth       Use HTTP Basic Auth instead of OAuth
      --version         Print version information and exit

All options that take a value can be set via environment variables:
  XMCHOST           -->  --host
  XMCPORT           -->  --port
  XMCPATH           -->  --path
  XMCTIMEOUT        -->  --timeout
  XMCNOHTTPS        -->  --nohttps
  XMCINSECUREHTTPS  -->  --insecurehttps
  XMCUSERID         -->  --userid
  XMCSECRET         -->  --secret
  XMCBASICAUTH      -->  --basicauth

Environment variables can also be configured via a file called .xmcenv, located in the current directory or in the home directory of the current user.

Authentication

DeviceLister supports two methods of authentication: OAuth2 and HTTP Basic Auth.

• OAuth2: To use OAuth2, provide the parameters userid and secret. DeviceLister will attempt to obtain an OAuth2 token from XMC with the supplied credentials and, if successful, submit only that token with each API request as part of the HTTP header.
• HTTP Basic Auth: To use HTTP Basic Auth, provide the parameters userid and secret as well as basicauth. DeviceLister will transmit the supplied credentials with each API request as part of the HTTP request header.

As all interactions between DeviceLister and XMC are secured with HTTPS by default both methods should be safe for transmission over networks. It is strongly recommended to use OAuth2 though. Should the credentials ever be compromised, for example when using them on the CLI on a shared workstation, remediation will be much easier with OAuth2. When using unencrypted HTTP transfer (nohttps), Basic Auth should never be used.

In order to use OAuth2 you will need to create a Client API Access client. To create such a client, visit the Administration -> Client API Access tab within XMC and click on Add. Make sure to note the returned credentials, as they will never be shown again.

Authorization

Any user or API client who wants to access the Northbound Interface needs the appropriate access rights. In general, checking the full Northbound API section within rights management will suffice. Depending on the use case, it may be feasible to go into detail and restrict the rights to the bare minimum required.

For API clients (OAuth2) the rights are defined when creating an API client and can later be adjusted in the same tab. For regular users (HTTP Basic Auth) the rights are managed via Authorization Groups found in the Administration -> Users tab within XMC.

Source

The original project is hosted at GitLab, with a copy over at GitHub for the folks over there. Additionally, there is a project at GitLab which collects all available clients.