Administration Guide

The Xshield Utility is an essential command-line interface designed to empower administrators with direct and efficient interaction with the Xshield Security Platform. This utility simplifies the execution of the platform's API-driven functionalities, enabling swift and straightforward management of security policies and configurations.

The administrative guide for Xshield Utility will navigate you through:

Setup and launch of the utility on the machine.
Detailed explanations of available commands and their usage, along with examples for practical application.
Best practices for leveraging the utility to manage and optimize the Xshield Security Platform effectively.

Deployment of Xshield Utility tool
Upgrade of Xshield Utility tool
Modification of utility configuration file

Deployment of Xshield Utility tool

After the Installation (please refer to Installation Guide for installation steps) of Xshield Utility package is completed, if the python virtual environment is not activated, Activate the python virtual environment from util directory and launch the Xshield utility tool.

Activating Virtual environment and launching the XshieldUtility tool:

source .venv/bin/activate
python3 xshield_util.py --help

XshieldUtility Commands and Supported Operations:

The help menu can be accessed by running the following command:
```
python3 xshield_util.py --help
```

The available commands and options are:

Successfully validated config data.
usage: xshield_util.py [-h]  ...

Command line utility for Xshield APIs

options:
  -h, --help                             Show this help message and exit

Available Commands:

Agents commands:
  agent-north-south-config             Configure north-south traffic for agents
  collect-agent-diagnostics            Collect diagnostics from agents
  configure-agent-debug-logs           Enable/disable debug logs in agents
  decommission-agents                  Decommission agents from Xshield platform (only server and endpoint type agents)
  get-agents                           Export agents based on criteria to an output CSV file
  show-offline-agents                  Fetch and export offline agents to an output CSV file
  upgrade-agents                       Upgrade agents to a higher version

Assets commands:
  asset-malicious-ip-blocking          Blocking malicious IP addresses for assets
  enforce-asset                        Securing assets with ZeroTrust enforcement
  get-asset-policies                   Export policies (named networks and templates) for assets to an output CSV file
  get-assets                           Export asset info to an output CSV file (fetch asset summary or detail, default: summary)
  get-risk-score                       Fetch risk score info for assets
  get-vulnerabilities                  Export vulnerabilities for tenant's assets to an output CSV file
  quarantine-restore-assets            Quarantine/Restore Assets by assigning/removing the Quarantine tag (will be deprecated in next release)
  synchronize-asset-firewall           Synchronize an assets firewall

Crowdstrike commands:
  crowdstrike                          CrowdStrike Integration

Named-Networks commands:
  attach-named-network-to-asset        Attach named network(s) to asset(s)
  create-named-network                 Create a named network from input file or CLI arguments
  delete-named-network                 Delete named networks from input file or by name
  detach-named-network-from-asset      Detach named network(s) from asset(s)
  get-named-networks                   Fetch details of named networks and export to CSV

Segments commands:
  attach-named-network-to-segment      Attach Named Networks to a Segment
  attach-template-to-segment           Attach Templates to a Segment
  configure-policy-automation-segment  Configure Policy Automation for a Segment
  create-segment                       Create Segment (Read from input csv file or provide arguments)
  delete-segment                       Delete a segment
  detach-named-network-from-segment    Detach Named Networks from a Segment
  detach-template-from-segment         Detach Templates from a Segment
  generate-segment-report              Generate report for segments
  get-segment-rules                    Fetch and export all port and path rules associated with segments to an output CSV file
  get-segments                         Fetch segment and it's details and export to CSV

Taglabelrules commands:
  create-tag-label-rule                Create tag label rule (basic or advanced)
  delete-tag-label-rule                Delete a tag label rule

Tags commands:
  assign-asset-tags                    Assign tags to assets via input file, asset names, or filter criteria.
  create-custom-tag                    Create custom tags (max 5 per tenant).
  get-asset-tags                       Fetch tags for assets provided via input file, asset names, or filter criteria.

Templates commands:
  attach-template-to-asset             Attach template(s) to asset(s)
  create-template                      Create a template from input file or CLI arguments
  delete-template                      Delete templates by name or input-file
  detach-template-from-asset           Detach template(s) from asset(s)
  get-templates                        Fetch template and it's details and export to CSV
  update-template                      Update a template configuration from input file or CLI arguments

Additionally, all commands and options can be viewed from the XShield Utility Command Reference Guide

Each command has its own help menu that can be accessed by running the following command:

python3 xshield_util.py <command> --help

Example:

python3 xshield_util.py get-templates --help

Successfully validated config data.
usage: xshield_util.py get-templates [-h] [--input-file INPUT_FILE]
                            [--output-file OUTPUT_FILE] [--name NAME]
                            [--category CATEGORY] [--type TYPE]
                            [--system-template SYSTEM_TEMPLATE]
                            [--all]
                            [--wildcard-search WILDCARD_SEARCH]
