diff --git a/windows/keep-secure/custom-ti-api-windows-defender-advanced-threat-protection.md b/windows/keep-secure/custom-ti-api-windows-defender-advanced-threat-protection.md index 39d95bc706..23312b38db 100644 --- a/windows/keep-secure/custom-ti-api-windows-defender-advanced-threat-protection.md +++ b/windows/keep-secure/custom-ti-api-windows-defender-advanced-threat-protection.md @@ -1,7 +1,7 @@ --- title: Create custom threat intelligence using REST API in Windows Defender ATP description: Create your custom alert definitions and indicators of compromise in Windows Defender ATP using the available APIs in Windows Enterprise, Education, and Pro editions. -keywords: alert definitions, indicators of compromise, threat intelligence, custom ti, rest api, api +keywords: alert definitions, indicators of compromise, threat intelligence, custom threat intelligence, rest api, api search.product: eADQiWindows 10XVcnh ms.prod: w10 ms.mktglfcycl: deploy @@ -11,7 +11,7 @@ author: mjcaparas localizationpriority: high --- -# Create custom threat intelligence (TI) using REST API +# Create custom alerts using the threat intelligence (TI) Application program interface (API) **Applies to:** @@ -23,13 +23,13 @@ localizationpriority: high [Some information relates to pre-released product, which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.] -You can define custom alert definitions and indicators of compromise (IOC) using the available APIs. Creating custom TIs allows you to create specific alerts that are applicable to your organization. +You can define custom alert definitions and indicators of compromise (IOC) using the threat intelligence API. Creating custom threat intelligence alerts allows you to create specific alerts that are applicable to your organization. ## Before you begin -Before creating custom TIs, you'll need to enable the custom TI application in Azure Active Directory and generate access tokens. For more information, see [Enable the custom threat intelligence application](enable-custom-ti-windows-defender-advanced-threat-protection.md). +Before creating custom alerts, you'll need to enable the threat intelligence application in Azure Active Directory and generate access tokens. For more information, see [Enable the custom threat intelligence application](enable-custom-ti-windows-defender-advanced-threat-protection.md). -### Use the available REST APIs to create custom TIs -You can call and specify the resource URLs using one of the following operations to access and manipulate a custom TI resource, you call and specify the resource URLs using one of the following operations: +### Use the threat intelligence REST APIs to create custom threat intelligence alerts +You can call and specify the resource URLs using one of the following operations to access and manipulate a threat intelligence resource, you call and specify the resource URLs using one of the following operations: - GET - POST @@ -37,14 +37,14 @@ You can call and specify the resource URLs using one of the following operations - PUT (used for managing entities relations only) - DELETE -All custom TI API requests use the following basic URL pattern: +All threat intelligence API requests use the following basic URL pattern: ``` https://TI.SecurityCenter.Windows.com/{version}/{resource}?[query_parameters] ``` For this URL: -- `https://TI.SecurityCenter.Windows.com` is the custom TI API endpoint. +- `https://TI.SecurityCenter.Windows.com` is the threat intelligence API endpoint. - `{version}` is the target service version. Currently only supported version is: v1.0. - `{resource}` is resource segment or path, such as: - AlertDefinitions (for specific single resource, add: (id)) @@ -54,7 +54,7 @@ For this URL: **Quotas**
Each tenant has a defined quota that limits the number of possible alert definitions, IOCs and another quota for IOCs of Action different than “equals” in the system. If you upload data beyond this quota, you'll encounter an HTTP error status code 507 (Insufficient Storage). -## Custom TI API metadata +## Threat Intelligence API metadata The metadata document ($metadata) is published at the service root. For example, you can view the service document for the v1.0 version using the following URL: @@ -63,11 +63,11 @@ For example, you can view the service document for the v1.0 version using the fo https://TI.SecurityCenter.Windows.com/v1.0/$metadata ``` -The metadata allows you to see and understand the data model of the custom TI, including the entity types and sets, complex types, and enums that make up the request and response packets sent to and from custom TI. +The metadata allows you to see and understand the data model of the custom threat intelligence, including the entity types and sets, complex types, and enums that make up the request and response packets sent to and from the threat intelligence API. -You can use the metadata to understand the relationships between entities in custom TI and establish URLs that navigate between entities. +You can use the metadata to understand the relationships between entities in custom threat intelligence and establish URLs that navigate between entities. -The following sections show a few basic programming pattern calls to the custom TI API. +The following sections show a few basic programming pattern calls to the threat intelligence API. ## Create new resource Typically, you'd need to create an alert definition to start creating custom threat intelligence. An ID is created for that alert definition. @@ -331,7 +331,7 @@ Upon a successful request the response will be HTTP 204. ## Windows Defender ATP optional query parameters -Windows Defender ATP custom TI provides several optional query parameters that you can use to specify and control the amount of data returned in a response. Custom TI supports the following query options: +The Windows Defender ATP threat intelligence API provides several optional query parameters that you can use to specify and control the amount of data returned in a response. The threat intelligence API supports the following query options: Name | Value | Description :---|:---|:-- diff --git a/windows/keep-secure/enable-custom-ti-windows-defender-advanced-threat-protection.md b/windows/keep-secure/enable-custom-ti-windows-defender-advanced-threat-protection.md index 32e8d9b2f3..8b7849114b 100644 --- a/windows/keep-secure/enable-custom-ti-windows-defender-advanced-threat-protection.md +++ b/windows/keep-secure/enable-custom-ti-windows-defender-advanced-threat-protection.md @@ -33,7 +33,8 @@ Before you can create custom threat intelligence (TI) using REST API, you'll nee >[!WARNING] >The client secret is only displayed once. Make sure you keep a copy of it in a safe place. ->For more information about getting a new secret see, [Learn how to get a new secret](). +>For more information about getting a new secret see, [Learn how to get a new secret](troubleshoot-custom-ti-windows-defender-advanced-threat-protection.md#learn-how-to-get-a-new-client-secret). + 4. Select **Generate tokens** to get an access and refresh token. diff --git a/windows/keep-secure/threat-indicator-concepts-windows-defender-advanced-threat-protection.md b/windows/keep-secure/threat-indicator-concepts-windows-defender-advanced-threat-protection.md index b7e0fe2900..32dc72d7fd 100644 --- a/windows/keep-secure/threat-indicator-concepts-windows-defender-advanced-threat-protection.md +++ b/windows/keep-secure/threat-indicator-concepts-windows-defender-advanced-threat-protection.md @@ -25,9 +25,9 @@ localizationpriority: high Advanced cybersecurity attacks comprise of multiple complex malicious events, attributes, and contextual information. Identifying and deciding which of these activities qualify as suspicious can be a challenging task. Your knowledge of known attributes and abnormal activities specific to your industry is fundamental in knowing when to call an observed behavior as suspicious. -With Windows Defender ATP, you can create custom threat intelligence that can help you keep track of possible attack activities in your organization. You can flag suspicious events to piece together clues and possibly stop an attack chain. These custom intelligence will only appear in your organization and will flag events that you set it to track. +With Windows Defender ATP, you can create custom threat alerts that can help you keep track of possible attack activities in your organization. You can flag suspicious events to piece together clues and possibly stop an attack chain. These custom threat alerts will only appear in your organization and will flag events that you set it to track. -Before creating custom threat intelligence, it's important to know the concepts behind alert definitions and indicators of compromise (IOCs) and the relationship between them. +Before creating custom threat alerts, it's important to know the concepts behind alert definitions and indicators of compromise (IOCs) and the relationship between them. ## Alert definitions Alert definitions are contextual attributes that can be used collectively to identify early clues on a possible cybersecurity attack. These indicators are typically a combination of activities, characteristics, and actions taken by an attacker to successfully achieve the objective of an attack. Monitoring these combinations of attributes is critical in gaining a vantage point against attacks and possibly interfering with the chain of events before an attacker's objective is reached. @@ -36,7 +36,7 @@ Alert definitions are contextual attributes that can be used collectively to ide IOCs are individually-known malicious events that indicate that a network or machine has already been breached. Unlike alert definitions, these indicators are considered as evidence of a breach. They are often seen after an attack has already been carried out and the objective has been reached, such as exfiltration. Keeping track of IOCs is also important during forensic investigations. Although it might not provide the ability to intervene with an attack chain, gathering these indicators can be useful in creating better defenses for possible future attacks. ## Relationship between alert definitions and IOCs -In the context of Windows Defender ATP, alert definitions are containers for IOCs and defines the alert, including the metadata that is raised in case of a specific IOC match. Various metadata is provided as part of the alert definitions. Metadata such as alert definition name of attack, severity, and description is provided along with other options. For more information on available metadata options, see [Custom TI API metadata](custom-ti-api-windows-defender-advanced-threat-protection.md#custom-ti-api-metadata). +In the context of Windows Defender ATP, alert definitions are containers for IOCs and defines the alert, including the metadata that is raised in case of a specific IOC match. Various metadata is provided as part of the alert definitions. Metadata such as alert definition name of attack, severity, and description is provided along with other options. For more information on available metadata options, see [Threat Intelligence API metadata](custom-ti-api-windows-defender-advanced-threat-protection.md#threat-intelligence-api-metadata). Each IOC defines the concrete detection logic based on its type and value as well as its action, which determines how it is matched. It is bound to a specific alert definition that defines how a detection is displayed as an alert on the Windows Defender ATP console. diff --git a/windows/keep-secure/troubleshoot-custom-ti-windows-defender-advanced-threat-protection.md b/windows/keep-secure/troubleshoot-custom-ti-windows-defender-advanced-threat-protection.md index 53c8414369..5448e0e2f5 100644 --- a/windows/keep-secure/troubleshoot-custom-ti-windows-defender-advanced-threat-protection.md +++ b/windows/keep-secure/troubleshoot-custom-ti-windows-defender-advanced-threat-protection.md @@ -28,7 +28,7 @@ You might need to troubleshoot issues while using the custom threat intelligence This page provides detailed steps to troubleshoot issues you might encounter while using the feature. -## Get a new client secret +## Learn how to get a new client secret If your client secret expires or if you've misplaced the copy provided when you were enabling the custom threat intelligence application, you'll need to get a new secret. 1. Login to the [Azure management portal](https://ms.portal.azure.com).