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

Merge pull request #4443 from adirdidi/mde-gov-updates

Browse Source 
API pages update
This commit is contained in:
jcaparas 2020-12-18 11:11:23 -08:00 committed by GitHub
commit 907585afc6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 101 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
windows/security/includes/improve-request-performance.md
View File

@ -16,7 +16,7 @@ ms.collection: M365-security-compliance
ms.topic: article
---
>[!NOTE]
>[!TIP]
>For better performance, you can use server closer to your geo location:
> - api-us.securitycenter.microsoft.com
> - api-eu.securitycenter.microsoft.com

20
windows/security/includes/microsoft-defender-api-usgov.md Normal file
View File

@ -0,0 +1,20 @@
---
title: Microsoft Defender for Endpoint API URIs for US Government
description: Microsoft Defender for Endpoint API URIs for US Government
keywords: defender, endpoint, api, government, gov
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
manager: dansimp
audience: ITPro
ms.collection: M365-security-compliance
ms.topic: article
---
>[!NOTE]
>If you are a US Government customer, please use the URIs listed in [here](gov.md#api).

10
windows/security/threat-protection/microsoft-defender-atp/api-hello-world.md
View File

@ -26,6 +26,8 @@ ms.topic: article
- Want to experience Microsoft Defender for Endpoint? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink)
[!include[Microsoft Defender for Endpoint API URIs for US Government](../../includes/microsoft-defender-api-usgov.md)]
## Get Alerts using a simple PowerShell script
@ -95,6 +97,8 @@ Done! You have successfully registered an application!
- Copy the script below to PowerShell ISE or to a text editor, and save it as "**Get-Token.ps1**"
- Running this script will generate a token and will save it in the working folder under the name "**Latest-token.txt**".
[!include[Improve request performance](../../includes/improve-request-performance.md)]
```
# That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
# Paste below your Tenant ID, App ID and App Secret (App key).
@ -103,8 +107,8 @@ $tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application secret here
$resourceAppIdUri = 'https://api.securitycenter.windows.com'
$oAuthUri = "https://login.windows.net/$TenantId/oauth2/token"
$resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$authBody = [Ordered] @{
resource = "$resourceAppIdUri"
client_id = "$appId"
@ -142,7 +146,7 @@ $dateTime = (Get-Date).ToUniversalTime().AddHours(-48).ToString("o")
# The URL contains the type of query and the time filter we create above
# Read more about other query options and filters at Https://TBD- add the documentation link
$url = "https://api.securitycenter.windows.com/api/alerts?`$filter=alertCreationTime ge $dateTime"
$url = "https://api.securitycenter.microsoft.com/api/alerts?`$filter=alertCreationTime ge $dateTime"
# Set the WebRequest headers
$headers = @{

8
windows/security/threat-protection/microsoft-defender-atp/api-power-bi.md
View File

@ -26,6 +26,8 @@ ms.topic: article
- Want to experience Defender for Endpoint? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink)
[!include[Microsoft Defender for Endpoint API URIs for US Government](../../includes/microsoft-defender-api-usgov.md)]
In this section you will learn create a Power BI report on top of Defender for Endpoint APIs.
The first example demonstrates how to connect Power BI to Advanced Hunting API and the second example demonstrates a connection to our OData APIs, such as Machine Actions or Alerts.
@ -44,11 +46,13 @@ The first example demonstrates how to connect Power BI to Advanced Hunting API a
- Copy the below and paste it in the editor:
[!include[Improve request performance](../../includes/improve-request-performance.md)]
```
let
AdvancedHuntingQuery = "DeviceEvents | where ActionType contains 'Anti'",
HuntingUrl = "https://api.securitycenter.windows.com/api/advancedqueries",
HuntingUrl = "https://api.securitycenter.microsoft.com/api/advancedqueries",
Response = Json.Document(Web.Contents(HuntingUrl, [Query=[key=AdvancedHuntingQuery]])),
@ -114,7 +118,7 @@ The first example demonstrates how to connect Power BI to Advanced Hunting API a
Query = "MachineActions",
Source = OData.Feed("https://api.securitycenter.windows.com/api/" & Query, null, [Implementation="2.0", MoreColumns=true])
Source = OData.Feed("https://api.securitycenter.microsoft.com/api/" & Query, null, [Implementation="2.0", MoreColumns=true])
in
Source

10
windows/security/threat-protection/microsoft-defender-atp/exposed-apis-create-app-nativeapp.md
View File

@ -112,6 +112,10 @@ This page explains how to create an AAD application, get an access token to Micr
For more information on AAD tokens, see [Azure AD tutorial](https://docs.microsoft.com/azure/active-directory/develop/active-directory-v2-protocols-oauth-client-creds)
[!include[Improve request performance](../../includes/improve-request-performance.md)]
[!include[Microsoft Defender for Endpoint API URIs for US Government](../../includes/microsoft-defender-api-usgov.md)]
### Using C#
- Copy/Paste the below class in your application.
@ -127,9 +131,9 @@ For more information on AAD tokens, see [Azure AD tutorial](https://docs.microso
public static class WindowsDefenderATPUtils
{
private const string Authority = "https://login.windows.net";
private const string Authority = "https://login.microsoftonline.com";
private const string WdatpResourceId = "https://api.securitycenter.windows.com";
private const string WdatpResourceId = "https://api.securitycenter.microsoft.com";
public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
{
@ -175,7 +179,7 @@ Verify to make sure you got a correct token:
```csharp
var httpClient = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.windows.com/api/alerts");
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.microsoft.com/api/alerts");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