Fetch template and it's details and export to CSV

options:
  -h, --help            show this help message and exit
  --input-file INPUT_FILE
                        Input file for template details (refer sample csv file
                        in config/util_data/input_csv_files/get_templates_inpu
                        t.csv)
  --output-file OUTPUT_FILE
                        Output file for template details (default: config/util
                        _data/output_csv_files/get_templates_output.csv)
  --name NAME           Comma-separated names of templates to fetch
  --category CATEGORY   Comma-separated categories to filter templates
  --type TYPE           Filter by template type (valid: allow, block)
  --system-template SYSTEM_TEMPLATE
                        Filter by system template status (valid: true, false)
  --all                 Fetch all templates (Caution: This will be very
                        expensive query for platform)
  --wildcard-search WILDCARD_SEARCH
                        Wildcard search for templates (eg: SampleTemplate)

The help menu of each command shows the arguments that can be passed for execution of the command.
The input CSV files that are required for execution of the command can be found in the config/util_data/input_csv_files directory.

Modifying CSV Files

For commands that require CSV input, you need to modify the corresponding CSV files in the config/util_data/input_csv_files directory with the appropriate data or create your own CSV file and provide the path as argument to the command.
The format of each CSV file is specific to the command and is described in the sample input CSV file in the config/util_data/input_csv_files directory.

Additional Notes

You can use the -h or --help flag with any command to get more information about its usage and arguments.

Upgrade of Xshield Utility tool

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

Go to the directory where xshield utility package was installed, deactivate and delete the python virtual environment and util directory In case of a Windows machine, please start the powershell in administrator mode

  sudo su

  cd <path/to/xshield_utility>/xshield_utility/util

  deactivate

  rm -rf .venv

  cd ../
  rm -rf util 

Install wget and tar packages on the VM, if not already present

For Linux systems

  apt install wget tar

For macOS systems

  brew install wget

most macOS systems come with tar package already installed, you can confirm it with tar --version command 3. Take a backup of your config.yaml file into a different folder if you don't have one along with the API private key file and also delete the config directory 4. Fetch the latest release version of utility package

Please replace <artifacts-url> with the appropriate URL for your domain:

For ng.colortokens.com and bom.colortokens.com, use artifacts.<domain url> eg: artifacts.ng.colortokens.com
For all other domains, use artifacts-<domain url> eg: artifacts-syd.colortokens.com, artifacts-fra.colortokens.com

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

   wget https://<artifacts-url>/ct-xshield-util/latest/packages/xshield_utility.tar.gz

For windows

Invoke-WebRequest -Uri https://<artifacts-url>/ct-xshield-util/latest/packages/xshield_utility.tar.gz

Check example URL below for reference

   wget https://artifacts.ng.colortokens.com/ct-xshield-util/latest/packages/xshield_utility.tar.gz

Untar the Xshield utility package.

  tar -xzvf xshield_utility.tar.gz

Remove the xshield_utility.tar.gz file post untar operation

  rm xshield_utility.tar.gz

Remove the downloaded tar ball file

  rm xshield_utility.tar.gz

For Linux and macOS machines, execute install script from util directory to get the fresh packages installed in a new python virtual env.

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

  cd util
  bash installXshieldUtil.sh

For Linux and macOS machines, activate python virtual Environment

  source .venv/bin/activate
  python3 xshield_util.py

For Windows machine, just activate the python virtual environment from util directory and install the python dependency packages.
```
   cd util
   .\venv\Scripts\Activate.ps1
   pip install -r requirements.txt
```
Copy the config.yaml file from the backup folder to the util directory
Launch the xshield utility tool

 python xshield_util.py

Modification of utility configuration file

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
Navigate to config/ directory inside /etc/colortokens/ or the workspace where you've downloaded and setup the Xshield utility
Copy the downloaded config.yaml file from new tenant or updated config.yaml file from existing tenant to the config directory
```
  cp <path-to-downloaded-config-file>/ColorTokens Xshield config.yaml config.yaml
```
Navigate back to util\ directory inside /etc/colortokens/ or the workspace where you've downloaded and setup the Xshield utility
Activate the python virtual environment from util directory and Launch the Xshield utility tool
```
 source .venv/bin/activate
 python3 xshield_util.py
```
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
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.

Table of Contents

Deployment of Xshield Utility tool​

Modifying CSV Files​

Additional Notes​

Upgrade of Xshield Utility tool​

Modification of utility configuration file​

Deployment of Xshield Utility tool

Modifying CSV Files

Additional Notes

Upgrade of Xshield Utility tool

Modification of utility configuration file