From f7b038cff2dbbab104eacccf03153269d981d9b7 Mon Sep 17 00:00:00 2001 From: jcaparas Date: Thu, 24 Aug 2017 23:03:22 -0700 Subject: [PATCH] update apis --- windows/threat-protection/TOC.md | 27 ++-- ...ows-defender-advanced-threat-protection.md | 98 +------------- ...ows-defender-advanced-threat-protection.md | 125 ++++++++++++++++++ 3 files changed, 141 insertions(+), 109 deletions(-) create mode 100644 windows/threat-protection/windows-defender-atp/supported-apis-windows-defender-advanced-threat-protection.md diff --git a/windows/threat-protection/TOC.md b/windows/threat-protection/TOC.md index e8493bb003..8ffdbfa378 100644 --- a/windows/threat-protection/TOC.md +++ b/windows/threat-protection/TOC.md @@ -71,19 +71,20 @@ #### [Experiment with custom threat intelligence alerts](windows-defender-atp\experiment-custom-ti-windows-defender-advanced-threat-protection.md) #### [Troubleshoot custom threat intelligence issues](windows-defender-atp\troubleshoot-custom-ti-windows-defender-advanced-threat-protection.md) ### [Use the Windows Defender ATP exposed APIs](windows-defender-atp\exposed-apis-windows-defender-advanced-threat-protection.md) -#### [Collect investigation package](windows-defender-atp\collect-investigation-package-windows-defender-advanced-threat-protection.md) -#### [Isolate machine](windows-defender-atp\isolate-machine-windows-defender-advanced-threat-protection.md) -#### [Unisolate machine](unisolate-machine-windows-defender-atp\windows-defender-advanced-threat-protection.md) -#### [Restrict code execution](windows-defender-atp\restrict-code-execution-windows-defender-advanced-threat-protection.md) -#### [Remove code execution restriction](windows-defender-atp\unrestrict-code-execution-windows-defender-advanced-threat-protection.md) -#### [Run antivirus scan](windows-defender-atp\run-av-scan-windows-defender-advanced-threat-protection.md) -#### [Stop and quarantine files](windows-defender-atp\stop-quarantine-file-windows-defender-advanced-threat-protection.md) -#### [Request sample](windows-defender-atp\request-sample-windows-defender-advanced-threat-protection.md) -#### [Block file](windows-defender-atp\block-file-windows-defender-advanced-threat-protection.md) -#### [Unblock file](windows-defender-atp\unblock-file-windows-defender-advanced-threat-protection.md) -#### [Get package SAS URI](windows-defender-atp\get-package-sas-uri-windows-defender-advanced-threat-protection.md) -#### [Get MachineAction object](windows-defender-atp\get-machineaction-object-windows-defender-advanced-threat-protection.md) -#### [Get FileMachineAction object](windows-defender-atp\get-filemachineaction-object-windows-defender-advanced-threat-protection.md) +#### [Supported Windows Defender ATP APIs](windows-defender-atp\supported-apis-windows-defender-advanced-threat-protection.md) +##### [Collect investigation package](windows-defender-atp\collect-investigation-package-windows-defender-advanced-threat-protection.md) +##### [Isolate machine](windows-defender-atp\isolate-machine-windows-defender-advanced-threat-protection.md) +##### [Unisolate machine](unisolate-machine-windows-defender-atp\windows-defender-advanced-threat-protection.md) +##### [Restrict code execution](windows-defender-atp\restrict-code-execution-windows-defender-advanced-threat-protection.md) +##### [Remove code execution restriction](windows-defender-atp\unrestrict-code-execution-windows-defender-advanced-threat-protection.md) +##### [Run antivirus scan](windows-defender-atp\run-av-scan-windows-defender-advanced-threat-protection.md) +##### [Stop and quarantine files](windows-defender-atp\stop-quarantine-file-windows-defender-advanced-threat-protection.md) +##### [Request sample](windows-defender-atp\request-sample-windows-defender-advanced-threat-protection.md) +##### [Block file](windows-defender-atp\block-file-windows-defender-advanced-threat-protection.md) +##### [Unblock file](windows-defender-atp\unblock-file-windows-defender-advanced-threat-protection.md) +##### [Get package SAS URI](windows-defender-atp\get-package-sas-uri-windows-defender-advanced-threat-protection.md) +##### [Get MachineAction object](windows-defender-atp\get-machineaction-object-windows-defender-advanced-threat-protection.md) +##### [Get FileMachineAction object](windows-defender-atp\get-filemachineaction-object-windows-defender-advanced-threat-protection.md) ### [Create and build Power BI reports using Windows Defender ATP data](windows-defender-atp\powerbi-reports-windows-defender-advanced-threat-protection.md) ### [Check sensor state](windows-defender-atp\check-sensor-status-windows-defender-advanced-threat-protection.md) #### [Fix unhealthy sensors](windows-defender-atp\fix-unhealhty-sensors-windows-defender-advanced-threat-protection.md) diff --git a/windows/threat-protection/windows-defender-atp/exposed-apis-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/exposed-apis-windows-defender-advanced-threat-protection.md index f188d8d4ff..a39fc723d2 100644 --- a/windows/threat-protection/windows-defender-atp/exposed-apis-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/exposed-apis-windows-defender-advanced-threat-protection.md @@ -94,102 +94,8 @@ HttpResponseMessage response = client.GetAsync(ep).Result; string resp = response.Content.ReadAsStringAsync().Result; Console.WriteLine($"response for: {ep} \r\n {resp}"); ``` -## Supported APIs -| Entity | Action | Description | Functions | Route | -|---------|---------------|--------------------------------------------------------------------------|--------------------------------------------|-------------------------------------------| -| Actor | Get | Retrieves an actor report from the CMS. | $top, $select, $count | /actor/{id} | -| | GetAlerts | Retrieves all alerts related to a given actor. | $expand, $top, $select, $count | /actor/{id}/alerts | -| Alerts | Get | Retrieves top recent alerts | $top, $select, $count, $skip, $expand | /alerts | -| | Get | Retrieves an alert by its ID | $top, $select, $count, $expand | /alerts/{id} | -| | GetMachines | Retrieves all machines related to a specific alert | $top, $select, $count | /alerts/{id}/machines | -| | GetFiles | Retrieves all files related to a specific alert | $top, $select, $count | /alerts/{id}/files | -| | GetActor | Retrieves the actor related to the specific alert | $top, $select, $count | /alerts/{id}/actor | -| | GetDomains | Retrieves all domains related to a specific alert | $top, $select, $count | /alerts/{id}/domains | -| | GetIPs | Retrieves all IPs related to a specific alert | $top, $select, $count | /alerts/{id}/ips | -| Machine | Get | Retrieves a collection of recently seen machines | $top, $select, $count, $skip | /machines | -| | Get | Retrieves a machine entity by ID | $top, $select, $count | /machines/{id} | -| | GetAlerts | Retrieves a collection of alerts related to a given machine ID | $top, $select, $count, $expand | /machines/{id}/alerts | -| | GetLogOnUsers | Retrieves a collection of logged on users related to a given machine ID | $top, $select, $count | /machines/{id}/logonusers | -| | Find | Find a machine entity around a specific timestamp by FQDN or internal IP | $top, $select, $count, $expand(logonusers) | /machines/find(key={id},timestamp={time}) | -| User | Get | Retrieve a User entity by key (user name or domain\user) | $top, $select, $count | /users/{id} | -| | GetAlerts | Retrieves a collection of alerts related to a given user ID | $top, $select, $count, $expand | /users/{id}/alerts | -| | GetMachines | Retrieves a collection of machines related to a given user ID | $top, $select, $count | /users/{id}/machines | -| Domain | Get | Retrieves a domain entity | $top, $select, $count | /domains/{id} | -| | GetAlerts | Retrieves a collection of alerts related to a given domain address | $top, $select, $count, $expand | /domains/{id}/alerts | -| | GetMachines | Retrieves a collection of machines related to a given domain address | $top, $select, $count | /domains/{id}/machines | -| | Stats | Retrieves the prevalence for the given domain | | /domains/{id}/stats | -| IP | Get | Retrieves an IP entity | $top, $select, $count | /ips/{id} | -| | GetAlerts | Retrieves a collection of alerts related to a given IP address | $top, $select, $count, $expand | /ips/{id}/alerts | -| | GetMachines | Retrieves a collection of machines related to a given IP address | $top, $select, $count | /ips/{id}/machines | -| | Stats | Retrieves the prevalence for the given IP | | /ips/{id}/stats | -| File | Get | Retrieves a file by identifier(Sha1, Sha256, MD5) | $top, $select, $count | /files/{id} | -| | GetAlerts | Retrieves a collection of alerts related to a given file hash | $top, $select, $count, $expand | /files/{id}/alerts | -| | GetMachines | Retrieves a collection of machines related to a given file hash | $top, $select, $count | /files{id}/machines | -| | Stats | Retrieves the prevalence for the given file | | /files/{id}/machines | - -### Example queries -After creating the application, you can run the following queries. - -Fetching the top 20 alerts with machine information: -``` -private const string authority = "https://login.microsoftonline.com/common/oauth2/v2.0/authorize"; -private const string resourceId = "https://graph.microsoft.com"; -private const string clientId = "{YOUR CLIENT ID/APP ID HERE}"; -private const string redirect = "https://localhost"; -HttpClient client = new HttpClient(); -AuthenticationContext auth = new AuthenticationContext(authority); -var token = auth.AcquireTokenAsync(resourceId, clientId, new Uri(redirect), new PlatformParameters(PromptBehavior.Auto)).Result; -client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(token.AccessTokenType, token.AccessToken); -var ep = $"{resourceId}/{apiVersion}/alerts?$top=20&$expand=machine"; // the query itself in yellow -HttpResponseMessage response = client.GetAsync(ep).Result; -string resp = response.Content.ReadAsStringAsync().Result; -Console.WriteLine($"response for: {ep} \r\n {resp}"); -``` - -Response: -``` -{ - "@odata.context": "https://graph.microsoft-ppe.com/testwdatp/$metadata#Alerts", - "@odata.count": 20, - "@odata.nextLink": "https://graph.microsoft-ppe.com/testwdatp/alerts?$top=20&$expand=machine&$skip=20", - "value": [ - { - "id": "636341278149188342_1960231459", - "severity": "Medium", - "status": "New", - "description": "A process has injected code into another process using process hollowing technique, indicating suspicious code being run in the target process memory. Injection is often used to hide malicious code execution within a trusted process. \nAs a result, the target process may exhibit abnormal behaviors such as opening a listening port or connecting to a command and control server.", - "recommendedAction": "1. Investigate the machine's timeline for any other indicators around the time of this alert \n2. Validate contextual information about the relevant components such as file prevalence, other machines it was observed on etc. \n3. Contact the machine's user to verify whether they received an email with a suspicious attachment or link around the time of the alert.\n4. Run a full malware scan on the machine, this may reveal additional related components. \n5. Consider submitting the relevant file(s) for deep analysis for detailed behavioral information. \n6. If initial investigation confirms suspicions, contact your incident response team for forensic analysis.", - "alertCreationTime": "2017-06-27T02:36:53.7841015Z", - "category": "Installation", - "title": "Process hollowing detected", - "threatFamilyName": null, - "detectionSource": null, - "classification": null, - "determination": null, - "assignedTo": null, - "resolvedTime": null, - "lastEventTime": "2017-06-29T10:11:54.2872094Z", - "firstEventTime": "2017-06-27T02:30:23.9320988Z", - "machine": { - "id": "67e5ef2c2eab150cc8638e21dba19c1b0a41ad0b", - "computerDnsName": null, - "firstSeen": "0001-01-01T00:00:00Z", - "isOnline": false, - "osPlatform": null, - "osVersion": null, - "systemProductName": null, - "lastIpAddress": null, - "lastExternalIpAddress": null, - "agentVersion": null, - "osBuild": null, - "healthStatus": "Active", - "isAadJoined": null - } - }, -}…. - -``` ## Related topics -- [Create and build Power BI reports using Windows Defender ATP data](powerbi-reports-windows-defender-advanced-threat-protection.md) \ No newline at end of file +- [Supported Windows Defender ATP APIs](supported-apis-windows-defender-advanced-threat-protection.md) +- [Create and build Power BI reports using Windows Defender ATP data](powerbi-reports-windows-defender-advanced-threat-protection.md) diff --git a/windows/threat-protection/windows-defender-atp/supported-apis-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/supported-apis-windows-defender-advanced-threat-protection.md new file mode 100644 index 0000000000..8522966f5b --- /dev/null +++ b/windows/threat-protection/windows-defender-atp/supported-apis-windows-defender-advanced-threat-protection.md @@ -0,0 +1,125 @@ +--- +title: Supported Windows Defender Advanced Threat Protection APIs +description: Use the exposed data and actions using a set of progammatic APIs that are part of the Microsoft Intelligence Security Graph. +keywords: apis, graph api, supported apis, actor, alerts, machine, user, domain, ip, file +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: high +ms.date: 09/01.2017 +--- + +# Supported Windows Defender ATP APIs + +**Applies to:** + +- Windows 10 Enterprise +- Windows 10 Education +- Windows 10 Pro +- Windows 10 Pro Education +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + + + +| Entity | Action | Description | Functions | Route | +|---------|---------------|--------------------------------------------------------------------------|--------------------------------------------|-------------------------------------------| +| Actor | Get | Retrieves an actor report from the CMS. | $top, $select, $count | /actor/{id} | +| | GetAlerts | Retrieves all alerts related to a given actor. | $expand, $top, $select, $count | /actor/{id}/alerts | +| Alerts | Get | Retrieves top recent alerts | $top, $select, $count, $skip, $expand | /alerts | +| | Get | Retrieves an alert by its ID | $top, $select, $count, $expand | /alerts/{id} | +| | GetMachines | Retrieves all machines related to a specific alert | $top, $select, $count | /alerts/{id}/machines | +| | GetFiles | Retrieves all files related to a specific alert | $top, $select, $count | /alerts/{id}/files | +| | GetActor | Retrieves the actor related to the specific alert | $top, $select, $count | /alerts/{id}/actor | +| | GetDomains | Retrieves all domains related to a specific alert | $top, $select, $count | /alerts/{id}/domains | +| | GetIPs | Retrieves all IPs related to a specific alert | $top, $select, $count | /alerts/{id}/ips | +| Machine | Get | Retrieves a collection of recently seen machines | $top, $select, $count, $skip | /machines | +| | Get | Retrieves a machine entity by ID | $top, $select, $count | /machines/{id} | +| | GetAlerts | Retrieves a collection of alerts related to a given machine ID | $top, $select, $count, $expand | /machines/{id}/alerts | +| | GetLogOnUsers | Retrieves a collection of logged on users related to a given machine ID | $top, $select, $count | /machines/{id}/logonusers | +| | Find | Find a machine entity around a specific timestamp by FQDN or internal IP | $top, $select, $count, $expand(logonusers) | /machines/find(key={id},timestamp={time}) | +| User | Get | Retrieve a User entity by key (user name or domain\user) | $top, $select, $count | /users/{id} | +| | GetAlerts | Retrieves a collection of alerts related to a given user ID | $top, $select, $count, $expand | /users/{id}/alerts | +| | GetMachines | Retrieves a collection of machines related to a given user ID | $top, $select, $count | /users/{id}/machines | +| Domain | Get | Retrieves a domain entity | $top, $select, $count | /domains/{id} | +| | GetAlerts | Retrieves a collection of alerts related to a given domain address | $top, $select, $count, $expand | /domains/{id}/alerts | +| | GetMachines | Retrieves a collection of machines related to a given domain address | $top, $select, $count | /domains/{id}/machines | +| | Stats | Retrieves the prevalence for the given domain | | /domains/{id}/stats | +| IP | Get | Retrieves an IP entity | $top, $select, $count | /ips/{id} | +| | GetAlerts | Retrieves a collection of alerts related to a given IP address | $top, $select, $count, $expand | /ips/{id}/alerts | +| | GetMachines | Retrieves a collection of machines related to a given IP address | $top, $select, $count | /ips/{id}/machines | +| | Stats | Retrieves the prevalence for the given IP | | /ips/{id}/stats | +| File | Get | Retrieves a file by identifier(Sha1, Sha256, MD5) | $top, $select, $count | /files/{id} | +| | GetAlerts | Retrieves a collection of alerts related to a given file hash | $top, $select, $count, $expand | /files/{id}/alerts | +| | GetMachines | Retrieves a collection of machines related to a given file hash | $top, $select, $count | /files{id}/machines | +| | Stats | Retrieves the prevalence for the given file | | /files/{id}/machines | + +### Example queries +After creating the application, you can run the following queries. + +Fetching the top 20 alerts with machine information: +``` +private const string authority = "https://login.microsoftonline.com/common/oauth2/v2.0/authorize"; +private const string resourceId = "https://graph.microsoft.com"; +private const string clientId = "{YOUR CLIENT ID/APP ID HERE}"; +private const string redirect = "https://localhost"; +HttpClient client = new HttpClient(); +AuthenticationContext auth = new AuthenticationContext(authority); +var token = auth.AcquireTokenAsync(resourceId, clientId, new Uri(redirect), new PlatformParameters(PromptBehavior.Auto)).Result; +client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(token.AccessTokenType, token.AccessToken); +var ep = $"{resourceId}/{apiVersion}/alerts?$top=20&$expand=machine"; // the query itself in yellow +HttpResponseMessage response = client.GetAsync(ep).Result; +string resp = response.Content.ReadAsStringAsync().Result; +Console.WriteLine($"response for: {ep} \r\n {resp}"); +``` + +Response: +``` +{ + "@odata.context": "https://graph.microsoft-ppe.com/testwdatp/$metadata#Alerts", + "@odata.count": 20, + "@odata.nextLink": "https://graph.microsoft-ppe.com/testwdatp/alerts?$top=20&$expand=machine&$skip=20", + "value": [ + { + "id": "636341278149188342_1960231459", + "severity": "Medium", + "status": "New", + "description": "A process has injected code into another process using process hollowing technique, indicating suspicious code being run in the target process memory. Injection is often used to hide malicious code execution within a trusted process. \nAs a result, the target process may exhibit abnormal behaviors such as opening a listening port or connecting to a command and control server.", + "recommendedAction": "1. Investigate the machine's timeline for any other indicators around the time of this alert \n2. Validate contextual information about the relevant components such as file prevalence, other machines it was observed on etc. \n3. Contact the machine's user to verify whether they received an email with a suspicious attachment or link around the time of the alert.\n4. Run a full malware scan on the machine, this may reveal additional related components. \n5. Consider submitting the relevant file(s) for deep analysis for detailed behavioral information. \n6. If initial investigation confirms suspicions, contact your incident response team for forensic analysis.", + "alertCreationTime": "2017-06-27T02:36:53.7841015Z", + "category": "Installation", + "title": "Process hollowing detected", + "threatFamilyName": null, + "detectionSource": null, + "classification": null, + "determination": null, + "assignedTo": null, + "resolvedTime": null, + "lastEventTime": "2017-06-29T10:11:54.2872094Z", + "firstEventTime": "2017-06-27T02:30:23.9320988Z", + "machine": { + "id": "67e5ef2c2eab150cc8638e21dba19c1b0a41ad0b", + "computerDnsName": null, + "firstSeen": "0001-01-01T00:00:00Z", + "isOnline": false, + "osPlatform": null, + "osVersion": null, + "systemProductName": null, + "lastIpAddress": null, + "lastExternalIpAddress": null, + "agentVersion": null, + "osBuild": null, + "healthStatus": "Active", + "isAadJoined": null + } + }, +}…. + +``` + +## Related topics +- [Use the Windows Defender ATP exposed APIs](exposed-apis-windows-defender-advanced-threat-protection.md) +