Skip to main content

How to integrate with XSOAR

Cortex XSOAR is a powerful Security Orchestration, Automation, and Response (SOAR) system. XSOAR allows SoC teams to organize cases, incidents and automate investigation rapidly using a central War Room for collaboration. By integrating Cado with XSOAR, you're going to increase efficiency and productive by automating Cado's powerful data acquisition and processing.

For more information, see the Cortex XSOAR documentation for the Cado Pack..

tip

If you're confused by the terminology mentioned here, or have never used XSOAR before, please consider checking out the XSOAR documentation.

Getting Started with XSOAR

Before properly getting started please see the following for general instructions on setting up the Cado platform for integrating with third-party tools:

Integrations Overview >

Contents

  1. Downloading from Marketplace
  2. Setup
  3. Testing your Settings

Downloading from Marketplace

In your Cortex XSOAR instance, click on the Marketplace section in the left-hand sidebar and search for Cado in the search bar.

Cado in the XSOAR marketplace

Setup

When configuring the Cado integration (which should open up when you install the application), you'll see the following screen to configure the XSOAR application:

Cado XSOAR Setup Wizard

In this screen, you'll need to setup the following:

  • Application Instance Name:

    This will be the name of the Application as it shows in XSOAR. If you're unsure, it's best to leave as default.

  • The URL of your Cado instance:

    This will the URL of your deployed Cado instance, if you're unsure, please see Integrations Overview >

  • The API key you retrieved from your platform:

    This will the generated private API key you retrieved earlier, if you're unsure, please see Integrations Overview >

  • The default Project ID

    Provides a fallback Project ID from Cado if you forget to add an ID to a command. If you're not sure, don't change! Defaults to 1.

  • The default AWS Region

    Provides a default AWS region to fallback on if you forget to add it to a command. Defaults to us-east-1.

  • The default AWS S3 bucket

    Provides a default AWS bucket to fallback on if you forget to add it to a command. Defaults to cado-default-bucket.

Testing your Settings

To test your settings, click the Test button in the setup screen. Ensure the result of the test is green and says result ok.

List of Commands

Contents

  1. List EC2 Instances
  2. List S3 Buckets
  3. List Projects
  4. List Project Pipelines
  5. Create a Project
  6. Retrieve a Pipeline
  7. Acquire a Disk Image From EC2
  8. Acquire a Disk Image From S3

List EC2 Instances

  • Command: cado-list-ec2
  • Description: This command will allow you to list all the EC2 instances in an AWS region.

Arguments

Argument NameDescriptionDefault Value
project_idThe ID of the project you wish to attach the acquisition to.The value of the pre-configured default.
regionThe AWS region to list instances from. This is a required parameter.The value of the pre-configured default.
limitInteger value to limit the amount of data retrieved from Response.100

XSOAR Context Output

PathTypeDescription
CadoResponse.EC2Instances.idNumberAWS ID of the EC2 Instance
CadoResponse.EC2Instances.instance_nameStringName of the EC2 Instance
CadoResponse.EC2Instances.instance_typeStringAWS Type of the EC2 instance
CadoResponse.EC2Instances.regionStringAWS region of the EC2 instance

Command example

!cado-list-ec2 project_id=1 region="us-east-1" limit=100

Context Example

{
"CadoResponse": {
"EC2Instances": [
{
"_placement": "us-east-1c",
"_state": "stopped",
"celery_worker_name": null,
"deployment_id": null,
"evidence_id": null,
"id": "i-00000000000",
"instance_name": "Instance",
"instance_type": "t3a.2xlarge",
"ip_address": null,
"launch_time": "Thu, 25 Mar 2021 18:38:13 GMT",
"processing_type": null,
"project_id": null,
"queue_name": null,
"region": {
"name": "us-east-1"
},
"worker_used": null
}
]
}
}

XSOAR Artifact Output

_placement_stateidinstance_nameinstance_typelaunch_timeregion
us-east-1cstoppedi-00000000000Instancet3a.2xlargeThu, 25 Mar 2021 18:38:13 GMTname: us-east-1

