# Set up Cortex XDR

Have your API URL and API key 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 Cortex XDR

Under **Guided setup**, choose **Palo Alto Cortex XDR**.

## Step 3 — Name it and enter your API URL

1. In **Display name for this connector**, give the connector a name. It
   appears in the connector list.
2. In **Cortex XDR API URL**, paste the URL you copied from **Settings ›
   Configurations › API Keys › Copy API URL** in Cortex XDR. Paste the whole
   URL, including `https://`.

The form also shows a collection preset, the field that begins **Collection
preset for Palo Alto Networks Cortex XDR**. 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 API key

| Field | What to enter |
| --- | --- |
| **API key** | The Standard API key from Cortex XDR. It is hidden as you type, and never shown again once saved |
| **API key ID** | The number shown next to the key in Cortex XDR's API key list |

Cortex XDR shows the key once, when it is created. If you no longer have it,
create a new key.

## Step 5 — Define your searches

This step is optional. Skip it if you only want endpoints and incidents.

1. Under **XQL 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 XQL for you from an event type
     and a list of terms. You need no query language.
   - **Custom (write your own XQL)** runs the XQL 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 names. A name must match the whole process image 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. Terms cannot contain
quotation marks or backslashes.

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 XQL

A custom search runs your query as written. For Mesh to tie each result to an
endpoint and an owner, return these Cortex XDR fields:

| Field | Used for |
| --- | --- |
| `agent_id` | The endpoint the match was found on |
| `agent_hostname` | The endpoint's name |
| `action_process_image_name` or `dns_query_name` | What matched |
| `actor_effective_username` | The account that ran it, which becomes the agent's owner |
| `_time` | When it was seen |

A result without these fields is still collected, but Mesh cannot attribute it
to an endpoint or owner.

## Step 6 — Set the search window

**XQL search window**, under **Advanced**, sets how far back each search looks, in hours (`h`) or
days (`d`) — for example `24h` or `7d`. It defaults to `24h`, which suits an
hourly schedule.

A custom query that starts with its own `config timeframe` stage keeps its own
window instead.

A longer window finds more, but makes a search more likely to reach its
1,000-row limit.

## Step 7 — Test the connection

Select **Test connection**. Mesh checks that it can reach Cortex XDR with your
API URL and key.

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 endpoints 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 search that finds nothing is not a failure. It means no endpoint ran a
matching process, or looked up a matching domain, within the search window.

## Change it later

To change the API key, 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 API URL, key or key ID is wrong, or the key has been revoked. Check all three. Check that the URL is the one Cortex XDR gave you, with `https://` |
| The test fails with an authentication error, and the details are right | The key is an Advanced key. Create a Standard key and enter it instead |
| Endpoints are collected, but searches fail | The API key cannot run XQL queries. Ask your Cortex XDR administrator to allow it |
| A search is flagged as reaching its limit | It matched more than 1,000 rows. Narrow its terms, shorten the search window, or split it into several searches |
| A search returns nothing | No endpoint matched within the search window, or a term is misspelled. Process names must match the whole name |
| A guided search is marked as invalid | A term contains a quotation mark or a backslash. Remove it |
| Collection worked, then stopped | The API key was revoked or expired in Cortex XDR. Create a new key and enter it under **Edit** |

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