# Microsoft Sentinel Integration

Integrate TrapEye with Microsoft Sentinel via the **Logs Ingestion API** to forward threats and interactions in real-time - without syslog and Azure Monitor Agent (AMA) overhead.

---

The steps required to configure the Logs ingestion API are as follows:

- Create a Microsoft Entra application to authenticate against the API
- Create the Data Collection Endpoint to receive data (DCE)
- Create two custom tables in a Log Analytics Workspace to store TrapEye **threats** and **interactions** events
- Configure the Sentinel connector in TrapEye
- Test the log flow by sending sample events from TrapEye to Sentinel

---

## Create Microsoft Entra application

1. On the **Microsoft Entra ID** menu in the Azure portal, select **App registrations > New registration**.

   ![Create App](~/assets/images/docs/integrations/sentinel/app-create.webp)

2. Choose a `Name` for your application. The Redirect URI is not needed for this integration.

   ![Set App Name](~/assets/images/docs/integrations/sentinel/app-naming.webp)

    Then click **Register** to create the application.

3. In the **Overview** section, you can view the details of the application. 

   Note the `Application (client) ID` and the `Directory (tenant) ID`. You will need these values later.

    ![Overview menu](~/assets/images/docs/integrations/sentinel/app-get-ids.webp)

4. Select **Certificates & secrets > New client secret**. Give the secret a name to identify its purpose and select an Expires duration. 

   ![Set Client Secret](~/assets/images/docs/integrations/sentinel/app-secret.webp)

5. Copy the generated secret `Value` immediately, it will no longer be visible once you navigate away from this page.

   ![Copy Client Secret](~/assets/images/docs/integrations/sentinel/app-copy-secret.webp)

---

## Create Data Collection Endpoint (DCE)

