# Set up Defender for Endpoint

Have your tenant ID and app registration ready before you start — see
[what you need](./index.md#what-you-need-before-you-start).

## Step 1 — Open Connectors

1. Select **Settings > Connectors**.
2. Select **Add connector**.

## Step 2 — Choose Defender for Endpoint

Under **Guided setup**, choose **Microsoft Defender for Endpoint**.

## Step 3 — Name it and enter your tenant

1. In **Display name for this connector**, give the connector a name. It
   appears in the connector list.
2. In **Entra ID tenant ID**, enter your tenant ID or your primary domain, for
   example `contoso.onmicrosoft.com`.

The form also shows a collection preset, the field that begins **Collection
preset for Microsoft Defender for Endpoint**. It comes filled in. Leave it as
it is unless Axiad support asks you to change it. Fields marked as set
automatically need nothing from you either.

**Default schedule frequency** sets how often the connector runs, as a duration
such as `1h` or `24h`. It defaults to `1h`.

## Step 4 — Enter your app registration

| Field | What to enter |
| --- | --- |
| **Application (client) ID** | The app registration's application (client) ID, from its **Overview** page in Entra ID |
| **Client secret** | The secret's **Value**, not its secret ID. It is hidden as you type, and never shown again once saved |

Entra ID shows a secret's value once, when it is created. If you no longer
have it, create a new secret.

> **caution**
Entra ID client secrets have an expiry date, set when the secret is created.
When it passes, collection stops. Note the date and replace the secret before
then.

## Step 5 — Define your searches

This step is optional. Skip it if you only want machines and alerts, or if your
Defender plan does not include advanced hunting.

1. Under **Advanced hunting searches**, select **Add search**.
2. Give the search a label, for example `Shadow AI process search`. The label
   becomes the name of the AI agents the search finds.
3. Choose a mode:
   - **Guided (event type + terms)** builds the KQL for you from an event type
     and a list of terms. You need no query language.
   - **Custom (write your own KQL)** runs the KQL you write.
4. Choose an event type. In custom mode, choose the one that matches what your
   query finds.

| Event type | What the terms are | What it finds |
| --- | --- | --- |
| **Process execution** | Process file names. A name must match the whole file name, ignoring case | AI tools, by the process that runs them |
| **DNS request** | Domains. A domain also matches its subdomains, so `example.com` matches `api.example.com` but not `myexample.com` | AI tools, by the services they call |

In guided mode, enter your terms separated by commas.

Select **Use standard list** to fill the terms with a prepared list of known AI
tool process names or domains. The list is a starting point, not a complete
list. You can edit it and add your own terms, or leave it out.

Add as many searches as you need. Select **Remove** to delete one.

### Writing your own KQL

A custom search runs your query as written. For Mesh to tie each result to a
device and an owner, return these advanced hunting columns:

| Column | Used for |
| --- | --- |
| `DeviceId` | The device the match was found on |
| `DeviceName` | The device's name |
| `FileName` or `RemoteUrl` | What matched |
| `AccountName` | The account that ran it, which becomes the agent's owner |
| `Timestamp` | When it was seen |

A result without these columns is still collected, but Mesh cannot attribute
it to a device or owner.

Microsoft's own advanced hunting limits apply to every search, including how
many rows a query can return and how long it can run.

## Step 6 — Set the search window

**Hunting query timespan** sets how far back every search looks, as an ISO 8601
duration — for example `P1D` for one day or `P7D` for seven. It defaults to
`P30D`, 30 days.

## Step 7 — Test the connection

Select **Test connection**. Mesh checks that it can sign in to Microsoft with
your app registration.

A pass does not prove every permission was granted. A missing permission is
reported on the first collection, for the data that needs it.

If the test does not pass, see [If something goes wrong](#if-something-goes-wrong).

## Step 8 — Add the connector

Select **Add & connect**.

Your connector appears in the list and the first collection starts. When it
finishes, check **Sync status** to confirm the connector is collecting.

## Check that it worked

1. Open **Settings > Connectors** and find your connector.
2. Check **Health** and **Sync status**. See
   [Read the Connectors page](../../../admin-guide/connectors-page.md).
3. Select the row to open **Collected data** and check the entity counts
   against the number of devices you expect.
4. If you defined searches, open your non-human identity inventory and look
   for the AI agents they found. See
   [Govern non-human and agentic identities](../../../use-cases/govern-nonhuman-identities.md).

A tenant with no devices reporting to Defender yet collects no machines. That
is the expected result, not a failure.

## Government and sovereign clouds

Leave these settings as they are for Microsoft's commercial cloud. For a US
government or other sovereign cloud, change them under **Advanced** to match
your environment. Change each host together with its scope.

The US government environments do not all use the same hosts. GCC signs in
through the commercial sign-in host, while GCC High and DoD have their own.
Use the values for your environment:

### Commercial (default)

| Setting | Value |
| --- | --- |
| **Microsoft sign-in base URL** | `https://login.microsoftonline.com` |
| **Microsoft Graph base URL** | `https://graph.microsoft.com` |
| **Microsoft Graph OAuth scope** | `https://graph.microsoft.com/.default` |
| **Defender for Endpoint API base URL** | `https://api.security.microsoft.com` |
| **Defender for Endpoint API OAuth scope** | `https://api.securitycenter.microsoft.com/.default` |

### GCC

| Setting | Value |
| --- | --- |
| **Microsoft sign-in base URL** | `https://login.microsoftonline.com` |
| **Microsoft Graph base URL** | `https://graph.microsoft.com` |
| **Microsoft Graph OAuth scope** | `https://graph.microsoft.com/.default` |
| **Defender for Endpoint API base URL** | `https://api-gcc.securitycenter.microsoft.us` |
| **Defender for Endpoint API OAuth scope** | `https://api-gcc.securitycenter.microsoft.us/.default` |

### GCC High

| Setting | Value |
| --- | --- |
| **Microsoft sign-in base URL** | `https://login.microsoftonline.us` |
| **Microsoft Graph base URL** | `https://graph.microsoft.us` |
| **Microsoft Graph OAuth scope** | `https://graph.microsoft.us/.default` |
| **Defender for Endpoint API base URL** | `https://api-gov.securitycenter.microsoft.us` |
| **Defender for Endpoint API OAuth scope** | `https://api-gov.securitycenter.microsoft.us/.default` |

### DoD

| Setting | Value |
| --- | --- |
| **Microsoft sign-in base URL** | `https://login.microsoftonline.us` |
| **Microsoft Graph base URL** | `https://dod-graph.microsoft.us` |
| **Microsoft Graph OAuth scope** | `https://dod-graph.microsoft.us/.default` |
| **Defender for Endpoint API base URL** | `https://api-gov.securitycenter.microsoft.us` |
| **Defender for Endpoint API OAuth scope** | `https://api-gov.securitycenter.microsoft.us/.default` |

If you are not sure which environment your tenant is in, check with your
Microsoft administrator, and confirm the hosts in Microsoft's documentation
for Defender for Endpoint for US Government customers.

## Change it later

To change the client secret, the searches or the search window, open the
connector's row menu and choose **Edit**. Search changes apply from the next
run.

## If something goes wrong

| What you see | What it means |
| --- | --- |
| The connection test fails | The tenant ID, client ID or client secret is wrong. Check that you entered the secret's value, not its ID |
| Machines fail with a permission error | `Machine.Read.All` on **WindowsDefenderATP** was not granted, or admin consent was not given |
| Alerts fail with a permission error | `SecurityAlert.Read.All` on Microsoft Graph was not granted, or admin consent was not given |
| Searches fail with a permission error | `ThreatHunting.Read.All` on Microsoft Graph was not granted, or your Defender plan does not include advanced hunting |
| A search returns nothing | No device matched within the search window, or a term is misspelled. Process names must match the whole file name |
| Every request fails in a government cloud | The hosts under **Advanced** do not match your environment's values in the tables above. For example, the Defender API host was left on the commercial value in GCC, or a host was changed without its scope |
| Collection worked, then stopped | The client secret expired or was deleted. Create a new secret and enter it under **Edit** |

If a problem persists, contact Axiad support with the connector name and the
time of the failed collection.