List S3 Buckets

  • Command: cado-list-s3
  • Description: This command will allow you to list all the S3 buckets in an AWS account.

Arguments

Argument NameDescriptionDefault Value
project_idThe ID of the project you wish to attach the acquisition to.The value of the pre-configured default.
limitInteger value to limit the amount of data retrieved from Response.100

XSOAR Context Output

PathTypeDescription
CadoResponse.S3Buckets.bucketsArrayAn array of S3 buckets available to the project

Command Example

!cado-list-s3 project_id=1 limit=100

Context Example

{
"CadoResponse": {
"S3Buckets": {
"buckets": [
"bucket",
]
}
}
}

XSOAR Artifact Output

buckets
bucket

List Projects

  • Command: cado-list-project
  • Description: This command will allow you to list all the projects, or a single project, in Cado.

Arguments

Argument NameDescriptionDefault Value
project_idThe ID of the project you want to retrieve.The value of the pre-configured default.
limitInteger value to limit the amount of data retrieved from Response.100

XSOAR Context Output

PathTypeDescription
CadoResponse.Projects.idNumberID of the retrieved project
CadoResponse.Projects.caseNameStringName of the retrieved project
CadoResponse.Projects.descriptionStringDescription of the retrieved project
CadoResponse.Projects.usersArrayArray of users assigned to the retrieved project
CadoResponse.Projects.createdDateCreation date of the project

Command Example

!cado-list-project limit=100

Context Example

{
"CadoResponse": {
"Projects": {
"caseName": "Project Name_XSOAR",
"created": "2022-01-17T12:21:46.613814",
"deleted": false,
"description": "This is a project in Cado created through Cortex XSOAR!",
"id": 1,
"status": "Pending",
"users": [
{
"display_name": "admin",
"id": 1,
"is_admin": true,
"login_type": 0,
"username": "admin"
}
]
}
}
}

XSOAR Artifact Output

caseNamecreateddeleteddescriptionidstatususers
Project Name_XSOAR2022-01-17T12:21:46.613814falseThis is a project in Cado created through Cortex XSOAR!1Pending{'display_name': 'admin', 'id': 1, 'is_admin': True, 'login_type': 0, 'username': 'admin'}

List Project Pipelines

  • Command: cado-get-pipeline
  • Description: This command will allow you to list all the pipelines, or a single pipeline, for a given project in Cado.

Arguments

Argument NameDescriptionDefault Value
pipeline_idThe id of the pipeline to retrieve.None
project_idThe id of the project the pipeline belongs to.The value of the pre-configured default.
limitLimit results to retrieve.100

XSOAR Context Output

PathTypeDescription
CadoResponse.Pipeline.pipeline_idNumberThe ID of the retrieved pipeline
CadoResponse.Pipeline.pipeline_typeStringThe type of pipeline that was retrieved
CadoResponse.Pipeline.createdDateThe date at which the retrieved pipeline was started
CadoResponse.Pipeline.evidence_idNumberThe evidence ID linked to the retrieved pipeline
CadoResponse.Pipeline.project_idNumberThe ID of the project the pipeline belongs to
CadoResponse.Pipeline.is_terminatedBooleanA boolean which says if the retrieved pipeline has been finished/terminated
CadoResponse.Pipeline.summaryArrayAn array of values containing the cancelled, failed, pending, running and successful pipeline subtasks
CadoResponse.Pipeline.subtaskArrayAn array of tasks in the retrieved pipeline

Command Example

!cado-get-pipeline project_id=1 pipeline_id=1

Context Example

