Skip to main content

Administration Guide

Welcome to the Xshield Lab Administration guide, where we provide detailed instructions on deploying and managing the demo lab environment powered by the Xshield platform. At the core of the Xshield Lab's functionality is the use of Docker containers, which are instrumental in simulating an enterprise network infrastructure.

Docker containers are used within the Xshield Lab to create isolated and reproducible environments that emulate different aspects of enterprise ecosystems.

The containerized approach allows for consistent and controlled deployments of demo labs, rapid installation of lab environments for quick and efficient demonstrations and a simplified process of teardown of demo setups

The menu options within the Xshield Lab facilitate the creation and management of these Docker container images.

These images hold the Xshield agents and other required components. Each lab is tailored to a specific segmentation use case that builds the docker containers using these images.

This guide outlines the procedures of deploying labs via Xshield Lab tool to facilitate micro-segmentation demonstrations. Additionally, it also lists down the steps to upgrade the Xshield Lab package and recover the demo lab environment in cases where the lab environment is down

Table of Contents

  1. Deployment of Demo Lab
  2. Upgrade of Xshield Lab Package
  3. Recovery of Demo Lab Environment
  4. Modification of lab configuration file

Deployment of Demo Lab​

After the Installation (please refer to Installation Guide for installation steps) of Xshield Lab package is completed, if the python virtual environment is not activated, Activate the python virtual environment from lab directory and deploy the demo lab.

source .venv/bin/activate

or

source ~/venv-activate

Use the xshield_lab.py CLI tool to deploy the lab environment. Run:

python3 xshield_lab.py

You’ll see the following menu:

Welcome to the Xshield Lab Environment setup tool.

1. Create Lab Environment for Server Segmentation
2. Create Lab Environment for Container Segmentation
3. Create Lab Environment for Gatekeeper
4. Create Lab Environment for User Segmentation
5. Create Lab Environment for EDR Segmentation (CrowdStrike/MDE)
6. Create Lab Environment for Cloud Segmentation (Beta)
7. Customize Lab Environment
8. Remove Lab Environment
9. Remove Docker Images
10. Exit
  1. Create Lab Environment for Server Segmentation: Deploy the server agent lab environment on your tenant.
  2. Create Lab Environment for Container Segmentation: Deploy the Xshield Container Agent lab environment for Kubernetes micro-segmentation.
  3. Create Lab Environment for Gatekeeper: Deploy the Xshield Gatekeeper lab environment for OT and IOT devices.
  4. Create Lab Environment for User Segmentation: Deploy the user agent lab environment on your tenant.
  5. Create Lab Environment for EDR Segmentation (CrowdStrike/MDE): Deploy the EDR Segmentation lab environment on your tenant.
  6. Create Lab Environment for Cloud Segmentation (Beta): Deploy the Cloud Segmentation lab environment on your tenant.
  7. Customize Lab Environment: Customize specific lab environment settings.
  8. Remove Lab Environment: Cleanly remove the lab environment and deregister assets from your tenant.
  9. Remove Docker Images: Remove container images built locally.
  10. Exit: Close the CLI tool.

Example Commands for Xshield Lab CLI​

To effectively simulate an enterprise network environment with numerous servers, user endpoints, and OT devices, we utilize Docker containers. By building Docker images with the latest server/endpoint/gateway agent, we can create a scaled-down representation of a network with 30-40 agents or devices, all hosted on a single VM.

This process is essential for a newly installed environment or when images are not previously available or have been removed, to ensure that your lab environment closely mirrors a complex, multi-node network, providing a realistic and practical demonstration platform.

Deploy Server Segmentation Lab Environment​

Run the command and select Option 1: Create Lab Environment for Server Segmentation. This will create the required Docker images if not present, and deploy the lab environment.

python3 xshield_lab.py

For building lab environment with customized setup file use --lab-config filepath and --traffic-config filepath while starting the tool

python3 xshield_lab.py --lab-config <filepath> --traffic-config <filepath>

Deploy Container Segmentation Lab on Kubernetes:​

To deploy the container segmentation lab environment, select Option 2: Create Lab Environment for Container Segmentation.

python3 xshield_lab.py

Deploy Gatekeeper Lab Environment:​

To deploy the gatekeeper lab environment, select Option 3: Create Lab Environment for Gatekeeper. This will create the required Docker images if not present, and deploy the lab environment.

python3 xshield_lab.py

Deploy User Segmentation Lab Environment​

Run the command and select Option 4: Create Lab Environment for User Segmentation. This will create the required Docker images if not present, and deploy the lab environment.

python3 xshield_lab.py

Deploy EDR Integration Lab Environment​

Run the command and select Option 5: Create Lab Environment for EDR Segmentation (CrowdStrike/MDE)

python3 xshield_lab.py

select appropriate option in the sub-menu

  1. Create Lab Environment for CrowdStrike Integration: Deploy the CrowdStrike Integration lab environment on your tenant.
  2. Create Lab Environment for Microsoft Defender (MDE): Deploy the Microsoft Defender (MDE) lab environment on your tenant.
  3. Back to Main Menu: Go back to the main menu.

Deploy Cloud Segmentation Lab Environment​

Run the command and select Option 6: Create Lab Environment for Cloud Segmentation (Beta).

python3 xshield_lab.py

Customize the Lab Environment​

To customize the lab environment, select Option 7: Customize Lab Environment.

