ThreatConnect v3

ThreatConnect’s integration is a intelligence-driven security operations solution with intelligence, automation, analytics, and workflows.
This integration was integrated and tested with version 3 of ThreatConnect v3 REST API

ThreatConnect v3 HMAC credentials

1. On the top navigation bar, hover the cursor over the Settings icon and select Org Settings from the dropdown menu.
2. Click the Create API User button on the Membership tab of the Organization Settings screen, and the API User Administration window will be displayed.
3. Enter the following information:
   • First Name: Enter the API user’s first name.
   • Last Name: Enter the API user’s last name.
   • Organization Role: Use the dropdown menu to select an Organization role for the user.
   • Include in Observations and False Positives: Check this box to allow data provided by the API user to be included in observation and false-positive counts.
   • Disabled: Click the checkbox to disable an API user’s account in the event that the Administrator wants to retain log integrity when the API user no longer requires ThreatConnect access.
4. Record the Secret Key, as it will not be accessible after the window is closed.
5. Click SAVE to create the API user account.

For more information - click here (Section - Creating an API User).

Configure ThreatConnect v3 on Cortex XSOAR

1. Navigate to Settings > Integrations > Servers & Services.
2. Search for ThreatConnect v3.

3. Click Add instance to create and configure a new integration instance.

   Parameter	Description	Required
   Base Url	The base URL for the API	True
   Access ID	The API credentials	True
   Secret key	The API secret key	True
   Default Organization	The default owner for the integration	False
   First fetch timestamp (<number> <time unit>, for example, 12 hours, 7 days, 3 months, 1 year)		True
   Maximum number of incidents to fetch	The maximum amount of incidents to fetch per run. Default is 200.	False
   Trust any certificate (not secure)	Whether to trust any certificate	False
   Use system proxy settings	Whether to use proxy	False
   Tags filter for the fetch	Free text box to add comma-separated tags to filter the fetched incidents by.	False
   Group Type filter for the fetch	The group type to filter the fetched incidents by.	False
   Status filter for the fetch	The status to filter the fetched incidents by (if not field will fetch all statuses).	False
   Incident Metadata	The metadata to collect.	False
   Source Reliability	Reliability of the source providing the intelligence data.	True
   Rating Threshold for Malicious Indicators	Rating Threshold for Malicious Indicators. This is necessary to calculate reputation.	False
   Confidence Threshold for Malicious Indicators	Confidence Threshold for Malicious Indicators. This is necessary to calculate reputation.	False
   Indicator Reputation Freshness in days	Indicator Reputation Freshness. This is necessary to calculate reputation.	False
   TQL Filter	A free text TQL filter to apply to the fetch. This filter is added as an AND to the other filters. Refer to https://knowledge.threatconnect.com/docs/threatconnect-query-language-tql for a basic TQL guide.	False

4. Click Test to validate the URLs, token, and connection.

Commands

You can execute these commands from the Cortex XSOAR CLI, as part of an automation, or in a playbook.
After you successfully execute a command, a DBot message appears in the War Room with the command details.

ip

Searches for an indicator of type IP address.

Base Command

ip

Input

Context Output

url

Searches for an indicator of type URL.

Notice: Submitting indicators using this command might make the indicator data publicly available. See the vendor’s documentation for more details.

Base Command

url

Input

Context Output

file

Searches for an indicator of type file.

Base Command

file

Input

Context Output

tc-owners

Retrieves all owners for the current account.

Base Command

tc-owners

Input

| Argument Name | Description | Required |
| — | — | — |

Context Output

tc-indicators

Retrieves a list of all indicators.

Base Command

tc-indicators

Input

Context Output

tc-get-tags

Returns a list of all ThreatConnect tags.

Base Command

tc-get-tags

Input

Context Output

tc-tag-indicator

Adds a tag to an existing indicator.

Base Command

tc-tag-indicator

Input

Context Output

There is no context output for this command.

tc-get-indicator

Retrieves information about an indicator.

Base Command

tc-get-indicator

Input

Context Output

tc-get-indicators-by-tag

Fetches all indicators that have a tag.

Base Command

tc-get-indicators-by-tag

Input

Context Output

tc-add-indicator

