Installing the Agent

Product Pricing Main Site Sign In / Try Now
Search…
BastionZero's agent secures access to your target through MrZAP and robust policy
Agent Installation
Agent installation has 2 parts: 1) installing the agent on your target and 2) registering the agent with BastionZero.
BastionZero's agent, bzero, is compatible with x86 and amd64 platforms. It is available through apt and yum package managers, a Bash script, a guided zli Quickstart, Ansible playbook, and via helm and yaml for Kubernetes.
Yum
Apt
Bash
Ansible
ZLI Quickstart
Helm
YAML
Use the yum-config-manager to add the BastionZero repo.
1
sudo yum-config-manager --add-repo \
2
https://download-yum.bastionzero.com/bastionzero.repo
Copied!
Install the agent bzero.
1
sudo yum install -y bzero
Copied!
Register the agent with BastionZero.
1
bzero -registrationKey *registration API key secret*
Copied!
For more detailed information regarding how to generate or retrieve your secret or what other flags are available with the registration command, take a look at our registration overview below.
Install the BastionZero public key from the Ubuntu key-server.
1
sudo apt-key adv --keyserver keyserver.ubuntu.com\
2
 --recv-keys E5C358E613982017
Copied!
For http (i.e., on an Ubuntu 14.x machine), add the BastionZero repo with:
1
sudo add-apt-repository \
2
'deb http://download-apt.bastionzero.com/production/apt-repo stable main'
Copied!
For https, add the BastionZero repo with:
1
sudo add-apt-repository \
2
'deb https://download-apt.bastionzero.com/production/apt-repo stable main'
Copied!
Update the apt cache.
1
sudo apt update
Copied!
Install the agent bzero.
1
sudo apt install -y bzero
Copied!
Register the agent with BastionZero.
1
bzero -registrationKey *registration API key secret*
Copied!
For more detailed information regarding how to generate or retrieve your secret or what other flags are available with the registration command, take a look at our registration overview below.
Install and register the bzero agent using Bash through the zli or the web app.
In order to retrieve the Bash script using either method, you must be a BastionZero administrator.
There is no additional action required to register your agent with BastionZero because it happens automatically when using the Bash script.
Via zli
Authenticate to BastionZero.
1
zli login
Copied!
Generate the Bash script. If running on the command line, make sure it is executable.
1
zli generate bash 
Copied!
Pro tip #1: Set the target name and environment by using the -n and -e flags respectively.
Pro tip #2: Use the -o flag to save the Bash script to a file directly.
Via Web App
Authenticate to BastionZero. Go to BastionZero's web app and log in.
Select "Create" in the upper right hand corner -> "Autodiscovery."
Choose the Bash script type, name scheme, and Linux distribution. Then copy the script for saving to a file or running directly on the desired target in a terminal.
Authenticate to BastionZero. Go to BastionZero's web app and log in.
Select "Create" in the upper right hand corner -> "Autodiscovery."
Choose Ansible as the script type and select your environment. The target name will be pulled from the Ansible hostname directly. Run the script with Ansible, and BastionZero will be installed on your targets.
There is no additional action required to register your agent with BastionZero because it happens automatically when using the Ansible script.
Quickstart is a 4-step process that installs and registers the bzero agent and secures your target host(s) in less than 10 minutes.
Launch the Quickstart process. The script will provide the remaining instructions.
1
zli quickstart
Copied!
Installing the bzero agent with Helm requires a registration secret.
For more detailed information regarding how to generate or retrieve your secret, take a look at our registration overview.
Add the BastionZero Helm repo.
1
helm repo add bastionzero `https://bastionzero.github.io/charts/`
Copied!
Install the Helm chart. Refer to the table below for a complete list of arguments. The command below is a base for you to expand on as desired.
1
helm install bctl-agent bastionzero/bctl-quickstart \
2
--set apiKey=$REGISTRATION_SECRET --set clusterName=helmcluster \
3
--namespace=bastionzero --create-namespace
Copied!
Flag
Description
apiKey
(required) The secret of your BastionZero registration key.
clusterName
(required) The name your cluster will appear as in BastionZero.
image.agentImageTag
(optional, but STRONGLY recommended) The specific version of the BastionZero agent to be downloaded using Helm. Refer to docker to find the most recent version. If not specified, latest will be used as the default.
namespace
(optional, but STRONGLY recommended) The namespace you would like to add your cluster into. If omitted, the agent will be installed in the default namespace, which is not recommended.
create-namespace
(optional) If creating a new namespace, this argument must be included as --create-namespace. If adding to an existing namespace, this argument must be omitted.
agentResources.limits.cpu
(optional) Limits the amount of CPU resources the agent installation can consume.
agentResources.limits.memory
(optional) Limits the amount of memory the agent installation can consume.
agentResources.requests.cpu
(optional) Limits the amount of CPU request resources the agent can consume.
agentResources.requests.memory
(optional) Limits the memory the requests from the agent installation can consume.
quickstartResources.limits.cpu
(optional) Limits the amount of CPU resources the quickstart installation script can consume.
quickstartResources.limits.memory
(optional) Limits the amount of memory the quickstart installation script can consume.
quickstartResources.requests.cpu
(optional) Limits the amount of CPU request resources the quickstart installation script can consume.
quickstartResources.requests.memory
(optional) Limits the memory the requests from the quickstart installation script can consume.
Pro tip: To get started faster, consider passing the following parameters to bypass additional policy setup.
Flag
Description
--set "users={SOME_ID_USERS}"
Use a list of comma separated SSO users (i.e., [email protected]) to add users automatically to the auto-generated policy. This will allow you and others permission to connect to your cluster right away.
--set "targetUsers={SOME_KUBE_USERS}"
Use a list of comma separated Kube users to automatically add to your policy. We utilize the impersonation API to give permissions to execute commands remotely. In order to create these users, ensure that there is a ClusterRoleBinding or RoleBinding that has a user as a subject. The name of this user is what we'll impersonate.
--set "targetGroups={SOME_KUBE_GROUPS}"
Pass a list of comma separated Kube groups to automatically add to your policy. These groups must already be established on your cluster.
Pro tip: The --namespace flag determines which namespace to install the BastionZero agent in. If the namespace already exists, omit the --create-namespace flag.
Best practice: If you don't use the --namespace flag, then the agent will be installed in the default namespace, which is not recommended.
Best practice: By default our Helm chart will use the tag latest for the agent. We strongly recommend that you override that using the flag
1
--set  "image.agentImageTag=x.x.x"
Copied!
to set the agent version explicitly. See docker for the most recent version.
Pulumi via Helm
Installing the bzero agent with Pulumi via Helm requires a registration secret.
For more detailed information regarding how to generate or retrieve your secret, take a look at our registration overview.
Below is an example of what that code may look like in Python:
1
"""A Kubernetes Python Pulumi program"""
2
​
3
from pulumi_kubernetes.helm.v3 import Release, ReleaseArgs, RepositoryOptsArgs
4
​
5
bzero_agent = Release(
6
    "bastionzero-agent",
7
    ReleaseArgs(
8
        chart="bctl-quickstart",
9
        version="1.0.0",
10
        repository_opts=RepositoryOptsArgs(
11
            repo="https://bastionzero.github.io/charts/",
12
        ),
13
        namespace="bastionzero",
14
        create_namespace=True,
15
        values={
16
            "apiKey": "SECRET_REDACTED",
17
            "clusterName": "some-cluster-name",
18
        },
19
    ),
20
)
Copied!
Please reference BastionZero's charts repo for the most recent version.
Upgrade Via Helm
Upgrading the bzero agent with Helm requires a registration secret.
For more detailed information regarding how to generate or retrieve your secret, take a look at our registration overview.
Upgrading From Chart Version 0.x.x to >=1.0.0
Pull updates from the chart repo.
1
helm repo update bastionzero
Copied!
Uninstall the chart.
1
helm uninstall bctl-agent
Copied!
Install the chart with the same clusterName from the previous installation.
1
helm install bctl-agent bastionzero/bctl-quickstart --set apiKey=$REGISTRATION_SECRET \
2
--set clusterName=helmcluster --namespace=bastionzero --create-namespace
Copied!
Upgrading From Chart Version 1.0.0 to >1.0.0
Pull updates from the chart repo.
1
helm repo update bastionzero
Copied!
Uninstall the chart.
1
helm uninstall bctl-agent --namespace bastionzero
Copied!
Install the chart with the same clusterName from the previous installation.
1
helm install bctl-agent bastionzero/bctl-quickstart --set apiKey=$REGISTRATION_SECRET \
2
--set clusterName=helmcluster --namespace=bastionzero
Copied!
Upgrade From Chart Version >1.1.0
BastionZero's latest Helm chart supports upgrading directly from Helm via
1
helm upgrade bctl-agent --namespace bastionzero
Copied!
To override the latest tag, specify the agent version with
1
--set  "image.agentImageTag=x.x.x"
Copied!
See docker for the most recent tag version.
Generate your YAML file, where clusterName is the name of your cluster. This command will generate a Kubernetes YAML with a Service Account, RBAC permissions/bindings, secret, and deployment.
1
zli generate kubeYaml {clusterName}
Copied!
To pipe the output to a file directly, use
1
zli generate kubeYaml {clusterName} --outputFile {someFile}
Copied!
where someFile is the name of your YAML file.
Important: This YAML file will only be valid for 10 minutes after creation due to the activation token expiration. If more than 10 minutes has passed, generate the YAML file again.
Apply the YAML. This will use your existing Kubernetes credentials to apply the YAML and create BastionZero's agent in the cluster.
1
kubectl apply -f {someFile}
Copied!
There is no additional action required to register your agent with BastionZero because it happens automatically when applying the YAML.
Agent Registration
The registration API key secret must already be shared with you by your admin or you must be a BastionZero administrator to generate one. Instructions on how to create a new registration key are here.
If you already have a registration key, you can retrieve it from the autodiscovery script, from the web app, or by using the API.
A description of all flags is provided in the table below, any number of flags can be specified after bzero.
Note: only the -registrationKey flag is required.
Flag
Description
-registrationKey
(required) The registration secret provisioned using the web app. It is an API key only usable for registering new targets. It is formatted as a base64 string.
-environmentName
(optional) The name of the environment you want to put the agent in. Can be provided in place of environmentId. If neither environmentName nor environmentId is provided, the target will be placed in the default environment and can be assigned a new environment via cloud.bastionzero.com.
-environmentId
(optional) The uuid of the environment you want to put the agent in. Can be provided in place of environmentName. If neither environmentName nor environmentId is provided, the target will be placed in the default environment and can be assigned a new environment via bastionzero.com.
-targetName
(optional) The desired name of the target. If no name is provided, this will default to the target’s host name.
-org
(optional) The unique identifier for your SSO instance. In Google, it’s referred to as orgID. In Microsoft, this is the tenantID. If you are using Okta, no -org is required.
-orgProvider
(optional) Your identity provider, e.g., “Google”, “Microsoft”, “Okta”, etc.. If neither the -org nor the -orgProvider are set, the information defaults to values provided by BastionZero during the registration process.
-y
(optional) If you're attempting to register a new version of the agent on a target that already had an agent installed, use the -y flag to force re-registration and create a new target. The old target will be deactivated.
Autodiscovery
BastionZero can autodiscover targets without public IPs, open ports, or VPNs. The BastionZero agent, bzero, will initiate an outbound connection to the BastionZero SaaS from any private or public cloud. In some cases, like an application-based firewall, the administrator may need to allow the BastionZero DNS entry or IP, but that is organization-specific. The only requirement for autodiscovery is that the agent can get out to the Internet.
Diagram of autodiscovery flow in BastionZero
Autodiscovery is initiated by a provisioner. Examples of provisioners may include:
​Package managers​
​Bash scripts​
​Ansible playbook​
​Helm chart​
​YAML​
It is the provisioner's responsibility to use a registration API key's secret to request the one time activation code from BastionZero. The activation code is used by the agent to identify itself to BastionZero as a resource within a specific organization. If an issue arises, bzero agents support error handling and recovery as part of the registration and activation process.
The specific provisioning implementation is described in greater detail below in Installation by Use Case.
Looking for how to connect to your resources instead? See Connecting To Your Resources in the User Guide.
Installation by Use Case
Remote Servers
To configure your server, you will need to:
​Download the zli​
​Install and register the bzero agent​
​Author policy for users to access your server​
The bzero agent can be installed on your remote server in a variety of ways: package managers, Bash script, Ansible playbook, or zli Quickstart.
Once the agent is installed on your target, it needs to register with BastionZero. If you've installed it using Bash, Ansible, or zli Quickstart, this process is already completed for you. For package managers, the registration process is detailed under yum and apt.
Bash
There are two ways to generate your Bash script: via zli or through the web app.
The Bash script allows installation of the bzero agent through the zli, during instance launch (i.e., by using the user data with AWS EC2), a Terraform deployment, or other deployment system.
The Bash script implements the autodiscovery process. Using your organization's default registration secret, or an administrator's registration secret, the script will request an activation token from BastionZero and then phone home to the service with an outbound connection. Registration in this case does not require any additional action from you. See here for more about registration API keys.
The script contains logic to autodiscover the Linux distribution and microarchitecture (x86 or ARM) in order to download and install the appropriate agent. The script also contains error recovery logic in the event the registration does not succeed for any reason. By default, the script will always download and install the latest BastionZero agent.
Ansible
BastionZero supports installing the bzero agent via an Ansible playbook. The Ansible playbook implements the autodiscovery process. Using your organization's default registration secret, or an administrator's registration secret, the playbook will request an activation token from BastionZero and then phone home to the service with an outbound connection. Registration in this case does not require any additional action from you. See here to learn more about generating a registration API key.
The playbook contains logic to autodiscover your Linux distribution and microarchitecture (X86 or ARM) in order to download and install the appropriate agent. By default, the playbook will always download and install the latest BastionZero agent.
Databases
To configure your database target, you will need to:
​Download the zli​
​Install and register the bzero agent​
​Configure your database target​
​Author policy for users to access your database​
Database Connection Architecture
BastionZero relies on a proxy target in order to make a secure connection to your database. The proxy target must be able to resolve a DNS hostname or reach the IP specified by the database target configuration. No configuration, outside of the proxy target having network access to the database, is required.
This feature utilizes our zli for end users to make connections. When connecting to a database target, traffic destined for the database will use local port forwarding through the zli and the proxy target to make a secure MrZAP connection to the database. Upon requesting a connection, the user is returned a local port number, which is used in the database client configuration. The database username, password, and role continue to be managed independent of BastionZero.
Install and Register the BastionZero Agent
First install the bzero agent. The agent can be installed on your server in a variety of ways: package managers, Bash script, Ansible playbook, or zli Quickstart.
Once the agent is installed on your target, it needs to register with BastionZero. If you've installed it using Bash, Ansible, or zli Quickstart, this process is already completed for you. For package managers, the registration process is detailed under yum and apt.
Accessing Databases Through a Kubernetes Cluster
Database Access Through Kubernetes Architecture
Database support is available on the BastionZero agent v.4.0.0+.
We recommend installing via Helm, but YAML is supported as well. Make sure to complete the Kubernetes setup to ensure the agent is registered with BastionZero.
Configure Your Database Target
Database target configuration is part of the "Create" function on the BastionZero web app, or you can use the API. The "Create" target screen in the web app is shown below:
Add a Database Target
Update the database target fields with the needed context as explained below.
Field
Description
Name
The name of the database target. This is assigned to an environment or used in a policy.
Proxy Target
The name of the target that is the proxy.
Remote Host
The DNS hostname or the IP address of the database target.
Remote Port
The remote port number that the database target is listening on, usually 443 for HTTPS.
Local Host
The localhost that the BastionZero zli will listen on. This should not need modification.
Local Port
The local port number, which the BastionZero zli will use to intercept traffic. If you leave it blank, an open port on the client machine will be selected for the user.
Environment
The environment to which this target should be added.
Add a Database Policy
The database policy will allow a user to connect to the database. For this type of access, BastionZero utilizes a proxy policy. Create a policy using the type proxy and update and save the fields per the descriptions below.
Proxy Policy
Field
Description
Policy Name
The name of your policy.
Description
Information useful for describing the purpose or context of your policy.
Users
A list of identity provider users who will be authorized to use this policy.
Groups
A list of identity provider groups who will be authorized to use this policy.
Resource Type
Either an envrionment or a list of targets which are the resource(s) authorized for access by this policy.
Kubernetes
To secure a Kubernetes cluster with BastionZero, you'll need to:
​Download the zli​
​Install and register the bzero agent​
​Set up your Kubernetes policy​
​Update your kubeConfig​
Users must have access to the cluster being secured (i.e., are able to create new deployments, secrets, and modify RBAC permissions). It is also recommended that the cluster have existing clusterRoles and clusterRoleBindings.
To install the bzero agent, we recommend using Helm. YAML is also supported.
If you're using Helm, you'll need a registration secret to install and register your agent. You can find those instructions here.
Verify the Agent Is Running
Once the agent is installed, ensure it has phoned home by listing your targets using
1
zli list-targets
Copied!
You should see a list of any existing targets in addition to your newly added Kubernetes cluster, {clusterName}.
List of targets within a Kubernetes cluster that is secured by BastionZero
You can also check that the agent has been installed using
1
kubectl get pods -n bastionzero
Copied!
The output should look similar to the following:
1
➜  ~ kubectl get pods -n bastionzero
2
| NAME                                  | READY | STATUS  | RESTARTS | AGE   |
3
| ------------------------------------- | ----- | ------  | -------- | ---   |
4
| bzdemo-cluster-agent-7f57c754b9-9qpnq | 1/1   | Running | 0        | 3m12s |
Copied!
Update Your Kubernetes Policy
Both Helm and YAML agent installation will create an environment and policy for your cluster. It must be updated to grant access to your desired users and target roles.
The auto-created environment and policy take the form "{clusterName}-policy" and "{clusterName}-env" respectively.
To update the target users:
1
zli targetuser dev-cluster-policy cluster-admin --add
Copied!
This tells BastionZero that the cluster-admin is an approved Kubernetes user that can access the cluster. Notably, this does not create a Kube policy on the cluster itself for access.
To update the target groups:
1
zli targetgroup dev-cluster-policy system:authenticated --add
Copied!
This updates the Kubernetes groups that are allowed to be assumed for this cluster.
To update the users:
1
zli user dev-cluster-policy [email protected] --add
Copied!
This updates the SSO users allowed to access the cluster.
Ensure the users, roles, and groups are correct by viewing the updated policy.
1
zli policy
Copied!
Example of an updated policy. Users removed for privacy purposes.
Webservers
To configure your webserver target, you will need to:
​Download the zli​
​Install and register the bzero agent​
​Configure your webserver target​
​Author policy for users to access your webserver​
Webserver Architecture
BastionZero relies on a proxy target in order to make a secure connection to your webserver. The proxy target must be able to resolve a DNS hostname or reach the IP specified by the webserver target configuration. No configuration, outside of the proxy target having network access to the webserver, is required.
This feature utilizes the zli for end users to make connections. When connecting to a webserver target, the user's default browser will open a new tab with the connection to the web service. This new connection will utilize a local port via a TCP socket to the BastionZero SaaS. This connection is made through the MrZAP protocol. As a result, BastionZero can authenticate and authorize the access, but it cannot alter any commands sent across.
Install the BastionZero Agent
First install the bzero agent. The agent can be installed on your server in a variety of ways: package managers, Bash script, Ansible playbook, or zli Quickstart.
Once the agent is installed on your target, it needs to register with BastionZero. If you've installed it using Bash, Ansible, or zli Quickstart, this process is already completed for you. For package managers, the registration process is detailed under yum and apt.
Accessing Webservers Through a Kubernetes Cluster
Webserver Access Through Kubernetes Architecture
Webserver support is available on the BastionZero agent v.4.0.0+.
We recommend installing via Helm, but YAML is also supported as well. Make sure to complete the Kubernetes setup to ensure the agent is registered with BastionZero.
Configure Your Webserver Target
Webserver target configuration is part of the "Create" function on the BastionZero web app, or you can use the API. The "Create" target screen in the web app is shown below:
Add a Web Target
Update the webserver target fields with the needed context as explained below.
Field
Description
Name
The name of the webserver target. This is assigned to an environment or used in a policy.
Proxy Target
The name of the target that is the proxy.
Remote Host
The DNS hostname or the IP address of the webserver target.
Remote Port
The remote port number that the webserver target is listening on, usually 443 for HTTPS.
Local Host
The localhost that the BastionZero zli will listen on. This should not need modification.
Local Port
The local port number, which the BastionZero zli will use to intercept traffic. If you leave it blank, an open port on the client machine will be selected for the user.
Environment
The environment to which this target should be added.
Add a Webserver Policy
The webserver policy will allow a user to connect to the webserver. For this type of access, BastionZero utilizes a proxy policy. Create a policy using the type proxy and update and save the fields per the descriptions below.
Proxy Policy
Field
Description
Policy Name
The name of your policy.
Description
Information useful for describing the purpose or context of your policy.
Users
A list of identity provider users who will be authorized to use this policy.
Groups
A list of identity provider groups who will be authorized to use this policy.
Resource Type
Either an envrionment or a list of targets which are the resource(s) authorized for access by this policy.
Dynamic Access Targets
Dynamic access targets (DATs) are machines discovered by querying a provisioning server that runs outside of BastionZero. The targets are dynamic because given a specific Dynamic Access configuration, the state, and number of targets online are constantly changing. The provisioning server has two main responsibilities:
1.Spin up and register a target. A target can be a server, container, virtual machine (e.g. EC2 instance), etc. The provisioning server can spin these targets up on-demand or have a pool of targets waiting to be registered; the way these machines are created is up to the provisioning server's implementation. The only requirement is that the server must install bzero agent and register itself with BastionZero on each spawned target. The server should also assign a UUID to the spawned target so that it can be torn down when it is no longer needed. When BastionZero calls out to the provisioning server, the required parameters needed to execute bzero -registrationKey on the spawned target will be provided.
2.Tear down a target. The provisioning server must have the ability to stop and spin down the spawned targets. BastionZero will remember the UUID the server assigned in step (1) and provide the same identifier when asking the server to stop a specific target.
Both of these functionalities should be abstracted behind two distinct HTTP POST endpoints, which the provisioning server must implement. Details on the full API specification, including a Python Flask reference implementation, is available here.
The provisioning server's architecture, due to being designed as POST webhooks, allows for dynamic targets without requiring BastionZero to have privileged access or special roles in an organization's cloud/network.
Why Use DATs
DATs encourage users to use ephemeral targets to access certain resources in an organization's network. Once the resources have been polluted by a user's access, the target may be torn down. For instance, one may require that any hands-on-keyboard database migration be performed from a fresh target container that is killed once the migration is complete.
Configuring DAT
Because DATs are dynamically created by querying a provisioning server, an organization administrator must first add a Dynamic Access configuration before other users in the organization can ask to connect to a DAT. Every DAT has a backing Dynamic Access configuration which determines how the target is spun up (provisioned) and torn down (destroyed).
An organization administrator has the ability to add a Dynamic Access configuration in the Create dropdown menu found in the top-right corner of the BastionZero web app.
Image of a DAT configuration
Below is an explanation of each configuration option.
Argument
Description
Name
A unique name that is used to refer to this Dynamic Access configuration. This is the name that appears in the Targets screen and Connect screen on the BastionZero web app. It is also the name that is used when a user wishes to connect to a DAT via the zli.
Environment
The environment that contains all DATs registered by the backing provisioning server. The environment determines the policies to apply to the spawned targets and therefore which users can access them.
Start webhook
The URL of the provisioning server's POST start endpoint. This endpoint is queried by BastionZero when it requests the server to spin up and register a target. Example: https://dynamic-access.example.com/start.
Stop webhook
The URL of the provisioning server's POST stop endpoint. This endpoint is queried by BastionZero when it requests the server to tear down a target. Example: https://dynamic-access.example.com/stop.
Health webhook
The URL of the provisioning server's GET health endpoint. This endpoint is queried by BastionZero periodically to check that the provisioning server is still online and accessible. Example: https://dynamic-access.example.com/health.
Shared secret (base64)
A shared secret between the provisioning server and BastionZero that is used to ensure only BastionZero is authorized to query the provisioning server. See more details in the reference specification's README found here.
Connecting To A DAT
Once the Dynamic Access configuration has been added, authorized users, as defined by the organization's policies, can connect to a DAT provisioned by the server specified in the configuration.
Connecting Via the Web App
To connect to a dynamic access target via the BastionZero web app, a user clicks on the Connect button found on the Spaces screen and finds the name of the Dynamic Access configuration in the list of accessible targets. This UX experience should be familiar as it is exactly the same flow as when connecting to SSM targets.
Picture of connecting to DAT via the web app
Connecting Via the zli
To connect to a dynamic access target via the zli, a user executes a command similar to the following one:
1
zli connect [email protected] --dynamic
Copied!
db-dat is the name of the Dynamic Access configuration, and ssm-user is a default user that exists on all DATs. The user can specify a username not equal to ssm-user as long as the specified username actually exists on the provisioned machine, and there exists a policy that allows access to such Target User.
DATs Vs. Targets
Once a DAT is fully provisioned and registered, a DAT does not appear differently from the user's perspective. It is listed as an SSH target in the list of the organization's targets (Targets screen), and the user connects to it through the same flow as described above. In fact, the provisioned target is running the same bzero agent that is installed when registering a target via any autodisdovery method.
DATs differ from standard SSH targets in three ways:
1.How they are discovered and initially connected to by BastionZero.
2.The lifetime of DATs.
3.The policies involving DATs.
Discovery and Initial Connection
Unlike SSH targets, which are discovered by BastionZero once an administrator installs the bzero agent, DATs are discovered on a per-user basis when the user asks to connect to a DAT. A single user cannot have more than one DAT target created by the same Dynamic Access configuration. The name of discovered DATs hint at this exact property: DAT-<name-of-dynamic-access-config>-<User's full name>.
When processing the connect request, BastionZero sends a POST request to the start webhook as defined in the Dynamic Access configuration. This request notifies the provisioning server that a fresh target should be created.
Because it can take the provisioning server some time to spin up a target, the terminal shell that appears after making the initial connection will be in the loading state. The shell cannot receive any input until the target is fully provisioned - that is until the target is fully registered, online, and reachable by BastionZero.
This initial connection experience is different than when connecting to an SSH target because of the nature of a DAT. A DAT's existence is known at the time of an initial, user-initiated connection. An SSH target, on the other hand, is known at the time of registration, which happens during the autodiscovery process. Due to this difference, an initial connection to a DAT will often take longer than when connecting to an SSH target whose existence is already known ahead of time.
Notice, however, that once the initial connection is made and not closed, future DAT connections made by the same user who initially connected, will finish connecting much faster than before. This is because all future connections to the same Dynamic Access configuration will connect to the already provisioned and running DAT created for the specific user.
Lifetime of DATs
DATs are meant to be used as ephemeral targets; therefore, the lifetime of a DAT is fairly short compared to an SSH target. A DAT target is automatically deleted once there are no more connections to it. When the last connection is closed, BastionZero sends a POST request to the stop webhook as defined in the Dynamic Access configuration. This request notifies the provisioning server that the backing machine should be destroyed and is no longer needed.
An SSH target, on the other hand, will not be deleted unless the user explicitly deletes it from the Targets screen or if the environment's offline target removal policy timeout is reached.
Policies of DATs
Similar to other kinds of targets, DATs are protected by the organization's policies. The two types of Target Access policies, environment-specific and target-specific, are applicable to DATs. However, there is a notable difference in a target-specific policy compared to SSH targets. A target-specific policy cannot refer to one of the spawned DATs; it can only refer to a specific Dynamic Access configuration.
The effect of this difference is as follows:
If the organization only has a target-specific policy for some Dynamic Access configuration, authorized users can only access the DATs created for them (i.e., the ones with the name DAT-<name-of-dynamic-access-config>-<User's full name>).
If an administrator wants to allow users to access DATs that were not created for them, then an environment-specific policy that refers to the Dynamic Access configuration's environment must be used.
SSH Tunnels & Secure File Copy
To configure your server target to utilize tunnels or file copy, ensure the BastionZero agent is already installed and online.
With BastionZero SSH tunneling, there is no need to utilize SSH keys; instead, BastionZero automatically sets up a one-time-use SSH key for each tunnel. You can then use your native SSH clients and scripts to connect to targets that are autodiscovered to BastionZero.
Diagram of ssh tunneling in BastionZero
The figure shows the architecture for the SSH tunnel. The connection from your SSH client is routed through BastionZero's zli. The zli then creates an SSH tunnel directly to the target. The SSH tunnel is passed over a websocket from the zli to BastionZero. From there, it is passed over a different websocket from BastionZero to the target.
If a user wants to access a target via an SSH tunnel, there must a policy in BastionZero that allows that user to do so.
At this time, BastionZero does not have the ability to read the contents of the SSH tunnel so command logging is not possible with SSH tunneling. However, BastionZero logs do capture the establishment of the SSH tunnel and its duration.
Setting It Up
Run zli generate ssh-proxy and configure your .ssh/config file with two lines:
1
host bzero-\*
2
    IdentityFile /home/user/.config/bastionzero-zli-nodejs/bzero-temp-key
3
ProxyCommand /home/user/zli ssh-proxy -s %h %r %p /home/user/.config/bastionzero-zli-nodejs/bzero-temp-key
Copied!
For simple access, just prefix the host with bzero:
$ ssh [email protected]
You can tunnel to a remote server application using the below.
$ ssh -L 6100:127.0.0.1:5432 [email protected]
You can also tunnel using a client browser to reach an HTTP application on your local network.
$ ssh -L 8080:10.0.0.1:80 [email protected]
For more information on SSH tunnels, check out the SSH tunneling man page.