{
"CadoResponse": {
"Pipeline": {
"pipeline_id": 1,
"pipeline_type": "processing",
"created": "2022-01-17T12:22:00.843869",
"evidence_id": 1,
"project_id": 1,
"is_terminated": false,
"subtasks": [
{
"execution_duration": 0,
"finish_time": 0,
"name": "Triage: Attaching disk for local data storage.",
"name_key": "infrastructure.check_ssd",
"notification_level": "Info",
"progress_text": [],
"start_time": 0,
"state": "PENDING",
"task_id": "3699827f-63c4-4408-88a4-0ae899187ed3",
"total_stages": null
}
],
"summary": {
"cancelled": 0,
"failure": 0,
"pending": 14,
"running": 0,
"success": 0,
"total": 14
}
}
}

}

XSOAR Artifact Output

pipeline_idpipeline_typecreatedevidence_idproject_idis_terminatedsummarysubtask
1processing2022-01-17T12:22:00.84386911false"execution_duration": 0,
"finish_time": 0,
"name": "Triage: attaching disk for local data storage.",
"name_key": infrastructure.check_ssd",
"notification_level": "Info",
"progress_text": [],
"start_time": 0,
"state": "PENDING",
"task_id": "3699827f-63c4-4408-88a4-0ae899187ed3",
"total_stages": null
"cancelled": 0,
"failure": 0,
"pending": 14,
"running": 0,
"success": 0,
"total": 14

Create a Project

  • Command: cado-create-project
  • Description: This command will allow you to create a new project in Cado.

Arguments

Argument NameDescriptionDefault Value
project_nameName of the project.
project_descriptionDescription for the project.

XSOAR Context Output

PathTypeDescription
CadoResponse.Project.idNumberThe Project ID of the newly created project

Command Example

!cado-create-project project_name="Project Name" description="Project Description"

Context Example

{
"CadoResponse": {
"Project": {
"id": 1,
"msg": "Created"
}
}
}

XSOAR Artifact Output

idmsg
1Created

Acquire a Disk Image From EC2

  • Command: cado-trigger-ec2
  • Description: This command will trigger a disk image acquisition task in Cado for a specified EC2 instance.

Arguments

Argument NameDescriptionDefault Value
project_idThe ID of the project you wish to attach the acquisition to.The value of the pre-configured default.
instance_idID of the EC2 instance to acquire.Required
regionAWS region in which the EC2 instance is located.The value of the pre-configured default.
bucketS3 bucket where the uploaded disk image resides.The value of the pre-configured default.
compressFlag indicating if disk compression is enabled.
include_disksFlag indicating if we include disk images in the acquisition.
include_hashFlag indicating if we calculate the hash of the disk.
include_logsFlag indicating if we include system logs in the acquisition.
include_screenshotFlag indicating if we include a screenshot of the system in the acquisition.

XSOAR Context Output

PathTypeDescription
CadoResponse.EC2Acquisition.pipeline_idNumberID of the created pipeline

Command Example

!cado-trigger-ec2 project_id=1 instance_id="i-00000000000" region="us-east-1" bucket="bucket" compress=true include_disks=true include_hash=true include_logs=true include_screenshot=true

Context Example

{
"CadoResponse": {
"EC2acquisition": {
"created": "2022-01-17T12:21:59.084282",
"evidence_id": 0,
"name": "Acquiring i-00000000000",
"pipeline_id": 1,
"pipeline_type": "acquisition",
"project_id": 1,
"subtasks": [
{
"id": "1587a9c9-c02c-464b-a6f7-d4b7e720bd93"
},
{
"id": "4f798bf8-c7d3-427c-9498-10a85cfe3978"
},
{
"id": "c5fa26f1-e282-47a6-8335-1160766e089b"
},
{
"id": "82ec9a7e-47ac-4539-9623-166a44a59d0f"
},
{
"id": "88151005-a999-422e-b4cb-9e76699d6e42"
}
],
"user_id": 1
}
}
}

XSOAR Artifact Output