14
windows/security/threat-protection/microsoft-defender-atp/exposed-apis-create-app-partners.md
View File

@ -129,6 +129,10 @@ The following steps will guide you how to create an Azure AD application, get an
<br>For more information on AAD token, see [AAD tutorial](https://docs.microsoft.com/azure/active-directory/develop/active-directory-v2-protocols-oauth-client-creds)
[!include[Improve request performance](../../includes/improve-request-performance.md)]
[!include[Microsoft Defender for Endpoint API URIs for US Government](../../includes/microsoft-defender-api-usgov.md)]
### Using PowerShell
```
@ -139,8 +143,8 @@ $tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application key here
$resourceAppIdUri = 'https://api.securitycenter.windows.com'
$oAuthUri = "https://login.windows.net/$TenantId/oauth2/token"
$resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$authBody = [Ordered] @{
resource = "$resourceAppIdUri"
client_id = "$appId"
@ -172,8 +176,8 @@ return $token
string appId = "11111111-1111-1111-1111-111111111111"; // Paste your own app ID here
string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here for a test, and then store it in a safe place!
const string authority = "https://login.windows.net";
const string wdatpResourceId = "https://api.securitycenter.windows.com";
const string authority = "https://login.microsoftonline.com";
const string wdatpResourceId = "https://api.securitycenter.microsoft.com";
AuthenticationContext auth = new AuthenticationContext($"{authority}/{tenantId}/");
ClientCredential clientCredential = new ClientCredential(appId, appSecret);
@ -227,7 +231,7 @@ Sanity check to make sure you got a correct token:
```
var httpClient = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.windows.com/api/alerts");
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.microsoft.com/api/alerts");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

14
windows/security/threat-protection/microsoft-defender-atp/exposed-apis-create-app-webapp.md
View File

@ -107,6 +107,10 @@ This article explains how to create an Azure AD application, get an access token
For more information on Azure AD tokens, see the [Azure AD tutorial](https://docs.microsoft.com/azure/active-directory/develop/active-directory-v2-protocols-oauth-client-creds).
[!include[Improve request performance](../../includes/improve-request-performance.md)]
[!include[Microsoft Defender for Endpoint API URIs for US Government](../../includes/microsoft-defender-api-usgov.md)]
### Use PowerShell
```
@ -117,8 +121,8 @@ $tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application key here
$resourceAppIdUri = 'https://api.securitycenter.windows.com'
$oAuthUri = "https://login.windows.net/$TenantId/oauth2/token"
$resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$authBody = [Ordered] @{
resource = "$resourceAppIdUri"
client_id = "$appId"
@ -150,8 +154,8 @@ The following code was tested with NuGet Microsoft.IdentityModel.Clients.ActiveD
string appId = "11111111-1111-1111-1111-111111111111"; // Paste your own app ID here
string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here for a test, and then store it in a safe place!
const string authority = "https://login.windows.net";
const string wdatpResourceId = "https://api.securitycenter.windows.com";
const string authority = "https://login.microsoftonline.com";
const string wdatpResourceId = "https://api.securitycenter.microsoft.com";
AuthenticationContext auth = new AuthenticationContext($"{authority}/{tenantId}/");
ClientCredential clientCredential = new ClientCredential(appId, appSecret);
@ -204,7 +208,7 @@ The following is an example of sending a request to get a list of alerts **using
```
var httpClient = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.windows.com/api/alerts");
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.microsoft.com/api/alerts");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

13
windows/security/threat-protection/microsoft-defender-atp/exposed-apis-list.md
View File

@ -30,9 +30,9 @@ ms.topic: article
### Endpoint URI:
> The service base URI is: https://api.securitycenter.windows.com
> The service base URI is: https://api.securitycenter.microsoft.com
>
> The queries based OData have the '/api' prefix. For example, to get Alerts you can send GET request to https://api.securitycenter.windows.com/api/alerts
> The queries based OData have the '/api' prefix. For example, to get Alerts you can send GET request to https://api.securitycenter.microsoft.com/api/alerts
### Versioning:
@ -40,9 +40,14 @@ ms.topic: article
>
> The current version is **V1.0**.
>
> To use a specific version, use this format: `https://api.securitycenter.windows.com/api/{Version}`. For example: `https://api.securitycenter.windows.com/api/v1.0/alerts`
> To use a specific version, use this format: `https://api.securitycenter.microsoft.com/api/{Version}`. For example: `https://api.securitycenter.microsoft.com/api/v1.0/alerts`
>
> If you don't specify any version (e.g. https://api.securitycenter.windows.com/api/alerts ) you will get to the latest version.
> If you don't specify any version (e.g. https://api.securitycenter.microsoft.com/api/alerts ) you will get to the latest version.
[!include[Improve request performance](../../includes/improve-request-performance.md)]
[!include[Microsoft Defender for Endpoint API URIs for US Government](../../includes/microsoft-defender-api-usgov.md)]
Learn more about the individual supported entities where you can run API calls to and details such as HTTP request values, request headers and expected responses.

26
windows/security/threat-protection/microsoft-defender-atp/exposed-apis-odata-samples.md
View File

@ -26,6 +26,10 @@ ms.topic: article
- [Microsoft Defender for Endpoint](https://go.microsoft.com/fwlink/p/?linkid=2146631)
[!include[Improve request performance](../../includes/improve-request-performance.md)]
[!include[Microsoft Defender for Endpoint API URIs for US Government](../../includes/microsoft-defender-api-usgov.md)]
If you are not familiar with OData queries, see: [OData V4 queries](https://www.odata.org/documentation/)
Not all properties are filterable.
@ -150,14 +154,14 @@ HTTP GET https://api.securitycenter.microsoft.com/api/alerts?$top=10&$expand=ev
Get all the alerts last updated after 2019-11-22 00:00:00
```http
HTTP GET https://api.securitycenter.windows.com/api/alerts?$filter=lastUpdateTime+ge+2019-11-22T00:00:00Z
HTTP GET https://api.securitycenter.microsoft.com/api/alerts?$filter=lastUpdateTime+ge+2019-11-22T00:00:00Z
```
**Response:**
```json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts",
"@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#Alerts",
"value": [
{
"id": "da637308392288907382_-880718168",
@ -206,14 +210,14 @@ HTTP GET https://api.securitycenter.windows.com/api/alerts?$filter=lastUpdateTi
Get all the devices with 'High' 'RiskScore'
```http
HTTP GET https://api.securitycenter.windows.com/api/machines?$filter=riskScore+eq+'High'
HTTP GET https://api.securitycenter.microsoft.com/api/machines?$filter=riskScore+eq+'High'
```
**Response:**
```json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines",
"@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#Machines",
"value": [
{
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
@ -245,14 +249,14 @@ HTTP GET https://api.securitycenter.windows.com/api/machines?$filter=riskScore+
Get top 100 devices with 'HealthStatus' not equals to 'Active'
```http
HTTP GET https://api.securitycenter.windows.com/api/machines?$filter=healthStatus+ne+'Active'&$top=100
HTTP GET https://api.securitycenter.microsoft.com/api/machines?$filter=healthStatus+ne+'Active'&$top=100
```
**Response:**
```json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines",
"@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#Machines",
"value": [
{
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
@ -284,14 +288,14 @@ HTTP GET https://api.securitycenter.windows.com/api/machines?$filter=healthStat
Get all the devices that last seen after 2018-10-20
```http
HTTP GET https://api.securitycenter.windows.com/api/machines?$filter=lastSeen gt 2018-08-01Z
HTTP GET https://api.securitycenter.microsoft.com/api/machines?$filter=lastSeen gt 2018-08-01Z
```
**Response:**
```json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines",
"@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#Machines",
"value": [
{
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
@ -323,14 +327,14 @@ HTTP GET https://api.securitycenter.windows.com/api/machines?$filter=lastSeen g
Get all the Anti-Virus scans that the user Analyst@examples.onmicrosoft.com created using Microsoft Defender for Endpoint
```http
HTTP GET https://api.securitycenter.windows.com/api/machineactions?$filter=requestor eq 'Analyst@contoso.com' and type eq 'RunAntiVirusScan'
HTTP GET https://api.securitycenter.microsoft.com/api/machineactions?$filter=requestor eq 'Analyst@contoso.com' and type eq 'RunAntiVirusScan'
```
**Response:**
```json
json{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions",
"@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#MachineActions",
"value": [
{
"id": "2e9da30d-27f6-4208-81f2-9cd3d67893ba",
@ -355,7 +359,7 @@ json{
Get the count of open alerts for a specific device:
```http
HTTP GET https://api.securitycenter.windows.com/api/machines/123321d0c675eaa415b8e5f383c6388bff446c62/alerts/$count?$filter=status ne 'Resolved'
HTTP GET https://api.securitycenter.microsoft.com/api/machines/123321d0c675eaa415b8e5f383c6388bff446c62/alerts/$count?$filter=status ne 'Resolved'
```
**Response:**

6
windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-api.md
View File

@ -26,6 +26,8 @@ ms.topic: article
- Want to experience Defender for Endpoint? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink)
[!include[Microsoft Defender for Endpoint API URIs for US Government](../../includes/microsoft-defender-api-usgov.md)]
## Limitations
1. You can only run a query on data from the last 30 days.
2. The results will include a maximum of 100,000 rows.
@ -50,7 +52,7 @@ Delegated (work or school account) | AdvancedQuery.Read | 'Run advanced queries'
## HTTP request
```
POST https://api.securitycenter.windows.com/api/advancedqueries/run
POST https://api.securitycenter.microsoft.com/api/advancedqueries/run
```
## Request headers
@ -81,7 +83,7 @@ Here is an example of the request.
```
POST https://api.securitycenter.windows.com/api/advancedqueries/run
POST https://api.securitycenter.microsoft.com/api/advancedqueries/run
Content-type: application/json
{
"Query":"DeviceProcessEvents

10
windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-sample-powershell.md
View File

@ -24,6 +24,8 @@ ms.topic: article
**Applies to:**
- [Microsoft Defender for Endpoint](https://go.microsoft.com/fwlink/p/?linkid=2146631)
[!include[Microsoft Defender for Endpoint API URIs for US Government](../../includes/microsoft-defender-api-usgov.md)]
Run advanced queries using PowerShell, see [Advanced Hunting API](run-advanced-query-api.md).
@ -51,8 +53,8 @@ $tenantId = '00000000-0000-0000-0000-000000000000' # Paste your own tenant ID he
$appId = '11111111-1111-1111-1111-111111111111' # Paste your own app ID here
$appSecret = '22222222-2222-2222-2222-222222222222' # Paste your own app secret here
$resourceAppIdUri = 'https://api.securitycenter.windows.com'
$oAuthUri = "https://login.windows.net/$TenantId/oauth2/token"
$resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$body = [Ordered] @{
resource = "$resourceAppIdUri"
client_id = "$appId"
@ -72,10 +74,12 @@ where
Run the following query:
[!include[Improve request performance](../../includes/improve-request-performance.md)]
```
$query = 'RegistryEvents | limit 10' # Paste your own query here
$url = "https://api.securitycenter.windows.com/api/advancedqueries/run"
$url = "https://api.securitycenter.microsoft.com/api/advancedqueries/run"
$headers = @{
'Content-Type' = 'application/json'
Accept = 'application/json'

10
windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-sample-python.md
View File

@ -26,6 +26,8 @@ ms.topic: article
- [Microsoft Defender for Endpoint](https://go.microsoft.com/fwlink/p/?linkid=2146631)
[!include[Microsoft Defender for Endpoint API URIs for US Government](../../includes/microsoft-defender-api-usgov.md)]
Run advanced queries using Python, see [Advanced Hunting API](run-advanced-query-api.md).
In this section, we share Python samples to retrieve a token and use it to run a query.
@ -36,6 +38,8 @@ In this section, we share Python samples to retrieve a token and use it to run a
- Run the following commands:
[!include[Improve request performance](../../includes/improve-request-performance.md)]
```
import json
@ -46,9 +50,9 @@ tenantId = '00000000-0000-0000-0000-000000000000' # Paste your own tenant ID her
appId = '11111111-1111-1111-1111-111111111111' # Paste your own app ID here
appSecret = '22222222-2222-2222-2222-222222222222' # Paste your own app secret here
url = "https://login.windows.net/%s/oauth2/token" % (tenantId)
url = "https://login.microsoftonline.com/%s/oauth2/token" % (tenantId)
resourceAppIdUri = 'https://api.securitycenter.windows.com'
resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
body = {
'resource' : resourceAppIdUri,
@ -78,7 +82,7 @@ where
```
query = 'RegistryEvents | limit 10' # Paste your own query here
url = "https://api.securitycenter.windows.com/api/advancedqueries/run"
url = "https://api.securitycenter.microsoft.com/api/advancedqueries/run"
headers = {
'Content-Type' : 'application/json',
'Accept' : 'application/json',