Skip to main content

Breach Response Actions

1. Introduction​

This document describes how a customer can automate a Breach Response (Quarantine) action on affected hosts from their Security Orchestration, Automation and Response (SOAR) tool using the ColorTokens Xshield Security Platform’s Public API.

When a SOAR platform correlates threat intelligence and identifies potentially compromised hosts, it can invoke a predefined playbook to automatically move those hosts to a designated Breach Response Level within Xshield.

Once hosts are transitioned into a specific Breach Response Level (for example, Red, Orange, Yellow), communication to and from those hosts is restricted as defined for that level. This ensures:

  • Critical assets (crown jewels) continue to operate at reduced connectivity while maintaining core functionality.
  • Compromised assets are effectively quarantined, minimizing their blast radius and preventing lateral movement across the enterprise.

2. How It Works​

The Xshield Security Platform provides a rich set of Public APIs that allow external tools, such as SOAR systems, to take action programmatically when a threat is detected.

Among these, the API endpoint for setting a Breach Response Level is used to quarantine or isolate assets dynamically.

3. API Endpoint​

Endpoint​

PUT /assets/breachresponse

Description​

This endpoint allows an operator (or automation platform such as SOAR) to update the breach response level for one or more assets.

4. Authentication​

4.1 Overview​

The Xshield Public API uses an authentication mechanism based on credentials generated within the platform. Customers are not recommended to use Bearer tokens. Instead, Xshield provides a Python API Client Library that handles secure authentication and API invocation.

The client library uses the credentials generated in the Xshield console to create the appropriate authentication headers internally.

4.2 Steps to Enable Authentication​

  1. Generate API Credentials Navigate to: Settings → API Keys Refer to the official Xshield documentation for detailed steps to generate API credentials. These credentials include:

    • Tenant ID
    • Tenant URL
    • User ID
    • Fingerprint
    • Private key file (colortokens_api_key.pem)

  2. Configure the Client Library Place the following two files in the same working directory:

    • config.yaml — contains the tenant details (Tenant ID, Tenant URL, User ID, and Fingerprint).
    • colortokens_api_key.pem — contains the private key generated and saved on the local machine.

  3. Initialize the Client in Your Script

    import client

    # initialize the client
    client.initialize()

Once initialized, the client manages authentication automatically for all API calls made through it.

5. API Request Format​

5.1 Request Payload​

The following JSON payload is used to define which assets should have their breach level updated:

{
  "criteria": "assetName in ('assetToBeQuarantined')",
  "breachLevel": "red"
  "comment": "network anomaly detected and quarantined"
}

5.2 Example 1: Quarantine a Single Asset​

This example sets the breach level to Red for a specific host:

from client import invoke_api

payload = {
  "criteria": "assetName in ('crmdbuswprod-1')",
  "breachLevel": "red",
  "comment": "network anomaly detected on host crmdbuswprod-1"
}

invoke_api("PUT", "/assets/breachresponse", payload)

5.3 Example 2: Apply Breach Level to Tagged Assets​

In some cases, an operator may want to set the breach response level for all hosts that share a specific tag or attribute.

For example, to quarantine all hosts located in Santa Clara at a Yellow breach level:

from client import invoke_api

payload = {
  "criteria": "location = 'Santa Clara'",
  "breachLevel": "yellow",
  "comment": "network anomaly detected in Santa Clara region"
}

invoke_api("PUT", "/assets/breachresponse", payload)

This allows bulk-level actions based on any metadata tag or attribute (such as location, application, owner, etc.) defined within Xshield.

6. Sample Breach Response Script​

A sample breach response program is available for download as a .tar package.

This package includes:

  • A Python script demonstrating how to set the breach response level programmatically.
  • A README.md file detailing setup, configuration, and execution instructions.

  • Download Link:

    Please reach out to your ColorTokens representative to get access to the script.

7. Summary​

By integrating the Xshield Breach Response API into their SOAR workflows, customers can:

  • Automate host isolation or restriction upon threat detection.
  • Reduce mean time to respond (MTTR) by removing manual intervention.
  • Minimize risk exposure through dynamic segmentation and rapid quarantine of compromised assets.