createdevidence_idnamepipeline_idpipeline_typeproject_idsubtasksuser_id
2022-01-17T12:21:59.0842820Acquiring i-000000000001acquisition1{'id': '1587a9c9-c02c-464b-a6f7-d4b7e720bd93'},
{'id': '4f798bf8-c7d3-427c-9498-10a85cfe3978'},
{'id': 'c5fa26f1-e282-47a6-8335-1160766e089b'},
{'id': '82ec9a7e-47ac-4539-9623-166a44a59d0f'},
{'id': '88151005-a999-422e-b4cb-9e76699d6e42'}
1

Acquire a Disk Image From S3

  • Command: cado-trigger-s3
  • Description: This command will trigger a disk image acquisition task in Cado from a file in a S3 Bucket.

Arguments

Argument NameDescriptionDefault Value
project_idThe ID of the project you wish to attach the acquisition to.The value of the pre-configured default.
bucketThe S3 bucket name containing the file.The value of the pre-configured default.
file_nameThe name of the file to process.

XSOAR Context Output

PathTypeDescription
CadoResponse.S3Acquisition.pipeline_idNumberID of the created pipeline

Command Example

!cado-trigger-s3 project_id=1 bucket="bucket" file_name="file"

Context Example

{
"CadoResponse": {
"S3Acquisition": {
"created": "2022-01-17T12:22:00.843869",
"evidence_id": 1,
"name": "",
"pipeline_id": 2,
"pipeline_type": "processing",
"project_id": 1,
"subtasks": [
{
"id": "3699827f-63c4-4408-88a4-0ae899187ed3"
},
{
"id": "727e2072-8bf7-4847-89ea-9447f5fd8fd0"
},
{
"id": "857d48b8-abaf-4ea6-b159-d25c9784b837"
},
{
"id": "533f7deb-74bc-4ffb-b81f-788ed714bead"
},
{
"id": "3f1defde-3986-4292-a423-1bef62d4c52b"
},
{
"id": "e41a0934-266b-4868-9a7d-5f083b1efcc1"
},
{
"id": "75411e10-46e9-41dd-8bf7-9b5fbdc8df71"
},
{
"id": "0afbf2f4-fbf3-4305-ad9f-b19d30f4b17c"
},
{
"id": "ca063c7b-1135-4922-8542-49f40ce71449"
},
{
"id": "67fdb0ea-dcee-4f65-a003-4f40fcd567fb"
},
{
"id": "1437ec33-6af2-4eb8-9c43-e071dcb7e0ac"
},
{
"id": "06db4dcc-57fd-48bc-bb34-5bd8f2da0a0d"
},
{
"id": "e3cc930e-9a60-46c3-97a1-611824c24437"
},
{
"id": "ad2c8877-39e7-4bff-9756-81278802ee76"
}
],
"user_id": 1
}
}
}

XSOAR Artifact Output

createdevidence_idnamepipeline_idpipeline_typeproject_idsubtasksuser_id
2022-01-17T12:22:00.84386912processing1{'id': '3699827f-63c4-4408-88a4-0ae899187ed3'},
{'id': '727e2072-8bf7-4847-89ea-9447f5fd8fd0'},
{'id': '857d48b8-abaf-4ea6-b159-d25c9784b837'},
{'id': '533f7deb-74bc-4ffb-b81f-788ed714bead'},
{'id': '3f1defde-3986-4292-a423-1bef62d4c52b'},
{'id': 'e41a0934-266b-4868-9a7d-5f083b1efcc1'},
{'id': '75411e10-46e9-41dd-8bf7-9b5fbdc8df71'},
{'id': '0afbf2f4-fbf3-4305-ad9f-b19d30f4b17c'},
{'id': 'ca063c7b-1135-4922-8542-49f40ce71449'},
{'id': '67fdb0ea-dcee-4f65-a003-4f40fcd567fb'},
{'id': '1437ec33-6af2-4eb8-9c43-e071dcb7e0ac'},
{'id': '06db4dcc-57fd-48bc-bb34-5bd8f2da0a0d'},
{'id': 'e3cc930e-9a60-46c3-97a1-611824c24437'},
{'id': 'ad2c8877-39e7-4bff-9756-81278802ee76'}
1