---
title: "ThreatConnect Threat Intelligence Enrichment API Plugin for Microsoft Security Copilot User Guide"
slug: "threatconnect-threat-intelligence-enrichment-api-plugin-for-microsoft-security-copilot-user-guide"
description: "This article is a user guide for the ThreatConnect Threat Intelligence Enrichment API plugin for Microsoft Security Copilot."
updated: 2024-12-21T02:36:26Z
published: 2024-12-21T02:36:26Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.threatconnect.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ThreatConnect Threat Intelligence Enrichment API Plugin for Microsoft Security Copilot User Guide

Software VersionThis guide applies to the **ThreatConnect Threat Intelligence Enrichment** API Plugin for Microsoft Security Copilot version 1.*x*.

## Overview

The **ThreatConnect Threat Intelligence Enrichment**API plugin for Microsoft® Security Copilot enables you to use ThreatConnect®-specific skills in the Copilot standalone experience to query ThreatConnect instances for Indicators, Groups, and Intelligence Requirements (IRs) and to generate [ThreatConnect Query Language (TQL)](https://knowledge.threatconnect.com/docs/threatconnect-query-language-tql) queries. You can then apply Copilot’s extensive AI summarization capabilities to the enriched data it returns from ThreatConnect to create comprehensive reports. In addition, you can use the ThreatConnect-specific skills in Copilot promptbooks to create fast and repeatable workflows.

![Overview image](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Overview%20image.jpg)

NoteCustomer data are isolated and not used to train Microsoft large language models (LLMs).

## Dependencies

### ThreatConnect Dependencies

- Active ThreatConnect Application Programming Interface (API) token
- ThreatConnect instance with version 7.7 or newer installed
- ThreatConnect **Threat Intelligence Enrichment API** plugin (provided by ThreatConnect; please email your Customer Success representative directly for access)

NoteAll ThreatConnect dependencies will be provided by default to subscribing ThreatConnect Cloud customers. Customers on Dedicated Cloud and On-Premises instances can enable these settings on the **Account Settings** screen within their ThreatConnect instance.

### Microsoft Dependencies

- Microsoft Security Copilot trial or full-product version

## Setup and Installation

Follow these steps to set up and install the **ThreatConnect Threat Intelligence Enrichment** API plugin for Copilot:

1. [Onboard to Copilot](/v1/docs/threatconnect-threat-intelligence-enrichment-api-plugin-for-microsoft-security-copilot-user-guide#copilot-onboarding).
2. [Set up the **ThreatConnect Threat Intelligence Enrichment** API plugin in Copilot](/v1/docs/threatconnect-threat-intelligence-enrichment-api-plugin-for-microsoft-security-copilot-user-guide#threatconnect-plugin-installation-and-configuration-in-copilot).

### Copilot Onboarding

Copilot operates using a provisioned-capacity model in which customers purchase and use a preset number of Security Compute Units (SCUs) per hour. Follow the instructions in *[Get Started with Microsoft Security Copilot](https://learn.microsoft.com/en-us/copilot/security/get-started-security-copilot)* to onboard to Copilot by provisioning your capacity for Copilot and setting up a default environment:

NoteYou can skip the instructions in this section if you have already purchased and configured SCUs in Copilot and have a working login at [https://securitycopilot.microsoft.com](https://securitycopilot.microsoft.com).

1. **[Step 1: Provision capacity](https://learn.microsoft.com/en-us/copilot/security/get-started-security-copilot#step-1-provision-capacity)**. Choose one of the following two methods to provision capacity for Copilot:
  1. [Option 1 (Recommended): Provision capacity through Security Copilot](https://learn.microsoft.com/en-us/copilot/security/get-started-security-copilot#option-1-recommended-provision-capacity-through-security-copilot).
  2. [Option 2: Provision capacity in Azure®](https://learn.microsoft.com/en-us/copilot/security/get-started-security-copilot#option-2-provision-capacity-in-azure).
2. **[Step 2: Set up the default environment](https://learn.microsoft.com/en-us/copilot/security/get-started-security-copilot#step-2-set-up-default-environment)**.

### ThreatConnect Plugin Installation and Configuration in Copilot

Follow these steps to install and configure the **ThreatConnect Threat Intelligence Enrichment**API plugin in Copilot:

1. Contact your Customer Success representative to request the Copilot Manifest File. The name of this file is **tc_manifest_separate.yml**.
2. [Open and log into Copilot](https://securitycopilot.microsoft.com/).
3. Click **Sources![Sources icon](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Sources%20icon.png)**on the Copilot prompt bar to open the **Plugins** tab of the **Manage Sources** window.
4. Scroll down to the **Custom** section and click **Upload plugin![Upload Plugin icon](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Upload%20Plugin%20icon.png)**. Then fill out the fields on the **Add a plugin** window (Figure 1) as follows: ![Figure 1_ThreatConnect Threat Intelligence Enrichment API Plugin for Microsoft Security Copilot User Guide_Software Version 1.0](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Figure%201_ThreatConnect%20Threat%20Intelligence%20Enrichment%20API%20Plugin%20for%20Microsoft%20Security%20Copilot%20User%20Guide_Software%20Version%201.0.png)
  - **Who can use this plugin?**: Select **Just me** to make the **ThreatConnect Threat Intelligence Enrichment** API plugin available only to you. Select **Anyone in my organization** to make the **ThreatConnect Threat Intelligence Enrichment**API plugin available to all members of your organization.
  - **Select an upload format**: Select **Copilot for Security plugin**. Once you select this option, the window will display the **Upload file** section.
  - **Upload as a link**: (Optional) Leave this toggle turned off.
  - **Upload file**: Click this button. Then locate and select the **tc_manifest_separate.yml** file.
5. Click **Add** on the **Add a plugin** window to add the **ThreatConnect Threat Intelligence Enrichment**API plugin to Copilot.
6. The **ThreatConnect Threat Intelligence Enrichment**API plugin will now be displayed as **ThreatConnect (Preview)** in the **Custom** section on the **Plugins** tab of the **Manage Sources** window. Click **Set up** next to **ThreatConnect (Preview)**. Then fill out the fields on the **ThreatConnect (Preview) settings** window (Figure 2) as follows: ![Figure 2_ThreatConnect Threat Intelligence Enrichment API Plugin for Microsoft Security Copilot User Guide_Software Version 1.0](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Figure%202_ThreatConnect%20Threat%20Intelligence%20Enrichment%20API%20Plugin%20for%20Microsoft%20Security%20Copilot%20User%20Guide_Software%20Version%201.0.png)
  - **ThreatConnect Instance URL**: Enter the URL for your ThreatConnect instance.
  - **Value**: Enter the API token for your ThreatConnect API user account. See the [“Creating an API User” section of *Creating User Accounts*](https://knowledge.threatconnect.com/docs/creating-user-accounts#creating-an-api-user)for more information.NoteIf your ThreatConnect API user account has an [Organization role](https://knowledge.threatconnect.com/docs/organization-roles) of Organization Administrator, you can find the API token for your user account by [navigating to the **Membership** tab of the **Organization Settings** screen](https://knowledge.threatconnect.com/docs/creating-user-accounts#viewing-membership-for-an-organization) and clicking **Edit![Pencil icon_Black](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Pencil%20icon_Black.png)**in the **Options** column for your user account to view the **API User Administration** window. If your ThreatConnect API user account does not have an Organization role of Organization Administrator, you will need to ask an Organization Administrator to provide you with the API key for your user account.
7. Click **Save** on the **ThreatConnect (Preview) settings** window to complete configuration for the **ThreatConnect Threat Intelligence Enrichment** API plugin for Copilot.

## Using ThreatConnect Skills in Copilot

After the **ThreatConnect Intelligence Enrichment** API plugin has been installed and set up, you can use [ThreatConnect skills](/v1/docs/threatconnect-threat-intelligence-enrichment-api-plugin-for-microsoft-security-copilot-user-guide#threatconnect-skills-for-copilot) when writing queries in Copilot. Follow these steps to use a ThreatConnect skill in a Copilot query:

1. [Open and log into Copilot](https://securitycopilot.microsoft.com/).
2. Enter a ThreatConnect skill followed by the input for the skill in the Copilot prompt bar. See the [“ThreatConnect Skills for Copilot” section](/v1/docs/threatconnect-threat-intelligence-enrichment-api-plugin-for-microsoft-security-copilot-user-guide#threatconnect-skills-for-copilot) for a table defining each skill, the type of input the skill takes, and the expected output in Copilot. See the [“ThreatConnect Skill Prompt Examples” section](/v1/docs/threatconnect-threat-intelligence-enrichment-api-plugin-for-microsoft-security-copilot-user-guide#threatconnect-skill-prompt-examples)for example prompts for each skill.NoteYou can also enter a natural-language prompt that does not use any of the ThreatConnect skills (e.g. `what are the indicators in my threatconnect organization`).
3. Click **Submit prompt![Submit prompt icon](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Submit%20prompt%20icon.png)**. Copilot will process the request and return results containing data available to your API user account on the ThreatConnect instance entered in the plugin configuration (Figure 2).

## Viewing Copilot Sessions

A session in Copilot represents a set of prompts you made during a particular time period and the results returned by those prompts. Sessions provide a record of work you have done in Copilot that you can review or use to create a [promptbook](https://learn.microsoft.com/en-us/copilot/security/using-promptbooks). Follow these steps to view your Copilot sessions:

1. Click **Open menu**![Open menu icon](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Open%20menu%20icon.png)at the upper left to display Copilot's side navigation bar.
2. Select **My sessions** to display the **My sessions** screen (Figure 3). On this screen, you can view a session by clicking the link in its **Name** column, create a new session by clicking **+ New session**, or delete one or more sessions by selecting their checkboxes and clicking **Delete**.NoteA new session is also created when you open Copilot and enter a prompt into the prompt bar.![Figure 3_ThreatConnect Threat Intelligence Enrichment API Plugin for Microsoft Security Copilot User Guide_Software Version 1.0](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Figure%203_ThreatConnect%20Threat%20Intelligence%20Enrichment%20API%20Plugin%20for%20Microsoft%20Security%20Copilot%20User%20Guide_Software%20Version%201.0.png)

## Creating Promptbooks in Copilot

A promptbook in Copilot is a [series of prompts that have been put together to accomplish specific security-related tasks](https://learn.microsoft.com/en-us/copilot/security/prompting-security-copilot#using-the-prompts-library). You can use promptbooks to store and repeat a set of prompts without having to retype each prompt individually. Follow these steps to [create a promptbook](https://learn.microsoft.com/en-us/copilot/security/build-promptbooks):

1. In your current session, or in a session you have opened from the [**My sessions** screen](/v1/docs/threatconnect-threat-intelligence-enrichment-api-plugin-for-microsoft-security-copilot-user-guide#viewing-copilot-sessions), select the checkbox to the left of each prompt that you want to add to a promptbook.
2. Click **Create promptbook![Create promptbook icon](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Create%20promptbook%20icon.png)**on the options strip above the session. Then fill out the fields on the**Create a prompt book**screen (Figure 4) as follows:![Figure 4_ThreatConnect Threat Intelligence Enrichment API Plugin for Microsoft Security Copilot User Guide_Software Version 1.0](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Figure%204_ThreatConnect%20Threat%20Intelligence%20Enrichment%20API%20Plugin%20for%20Microsoft%20Security%20Copilot%20User%20Guide_Software%20Version%201.0.png)
  - **Name**: Enter a name for the promptbook.
  - **Tags**: (Optional) Add one or more tags to the promptbook. If entering multiple tags, press **Enter**after entering each tag.
  - **Description**: Enter a description for the promptbook.
  - **Plugins**: This field will list the plugins used for the prompts in the promptbook and cannot be edited.
  - **Prompts**: This section lists the prompts you selected from the session to add to the promptbook. Hovering over the right side of the row for a prompt provides an option to edit![Edit prompt icon](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Edit%20prompt%20icon.png)the prompt and a **⋯**menu with options to delete the prompt from the promptbook and move the prompt up or down in the prompt list. Click **+ Add prompt** under the last prompt to add a row in which you can enter a new prompt to the list. When adding a new prompt, you can include one or more inputs. An input is a variable name enclosed in angle brackets (e.g., `<IntelRequirementID>`, `<hostname>`) to indicate that, the next time the promptbook is run, the user will need to enter a value for the input. Note that inputs cannot contain spaces.
  - **Inputs you’ll need**: This section lists inputs in the promptbook’s prompts, if applicable.
  - **Who can use this promptbook?**: Select **Just me** to make the promptbook available only to you. Select **Anyone in my organization** to make the promptbook available to all members of your organization.
3. Click **Create** on the **Create a prompt book** window to create the promptbook.

You can view, edit, and run your saved promptbooks from your promptbook library, which you can view by clicking **Open menu**![Open menu icon](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Open%20menu%20icon.png)at the upper left of Copilot and selecting **Promptbook library**.

## ThreatConnect Skills for Copilot

Table 1 lists all ThreatConnect skills for Copilot and defines their required input and expected output.

| ThreatConnect Skill | Input for Skill | Expected Output |
| --- | --- | --- |
| /tcGetIndicators | Name/Summary of a single ThreatConnect Indicator *or* a natural-language description of a set of Indicators to return from ThreatConnect. Natural-language prompts are translated into a TQL query when ThreatConnect processes the request from Copilot. | Details, Tags, and Attributes for the Indicator, as well as links to the Indicator’s **Details** screen in all ThreatConnect owners you have access to. If the results set contains multiple Indicators, they will be returned as a list or table. |
| /tcGetGroups | Name/Summary of a single ThreatConnect Group *or* a natural-language description of a set of Groups to return from ThreatConnect. Natural-language prompts are translated into a TQL query when ThreatConnect processes the request from Copilot. | Details for the Group, as well as links to the Group’s **Details** screen in all ThreatConnect owners you have access to. Links to the Group in non-ThreatConnect feeds may also be provided. If the results set contains multiple Groups, they will be returned as a list or table. |
| /tcGetGroupById | ThreatConnect ID number of a single ThreatConnect Group. This number may be found by navigating to the **Details** screen for the Group and identifying the number at the end of the URL. | Details for the Group, as well as links to the Group’s **Details** screen in all ThreatConnect owners you have access to. Links to the Group in non-ThreatConnect feeds may also be provided. |
| /tcGetIR | Unique ID for a single IR in ThreatConnect (that is, the ID number defined for the IR by the user who created it, not the ThreatConnect ID number found in the URL for the IR’s **Details** screen) *or* a natural-language description of a set of IRs to return from ThreatConnect. Natural-language prompts are translated into a TQL query when ThreatConnect processes the request from Copilot. | Details and Tags for the IR, as well as a link to the IR’s **Details** screen in ThreatConnect. If the results set contains multiple IRs, they will be returned as a list or table. |
| /tcGetIRResults | ID for a single IR in ThreatConnect.HintAdd `global results` for between the prompt and the IR’s ID to get only global results. Add `local results for` between the prompt and the IR’s ID to get only local results. Note that a search requesting local results only may return the same results set as a search that does not specify a result type, as the 10 results returned for a general search may be the same 10 results returned from a search for local results only. | A table displaying 10 of the IR’s results. |
| /tcGenerateBasicTQL | A natural-language description of the set of ThreatConnect data you want a TQL query to return. | A TQL query matching the criteria of the prompt.HintAfter Copilot returns the TQL query, you can submit the prompt `run this tql` to run the query in Copilot. |

WarningAI-generated information is sometimes inaccurate. It is recommended that you review responses generated by Copilot before proceeding.ImportantAll output sets containing multiple objects will return a maximum of 10 objects in the list or table, even if more objects match the requirements in the prompt. If a table is returned, Copilot will display a subset of the table’s rows and columns. Click **Expand![Expand icon](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Expand%20icon.png)**to expand the view of the table. Click **Export to Excel** to export the table to an Excel® spreadsheet.ImportantResults returned by Copilot currently use the term “organization” to refer to any ThreatConnect owner rather than the Organization [owner type](https://knowledge.threatconnect.com/docs/ownership-in-threatconnect) in ThreatConnect. For example, the statement ‘Here are the details of the “bad.com” in your ThreatConnect organization’ in Copilot’s results may be followed by details for the Indicator in a ThreatConnect Organization, Community, or Source.HintCopilot prompts are not case sensitive.

## ThreatConnect Skill Prompt Examples

### Skill Prompt Examples: /tcGetIndicators

```none
/tcGetIndicators 1.2.3.4
```

```none
/tcGetIndicators bad.com
```

```none
/tcGetIndicators indicators created in the past 12 months in the source "CrowdStrike Falcon Intelligence" and has tag "Threat Type: Criminal" with at least one observation and no false positive reports
```

NoteYou can add an Indicator type to the prompt after the skill name or at the end of the prompt (e.g., `/tcGetIndicators host indicators created in the past 12 months in the source "CrowdStrike Falcon Intelligence" and has tag "Threat Type: Criminal" with at least one observation and no false positive reports`; `/tcGetIndicators bad.com host indicator`). However, Copilot sometimes returns other Indicator types in its response.Hint[File Indicators in ThreatConnect](https://knowledge.threatconnect.com/docs/managing-file-hashes-and-known-file-occurrences) can have up to three hashes (MD5, SHA1, and SHA256). If you are searching for a single File Indicator with more than one hash, you can query Copilot with one of the hashes (e.g., `/tcGetIndicators EAF62ADE86350B658D68973A5299DE82E25DE759`) or with multiple hashes separated by colons (e.g., `/tcGetIndicators 11B44C0FFCE780A3CE48A641431D0AD0 : EAF62ADE86350B658D68973A5299DE82E25DE759 : E079961F8556B5FC0C3BDC0E4DD1558CCB775BE4D80AE847B26CDA0658B85373`). (Including a space on either side of the colon is optional.) To query Copilot for all File Indicators that have at least one of a set of multiple hashes, separate each hash by a space (e.g., `/tcGetIndicators 11B44C0FFCE780A3CE48A641431D0AD0 EAF62ADE86350B658D68973A5299DE82E25DE759 E079961F8556B5FC0C3BDC0E4DD1558CCB775BE4D80AE847B26CDA0658B85373`). Similarly, Registry Key Indicators in ThreatConnect can have three parts to their Name/Summary: Key Name, Value Name, and Value Type. Queries for Registry Keys in Copilot operate similarly to queries for File Indicators. Note that queries for multiple named Indicators of other types (e.g., `/tcGetIndicators bad.com badguy.com`) may return results for only one of the Indicators.

### Skill Prompt Examples: /tcGetGroups

```none
/tcGetGroups Mustang Panda
```

```none
/tcGetGroups CVE-2024-21743
```

```none
/tcGetGroups group associated with an ip address indicator and the indicator having a tag of "Threat Type: RAT"
```

NoteYou can add a Group type to the prompt after the skill name or at the end of the prompt (e.g., `/tcGetGroups malware group associated with an ip address indicator and the indicator having a tag of "Threat Type: RAT"`; `/tcGetGroups Mustang Panda adversary group`). However, Copilot sometimes returns other Group types in its response.

### Skill Prompt Examples: /tcGetGroupByID

```none
/tcGetGroupById 1125899927003855
```

### Skill Prompt Examples: /tcGetIR

```none
/tcGetIR IR-001-2022.1
```

```none
/tcGetIR What intel requirements does threatconnect have with a tag containing "dragos"?
```

### Skill Prompt Examples: /tcGetIRResults

```none
/tcGetIRResults IR-010-2022
```

```none
/tcGetIRResults local results for IR-010-2022
```

```none
/tcGetIRResults global results for IR-010-2022
```

NoteA search requesting local results only may return the same results set as a search that does not specify a result type, as the 10 results returned for a general search may be the same 10 results returned from a search for local results only.

### Skill Prompt Examples: /tcGenerateBasicTQL

```none
tcGenerateBasicTQL report made in February
```

```none
/tcGenerateBasicTQL groups that match the names CVE-2024-5806, CVE-2024-5806, CVE-2024-6387
```

## Frequently Asked Questions (FAQ)

**How does Copilot work?**

Figure 5 displays an overview of what happens when you submit a prompt to Copilot. Copilot can operate using natural-language prompts, or it can use skills—that is, rules for how to access, retrieve, and perform certain actions with data—for direct interaction with a plugin or module.

![Figure 5_ThreatConnect Threat Intelligence Enrichment API Plugin for Microsoft Security Copilot User Guide_Software Version 1.0](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Figure%205_ThreatConnect%20Threat%20Intelligence%20Enrichment%20API%20Plugin%20for%20Microsoft%20Security%20Copilot%20User%20Guide_Software%20Version%201.0.png)**Image credit**: Microsoft Security Copilot, “Security Copilot Coverage and Capabilities,” [https://www.microsoft.com/en-us/security/business/ai-machine-learning/microsoft-security-copilot#modal-021](https://www.microsoft.com/en-us/security/business/ai-machine-learning/microsoft-security-copilot#modal-021), 2024

**How does Copilot choose which plugins to use when a user submits a prompt?**

The following is an excerpt from Microsoft details how the Copilot orchestrator decides which plugins to use:

> When a user submits a query to Copilot, the orchestrator searches its full catalog of skills (*functions*) from installed plugins to identify up to five skills which best match the query. The orchestrator first tries to match on exact words (**lexical match**) and expands its search scope as needed to include matches on descriptive meanings (**semantic match**), working from specific function names to general plugin descriptions, until all five function candidate slots are filled. Specifically, here is the hierarchy of matching mechanisms for Copilot plugin function selection:
> 
> 1. Lexical match on function name.
> 2. Semantic match on function description.
> 3. Lexical match on plugin name (adds all plugin functions to candidate list).
> 4. Semantic match on plugin name (adds all plugin functions to candidate list).
> 
> See [*Overview of the Microsoft 365 Copilot orchestrator*](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/orchestrator) for further information.

**What do I do if Copilot is returning error messages, no data, or otherwise not providing expected results?**

There are several troubleshooting steps you can take if Copilot is returning error messages, no data, or not providing expected results:

1. Check your Copilot usage to ensure you are under your organization’s usage limit.
2. Make sure the ThreatConnect instance URL in the **ThreatConnect (Preview) settings** (Figure 2) is pointing to the correct instance.
3. Make sure your ThreatConnect API token is entered correctly in the **ThreatConnect (Preview) settings** (Figure 2) and that it is not expired.
4. Make sure you have only one version of the **ThreatConnect (Preview)** plugin installed in the **Custom** section on the **Plugins** tab of the **Manage sources** window.
5. If pure natural-language prompts are not working, try using ThreatConnect skills for Copilot instead.
6. If some skills are not returning the expected data, try adding the Group or Indicator type right after the skill (e.g., `/tcGetIndicators host bad.com`).

---

*ThreatConnect® is a registered trademark of ThreatConnect, Inc.* *Azure®, Excel®, and Microsoft® are registered trademarks of Microsoft Corporation*

30090-01 EN Rev. A