Overview

The BastionZero ZLI is an exec level command line interface client which provides users the ability to connect, tunnel, and copy files from targets using a terminal emulator.  

Open Source & Distribution

The ZLI is an open source project licensed under the Apache License, version 2.0. The project is available from the BastionZero Github repositories and can be found here: BastionZero Open Source.


Installation can also be found in the open source documentation. For MAC users we highly recommend installing from our brew tap:


        brew install bastionzero/tap/zli


The brew install also works for Linux users of homebrew.


Linux and Windows users can download from the BastionZero webapp or from the latest download links.


For convenience, move your download of the ZLI into your bin $PATH. (Read more about $PATH)



Command Summary

The following tables list all the ZLI commands and their functions. 

All commands are prefaced by the exec name. 

You can run zli help to list the most current commands.


CommandDescription
loginAuthenticates a user to the service using an Identity Provider (IdP)
logoutInvalidates a users access credentials (id_token)
connectShell connect to a specific target
attachConnect to a detached ZLI shell
closeClose an open ZLI connection
list-targets, ltList all targets
list-connections, lcList all open connections associated with the ZLI space
copyUpload or download a file to or from the target
ssh-proxy-config
Generate a SSH tunnel configuration 
ssh-proxyUsed when SSH tunneling through BastionZero
configReturns the configuration path for the ZLI client.  It is recommended not to modify the configuration


Global Flag Options


The ZLI includes a few global options which can be used with any command.

Flag OptionDescription
--versionShow ZLI version number
--debugShow debug events
--silent, -sSilence all ZLI output messages
--helpShow command help



Command Manual

The follow section documents each ZLI command operation.


Name

login - Authenticates a user to the service using an Identity Provider (IdP)

Synopsis

zli login <provider> [option]...  

Description

login -  The login command authenticates a user to the BastionZero service.  When executed it will open a browser window. The user may then select their Identity Provider (IdP), currently Google or Azure/ Microsoft, and authenticate by supplying their username and password.  This is accomplished using the Open ID Connect (OIDC) specification.  

<provider> The provider is either Google or Microsoft and is required.

Options

-m, --mfa [string]

When multi-factor authentication is enabled for a user this conveys the one time token to be used to identify the user to BastionZero.  This is not the same as an MFA supplied to the IdP. This MFA is a separate authentication factor between the user and BastionZero and ensures that your targets remain secure even if your IdP is compromised.


The global options are available with this command as well.



Name

logout - Invalidates a users access credentials (id_token)

Synopsis

zli logout [option]

Description

logout -  The logout command invalidates the users OIDC identity token.  All terminal connections to the BastionZero SaaS from the user on that endpoint are now closed.  Please note however, that if the same user on the same endpoint has a WebApp session that session remains active.


Options

The global options may be used with this command.


Name

connect - Shell connect to a specific target

Synopsis

zli connect <targetString> [options]

Description

connect -  The connect command will request the bastion connect an IdP user to a target as indicated by the <targetString> supplied by the user.  The <targetString> is required and must be in the format targetUser@targetName'.

targetUser

The targetUser is a Linux user name that is specified via the access policy.  


targetName

The targetName is either the text Name of the target or the ID.  In cases where there is a name conflict, i.e. two or more targets with the same name (regardless of target type), the ID must be used to connect to the target.

Options

The global options may be used with this command.


Name

attach - Reconnect to a disconnected ZLI shell 

Synopsis

zli attach -t  <connection_id> [options]

Description

attach -  The attach command will request the bastion connect to an existing ZLI shell.  The state of that shell, connected via the web client or connected in another terminal is immaterial.  This command will connect a user to an existing ZLI shell.  

-t, --terminal, <connection_id>

Used to identify which ZLI shell the user is requesting attachment.


<connection_id>

Used to identify which ZLI shell the user is requesting attachment. 



Options

The global options may be used with this command.


Name

close - Close an open ZLI connection

Synopsis

zli close [<connection_id>] [options]

Description

close -  The close command will close either a single ZLI shell connection as specified by the <connection_id> or all ZLI shell connections for the currently logged in user.