Select appropriate customize option in the sub-menu

  1. Rename Assets using Agent prefix – To rename assets for better organization for your use case. Renaming assets may help build appropriate tag rules, searches etc.
  2. Customize Lab - Assign Tags, Named Network, Templates,Segments via csv input – This will set tags, and build tag rules, templates, segments and named network using predefined csv config files supplied with the virtual lab.
  3. Remove Lab Customizations – This will remove all customizations applied to the lab environment.
  4. Exit – Exit the customize lab environment tool menu

Remove Lab Environment​

To remove and clean up the lab environment, select Option 8: Remove Lab Environment.

python3 xshield_lab.py

Remove Docker Images​

To remove and clean up the docker container images, select:

python3 xshield_lab.py

Select Option 9: Remove Docker Images.

Exit the Lab environment tool menu​

Select Option 10: Exit.

Upgrade of Xshield Lab Package​

Upgrade of Lab package version on VM:​

For a new released version, please follow below steps to load the new Xshield Lab changes on the existing VM

  1. If upgrade version has changes related to existing lab, it's advisable to recreate the lab again post upgrade steps for new changes to be reflected.
  2. Take a backup of your config.yaml file into a different folder along with the API private key file
  3. Deactivate and delete the python virtual environment from lab directory and remove the config directory too (The xshield lab package can be in /etc/colortokens/ directory or the workspace where you've downloaded and setup the xshield lab package)
  sudo su
  cd /etc/colortokens/lab
  deactivate
  rm -rf .venv ../config
  1. Install wget and tar packages on the VM, if not already present
  apt install wget tar

  1. Fetch the latest published lab package

    Please replace <artifacts_url> with the appropriate URL for your domain:

  • For ng.colortokens.com and bom.colortokens.com, use artifacts.<domain url> For example: artifacts.ng.colortokens.com
  • For all other domains, use artifacts-<domain url> For example: artifacts-ng-stage.colortokens.com
  • It is advised to deploy the lab environments on non-production clusters

Ensure that you substitute <domain url> with your specific domain name to form the correct URL for downloading the package.

    cd /etc/colortokens
    wget https://<artifacts url>/ct-xshield-util/latest/packages/xshield_lab.tar.gz

Check example URL below for reference

    cd /etc/colortokens
    wget https://artifacts.ng.colortokens.com/ct-xshield-util/latest/packages/xshield_lab.tar.gz
  1. Untar the Xshield lab package.
  tar -xzvf xshield_lab.tar.gz
  1. Remove the downloaded tar ball file
  rm xshield_lab.tar.gz

  1. Execute install script from lab directory to get the fresh packages installed in a new python virtual env.

    Either provide the config file path along with API key path when prompted during the execution of install script or if backup was not taken build the config data via interactive menu option

  cd /etc/colortokens/lab
  bash install.sh
  1. Activate Virtual Environment and deploy the lab with new lab package
  source ~/venv-activate
  python3 xshield_lab.py

Recovery of Demo Lab Environment​

  1. If the VM is restarted or docker containers are restarted then bridge interfaces on host and eth interfaces inside each of the docker containers are lost, this will cause the ctagent inside each docker container to lose communication with the Xshield platform
  2. In order to regain the communication and reconnect the lab with Xshield platform, please follow below steps
  3. Navigate to lab directory inside /etc/colortokens/ or the workspace where you've downloaded and setup the lab utility
  4. Execute the below commands to reconnect the lab
sudo su
cd /etc/colortokens/lab
bash lab_reconnect.sh
  1. Once the script execution is finished, please verify if the agents are all back to Active state on Xshield platform
  2. In case of any errors/queries, please contact the Xshield Utility team

Modification of lab configuration file​

  1. If there's a change in Xshield tenant or credentials, the config.yaml requires modification to connect and authenticate the Xshield tenant with new credentials
  2. If there's a change in Xshield tenant then please remove any existing lab that is present on the VM by using Remove Lab Environment option from the above menu before changing the config.yaml
  3. This needs to be done since the new lab creation or modification will be done on a new Xshield tenant and old lab will not be able to connect to the new Xshield tenant
  4. Navigate to lab directory inside /etc/colortokens/ or the workspace where you've downloaded and setup the lab utility
  5. Remove the lab environment by launching the xshield lab tool inside python virtual env (python3 xshield_lab.py)
  6. Move back to the main directory /etc/colortokens/ or the workspace where you've downloaded and setup the lab utility
  7. Upload/Copy the new config.yaml along with the API private key file to the VM where the installation is to be done.
  8. Update your new config.yaml file with the API private key path from the VM
  9. Copy the new config.yaml file to the config directory 
    cp <path-to-downloaded-config-file>/ColorTokens Xshield config.yaml config/config.yaml
  10. Activate the python virtual environment from /etc/colortokens/lab directory and Launch the Xshield lab tool 
    source .venv/bin/activate
    python3 xshield_lab.py
  11. If the config.yaml file is not available for download, please fill up the details interactively from the menu during launch of Xshield lab tool
  12. In order to fetch the credentials for building the config.yaml file data, please use below steps
  • Copy the tenant_id, user_id from Settings > API Keys section on the tenant UI
  • Copy the deployment_key from Sensors > Agents > Install Agent > Installation Script section on the tenant UI
    • Copy the value of -CT_DEPLOYMENT_KEY in the installation command mentioned
  • For fingerprint, generate a New API Key from Settings > API Keys section on the tenant UI and click on Save, copy the generated fingerprint value
  • Ensure that the Xshield API private key is downloaded to the local machine where the lab will be created and has the appropriate permissions. Note that, this private key is NOT your SSH private key.
  • For private_key_location, specify the path to your downloaded private key file (.pem) used for API authentication.