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

add in custom ti content

Browse Source
This commit is contained in:
Joey Caparas 2017-02-07 16:06:47 -08:00
parent 05d0f91436
commit ebc6fa19f1
3 changed files with 386 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

339
windows/keep-secure/custom-ti-api-windows-defender-advanced-threat-protection.md Normal file
View File

@ -0,0 +1,339 @@
---
title: Create custom threat indicators 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 indicators, custom ti, rest api, api
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
author: mjcaparas
localizationpriority: high
---
# Create custom threat indicators (TI) using REST API
**Applies to:**
- Windows 10 Enterprise
- Windows 10 Education
- Windows 10 Pro
- Windows 10 Pro Education
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
You can define custom Alert definitions and Indicators of Compromise (IOC) using the available APIs. Creating custom TI’s allows you to create specific alerts that are applicable to your organization.
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:
- GET
- POST
- PATCH
- PUT (used for managing entities relations only)
- DELETE
All Custom TI API requests use the following basic URL pattern:
```
https://wdatp-tiapi-prd.trafficmanager.net/{version}/{resource}?[query_parameters]
```
For this URL:
- `https://wdatp-tiapi-prd.trafficmanager.net` is the Custom TI 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))
- 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 and IOCs 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
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://wdatp-tiapi-prd.trafficmanager.net/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.
You can use the metadata to understand the relationships between entities in Custom TI and establish URLs that navigate between entities.
The following sections show a few basic programming pattern calls to the Custom TI API.
## Create new resource
Typically, you would start creating custom threat indicators by first creating an Alert definition.
An ID is created for that Alert definition. You would then create an Indicator Of Compromise and associate it to the ID of the Alert definition.
### Create a new Alert definition
```json
POST https://wdatp-tiapi-prd.trafficmanager.net/v1.0/AlertDefinition HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json;
{
"Name": " The name of the IOA. Does not appear in the potal. Max length: 100 ",
"Severity": "Low",
"InternalDescription": " Internal description for the IOA. Does not appear in the portal. Max length: 350",
"ShortUxDescription": " A short, one sentence, description of the IoA. Max length: 120",
"UxDescription": " Max length: 500",
"RecommendedAction": " Custom text to explain what should be done in case of detection. Max length: 2000 ",
"Category": "Trojan",
"Enabled": true
}
```
The following values correspond to the alert sections surfaced on the Windows Defender ATP portal:
![Image of alert from the portal](images/atp-custom-ti-mapping.png)
Highlighted section | JSON Value
:---:|:---
1 | ShortUxDescription
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",
"ShortUxDescription": "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://wdatp-tiapi-prd.trafficmanager.net/v1.0/IndicatorsOfCompromise HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json;
Content-Length: 194
{
"Type": "Sha1",
"Value": "8311e8b377736fb93b18b15372355f3f26c4cd29",
"DetectionFunction": "Equals",
"Enabled": true,
"AlertDefinition@odata.bind": "AlertDefinition(1)"
}
```
If successful, you should get a 201 CREATED response containing the representation of the newly created Indicators Of Compromise in the payload.
## 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 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 IOC 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 `alertdefinition` 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://wdatp-tiapi-prd.trafficmanager.net/V1.0/IndicatorsOfCompromise/Actions.BulkUpload
JSON Body:
```json
{
"IOCs": [{
"Type": "Sha1",
"Value": "b68e0b50420dbb03cb8e56a927105bf4b06f3793",
"DetectionFunction": "Equals",
"Enabled": true,
"IndicationOfAttack@odata.bind": "AlertDefinition(1)"
},
{
"Type": "Sha1",
"Value": "b68e0b50420dbb03cb8e56a927105bf4b06f3793",
"DetectionFunction": "Equals",
"Enabled": true,
"IndicationOfAttack@odata.bind": "AlertDefinition(1)"
}
]
}
```
>[!NOTE]
> - Max bulk size is 5000 entities
## Read existing data
### Get a specific resource
```json
GET https://wdatp-tiapi-prd.trafficmanager.net/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 Indications Of Compromise representation (per 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://wdatp-tiapi-prd.trafficmanager.net/v1.0/AlertDefinitions HTTP/1.1
Authorization : Bearer <access_token>
```
If successful, you should get a 200 OK response containing the collection of Indications Of Attack representation in the payload, as shown as follows:
```json
HTTP/1.1 200 OK
content - type: application / json;odata.metadata = none
{
"@odata.context": "https://wdatp-tiapi-prd.trafficmanager.net/V1.0/$metadata#AlertDefinitions",
"value": [{
"Name": "Demo Alert definition",
"Severity": "Medium",
"InternalDescription": "Some description",
"ShortUxDescription": "Demo short Ux Desc",
"UxDescription": "Demo ux desc",
"RecommendedAction": "Actions",
"Category": "Malware",
"Id": 1,
"CreatedAt": "2016-12-05T15:50:53Z",
"CreatedBy": "user@Company1.constoso.com",
"LastModifiedAt": null,
"LastModifiedBy": null,
"Enabled": true
},
{
"Name": "demo Alert definition 2",
"Severity": "Low",
"InternalDescription": "Some description",
"ShortUxDescription": "Demo short UX Desc2",
"UxDescription": "Demo UX Desc2",
"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://wdatp-tiapi-prd.trafficmanager.net/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 Indications Of Attack representation (per the specified Id) in the payload.
## Update the association (relation) between an Indication Of Compromise to a different Indication Of Attack
```json
PUT https://wdatp-tiapi-prd.trafficmanager.net/v1.0/IndicatorsOfCompromise(3)/IndicationOfAttack/$ref HTTP/1.1
Authorization : Bearer <access_token>
Content-Type: application/json;
{
"@odata.id": "https://wdatp-tiapi-prd.trafficmanager.net/v1.0/AlertDefinitions(6)"
}
```
## Delete a resource
```
DELETE https://wdatp-tiapi-prd.trafficmanager.net/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 IOC.
> - 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://wdatp-tiapi-prd.trafficmanager.net/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://wdatp-tiapi-prd.trafficmanager.net/V1.0/IndicatorsOfAttack(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.
## 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.
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).

BIN
windows/keep-secure/images/atp-custom-ti-mapping.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 133 KiB

47
windows/keep-secure/threat-indicator-concepts-windows-defender-advanced-threat-protection.md Normal file
View File

@ -0,0 +1,47 @@
---
title: Understand threat indicators in Windows Defender ATP
description: Understand the concepts around threat indicators in Windows Defender Advanced Threat Protection so that you can effectively create custom indicators for your organization.
keywords: threat indicators, alert definitions, indicators of compromise, concepts
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
author: mjcaparas
localizationpriority: high
---
# Understand threat indicators
**Applies to:**
- Windows 10 Enterprise
- Windows 10 Education
- Windows 10 Pro
- Windows 10 Pro Education
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
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 indicators 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 indicators will only appear in your organization and will flag events that you set it to track.
Before creating custom threat indicators, 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 events, tools, 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 intervening the chain of events before an attacker's objective is reached.
## Indicators of Compromise (IOC)
IOCs are individual 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 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).
IOCs define the actual concrete detection logic based on type, value and detection function and the corresponding Alert definition ID to be identified with. Each IOC has a type, value, and an action for example:
- Type: Sha1
- Value: 92cfceb39d57d914ed8b14d0e37643de0797ae56
- Action: Equals
IOCs have a many-to-one relationship with Alert definitions such that an Alert definition can have many IOCs that correspond to it.
## Related topic
- [Create custom threat indicators using REST API](custom-ti-api-windows-defender-advanced-threat-protection.md)