A [Data Collection Endpoint](https://learn.microsoft.com/en-us/azure/azure-monitor/data-collection/data-collection-endpoint-overview) is required to ingest logs via HTTP. After you configure the DCE and link it to a Data Collection Rule (DCR), you will be able to receive events in real-time. 

1. In the [Azure Portal](https://portal.azure.com/), navigate to **Subscriptions > Resource providers** and verify that `Microsoft.Insights` is registered. If not registered, select it and click on **Register**.

   ![Register Microsoft.Insights](~/assets/images/docs/integrations/sentinel/dce-insights.webp)

2. Navigate to **Azure Monitor > Data Collection Endpoints** and click on **Create**.

   ![Create DCE](~/assets/images/docs/integrations/sentinel/dce-create.webp)

3. Specify an `Endpoint Name`, a `Resource Group` and a `Region`.

**Caution:** The DCE must be located **in the same region** as the Log Analytics workspace to which events are sent.

    ![DCE Config](~/assets/images/docs/integrations/sentinel/dce-config.webp)

4. After the DCE is created, from the **Overview** page, copy the `Logs Ingestion Endpoint URL` value, you will need this value in the TrapEye configuration step.

   ![DCE Overview](~/assets/images/docs/integrations/sentinel/dce-overview.webp)

## Create Tables in Log Analytics workspace

To store TrapEye events in Sentinel, you need to create two custom tables in your Log Analytics workspace: one for **threats** and another for **interactions**.

1. In the [Azure Portal](https://portal.azure.com/), navigate to **Log Analytics workspaces** and select your workspace.

   Click on **Tables > Create**.

    ![Create Table](~/assets/images/docs/integrations/sentinel/table-create.webp)

2. Specify a `Table Name` (e.g., `TrapEye_Threats`), set the `Table Plan` to `Analytics`.

   For the **Data Collection Rule (DCR)**, select `Create new data collection rule` and choose a name for the DCR (e.g., `TrapEye-dcr`).

    For the **Data Collection Endpoint (DCE)**, select the DCE you created in the previous step.

    ![Configure Table](~/assets/images/docs/integrations/sentinel/table-config.webp)

3. Download a sample **threat JSON event** from the [TrapEye Event Schema documentation](/docs/integrations/event-schema/#example-threat-event) and upload it in the **Sample Data** section. This will allow Sentinel to automatically infer the table schema based on the event structure.
   
   ![Upload Sample](~/assets/images/docs/integrations/sentinel/table-upload.webp)
    
4. Click on **Transformation editor** and paste the following Kusto Query Language (KQL) code to extract relevant fields from the JSON event and create a structured table:
   ```
    source
    | where event_type == "new_threat"
    | extend 
        TimeGenerated = todatetime(first_interaction),
        Product = tostring(['@meta'].product),
        Vendor = tostring(['@meta'].vendor)
    | project-away ['@meta']
    ```

    ![Transformation Editor](~/assets/images/docs/integrations/sentinel/table-test-transform.webp)

    **Run** the query to verify the results. Then click on **Apply** to save the transformation and create the table.

5. Repeat the process to create the **interactions** table.

   - Use the same **DCR** and **DCE** as the threats table.
    - Upload a sample **interaction JSON event** available [here](/docs/integrations/event-schema/#example-interaction-event).
    - Use the following KQL code in the transformation editor:
        ```
        source
        | where event_type == "new_interaction"
        | extend 
            TimeGenerated = todatetime(timestamp),
            Product = tostring(['@meta'].product),
            Vendor = tostring(['@meta'].vendor)
        | project-away ['@meta']
        ```
    
6. After both tables are created, navigate to the **Data Collection Rules** page. 

   From the **Overview** menu, copy the `Immutable ID` value, you will need this value later.

    ![DCR Overview](~/assets/images/docs/integrations/sentinel/dcr-overview.webp)

7. Navigate to the **Access Control (IAM)** section to assign permissions to the Microsoft Entra application created in the first step.
   
   ![Add Role](~/assets/images/docs/integrations/sentinel/dcr-role-add.webp)

    Click on **Add role assignment**.

8. Search for the role `Monitoring Metrics Publisher`, select it and click **Next**.

   ![Config Role](~/assets/images/docs/integrations/sentinel/dcr-role-config.webp)

9. In the new page, select **User, group, or service principal** and search for the name of the Microsoft Entra application created in the first step. Select it and confirm the role assignment.

   ![Assign Access to App](~/assets/images/docs/integrations/sentinel/dcr-assign-access.webp)

**Caution:** Allow at least 30 minutes for the configuration to take effect inside Azure.
## Configure the Sentinel Connector in TrapEye

1. Log in to the [TrapEye Portal](https://trapeye.anantis.io)

2. Navigate to **Settings → Integrations** and select the **JSON over HTTP** card.

   - Enable **JSON over HTTP Connector**.
    - Choose the **Microsoft Sentinel** tab. 
    - For the **Data Collection Endpoint URL** field, please use the following format with the two values copied earlier:

        - `DCE LogsIngestion Endpoint URL`
        - `DCR ImmutableId`

            ```
            <DCE LogsIngestion Endpoint URL>/dataCollectionRules/<DCR ImmutableId>/streams/
            ```
    - For the **Table Name** fields, enter the names of the tables with the suffix `_CL` (custom log). For example, if your table is named `TrapEye_Threats`, enter `TrapEye_Threats_CL`.
    - Enter the `Directory (tenant) ID`, `Application (client) ID` and `Client Secret` values from the **Microsoft Entra application** created in the first step.

    ![Configure TrapEye](~/assets/images/docs/integrations/sentinel/trapeye-config.webp)

    - Click **Save Changes** to apply the configuration.

## Test the Log Flow

With the connector enabled, click **Test Connection** in TrapEye.

**Caution:** If there is an error, please allow at least 30 minutes for the previous role assignment to take effect inside Azure.

    If the issue persists after 1 hour, verify that all values entered in the configuration are correct, especially the `DCE URL`, `DCR ImmutableId` and `table names`.

    If needed, let's troubleshoot together! Send us an email at support@anantis.io.

Once the test event is sent successfully, navigate to your Log Analytics workspace in the Azure portal and run the following KQL queries to verify that events are received:

**Threats table:**
```kql
YourThreatsTableName_CL
```

**Interactions table:**
```kql
YourInteractionsTableName_CL
```

![Event Received](~/assets/images/docs/integrations/sentinel/test-kql.webp)

**Tip:** The first time events are ingested into the tables, it may take up to 10 minutes for Azure to index them and for the events to appear in search results.

    The `DCRLogErrors` table can be queried to check for any errors related to the DCR configuration and data ingestion:

    ```kql
    DCRLogErrors
    | where TimeGenerated > ago(1h)
    ```

## Optional: Create Analytics Rules

Analytics rules allow you to automatically correlate TrapEye threats with Microsoft Sentinel incidents, and trigger automated response playbooks.

1. In the [Microsoft Defender portal](https://security.microsoft.com), navigate to **Microsoft Sentinel → Analytics** and click on **Create → Scheduled query rule**.

   ![Create Analytics Rule](~/assets/images/docs/integrations/sentinel/create_rule.webp)

2. Set a `Name` for the rule and choose an appropriate `Severity` level. 

   For the `MITRE ATT&CK` technique mapping, you can select:

    - Reconnaissance
    - Credential Access
    - Discovery
    - Lateral Movement

    ![Set Rule Name and Severity](~/assets/images/docs/integrations/sentinel/config_rule1.webp)

3. In the **Set rule logic → Rule query** section, use the following KQL query as a base to create the logic for the rule:

   ```kql
    YourThreatsTableName_CL
    ``` 

    In the **Alert enhancement → Entity mapping** section:
        - Map the `source_ip` field to the **IP Address** entity.
        - Map the `reverse_lookup` field to the **DomainName** entity.
    
    ![Set Rule Logic](~/assets/images/docs/integrations/sentinel/config_rule2.webp)

4. In the **Alert enhancement → Custom details** section, create two key-value pairs:

   - Key 1: `threat_uuid` / Value 1: `threat_uuid`
    - Key 2: `source_ip` / Value 2: `source_ip`

    ![Set custom details](~/assets/images/docs/integrations/sentinel/config_rule3.webp)

5. In the **Alert enhancement → Alert details** section, enrich the alert with contextual data by populating the name and description fields using the **Custom details** defined in the previous step.

   In the `Alert Name Format` field:

    ```
    New TrapEye Threat from {{source_ip}}
    ```

    In the `Alert Description Format` field:
    ```
    To investigate related interactions, run:

    YourInteractionsTableName_CL
    | where threat_uuid == '{{threat_uuid}}'
    | order by TimeGenerated desc
    ```
    ![Set alert details](~/assets/images/docs/integrations/sentinel/config_rule4.webp)

6. In the **Query scheduling** section, set the frequency and lookback period for the rule.
   - Run query every: `5 minutes`
    - Lookup data from the last: `5 minutes`
    - Start running: `Automatically`

7. In the **Event grouping** section, select `Trigger an alert for each event`.

8. In the **Incident settings** section:
   - Enable `Create incidents from alerts triggered by this analytics rule`.
    - Disable **Alert grouping**.

9. Optionally, assign an **Automated response** playbook to trigger remediation actions when an incident is created. Click **Create** to save the rule.
## Setup Complete

TrapEye platform is now fully integrated with Microsoft Sentinel.