code examples

windows/keep-secure/custom-ti-api-windows-defender-advanced-threat-protection.md

@@ -344,6 +344,13 @@ $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
+- Python code examples
+
+
 ## Related topics
 - [Understand threat intelligence](threat-indicator-concepts-windows-defender-advanced-threat-protection.md)
 - [Enable the custom threat intelligence application](enable-custom-ti-windows-defender-advanced-threat-protection.md)

windows/keep-secure/powershell-example-code-windows-defender-advanced-threat-protection.md

@@ -0,0 +1,111 @@
+---
+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
+ms.prod: w10
+ms.mktglfcycl: deploy
+ms.sitesec: library
+ms.pagetype: security
+author: mjcaparas
+localizationpriority: high
+---
+
+# PowerShell code examples for the custom threat intelligence API
+
+**Applies to:**
+
+- Windows 10 Enterprise
+- Windows 10 Education
+- Windows 10 Pro
+- Windows 10 Pro Education
+- Windows Defender Advanced Threat Protection (Windows Defender ATP)
+
+<span style="color:#ED1C24;">[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.]</span>
+
+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](#obtain-an-azure-ad-access-token)
+- [Create headers](#create-headers)
+- - [Create calls to the custom threat intelligence API](create-calls-to-the-custom-threat intelligence-api)
+
+## 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 *tenant\_id*, *client_id*, and *client_secret* values with the ones you got from **Preferences settings** page in the portal:
+
+```
+
+$tenantId = '{Your Tenant ID}
+$clientId = '{Your Client ID}'
+$clientSecret = '{Your Client Secret}'
+
+$authUrl = "https://login.windows.net/{0}/oauth2/token" -f $tenantId
+
+$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
+
+```
+
+## Create headers
+The following example demonstrates how to create headers used for the requests with the API.
+
+```
+$headers = @{}
+$headers.Add("Content-Type", "application/json")
+$headers.Add("Accept", "application/json")
+$headers.Add("Authorization", "Bearer {0}" -f $token)
+
+```
+
+## Create calls to the custom threat intelligence API
+The following example demonstrates how to view all alert definition entities by creating a call to the API.
+
+```
+$apiBaseUrl = "https://ti.securitycenter.windows.com/V1.0/"
+$alertDefinitions =
+    (Invoke-RestMethod ("{0}AlertDefinitions" -f $apiBaseUrl) -Method Get -Headers $headers).value
+```
+
+If this is the first time to use the API, the response is empty.
+
+## Create a new alert definition
+The following example shows how to create a new alert definition.
+
+```
+$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)
+```
+
+## Create a new indicator of compromise
+The following example shows how to use the alert ID obtained from creating a new alert definition to create a new indicator of compromise.
+
+```
+$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)
+```

windows/keep-secure/python-example-code-windows-defender-advanced-threat-protection.md

@@ -0,0 +1,120 @@
+---
+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
+ms.prod: w10
+ms.mktglfcycl: deploy
+ms.sitesec: library
+ms.pagetype: security
+author: mjcaparas
+localizationpriority: high
+---
+
+# Python code examples for the custom threat intelligence API
+
+**Applies to:**
+
+- Windows 10 Enterprise
+- Windows 10 Education
+- Windows 10 Pro
+- Windows 10 Pro Education
+- Windows Defender Advanced Threat Protection (Windows Defender ATP)
+
+<span style="color:#ED1C24;">[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.]</span>
+
+## 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](#obtain-an-azure-ad-access-token)
+- [Create request session object](#create-a-request's-session-object)
+- [Create calls to the custom threat intelligence API](create-calls-to-the-custom-threat intelligence-api)
+- [Create a new indicator of compromise](create-a-new-indicator-of-compromise)
+
+## 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 *tenant\_id*, *client_id*, and *client_secret* values with the ones you got from **Preferences settings** page in the portal:
+
+```json
+
+import json
+import requests
+from pprint import pprint
+
+tenant_id="{your tenant ID}"
+client_id="{your client ID"
+client_secret="{your client secret}"
+
+full_auth_url = r"https://login.windows.net/{0}/oauth2/token".format(tenant_id)
+
+payload = {"resource": r"https://graph.windows.net",
+           "client_id": client_id,
+           "client_secret": client_secret,
+           "grant_type": "client_credentials"}
+
+
+response = requests.post(full_auth_url, payload)
+token = json.loads(response.text)["access_token"]
+```
+
+## Create request session object
+Add HTTP headers to the session object, including the Authorization header with the token that was obtained.
+
+```json
+with requests.Session() as session:
+    session.headers = {
+        'Authorization': 'Bearer {}'.format(token),
+        'Content-Type': 'application/json',
+        'Accept': 'application/json'}
+```
+
+## Create calls to the custom threat intelligence API
+The following example shows how to view all of the alert definition entities by creating a call to the API.
+
+>[!NOTE]
+> All code is still within the ```with``` statement with the same indention level.
+
+```json
+
+response = session.get("https://ti.securitycenter.windows.com/V1.0/AlertDefinitions")
+pprint(json.loads(response.text))
+```
+
+If this is the first time to use the API, the response is empty.
+
+## Create a new alert definition
+The following example shows how to create a new alert definition.
+
+```json
+
+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)
+```
+
+## Create a new indicator of compromise
+The following example shows how to use the alert ID obtained from creating a new alert definition to create a new indicator of compromise.
+
+```json
+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)
+```