From ab23a07485d82a6957bc93f4f95788dde589f4ea Mon Sep 17 00:00:00 2001 From: jcaparas Date: Mon, 27 Feb 2017 20:57:52 -0800 Subject: [PATCH] code examples --- ...ows-defender-advanced-threat-protection.md | 7 + ...ows-defender-advanced-threat-protection.md | 111 ++++++++++++++++ ...ows-defender-advanced-threat-protection.md | 120 ++++++++++++++++++ 3 files changed, 238 insertions(+) create mode 100644 windows/keep-secure/powershell-example-code-windows-defender-advanced-threat-protection.md create mode 100644 windows/keep-secure/python-example-code-windows-defender-advanced-threat-protection.md 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 8b4e485dd3..7c5f60b159 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 @@ -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) diff --git a/windows/keep-secure/powershell-example-code-windows-defender-advanced-threat-protection.md b/windows/keep-secure/powershell-example-code-windows-defender-advanced-threat-protection.md new file mode 100644 index 0000000000..3e966f406e --- /dev/null +++ b/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) + +[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.] + +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) +``` diff --git a/windows/keep-secure/python-example-code-windows-defender-advanced-threat-protection.md b/windows/keep-secure/python-example-code-windows-defender-advanced-threat-protection.md new file mode 100644 index 0000000000..af122f4d7e --- /dev/null +++ b/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) + +[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.] + +## 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) +```