diff --git a/windows/keep-secure/experiment-custom-ti-windows-defender-advanced-threat-protection.md b/windows/keep-secure/experiment-custom-ti-windows-defender-advanced-threat-protection.md index b7f9bce85f..df1301d438 100644 --- a/windows/keep-secure/experiment-custom-ti-windows-defender-advanced-threat-protection.md +++ b/windows/keep-secure/experiment-custom-ti-windows-defender-advanced-threat-protection.md @@ -45,7 +45,71 @@ This step will guide you in creating an alert definition and an IOC for a malici 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. - [!code[ExampleScript](./code/example-script.ps1#L1-L60)] + ``` + $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 Windows 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. 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 index b41b8bdaae..9bf4342870 100644 --- 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 @@ -36,19 +36,43 @@ The following example demonstrates how to obtain an Azure AD access token that y Replace the *authUrl*, *clientid*, and *clientSecret* values with the ones you got from **Preferences settings** page in the portal: -[!code[CustomTIAPI](./code/example.ps1#L1-L14)] +```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 + +``` ## 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: -[!code[CustomTIAPI](./code/example.ps1#L16-L19)] +```powershell +$headers = @{ + "Content-Type"="application/json" + "Accept"="application/json" + "Authorization"="Bearer {0}" -f $token } + +$apiBaseUrl = "https://ti.securitycenter.windows.com/V1.0/" +``` ## 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: -[!code[CustomTIAPI](./code/example.ps1#L21-L24)] +```powershell +$alertDefinitions = + (Invoke-RestMethod ("{0}AlertDefinitions" -f $apiBaseUrl) -Method Get -Headers $headers).value +``` The response is empty on initial use of the API. @@ -56,18 +80,96 @@ The response is empty on initial use of the API. ## Step 4: Create a new alert definition The following example demonstrates how you to create a new alert definition. -[!code[CustomTIAPI](./code/example.ps1#L26-L39)] +```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) +``` ## 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. -[!code[CustomTIAPI](./code/example.ps1#L43-L53)] +```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. -[!code[CustomTIAPI](./code/example.ps1#L1-L53)] +```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) + +``` ## Related topics - [Understand threat intelligence concepts](threat-indicator-concepts-windows-defender-advanced-threat-protection.md) 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 index a67b250923..dc44b7cbea 100644 --- 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 @@ -38,20 +38,45 @@ The following example demonstrates how to obtain an Azure AD access token that y Replace the *auth_url*, *client_id*, and *client_secret* values with the ones you got from **Preferences settings** page in the portal: -[!code[CustomTIAPI](./code/example.py#L1-L17)] +``` +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"] +``` ## Step 2: Create request session object Add HTTP headers to the session object, including the Authorization header with the token that was obtained. -[!code[CustomTIAPI](./code/example.py#L19-L23)] +``` +with requests.Session() as session: + session.headers = { + 'Authorization': 'Bearer {}'.format(token), + 'Content-Type': 'application/json', + 'Accept': 'application/json'} +``` ## 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: -[!code[CustomTIAPI](./code/example.py#L25-L26)] +``` + 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. @@ -59,18 +84,95 @@ The response is empty on initial use of the API. ## Step 4: Create a new alert definition The following example demonstrates how you to create a new alert definition. -[!code[CustomTIAPI](./code/example.py#L28-L39)] +``` + 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) +``` ## 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. -[!code[CustomTIAPI](./code/example.py#L41-L51)] +``` + 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. -[!code[CustomTIAPI](./code/example.py#L1-L53)] +```syntax +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)) +``` ## Related topics - [Understand threat intelligence concepts](threat-indicator-concepts-windows-defender-advanced-threat-protection.md)