-a, --all

Used to close all ZLI shell connections for the current user.


<connection_id>

Used to close a single ZLI shell connection.   This is the connection_id of the ZLI shell which can be obtained via list-connections.


Options

-a, --all

Used to close all ZLI connections.


The global options may be used with this command.


Name

 list-targets, lt - List all targets 

Synopsis

zli list-targets [option]...  
zli lt [option]...

Description

list-targets or lt -  Returns all the targets associated with the organization.  The command defaults to listing all targets, offline and online, with the target type, Name, and Environment fields. Additional options are provided to list further details regarding the targets.  

Options

-t, --targetType [string]

Limits the output to the specific targetType.  TargetType choices are "ssm", "ssh", and "dynamic"


-e, --env [string]

Limits the output to those targets associated with a particular environment name.


-n, --name [string]

Limits the output to those target associated with a target Name.  Note, the target ID is not used with this option.


-d, --detail 

Includes the Agent version number and the target status in the output


-j, --json 

Provide the output in JSON format


The global options are available with this command as well.


Name

 list-connections, lc - List all ZLI shell connection ID's  

Synopsis

zli list-connections [option]...  
zli lc [option]...

Description

list-connections or lc -  Returns all the connection ID's associated with your ZLI clients.  The connection IDs may be used to re-establish connections to a ZLI client.  

Options

            The global options are available with this command as well.


Name

copy - Upload or download a file to or from the target

Synopsis

zli copy [targetString:]<source> [targetString:]<destination> [option]...

Description

copy -  The copy command will upload or download a file between the endpoint (user device) and the target.  Please note that a policy must exist that allows the IdP user to perform this operation. Only one of the targetStrings (with the colon) must be filled out and that will determine if a file upload or download is happening relative to your machine.


[targetString]

The <source> or <destination> requires specifying the target. This is done by using the same targetString format as specified in the connect command, targetUser@targetName.  


<source>

<destination>

The <source> and <destination> specifies the full filepath, including the filename to be copied.  It must start with a '/' and include all relative directories necessary before ending in the filename. 

Options

The global options may be used with this command.


Name

ssh-proxy-config - Creates a session that can be used for SSH Tunneling.  Informs the user of the steps necessary to configure SSH to use the ZLI proxy for tunneling

Synopsis

zli ssh-proxy-config [option]...  

Description

ssh-proxy-config -  Sets up the user to utilize SSH tunneling. The command only needs to be run once, with the user taking the actions as specified in the output of the command to modify their ~/.ssh/config file. After doing so the user may utilize SSH Tunneling by using SSH and specifying the correct hostname prefix, as specified by the ~/.ssh/config file.


Options

The global options may be used with this command.


Name

ssh-proxy - The ssh-proxy command is used for SSH Tunneling. It can be used directly in lieu of SSH and a ssh configuration file.   (Learn more about SSH Tunneling).

Synopsis

zli ssh-proxy <targetUser>@bzero-<targetName> <port> <identity-file> [option]...  

Description

ssh-proxy -  The ssh-proxy command will SSH tunnel through b() to a target. The user must have a valid policy and they must specify the  targetName to include the 'bzero prefix in order to recognize this is a tunnel connection.

targetUser

The targetUser is a linux user name that is specified via the tunnel policy.  


bzero-<targetName>

To identify this as a tunneling target the user must specify 'bzero-' in front of the targetName. The targetName is either the text Name of the target or the ID.  In cases where there is a name conflict, i.e. two or more targets with the same name, the ID must be used to connect to the target.  


<port>

Port is the local port number to which a user wishes to enable the local port redirect through.


<identity-file>

The identity-file is the file path and name to the identity-key that was created using the ssh-proxy-config command.

Options

The global options may be used with this command.



Name

config - Returns the path of the configuration and log files for the client

Synopsis

zli config [option]...  

Description

config - Returns the file path of both the client configuration and the logs kept as part of normal client operation. These files should not need to be configured or modified by a user.


Options

The global options may be used with this command.