deepblue/windows-itpro-docs
1
0
Fork 0
mirror of https://github.com/MicrosoftDocs/windows-itpro-docs.git synced 2025-05-13 05:47:23 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Merge pull request #1687 from MicrosoftDocs/delete-ti

Browse Source 
Delete ti
This commit is contained in:
Kelly Baker 2019-12-10 14:36:47 -08:00 committed by GitHub
commit 444acb0e00
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 34 additions and 1068 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
.openpublishing.redirection.json
View File

@ -1247,6 +1247,11 @@
"redirect_document_id": true
},
{
"source_path": "windows/security/threat-protection/microsoft-defender-atp/custom-ti-api.md",
"redirect_url": "https://docs.microsoft.com/windows/security/threat-protection/microsoft-defender-atp/manage-indicators",
"redirect_document_id": false
},
{
"source_path": "windows/security/threat-protection/windows-defender-atp/custom-detection-rules.md",
"redirect_url": "https://docs.microsoft.com/windows/security/threat-protection/microsoft-defender-atp/custom-detection-rules",
"redirect_document_id": true
@ -1357,6 +1362,11 @@
"redirect_document_id": true
},
{
"source_path": "windows/security/threat-protection/microsoft-defender-atp/experiment-custom-ti.md",
"redirect_url": "https://docs.microsoft.com/windows/security/threat-protection/microsoft-defender-atp/manage-indicators",
"redirect_document_id": false
},
{
"source_path": "windows/threat-protection/windows-defender-atp/fix-unhealhty-sensors-windows-defender-advanced-threat-protection.md",
"redirect_url": "https://docs.microsoft.com/windows/security/threat-protection/windows-defender-atp/fix-unhealhty-sensors-windows-defender-advanced-threat-protection",
"redirect_document_id": true
@ -1692,6 +1702,11 @@
"redirect_document_id": true
},
{
"source_path": "windows/security/threat-protection/microsoft-defender-atp/powershell-example-code.md",
"redirect_url": "https://docs.microsoft.com/windows/security/threat-protection/microsoft-defender-atp/manage-indicators",
"redirect_document_id": false
},
{
"source_path": "windows/keep-secure/preferences-setup-windows-defender-advanced-threat-protection.md",
"redirect_url": "https://docs.microsoft.com/windows/threat-protection/windows-defender-atp/preferences-setup-windows-defender-advanced-threat-protection",
"redirect_document_id": true
@ -1762,6 +1777,11 @@
"redirect_document_id": true
},
{
"source_path": "windows/security/threat-protection/microsoft-defender-atp/python-example-code.md",
"redirect_url": "https://docs.microsoft.com/windows/security/threat-protection/microsoft-defender-atp/manage-indicators",
"redirect_document_id": false
},
{
"source_path": "windows/security/threat-protection/windows-defender-atp/rbac-windows-defender-advanced-threat-protection.md",
"redirect_url": "https://docs.microsoft.com/windows/security/threat-protection/microsoft-defender-atp/rbac",
"redirect_document_id": true
@ -1894,7 +1914,7 @@
{
"source_path": "windows/keep-secure/troubleshoot-windows-defender-antivirus.md",
"redirect_url": "https://docs.microsoft.com/windows/threat-protection/windows-defender-antivirus/troubleshoot-windows-defender-antivirus",
"redirect_document_id": true
"redirect_document_id": true
},
{
"source_path": "windows/keep-secure/troubleshoot-windows-defender-in-windows-10.md",
@ -1927,6 +1947,11 @@
"redirect_document_id": true
},
{
"source_path": "windows/security/threat-protection/microsoft-defender-atp/troubleshoot-custom-ti.md",
"redirect_url": "https://docs.microsoft.com/windows/security/threat-protection/microsoft-defender-atp/manage-indicators",
"redirect_document_id": false
},
{
"source_path": "windows/threat-protection/windows-defender-atp/troubleshoot-onboarding-windows-defender-advanced-threat-protection.md",
"redirect_url": "https://docs.microsoft.com/windows/security/threat-protection/windows-defender-atp/troubleshoot-onboarding-windows-defender-advanced-threat-protection",
"redirect_document_id": true
@ -1977,6 +2002,11 @@
"redirect_document_id": true
},
{
"source_path": "windows/security/threat-protection/microsoft-defender-atp/use-custom-ti.md",
"redirect_url": "https://docs.microsoft.com/windows/security/threat-protection/microsoft-defender-atp/manage-indicators",
"redirect_document_id": false
},
{
"source_path": "windows/security/threat-protection/windows-defender-atp/user-roles-windows-defender-advanced-threat-protection.md",
"redirect_url": "https://docs.microsoft.com/windows/security/threat-protection/microsoft-defender-atp/user-roles",
"redirect_document_id": true

7
windows/security/threat-protection/TOC.md
View File

@ -448,13 +448,6 @@
#### [Common Vulnerabilities and Exposures (CVE) to KB map]()
##### [Get CVE-KB map](microsoft-defender-atp/get-cvekbmap-collection.md)
#### [API for custom alerts (Deprecated)]()
##### [Use the threat intelligence API to create custom alerts (Deprecated)](microsoft-defender-atp/use-custom-ti.md)
##### [Create custom threat intelligence alerts (Deprecated)](microsoft-defender-atp/custom-ti-api.md)
##### [PowerShell code examples (Deprecated)](microsoft-defender-atp/powershell-example-code.md)
##### [Python code examples (Deprecated)](microsoft-defender-atp/python-example-code.md)
##### [Experiment with custom threat intelligence alerts (Deprecated)](microsoft-defender-atp/experiment-custom-ti.md)
##### [Troubleshoot custom threat intelligence issues (Deprecated)](microsoft-defender-atp/troubleshoot-custom-ti.md)
#### [Pull detections to your SIEM tools]()
##### [Learn about different ways to pull detections](microsoft-defender-atp/configure-siem.md)

414
windows/security/threat-protection/microsoft-defender-atp/custom-ti-api.md
View File

@ -1,414 +0,0 @@
---
title: Create custom alerts using the threat intelligence API
description: Create your custom alert definitions and indicators of compromise in Microsoft Defender ATP using the available APIs in Windows Enterprise, Education, and Pro editions.
keywords: alert definitions, indicators of compromise, threat intelligence, custom threat intelligence, rest api, api
search.product: eADQiWindows 10XVcnh
search.appverid: met150
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
manager: dansimp
audience: ITPro
ms.collection: M365-security-compliance
ms.topic: article
---
# Create custom alerts using the threat intelligence (TI) application program interface (API) (Deprecated)
**Applies to:**
- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
>Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-customti-abovefoldlink)
You can define custom alert definitions and indicators of compromise (IOC) using the threat intelligence API. Creating custom threat intelligence alerts allows you to generate specific alerts that are applicable to your organization.
## Before you begin
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.md).
### Use the threat intelligence REST API 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:
- GET
- POST
- PATCH
- PUT (used for managing entities relations only)
- DELETE
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 threat intelligence API endpoint.
- `{version}` is the target service version. Currently, the only supported version is: v1.0.
- `{resource}` is resource segment or path, such as:
- AlertDefinitions (for specific single resource, add: (id))
- IndicatorsOfCompromise (for specific single resource, add: (id))
- `[query_parameters]` represents additional query parameters such as $filter and $select.
**Quotas**</br>
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).
## Request an access token from the token issuing endpoint
Microsoft Defender ATP Threat Intelligence API uses OAuth 2.0. In the context of Microsoft Defender ATP, the alert definitions are a protected resource. To issue tokens for ad-hoc, non-automatic operations you can use the **Settings** page and click the **Generate Token** button. However, if you’d like to create an automated client, you need to use the “Client Credentials Grant” flow. For more information, see the [OAuth 2.0 authorization framework](https://tools.ietf.org/html/rfc6749#section-4.4).
For more information about the authorization flow, see [OAuth 2.0 authorization flow](https://docs.microsoft.com/azure/active-directory/develop/active-directory-protocols-oauth-code#oauth-20-authorization-flow).
Make an HTTP POST request to the token issuing endpoint with the following parameters, replacing `<ClientId>`, `<ClientSecret>`, and `<AuthorizationServerUrl>` with your app's client ID, client secret and authorization server URL.
>[!NOTE]
> The authorization server URL is `https://login.windows.net/<AADTenantID>/oauth2/token`. Replace `<AADTenantID>` with your Azure Active Directory tenant ID.
>[!NOTE]
> The `<ClientId>`, `<ClientSecret>`, and the `<AuthorizationServerUrl>` are all provided to you when enabling the custom threat intelligence application. For more information, see [Enable the custom threat intelligence application](enable-custom-ti.md).
```
POST <AuthorizationServerUrl> HTTP/1.1
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id=<ClientId>
&client_secret=<ClientSecret>
&resource=https://graph.microsoft.com
```
The response will include an access token and expiry information.
```json
{
"token_type": "Bearer",
"expires_in": "3599",
"ext_expires_in": "0",
"expires_on": "1449685363",
"not_before": "1449681463",
"resource": "https://graph.microsoft.com",
"access_token": "<token>"
}
```
## 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:
```
https://TI.SecurityCenter.Windows.com/v1.0/$metadata
```
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 the custom threat intelligence and establish URLs that navigate between entities.
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.
You can then proceed to create an indicator of compromise and associate it to the ID of the alert definition.
### Create a new alert definition
```json
POST https://TI.SecurityCenter.Windows.com/v1.0/AlertDefinitions HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json;
{
"Name": " The name of the alert definition. Does not appear in the portal. Max length: 100 ",
"Severity": "Low",
"InternalDescription": "Internal description for the alert definition. Does not appear in the portal. Max length: 350",
"Title": "A short, one sentence, description of the alert definition. Max length: 120",
"UxDescription": "Max length: 500",
"RecommendedAction": "Custom text to explain what should be done in case of detection. Max length: 2000",
"Category": "Category from the metadata",
"Enabled": true
}
```
The following values correspond to the alert sections surfaced on Microsoft Defender Security Center:
![Image of alert from the portal](images/atp-custom-ti-mapping.png)
Highlighted section | JSON key name
:---:|:---
1 | Title
2 | Severity
3 | Category
4 | UX description
5 | Recommended Action
If successful, you should get a 201 CREATED response containing the representation of the newly created alert definition, for example:
```json
"Name": "Connection to restricted company IP address",
"Severity": "Low",
"InternalDescription": "Unusual connection to restricted IP from production machine",
"Title": "Connection to restricted company IP address",
"UxDescription": "Any connection to this IP address from a production machine should be suspicious. Only special build machines should access this IP address.",
"RecommendedAction": "Isolate machine immediately and contact machine owner for awareness.",
"Category": "Trojan",
"Id": 2,
"CreatedAt": "2017-02-01T10:46:22.08Z",
"CreatedBy": "User1",
"LastModifiedAt": null,
"LastModifiedBy": null,
"Enabled": true
```
### Create a new indicator of compromise
```json
POST https://TI.SecurityCenter.Windows.com/v1.0/IndicatorsOfCompromise HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json;
{
"Type": "SHA1",
"Value": "8311e8b377736fb93b18b15372355f3f26c4cd29",
"DetectionFunction": "Equals",
"Enabled": true,
"AlertDefinition@odata.bind": "AlertDefinitions(1)"
}
```
If successful, you should get a 201 CREATED response containing the representation of the newly created indicators of compromise in the payload.
The API currently supports the following IOC types:
- Sha1
- Sha256
- Md5
- IpAddress
- DomainName
And the following operators:
- Equals
- StartWith
- EndWith
- Contains
## Bulk upload of alert definitions and IOCs
Bulk upload of multiple entities can be done by sending an HTTP POST request to `/{resource}/Actions.BulkUpload`. </br>
>[!WARNING]
>- This operation is atomic. The entire operation can either succeed or fail. If one alert definition or IOC has a malformed property, the entire upload will fail.
>- If your upload exceeds the IOCs or alert definitions quota, the entire operation will fail. Consider limiting your uploads.
The request’s body should contain a single JSON object with a single field. The name of the field in the case that the entity is alert definition is `alertDefinitions` and in the case of IOC is `iocs`. This field’s value should contain a list of the desired entities.
For example:
Sending an HTTP POST to https://TI.SecurityCenter.Windows.com/V1.0/IndicatorsOfCompromise/Actions.BulkUpload
JSON Body:
```json
{
"iocs": [{
"Type": "SHA1",
"Value": "b68e0b50420dbb03cb8e56a927105bf4b06f3793",
"DetectionFunction": "Equals",
"Enabled": true,
"AlertDefinition@odata.bind": "AlertDefinitions(1)"
},
{
"Type": "SHA1",
"Value": "b68e0b50420dbb03cb8e56a927105bf4b06f3793",
"DetectionFunction": "Equals",
"Enabled": true,
"AlertDefinition@odata.bind": "AlertDefinitions(1)"
}
]
}
```
>[!NOTE]
> - Max bulk size is 5000 entities
## Read existing data
### Get a specific resource
```json
GET https://TI.SecurityCenter.Windows.com/v1.0/IndicatorsOfCompromise(1) HTTP/1.1
Authorization: Bearer <access_token>
Accept: application/json;odata.metadata=none
```
If successful, you should get a 200 OK response containing a single indicator of compromise representation (for the specified ID) in the payload, as shown as follows:
```json
HTTP/1.1 200 OK
content - type: application/json;odata.metadata = none
{
"value": [{
"Type": "SHA1",
"Value": "abcdeabcde1212121212abcdeabcde1212121212",
"DetectionFunction": "Equals",
"ExpiresAt": null,
"Id": 1,
"CreatedAt": "2016-12-05T15:51:02Z",
"CreatedBy": "user2@Company1.contoso.com",
"LastModifiedAt": null,
"LastModifiedBy": null,
"Enabled": true
}]
}
```
### Get the entire collection of entities of a given resource
```
GET https://TI.SecurityCenter.Windows.com/v1.0/AlertDefinitions HTTP/1.1
Authorization: Bearer <access_token>
```
If successful, you should get a 200 OK response containing the collection of alert definitions representation in the payload, as shown as follows:
```json
HTTP/1.1 200 OK
content - type: application / json;odata.metadata = none
{
"@odata.context": "https://TI.SecurityCenter.Windows.com/V1.0/$metadata#AlertDefinitions",
"value": [{
"Name": "Demo alert definition",
"Severity": "Medium",
"InternalDescription": "Some description",
"Title": "Demo short ux description",
"UxDescription": "Demo ux description",
"RecommendedAction": "Actions",
"Category": "Malware",
"Id": 1,
"CreatedAt": "2016-12-05T15:50:53Z",
"CreatedBy": "user@Company1.contoso.com",
"LastModifiedAt": null,
"LastModifiedBy": null,
"Enabled": true
},
{
"Name": "Demo alert definition 2",
"Severity": "Low",
"InternalDescription": "Some description",
"Title": "Demo short ux description2",
"UxDescription": "Demo ux description2",
"RecommendedAction": null,
"Category": "Malware",
"Id": 2,
"CreatedAt": "2016-12-06T13:30:00Z",
"CreatedBy": "user2@Company1.contoso.com",
"LastModifiedAt": null,
"LastModifiedBy": null,
"Enabled": true
}
]
}
```
## Update an existing resource
You can use the same pattern for both full and partial updates.
```json
PATCH https://TI.SecurityCenter.Windows.com/v1.0/AlertDefinitions(2) HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json;
Accept: application/json;odata.metadata=none
{
"Category": "Backdoor",
"Enabled": false
}
```
If successful, you should get a 200 OK response containing the updated alert definition representation (per the specified ID) in the payload.
## Update the association (relation) between an indicator of compromise to a different alert definition
```json
PUT https://TI.SecurityCenter.Windows.com/v1.0/IndicatorsOfCompromise(3)/AlertDefinition/$ref HTTP/1.1
Authorization : Bearer <access_token>
Content-Type: application/json;
{
"@odata.id": "https://TI.SecurityCenter.Windows.com/v1.0/AlertDefinitions(6)"
}
```
## Delete a resource
```
DELETE https://TI.SecurityCenter.Windows.com/v1.0/IndicatorsOfCompromise(1) HTTP/1.1
Authorization: Bearer <access_token>
```
If successful, you should get a 204 NO CONTENT response.
>[!NOTE]
> - Deleting an alert definition also deletes its corresponding IOCs.
> - Deleting an IOC or an alert definition will not delete or hide past alerts matching the alert definition. However, deleting an alert definition and creating a new one with the exact same metadata will result in new alerts in the portal. It's not advised to delete an alert definition and create a new one with the same content.
## Delete all
You can use the HTTP DELETE method sent to the relevant source to delete all resources.
```
DELETE https://TI.SecurityCenter.Windows.com/v1.0/IndicatorsOfCompromise HTTP/1.1
Authorization : Bearer <access_token>
```
If successful, you should get a 204 NO CONTENT response.
## Delete all IOCs connected to a given alert definition
This action will delete all the IOCs associated with a given alert definition without deleting the alert definition itself.
For example, deleting all of the IOCs associated with the alert definition with ID `1` deletes all those IOCs without deleting the alert definition itself.
Send an HTTP POST to `https://TI.SecurityCenter.Windows.com/V1.0/AlertDefinitions(1)/Actions.DeleteIOCs`.
Upon a successful request the response will be HTTP 204.
>[!NOTE]
> As with all OData actions, this action is sending an HTTP POST request not DELETE.
## Microsoft Defender ATP optional query parameters
The Microsoft 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
:---|:---|:--
$select | string | Comma-separated list of properties to include in the response.
$expand | string | Comma-separated list of relationships to expand and include in the response.
$orderby | string | Comma-separated list of properties that are used to sort the order of items in the response collection.
$filter | string | Filters the response based on a set of criteria.
$top | int | The number of items to return in a result set.
$skip | int | The number of items to skip in a result set.
$count | boolean | A collection and the number of items in the collection.
These parameters are compatible with the [OData V4 query language](http://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part2-url-conventions/odata-v4.0-errata03-os-part2-url-conventions-complete.html#_Toc453752356).
## Code examples
The following articles provide detailed code examples that demonstrate how to use the custom threat intelligence API in several programming languages:
- [PowerShell code examples](powershell-example-code.md)
- [Python code examples](python-example-code.md)
## Related topics
- [Understand threat intelligence concepts](threat-indicator-concepts.md)
- [Enable the custom threat intelligence API in Microsoft Defender ATP](enable-custom-ti.md)
- [PowerShell code examples for the custom threat intelligence API](powershell-example-code.md)
- [Python code examples for the custom threat intelligence API](python-example-code.md)
- [Experiment with custom threat intelligence alerts](experiment-custom-ti.md)
- [Troubleshoot custom threat intelligence issues](troubleshoot-custom-ti.md)

2
windows/security/threat-protection/microsoft-defender-atp/enable-siem-integration.md
View File

@ -47,7 +47,7 @@ Enable security information and event management (SIEM) integration so you can p
> [!WARNING]
>The client secret is only displayed once. Make sure you keep a copy of it in a safe place.<br>
For more information about getting a new secret see, [Learn how to get a new secret](troubleshoot-custom-ti.md#learn-how-to-get-a-new-client-secret).
![Image of SIEM integration from Settings menu](images/siem_details.png)

161
windows/security/threat-protection/microsoft-defender-atp/experiment-custom-ti.md
View File

@ -1,161 +0,0 @@
---
title: Experiment with custom threat intelligence alerts
description: Use this end-to-end guide to start using the Microsoft Defender ATP threat intelligence API.
keywords: alert definitions, indicators of compromise, threat intelligence, custom threat intelligence, rest api, api
search.product: eADQiWindows 10XVcnh
search.appverid: met150
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
manager: dansimp
audience: ITPro
ms.collection: M365-security-compliance
ms.topic: article
ms.date: 11/09/2017
---
# Experiment with custom threat intelligence (TI) alerts (Deprecated)
**Applies to:**
- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
>Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-experimentcustomti-abovefoldlink)
With the Microsoft Defender ATP threat intelligence API, you can create custom threat intelligence alerts that can help you keep track of possible attack activities in your organization.
For more information about threat intelligence concepts, see [Understand threat intelligence concepts](threat-indicator-concepts.md).
This article demonstrates an end-to-end usage of the threat intelligence API to get you started in using the threat intelligence API.
You'll be guided through sample steps so you can experience how the threat intelligence API feature works. Sample steps include creating alerts definitions and indicators of compromise (IOCs), and examples of how triggered custom TI alerts look like.
## Step 1: Enable the threat intelligence API and obtain authentication details
To use the threat intelligence API feature, you'll need to enable the feature. For more information, see [Enable the custom threat intelligence application](enable-custom-ti.md).
This step is required to generate security credentials that you need to use while working with the API.
## Step 2: Create a sample alert definition and IOCs
This step will guide you in creating an alert definition and an IOC for a malicious IP.
1. Open a Windows PowerShell ISE.
2. Copy and paste the following PowerShell script. This script will upload a sample alert definition and IOC to Microsoft Defender ATP which you can use to generate an alert.
NOTE:
Make sure you replace the authUrl, clientId, and clientSecret values with your details which you saved in when you enabled the threat intelligence application.
~~~~
$authUrl = 'Your Authorization URL'
$clientId = 'Your Client ID'
$clientSecret = 'Your Client Secret'
Try
{
$tokenPayload = @{
"resource" = 'https://graph.windows.net'
"client_id" = $clientId
"client_secret" = $clientSecret
"grant_type"='client_credentials'}
"Fetching an access token"
$response = Invoke-RestMethod $authUrl -Method Post -Body $tokenPayload
$token = $response.access_token
"Token fetched successfully"
$headers = @{
"Content-Type" = "application/json"
"Accept" = "application/json"
"Authorization" = "Bearer {0}" -f $token }
$apiBaseUrl = "https://ti.securitycenter.windows.com/V1.0/"
$alertDefinitionPayload = @{
"Name" = "Test Alert"
"Severity" = "Medium"
"InternalDescription" = "A test alert used to demonstrate the Microsoft Defender ATP TI API feature"
"Title" = "Test alert."
"UxDescription" = "This is a test alert based on a sample custom alert definition. This alert was triggered manually using a provided test command. It indicates that the Threat Intelligence API has been properly enabled."
"RecommendedAction" = "No recommended action for this test alert."
"Category" = "SuspiciousNetworkTraffic"
"Enabled" = "true"}
"Creating an Alert Definition"
$alertDefinition =
Invoke-RestMethod ("{0}AlertDefinitions" -f $apiBaseUrl) `
-Method Post -Headers $headers -Body ($alertDefinitionPayload | ConvertTo-Json)
"Alert Definition created successfully"
$alertDefinitionId = $alertDefinition.Id
$iocPayload = @{
"Type"="IpAddress"
"Value"="52.184.197.12"
"DetectionFunction"="Equals"
"Enabled"="true"
"AlertDefinition@odata.bind"="AlertDefinitions({0})" -f $alertDefinitionId }
"Creating an Indicator of Compromise"
$ioc =
Invoke-RestMethod ("{0}IndicatorsOfCompromise" -f $apiBaseUrl) `
-Method Post -Headers $headers -Body ($iocPayload | ConvertTo-Json)
"Indicator of Compromise created successfully"
"All done!"
}
Catch
{
"Something went wrong! Got the following exception message: {0}" -f $_.Exception.Message
}
~~~~
3. Run the script and verify that the operation succeeded in the results the window. Wait up to 20 minutes until the new or updated alert definition propagates to the detection engines.
![Image of the script running](images/atp-running-script.png)
NOTE:<br>
If you get the exception “The remote server returned an error: (407) Proxy Authentication Required", you need to add the proxy configuration by adding the following code to the PowerShell script:
~~~~
$webclient=New-Object System.Net.WebClient
$creds=Get-Credential
$webclient.Proxy.Credentials=$creds
~~~~
## Step 3: Simulate a custom TI alert
This step will guide you in simulating an event in connection to a malicious IP that will trigger the Microsoft Defender ATP custom TI alert.
1. Open a Windows PowerShell ISE in the machine you onboarded to Microsoft Defender ATP.
2. Type `Invoke-WebRequest 52.184.197.12` in the editor and click **Run**. This call will generate a network communication event to a Microsoft's dedicated demo server that will raise an alert based on the custom alert definition.
![Image of editor with command to Invoke-WebRequest](images/atp-simulate-custom-ti.png)
## Step 4: Explore the custom alert in the portal
This step will guide you in exploring the custom alert in the portal.
1. Open [Microsoft Defender Security Center](http://securitycenter.windows.com/) on a browser.
2. Log in with your Microsoft Defender ATP credentials.
3. The dashboard should display the custom TI alert for the victim machine resulting from the simulated attack.
![Image of sample custom ti alert in the portal](images/atp-sample-custom-ti-alert.png)
> [!NOTE]
> There is a latency time of approximately 20 minutes between the time a custom TI is introduced and when it becomes effective.
## Related topics
- [Understand threat intelligence concepts](threat-indicator-concepts.md)
- [Enable the custom threat intelligence API in Microsoft Defender ATP](enable-custom-ti.md)
- [Create custom alerts using the threat intelligence API](custom-ti-api.md)
- [PowerShell code examples for the custom threat intelligence API](powershell-example-code.md)
- [Python code examples for the custom threat intelligence API](python-example-code.md)
- [Troubleshoot custom threat intelligence issues](troubleshoot-custom-ti.md)

184
windows/security/threat-protection/microsoft-defender-atp/powershell-example-code.md
View File

@ -1,184 +0,0 @@
---
title: PowerShell code examples for the custom threat intelligence API
description: Use PowerShell code to create custom threat intelligence using REST API.
keywords: powershell, code examples, threat intelligence, custom threat intelligence, rest api, api
search.product: eADQiWindows 10XVcnh
search.appverid: met150
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
manager: dansimp
audience: ITPro
ms.collection: M365-security-compliance
ms.topic: article
---
# PowerShell code examples for the custom threat intelligence API (Deprecated)
**Applies to:**
- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
This article provides PowerShell code examples for using the custom threat intelligence API.
These code examples demonstrate the following tasks:
- [Obtain an Azure AD access token](#token)
- [Create headers](#headers)
- [Create calls to the custom threat intelligence API](#calls)
- [Create a new alert definition](#alert-definition)
- [Create a new indicator of compromise](#ioc)
<span id="token" />
## Step 1: Obtain an Azure AD access token
The following example demonstrates how to obtain an Azure AD access token that you can use to call methods in the custom threat intelligence API. After you obtain a token, you have 60 minutes to use this token in calls to the custom threat intelligence API before the token expires. After the token expires, you can generate a new token.
Replace the *authUrl*, *clientid*, and *clientSecret* values with the ones you got from **Settings** page in the portal:
```powershell
$authUrl = 'Your Authorization URL'
$clientId = 'Your Client ID'
$clientSecret = 'Your Client Secret'
$tokenPayload = @{
"resource"='https://graph.windows.net'
"client_id" = $clientId
"client_secret" = $clientSecret
"grant_type"='client_credentials'}
$response = Invoke-RestMethod $authUrl -Method Post -Body $tokenPayload
$token = $response.access_token
```
<span id="headers" />
## Step 2: Create headers used for the requests with the API
Use the following code to create the headers used for the requests with the API:
```powershell
$headers = @{
"Content-Type"="application/json"
"Accept"="application/json"
"Authorization"="Bearer {0}" -f $token }
$apiBaseUrl = "https://ti.securitycenter.windows.com/V1.0/"
```
<span id="calls" />
## Step 3: Create calls to the custom threat intelligence API
After creating the headers, you can now create calls to the API. The following example demonstrates how you can view all the alert definition entities:
```powershell
$alertDefinitions =
(Invoke-RestMethod ("{0}AlertDefinitions" -f $apiBaseUrl) -Method Get -Headers $headers).value
```
The response is empty on initial use of the API.
<span id="alert-definition" />
## Step 4: Create a new alert definition
The following example demonstrates how you to create a new alert definition.
```powershell
$alertDefinitionPayload = @{
"Name"= "The alert's name"
"Severity"= "Low"
"InternalDescription"= "An internal description of the Alert"
"Title"= "The Title"
"UxDescription"= "Description of the alerts"
"RecommendedAction"= "The alert's recommended action"
"Category"= "Trojan"
"Enabled"= "true"}
$alertDefinition =
Invoke-RestMethod ("{0}AlertDefinitions" -f $apiBaseUrl) `
-Method Post -Headers $headers -Body ($alertDefinitionPayload | ConvertTo-Json)
```
<span id="ioc" />
## Step 5: Create a new indicator of compromise
You can now use the alert ID obtained from creating a new alert definition to create a new indicator of compromise.
```powershell
$iocPayload = @{
"Type"="Sha1"
"Value"="dead1111eeaabbccddeeaabbccddee11ffffffff"
"DetectionFunction"="Equals"
"Enabled"="true"
"AlertDefinition@odata.bind"="AlertDefinitions({0})" -f $alertDefinitionId }
$ioc =
Invoke-RestMethod ("{0}IndicatorsOfCompromise" -f $apiBaseUrl) `
-Method Post -Headers $headers -Body ($iocPayload | ConvertTo-Json)
```
## Complete code
You can use the complete code to create calls to the API.
```powershell
$authUrl = 'Your Authorization URL'
$clientId = 'Your Client ID'
$clientSecret = 'Your Client Secret'
$tokenPayload = @{
"resource"='https://graph.windows.net'
"client_id" = $clientId
"client_secret" = $clientSecret
"grant_type"='client_credentials'}
$response = Invoke-RestMethod $authUrl -Method Post -Body $tokenPayload
$token = $response.access_token
$headers = @{
"Content-Type"="application/json"
"Accept"="application/json"
"Authorization"="Bearer {0}" -f $token }
$apiBaseUrl = "https://ti.securitycenter.windows.com/V1.0/"
$alertDefinitions =
(Invoke-RestMethod ("{0}AlertDefinitions" -f $apiBaseUrl) -Method Get -Headers $headers).value
$alertDefinitionPayload = @{
"Name"= "The alert's name"
"Severity"= "Low"
"InternalDescription"= "An internal description of the Alert"
"Title"= "The Title"
"UxDescription"= "Description of the alerts"
"RecommendedAction"= "The alert's recommended action"
"Category"= "Trojan"
"Enabled"= "true"}
$alertDefinition =
Invoke-RestMethod ("{0}AlertDefinitions" -f $apiBaseUrl) `
-Method Post -Headers $headers -Body ($alertDefinitionPayload | ConvertTo-Json)
$alertDefinitionId = $alertDefinition.Id
$iocPayload = @{
"Type"="Sha1"
"Value"="dead1111eeaabbccddeeaabbccddee11ffffffff"
"DetectionFunction"="Equals"
"Enabled"="true"
"AlertDefinition@odata.bind"="AlertDefinitions({0})" -f $alertDefinitionId }
$ioc =
Invoke-RestMethod ("{0}IndicatorsOfCompromise" -f $apiBaseUrl) `
-Method Post -Headers $headers -Body ($iocPayload | ConvertTo-Json)
```
>Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-psexample-belowfoldlink)
## Related topics
- [Understand threat intelligence concepts](threat-indicator-concepts.md)
- [Enable the custom threat intelligence API in Microsoft Defender ATP](enable-custom-ti.md)
- [Create custom alerts using the threat intelligence API](custom-ti-api.md)
- [Python code examples for the custom threat intelligence API](python-example-code.md)
- [Experiment with custom threat intelligence alerts](experiment-custom-ti.md)
- [Troubleshoot custom threat intelligence issues](troubleshoot-custom-ti.md)

188
windows/security/threat-protection/microsoft-defender-atp/python-example-code.md
View File

@ -1,188 +0,0 @@
---
title: Python code examples for the custom threat intelligence API
description: Use Python code to create custom threat intelligence using REST API.
keywords: python, code examples, threat intelligence, custom threat intelligence, rest api, api
search.product: eADQiWindows 10XVcnh
search.appverid: met150
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
manager: dansimp
audience: ITPro
ms.collection: M365-security-compliance
ms.topic: article
---
# Python code examples for the custom threat intelligence API (Deprecated)
**Applies to:**
- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
## Before you begin
You must [install](http://docs.python-requests.org/en/master/user/install/#install) the "[requests](http://docs.python-requests.org/en/master/)" python library.
These code examples demonstrate the following tasks:
- [Obtain an Azure AD access token](#token)
- [Create request session object](#session-object)
- [Create calls to the custom threat intelligence API](#calls)
- [Create a new alert definition](#alert-definition)
- [Create a new indicator of compromise](#ioc)
<span id="token" />
## Step 1: Obtain an Azure AD access token
The following example demonstrates how to obtain an Azure AD access token that you can use to call methods in the custom threat intelligence API. After you obtain a token, you have 60 minutes to use this token in calls to the custom threat intelligence API before the token expires. After the token expires, you can generate a new token.
Replace the *auth_url*, *client_id*, and *client_secret* values with the ones you got from **Settings** page in the portal:
```python
import json
import requests
from pprint import pprint
auth_url="Your Authorization URL"
client_id="Your Client ID"
client_secret="Your Client Secret"
payload = {"resource": "https://graph.windows.net",
"client_id": client_id,
"client_secret": client_secret,
"grant_type": "client_credentials"}
response = requests.post(auth_url, payload)
token = json.loads(response.text)["access_token"]
```
<span id="session-object" />
## Step 2: Create request session object
Add HTTP headers to the session object, including the Authorization header with the token that was obtained.
```python
with requests.Session() as session:
session.headers = {
'Authorization': 'Bearer {}'.format(token),
'Content-Type': 'application/json',
'Accept': 'application/json'}
```
<span id="calls" />
## Step 3: Create calls to the custom threat intelligence API
After adding HTTP headers to the session object, you can now create calls to the API. The following example demonstrates how you can view all the alert definition entities:
```python
response = session.get("https://ti.securitycenter.windows.com/V1.0/AlertDefinitions")
pprint(json.loads(response.text))
```
The response is empty on initial use of the API.
<span id="alert-definition" />
## Step 4: Create a new alert definition
The following example demonstrates how you to create a new alert definition.
```python
alert_definition = {"Name": "The alert's name",
"Severity": "Low",
"InternalDescription": "An internal description of the alert",
"Title": "The Title",
"UxDescription": "Description of the alerts",
"RecommendedAction": "The alert's recommended action",
"Category": "Trojan",
"Enabled": True}
response = session.post(
"https://ti.securitycenter.windows.com/V1.0/AlertDefinitions",
json=alert_definition)
```
<span id="ioc" />
## Step 5: Create a new indicator of compromise
You can now use the alert ID obtained from creating a new alert definition to create a new indicator of compromise.
```python
alert_definition_id = json.loads(response.text)["Id"]
ioc = {'Type': "Sha1",
'Value': "dead1111eeaabbccddeeaabbccddee11ffffffff",
'DetectionFunction': "Equals",
'Enabled': True,
"AlertDefinition@odata.bind": "AlertDefinitions({0})".format(alert_definition_id)}
response = session.post(
"https://ti.securitycenter.windows.com/V1.0/IndicatorsOfCompromise",
json=ioc)
```
## Complete code
You can use the complete code to create calls to the API.
```python
import json
import requests
from pprint import pprint
auth_url="Your Authorization URL"
client_id="Your Client ID"
client_secret="Your Client Secret"
payload = {"resource": "https://graph.windows.net",
"client_id": client_id,
"client_secret": client_secret,
"grant_type": "client_credentials"}
response = requests.post(auth_url, payload)
token = json.loads(response.text)["access_token"]
with requests.Session() as session:
session.headers = {
'Authorization': 'Bearer {}'.format(token),
'Content-Type': 'application/json',
'Accept': 'application/json'}
response = session.get("https://ti.securitycenter.windows.com/V1.0/AlertDefinitions")
pprint(json.loads(response.text))
alert_definition = {"Name": "The alert's name",
"Severity": "Low",
"InternalDescription": "An internal description of the alert",
"Title": "The Title",
"UxDescription": "Description of the alerts",
"RecommendedAction": "The alert's recommended action",
"Category": "Trojan",
"Enabled": True}
response = session.post(
"https://ti.securitycenter.windows.com/V1.0/AlertDefinitions",
json=alert_definition)
alert_definition_id = json.loads(response.text)["Id"]
ioc = {'Type': "Sha1",
'Value': "dead1111eeaabbccddeeaabbccddee11ffffffff",
'DetectionFunction': "Equals",
'Enabled': True,
"AlertDefinition@odata.bind": "AlertDefinitions({0})".format(alert_definition_id)}
response = session.post(
"https://ti.securitycenter.windows.com/V1.0/IndicatorsOfCompromise",
json=ioc)
pprint(json.loads(response.text))
```
>Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-pyexample-belowfoldlink)
## Related topics
- [Understand threat intelligence concepts](threat-indicator-concepts.md)
- [Enable the custom threat intelligence API in Microsoft Defender ATP](enable-custom-ti.md)
- [Create custom alerts using the threat intelligence API](custom-ti-api.md)
- [PowerShell code examples for the custom threat intelligence API](powershell-example-code.md)
- [Experiment with custom threat intelligence alerts](experiment-custom-ti.md)
- [Troubleshoot custom threat intelligence issues](troubleshoot-custom-ti.md)

9
windows/security/threat-protection/microsoft-defender-atp/threat-indicator-concepts.md
View File

@ -39,7 +39,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 Microsoft 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.md#threat-intelligence-api-metadata).
In the context of Microsoft 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.
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 Microsoft Defender ATP console.
@ -51,9 +51,4 @@ Here is an example of an IOC:
IOCs have a many-to-one relationship with alert definitions such that an alert definition can have many IOCs that correspond to it.
## Related topics
- [Enable the custom threat intelligence API in Microsoft Defender ATP](enable-custom-ti.md)
- [Create custom alerts using the threat intelligence API](custom-ti-api.md)
- [PowerShell code examples for the custom threat intelligence API](powershell-example-code.md)
- [Python code examples for the custom threat intelligence API](python-example-code.md)
- [Experiment with custom threat intelligence alerts](experiment-custom-ti.md)
- [Troubleshoot custom threat intelligence issues](troubleshoot-custom-ti.md)
- [Manage indicators](manage-indicators.md)

60
windows/security/threat-protection/microsoft-defender-atp/troubleshoot-custom-ti.md
View File

@ -1,60 +0,0 @@
---
title: Troubleshoot custom threat intelligence issues in Microsoft Defender ATP
description: Troubleshoot issues that might arise when using the custom threat intelligence feature in Microsoft Defender ATP.
keywords: troubleshoot, custom threat intelligence, custom ti, rest api, api, alert definitions, indicators of compromise
search.product: eADQiWindows 10XVcnh
search.appverid: met150
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
manager: dansimp
audience: ITPro
ms.collection: M365-security-compliance
ms.topic: troubleshooting
---
# Troubleshoot custom threat intelligence issues (Deprecated)
**Applies to:**
- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
You might need to troubleshoot issues while using the custom threat intelligence feature.
This page provides detailed steps to troubleshoot issues you might encounter while using the feature.
## 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://portal.azure.com).
2. Select **Active Directory**.
3. Select your tenant.
4. Click **App registrations** > **All apps**. Then select the relevant application name:
- **WindowsDefenderATPThreatIntelAPI** (formerly known as **WindowsDefenderATPCustomerTiConnector**)
- **WindowsDefenderATPSiemConnector**
5. Under **Settings**, select **Keys**, then provide a key description and specify the key validity duration.
6. Click **Save**. The key value is displayed.
7. Copy the value and save it in a safe place.
>Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-troubleshootcustomti-belowfoldlink)
## Related topics
- [Understand threat intelligence concepts](threat-indicator-concepts.md)
- [Enable the custom threat intelligence API in Microsoft Defender ATP](enable-custom-ti.md)
- [Create custom alerts using the threat intelligence API](custom-ti-api.md)
- [PowerShell code examples for the custom threat intelligence API](powershell-example-code.md)
- [Python code examples for the custom threat intelligence API](python-example-code.md)
- [Experiment with custom threat intelligence alerts](experiment-custom-ti.md)

45
windows/security/threat-protection/microsoft-defender-atp/use-custom-ti.md
View File

@ -1,45 +0,0 @@
---
title: Use the custom threat intelligence API to create custom alerts
description: Use the threat intelligence API in Microsoft Defender Advanced Threat Protection to create custom alerts
keywords: threat intelligence, alert definitions, indicators of compromise
search.product: eADQiWindows 10XVcnh
search.appverid: met150
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
manager: dansimp
audience: ITPro
ms.collection: M365-security-compliance
ms.topic: article
ms.date: 04/24/2018
---
# Use the threat intelligence API to create custom alerts (Deprecated)
**Applies to:**
- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
> [!TIP]
> This topic has been deprecated. See [Indicators](ti-indicator.md) for the updated content.
>
> Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-customti-abovefoldlink)
Understand threat intelligence concepts, then enable the custom threat intelligence application so that you can proceed to create custom threat intelligence alerts that are specific to your organization.
You can use the code examples to guide you in creating calls to the custom threat intelligence API.
## In this section
Topic | Description
:---|:---
[Understand threat intelligence concepts](threat-indicator-concepts.md) | Understand the concepts around threat intelligence so that you can effectively create custom intelligence for your organization.
[Enable the custom threat intelligence application](enable-custom-ti.md) | Set up the custom threat intelligence application through Microsoft Defender Security Center so that you can create custom threat intelligence (TI) using REST API.
[Create custom threat intelligence alerts](custom-ti-api.md) | Create custom threat intelligence alerts so that you can generate specific alerts that are applicable to your organization.
[PowerShell code examples](powershell-example-code.md) | Use the PowerShell code examples to guide you in using the custom threat intelligence API.
[Python code examples](python-example-code.md) | Use the Python code examples to guide you in using the custom threat intelligence API.
[Experiment with custom threat intelligence alerts](experiment-custom-ti.md) | This article demonstrates an end-to-end usage of the threat intelligence API to get you started in using the threat intelligence API.
[Troubleshoot custom threat intelligence issues](troubleshoot-custom-ti.md) | Learn how to address possible issues you might encounter while using the threat intelligence API.