Adds a new indicator to ThreatConnect.

Base Command

tc-add-indicator

Input

Context Output

tc-create-incident

Creates a new incident group.

Base Command

tc-create-incident

Input

Context Output

tc-incident-associate-indicator

Associates an indicator with an existing incident. The indicator must exist before running this command. To add an indicator, run the tc-add-indicator command.

Base Command

tc-incident-associate-indicator

Input

Context Output

domain

Searches for an indicator of type domain.

Notice: Submitting indicators using this command might make the indicator data publicly available. See the vendor’s documentation for more details.

Base Command

domain

Input

Context Output

tc-get-incident-associate-indicators

Returns indicators that are related to a specific incident.

Base Command

tc-get-incident-associate-indicators

Input

Context Output

tc-update-indicator

Updates the indicator in ThreatConnect.

Base Command

tc-update-indicator

Input

Context Output

tc-delete-indicator-tag

Removes a tag from a specified indicator.

Base Command

tc-delete-indicator-tag

Input

Context Output

tc-delete-indicator

Deletes an indicator from ThreatConnect.

Base Command

tc-delete-indicator

Input

Context Output

There is no context output for this command.

tc-create-campaign

Creates a group based on the Campaign type.

Base Command

tc-create-campaign

Input

Context Output

tc-create-event

Creates a group based on the Event type.

Base Command

tc-create-event

Input

Context Output

tc-create-threat

Creates a group based on the “Threats” type.

Base Command

tc-create-threat

Input

Context Output

tc-delete-group

Deletes a group.

Base Command

tc-delete-group

Input

Context Output

There is no context output for this command.

tc-get-events

Returns a list of events.

Base Command

tc-get-events

Input

Context Output

tc-list-groups

Returns all groups.

Base Command

tc-list-groups

Input

Context Output

tc-add-group-tag

Adds tags to a specified group.

Base Command

tc-add-group-tag

Input

Context Output

There is no context output for this command.

tc-get-indicator-types

Returns all indicator types available.

Base Command

tc-get-indicator-types

Input

| Argument Name | Description | Required |
| — | — | — |

Context Output

tc-create-document-group

Creates a document group.

Base Command

tc-create-document-group

Input

Context Output

tc-download-document

Downloads the contents of a document.

Base Command

tc-download-document

Input

Context Output

tc-get-associated-groups

Returns groups associated with a specified group.

Base Command

tc-get-associated-groups

Input

Context Output

tc-get-indicator-owners

Get the owner for an indicator.

Base Command

tc-get-indicator-owners

Input

Context Output

There is no context output for this command.

tc-download-report

The group report to download in PDF format.

Base Command

tc-download-report

Input

Context Output

tc-update-group

Updates a group.

Base Command

tc-update-group

Input

Context Output

Redundant Arguments

The following arguments were removed in this version:

In the tc-tag-indicator command:

• owner - this argument was redundant.

In the tc-get-indicator command:

• indicator_type - this argument was redundant.
• owners - this argument was redundant.
• ratingThreshold - this argument was redundant.
• confidenceThreshold - this argument was redundant.
• group_associations - this argument was redundant.
• indicator_associations - this argument was redundant.
• indicator_observations - this argument was redundant.
• indicator_tags - this argument was redundant.
• indicator_attributes - this argument was redundant.

In the tc-add-indicator command:

• owner - this argument was redundant.

In the tc-create-incident command:

• owner - this argument was redundant.

In the tc-fetch-incidents command:

• incidentName - this argument was redundant.

In the tc-incident-associate-indicator command:

• indicatorType - this argument was redundant.
• owner - this argument was redundant.

In the tc-get-incident-associate-indicators command:

• owner - this argument was redundant.

In the tc-update-indicator command:

• observations - this argument was redundant.
• threatAssessConfidence - this argument was redundant.
• threatAssessRating - this argument was redundant.
• owner - this argument was redundant.

In the tc-create-campaign command:

• owner - this argument was redundant.

In the tc-create-event command:

• owner - this argument was redundant.

In the tc-delete-group command:

• type - this argument was redundant.

In the tc-add-group-attribute command:

• group_type - this argument was redundant.

In the tc-add-group-security-label command:

