| 1 | # [Defender For Endpoint Integration](https://learn.microsoft.com/en-us/defender-endpoint/api/get-alerts) |
| 2 | |
| 3 | ## Prerequisites |
| 4 | |
| 5 | Before using the Defender For Endpoint SIEM Connector, you’ll want to first define the API client and set its scope. Refer to this guide (https://learn.microsoft.com/en-us/defender-endpoint/api/get-alerts) to getting access to the Defender For Endpoint API for setting up a new API client key. For the new API client, make sure the scope includes access for `Alert.Read.All` and `Alert.ReadWrite.All`. |
| 6 | |
| 7 | ### IMPORTANT: Make sure your API has the below configred roles: |
| 8 | |
| 9 | `Alert.Read.All, Alert.ReadWrite.All` |
| 10 | |
| 11 |  |
| 12 | |
| 13 | ## Configuration |
| 14 | |
| 15 | The configuration for our API creds and syslog forwarder settings are stored within `/usr/share/filebeat/filebeat.yml`. Adjust to make your changes. **NOTE that the `tenant_id` , `cliend_id` , `client_secret` , `syslog_port`, and `syslog_host` will need to be updated.** Below is an example, CoPilot will take care of this for you. |
| 16 | |
| 17 | ```yaml |
| 18 | filebeat.modules: |
| 19 | - module: microsoft |
| 20 | defender_atp: |
| 21 | enabled: true |
| 22 | var.oauth2.client.id: "CLIENT_ID" |
| 23 | var.oauth2.client.secret: "CLIENT_SECRET" |
| 24 | var.oauth2.token_url: "https://login.microsoftonline.com/TENANT_ID/oauth2/token" |
| 25 | |
| 26 | filebeat.inputs: |
| 27 | - type: log |
| 28 | enabled: false |
| 29 | paths: |
| 30 | - /var/log/*.log |
| 31 | |
| 32 | output.logstash: |
| 33 | hosts: ["REPLACE_SYSLOG_HOST:REPLACE_SYSLOG_PORT"] |
| 34 | ``` |
| 35 | |
| 36 | ## Provisioning |
| 37 | |
| 38 | Once you have saved the Defender For Endpoint configuration for the customer, you are ready to deploy the integration. Navigate to the `Customers` tab and select the appropriate customer. The provisiong creates the necessary: |
| 39 | |
| 40 | - Graylog CEF Input |
| 41 | - Graylog Stream |
| 42 | - Graylog Index |
| 43 | - Grafana Datasource |
| 44 | - Grafana Dashboards |
| 45 | - Defender For Endpoint Docker-Compose File |
| 46 | |
| 47 | ## Deployment of Defender For Endpoint Container |
| 48 | |
| 49 | The Defender For Endpoint integration runs via a docker container. During provisioning, the following directory is created `/opt/CoPilot/data/data/CUSTOMER_NAME`. Within this directory will reside the `CUSTOMER_NAME_docker-compose-defender-for-endpoint.yml` and the `filebeat.yml` files. These can be modified if desired but should already contain the details needed to collect logs for their Defender For Endpoint environment. |
| 50 | |
| 51 | Start the container with the below command: |
| 52 | |
| 53 | ```bash |
| 54 | docker compose -f /opt/CoPilot/data/data/CUSTOMER_NAME/CUSTOMER_NAME_docker-compose-defender-for-endpoint.yml up -d |
| 55 | ``` |
| 56 | |
| 57 | You should now see the container running. |