Skip to main content

Xshield Lab FAQ

Question​

Can I simulate Windows, macOS, and Linux machines in my lab environment via Xshield Lab?

Answer​

No, Xshield Lab can only simulate Linux machines as Docker containers on a Linux (Ubuntu 22.04) VM host.

Question​

How do I remove or upgrade assets once added?

Answer​

Removal of assets:

  1. Select Option 8: "Remove Lab Environment" from the Xshield Lab menu.

Upgrade of assets:

  1. Navigate to the Sensors page in the Xshield UI.
  2. Select the asset(s) you want to upgrade.
  3. Click the Upgrade button and select the desired agent version.

Question​

How can I fetch the API credentials (config.yaml) for Xshield Lab/Util?

Answer​

  1. Navigate to Settings > API Keys in the Xshield UI.
  2. Locate the API key by its fingerprint. The config.yaml file is available for each generated API key.
  3. Click the Download config.yaml button to download the configuration file.
  4. To remove an API key, click the Delete button.

Note: You must have already generated and downloaded the API key before fetching the config.yaml file.

Question​

How can I generate the API private key and config.yaml for Xshield Lab/Util?

Answer​

Refer to the Generate API key credentials section for detailed instructions.

Question​

How do I customize the asset names in a particular lab?

Answer​

  1. Select Option 7: "Customize Lab Environment" from the Xshield Lab menu.
  2. Refer to the Deployment of Demo Lab section in the admin guide for detailed instructions.

Question​

How do I customize the traffic flows in the lab?

Answer​

Each lab environment includes pre-defined asset configurations, networks, agent types, and traffic flows based on the selected use-case.

To modify the traffic flow:

  1. Navigate to the config/lab_data/ directory on the VM host.
  2. Edit the <lab_name>_lab.yaml and <lab_name>_lab_traffic.yaml files for your lab setup.
  3. Recreate the lab environment with the modified configuration files.

Question​

I have setup my lab, containers are running but I do not see assets on Xshield UI. What should I do if assets are not showing up in the dashboard?

Answer​

  1. Verify that the config.yaml file used for the lab environment corresponds to the same tenant where you are checking for assets.

  2. Check the Docker container status on the VM host:

docker ps

  1. Agent registration typically takes one or two heartbeat cycles to appear in the Xshield platform UI.

  2. If assets are still not registered, check the agent logs in one of the containers to verify successful registration:

docker exec -it <container_name> cat /var/log/colortokens/agent.json
  1. If the agent logs contain errors, share them with the engineering team or contact the Xshield Utility team for assistance.

Question​

My lab VM disk is full. How do I recover?

Answer​

  1. Connect to the VM via SSH and execute the following commands individually to clean up Docker overlay storage:
sudo su
systemctl status docker
systemctl stop docker
df -h
rm -rf /var/lib/docker/overlay2
systemctl start docker
docker ps
docker images
  1. Verify the disk space has been freed up:
df -h
  1. Check if the xcloud data cleanup cron job is scheduled:
crontab -l

If the cron job is not present, it may not have been scheduled due to an incomplete execution of the install.sh script during the initial installation or upgrade of the Xshield Util VM.

To schedule the cron job:

  1. Navigate to the /etc/colortokens/lab directory.
  2. Create a shell script script.sh with the following content and execute it:
SCRIPT_NAME="xcloud_cleanup.sh"
SCRIPT_PATH="$(realpath "$SCRIPT_NAME")"
if [[ ! -f "$SCRIPT_PATH" ]]; then
    echo "Error: Xcloud cleanup script not found at $SCRIPT_PATH"
    exit 1
fi
CRON_JOB="0 */10 * * * sudo bash $SCRIPT_PATH > $HOME/xcloud_cleanup.log 2>&1"
crontab -l | grep -v "$SCRIPT_PATH" | crontab -
(crontab -l 2>/dev/null; echo "$CRON_JOB") | crontab -
echo "Cron job added."
  1. Run the script:
bash script.sh

Note: This process will remove the existing lab setup, but the VM will be available for upgrading to the latest release build and recreating the lab environment.

Question​

After recovering my VM from a disk full issue, how do I bring up the lab environment?

Answer​

After recovering from a disk full issue and scheduling the cron job, if you have Docker containers running, follow these steps to restore your lab environment:

  1. Run the cleanup script to free up disk space and verify the ctagent status:
cd /etc/colortokens/lab
bash xcloud_cleanup.sh
  1. Verify that heartbeat (HB) messages are being logged successfully in the agent logs:
docker exec -it <container_name> cat /var/log/colortokens/agent.json

Check the logs inside each container to confirm that agents can now write logs with the freed-up disk space.

  1. If heartbeat messages continue to fail, restart the agent on all containers to re-establish connectivity with the Xshield platform.

Create and run the following script to restart agents on all containers:

#!/bin/bash
# Get list of all running container IDs
# Restart agents on all containers if HB fails while agent is in running state
containers=$(docker ps -q)
for cid in $containers; do
    echo "Processing container: $cid"
    docker exec "$cid" /etc/colortokens/ctagent stop
    sleep 5
    docker exec "$cid" /etc/colortokens/ctagent start
    sleep 5
    docker exec "$cid" /etc/colortokens/ctagent status
    sleep 2
    echo "Done with container: $cid"
done

Question​

I want to clean up my lab VM and reset it. How do I do it?

Answer​

  1. Navigate to the /etc/colortokens/lab directory and execute the cleanup script:
sudo su
cd /etc/colortokens/lab
bash cleanup.sh

This will remove all Docker containers, images, networks, volumes, and lab configuration directories from the VM.

  1. Decommission the removed assets from the Xshield platform via the Xshield UI.

  2. Perform a fresh installation of Xshield Lab to recreate the lab environment.

Question​

I want to upgrade my lab VM. How do I do it?

Answer​

Refer to the Upgrade of Xshield Lab Package section in the admin guide for detailed steps to upgrade the Xshield Lab package.

Question​

What file formats are supported by Xshield Util and/or Xshield Lab (CSV, YAML, JSON)?

Answer​

Xshield Util:

  • Supports CSV format for input and output files for each command.
  • Existing files are located in the config/util_data/ directory.

Xshield Lab:

  • Supports YAML format for lab configuration and traffic configuration files.
  • Supports CSV format for configuring tags, tag-rules, named-networks, templates, and segments via lab customization.
  • Existing files are located in the config/lab_data/ directory.

Question​

Are EDR integrations supported by Xshield Lab?

Answer​

Yes, Xshield Lab supports EDR integration lab environments for CrowdStrike and Microsoft Defender.

To deploy an EDR integration lab environment:

  1. Select Option 5: "Create Lab Environment for EDR Segmentation (CrowdStrike/MDE)" from the Xshield Lab menu.
  2. Refer to the Deployment of Demo Lab section in the admin guide for detailed instructions.

Question​

I have installed Linux packages via snap, and my xshield_lab.py tool is not starting. How do I resolve this?

Answer​

When packages are installed via snap repositories, the Docker daemon.json file is stored in a different location.

To resolve this issue:

  1. Run the following command to identify the correct path for the daemon.json file:
docker info

  1. Update the daemon.json file at the identified path.

  2. Restart the Docker service:

sudo systemctl restart docker
  1. Start the xshield_lab.py tool.