• group_type - this argument was redundant.

In the tc-add-group-tag command:

• group_type - this argument was redundant.

In the tc-group-associate-indicator command:

• indicator_type - this argument was redundant.
• group_type - this argument was redundant.

In the tc-get-group command:

• group_type - this argument was redundant.

In the tc-get-group-attributes command:

• group_type - this argument was redundant.

In the tc-get-group-security-labels command:

• group_type - this argument was redundant.

In the tc-get-group-tags command:

• group_type - this argument was redundant.

In the tc-get-group-indicators command:

• group_type - this argument was redundant.

In the tc-get-associated-groups command:

• group_type - this argument was redundant.

In the tc-associate-group-to-group command:

• group_type - this argument was redundant.
• associated_group_type - this argument was redundant.

In the tc-download-report command:

• group_type - this argument was redundant.

Additional Considerations for this version

API version 3 documentation
Use the new REST v3 API instead of the old python module.

tc-create-victim-attribute

Creates a victim attribute.

Base Command

tc-create-victim-attribute

Input

Context Output

Command example

!tc-create-victim-attribute attribute_type="Takedown Requests" victim_id=668 attribute_value="test"

Context Example

{
    "TC": {
        "VictimAttribute": {
            "createdBy": {
                "firstName": "Demisto API",
                "id": 615,
                "lastName": "Demisto API",
                "owner": "Palo Alto Cortex XSOAR",
                "pseudonym": "APIUsersTest",
                "userName": "test"
            },
            "dateAdded": "2024-01-04T13:24:53Z",
            "default": false,
            "id": 133,
            "lastModified": "2024-01-04T13:24:53Z",
            "pinned": false,
            "type": "Takedown Requests",
            "value": "test"
        }
    }
}

Human Readable Output

Victim Attribute 133 created successfully for victim id: 668

tc-create-victim

Creates a victim.

Base Command

tc-create-victim

Input

Context Output

Command example

!tc-create-victim name="test" org="test" asset_type="EmailAddress" asset_value="test@test.com" attribute_type="Description" attribute_value="test"

Context Example

{
    "TC": {
        "Victim": {
            "id": 671,
            "name": "test",
            "org": "test",
            "ownerId": 271,
            "ownerName": "Palo Alto Cortex XSOAR",
            "webLink": "https://threatconnect.com/auth/victim/victim.xhtml?victim=671"
        }
    }
}

Human Readable Output

Victim test created successfully with id: 671

tc-create-victim-asset

Creates a victim asset.

Base Command

tc-create-victim-asset

Input

Context Output

Command example

!tc-create-victim-asset victim_id=668 asset_type=SocialNetwork asset_value=test asset_social_network=test

Context Example

{
    "TC": {
        "VictimAsset": {
            "accountName": "test",
            "id": 753,
            "socialNetwork": "test",
            "type": "SocialNetwork",
            "victimId": 668,
            "webLink": "https://threatconnect.com/auth/victim/victim.xhtml?victim=668"
        }
    }
}

Human Readable Output

Victim Asset 753 created successfully for victim id: 668

tc-list-victim-assets

Retrieves victim assets.

Base Command

tc-list-victim-assets

Input

Context Output

Command example

!tc-list-victim-assets limit=1

Context Example

{
    "TC": {
        "VictimAsset": {
            "id": 740,
            "phone": "111111",
            "type": "Phone",
            "victimId": 660,
            "webLink": "https://threatconnect.com/auth/victim/victim.xhtml?victim=660"
        }
    }
}

Human Readable Output

Victim assets

id	type	victimId	asset
740	Phone	660	111111

tc-list-victim-attributes

Retrieves victim attributes.

Base Command

tc-list-victim-attributes

Input

Context Output

Command example

!tc-list-victim-attributes limit=1

Context Example

{
    "TC": {
        "VictimAttribute": {
            "createdBy": {
                "firstName": "Demisto API",
                "id": 615,
                "lastName": "Demisto API",
                "owner": "Palo Alto Cortex XSOAR",
                "pseudonym": "APIUsersTest",
                "userName": "08265138623174323158"
            },
            "dateAdded": "2024-01-04T13:24:57Z",
            "default": false,
            "id": 134,
            "lastModified": "2024-01-04T13:24:57Z",
            "pinned": false,
            "type": "Description",
            "value": "test"
        }
    }
}

Human Readable Output

Victim attributes

id	type	value	dateAdded
134	Description	test	2024-01-04T13:24:57Z

tc-list-victims

Retrieves victims.

Base Command

tc-list-victims

Input

Context Output

Command example

!tc-list-victims limit=1

Context Example

{
    "TC": {
        "Victim": {
            "id": 663,
            "name": "nat",
            "ownerId": 271,
            "ownerName": "Palo Alto Cortex XSOAR",
            "webLink": "https://threatconnect.com/auth/victim/victim.xhtml?victim=663"
        }
    }
}

Human Readable Output

Victims

id	name	ownerName	description	org
663	nat	Palo Alto Cortex XSOAR

tc-update-victim

Updates a victim.

Base Command

tc-update-victim

Input

Context Output

Command example

!tc-update-victim victim_id=668 mode=append attribute_type="Source" attribute_value="test"

Context Example

{
    "TC": {
        "Victim": {
            "id": 668,
            "name": "nat",
            "ownerId": 271,
            "ownerName": "Palo Alto Cortex XSOAR",
            "webLink": "https://threatconnect.com/auth/victim/victim.xhtml?victim=668"
        }
    }
}

Human Readable Output

Victim 668 was successfully updated.

tc-update-victim-asset

Updates a victim asset.

Base Command

tc-update-victim-asset

Input

Context Output

Command example

!tc-update-victim-asset victim_asset_id=750 asset_value="11111"

Context Example

{
    "TC": {
        "VictimAsset": {
            "id": 750,
            "phone": "11111",
            "type": "Phone",
            "victimId": 669,
            "webLink": "https://threatconnect.com/auth/victim/victim.xhtml?victim=669"
        }
    }
}

Human Readable Output

Victim Asset 750 updated successfully for victim id: 669

tc-update-victim-attribute

Updates a victim attribute.

Base Command

tc-update-victim-attribute

Input

Context Output

Command example

!tc-update-victim-attribute victim_attribute_id="132" attribute_value="test2"

Context Example

{
    "TC": {
        "VictimAttribute": {
            "createdBy": {
                "firstName": "Demisto API",
                "id": 615,
                "lastName": "Demisto API",
                "owner": "Palo Alto Cortex XSOAR",
                "pseudonym": "APIUsersTest",
                "userName": "test"
            },
            "dateAdded": "2024-01-04T09:14:16Z",
            "default": false,
            "id": 132,
            "lastModified": "2024-01-04T13:25:19Z",
            "pinned": false,
            "type": "Source",
            "value": "test2"
        }
    }
}

Human Readable Output

Victim attribute 132 was successfully updated.

tc-delete-victim-asset

Deletes a victim asset.

Base Command

tc-delete-victim-asset

Input

Context Output

There is no context output for this command.

Command example

!tc-delete-victim-asset victim_asset_id=738

Human Readable Output

Victim asset 738 was successfully deleted.

tc-delete-victim-attribute

Deletes a victim attribute.

Base Command

tc-delete-victim-attribute

Input

Context Output

There is no context output for this command.

Command example

!tc-delete-victim-attribute victim_attribute_id=110

Human Readable Output

Victim attribute 110 was successfully deleted.

tc-list-attribute-type

Retrieved all attribute types

Base Command

tc-list-attribute-type

Input

Context Output

Command example

!tc-list-attribute-type limit=1

Context Example

{
    "TC": {
        "AttributeType": {
            "allowMarkdown": true,
            "description": "Describe the Course of Action Taken.",
            "errorMessage": "Please enter a valid Course of Action.",
            "id": 1,
            "maxSize": 500,
            "name": "Course of Action Taken"
        }
    }
}

Human Readable Output

Attribute types

id	name	description
1	Course of Action Taken	Describe the Course of Action Taken.

tc-delete-victim

Deletes a victim.

Base Command

tc-delete-victim

Input

Context Output

There is no context output for this command.

Command example

!tc-delete-victim victim_id=660

Human Readable Output

Victim 660 was successfully deleted.