---
title: "Microsoft Defender Cloud Apps"
canonical: "https://docs.devo.com/space/latest/217251973/Microsoft%20Defender%20Cloud%20Apps"
format: markdown
---
> Macro (excerpt-include)



> Macro (toc)

## Purpose

An analyst wants to detect suspicious access to cloud applications. Using the [Microsoft Defender Cloud Apps](https://www.microsoft.com/en-us/security/business/microsoft-defender-cloud-apps) collector to send security events to Devo, the analyst will find unusual file downloads from cloud storage services. As a result, the analyst will isolate the compromised user accounts, preventing data exfiltration.

## Example tables

| **Table** | **Description** |
| --- | --- |
| `casb.microsoft_defender.cloud_apps.activities` | User activity logs from cloud applications |
| `casb.microsoft_defender.cloud_apps.alerts` | Security alerts for suspicious behavior |
| `casb.microsoft_defender.cloud_apps.entities` | Information about users and accounts |
| `casb.microsoft_defender.cloud_apps.data_enrichment` | IP address range information |
| `casb.microsoft_defender.cloud_apps.files` | Metadata about files stored in cloud apps |

## Authorize it

1. Go to **Microsoft Defender for Cloud Apps** portal.
2. Create an account or sign in if you already have one.
3. Sign in to [Microsoft Azure](https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize?redirect_uri=https%3A%2F%2Fportal.azure.com%2Fsignin%2Findex%2F&response_type=code%20id_token&scope=https%3A%2F%2Fmanagement.core.windows.net%2F%2Fuser_impersonation%20openid%20email%20profile&state=OpenIdConnect.AuthenticationProperties%3D2ThIR1WASQoeqkAWJoy1TEVz7FiG0hJaVnAfChKqR7dCrE7NYY3dKMsBdjHK8dSXSGNxILLptBWj7VxRKN6BUejRLsuzdWU-atfBvN6YjeCttShtBYKaHB4vkkAbZCpRu-QqfruuTuJzoYP6jOTXvq_r0seVCuTE6yZOEvgXqHgOzo6UsmDErsPSj4hVmifmntR-ZWukYMCiKHxvXylmNPxHf2MGKgYcso5ga0cHXjER7xSM7qXF2pX8XjRvK7g8H7MuVP2rt3br06vJSUFastQiZdUQ6gaitV6Zu2Xy1W33YC-pFslIO2oXyBEJ9AXTUoKtj4Is6fUYvV_NUFbJkz2lTj0YltA8VVA0UDppIrY_OGyAKwuF4KmGtwD-oub4cx1cfC2RKcuzPs62Lfudo-OXLDdgWbQaOjG5mncjC1dH-WgNQFfwwnvEJHN2KncN-anpRSkWijH8VJlLbw2hJKsMgPVkJMBXFo4PEYkK91o&response_mode=form_post&nonce=638034946245255947.MmMwMzU4YTctMzc3Zi00NzYwLWFlNDMtMjQ2MGRiZWJmZTZjODAwNTM2ZTAtODE5OS00MTFkLTk3ZDgtMGIzMjBjMjM1MDJl&client_id=c44b4083-3bb0-49c1-b47d-974e53cbdf3c&site_id=501430&client-request-id=a8e15d31-2093-4ad3-98f5-5a96de058086&x-client-SKU=ID_NET472&x-client-ver=6.22.1.0&sso_reload=true) using the same credentials you used for Microsoft Defender for Cloud Apps portal.
4. Search for **"App registrations"** in the search bar and click it. Click on **"New Registration" **button.

![image](media://e033235f-f286-4ba0-b643-ca53cc3ad88a)

5. Give a name to your app and click on the **"Register"** button.

![image](media://18c7f6c4-4710-444c-b80e-bb0f4e173205)

6. In the **"Overview"** section, note your **Client ID** and other necessary IDs.

![image](media://f852da6f-6e9d-4de9-852a-2aba8ad31b2b)

7. **Go to "API permissions"** and click **"Add permissions"** button:

The below screenshot shows only `Investigation.read` permission as an example. For other permission scopes, see <u>[Supported permission scopes](https://learn.microsoft.com/en-us/defender-cloud-apps/api-authentication-application#supported-permission-scopes)</u>

![image](media://42536935-baa5-4411-9f8a-5727067ad52a)

8. Select** "APIs my organization uses" **and search for **"Defender for Cloud Apps"**.
9. Select **"Application permissions"** and enable read permissions for the API (*Investigation.Read*, *Discovery.read*, *Settings.read*).

![image](media://2a72794d-1b98-42d3-a74f-17a00a20bd0e)

![image](media://7c69bad5-bfec-42e1-a878-a58733e903dc)

10. Go to **"Certificates & secrets"** and create a new **client secret**.

![image](media://cd4005d5-85ab-4408-89fb-799302925d69)

11. Copy the generated secret value immediately as it will only be shown once.

![image](media://aa0907c1-9793-49fa-8df5-f21d50992bfb)

## Run it

In the Cloud Collector App, [create](https://devodocs.atlassian.net/wiki/spaces/latest/pages/409305131) a **Microsoft Defender Cloud Apps** collector instance.  Insert this parameters template, replacing the values enclosed in `< >`.  The `id` must be a unique [five digit number](https://www.random.org/integers/?num=1&min=10000&max=99999&col=5&base=10&format=html&rnd=new).

```

  "inputs": {
    "microsoft_defender_cloud_apps_collector_input": {
      "id": "<FIVE_UNIQUE_DIGITS>",
      "enabled": true,
      "api_base_url": "<API_BASE_URL>",
      "token_url": "<TOKEN_URL>",
      
      "services": {
       "files": {
           "historic_date_utc": "<HISTORIC_DATE_UTC_VALUE>",
          "request_period_in_seconds": "<REQUEST_PERIOD_IN_SECONDS>",
          "filters": "<FILTER_LIST>"
      },
      "credentials": {
        "tenant_id": "<TENANT_ID>",
        "client_id": "<CLIENT_ID>",
        "client_secret": "<CLIENT_SECRET>",
        "files_access_token": "<FILES_ACCESS_TOKEN>"
      }
    }
  }
}
```


## Monitor it

Create an [inactivity alert](https://devodocs.atlassian.net/wiki/spaces/latest/pages/95126785) to detect interruptions of transfer of data from the source  using the query

```
from casb.microsoft_defender.cloud_apps.activities
where toktains(hostchain,"collector-") 
select split(hostchain,"-",1) as collector_id
```

Set the inactivity alert to keep track of the `collector_id`.

## Parameters

### Example

```
{
  "global_overrides": {
    "debug": "<enable_debug_logs>"
  },
  "inputs": {
    "microsoft_defender_cloud_apps_collector_input": {
      "id": "<short_unique_id>",
      "enabled": true,
      "api_base_url": "<api_base_url>",
      "token_url": "<token_url>",
      "credentials": {
        "tenant_id": "<tenant_id>",
        "client_id": "<client_id>",
        "client_secret": "<client_secret>",
        "files_access_token": "<files_access_token>"
      },
      "services": {
        "activities": {
          "historic_date_utc": "<historic_date_utc_value>",
          "request_period_in_seconds": "<request_period_in_seconds>",
          "override_limit_data_per_request": "<override_limit_data_per_request_value>",
          "filters": "<filter_list>"
        },
        "alerts": {
           "historic_date_utc": "<historic_date_utc_value>",
          "request_period_in_seconds": "<request_period_in_seconds>",
          "override_limit_data_per_request": "<override_limit_data_per_request_value>",
          "filters": "<filter_list>",
          "flatten_entities": "<boolean>"
        },
        "entities": {
           "historic_date_utc": "<historic_date_utc_value>",
          "request_period_in_seconds": "<request_period_in_seconds>",
          "override_limit_data_per_request": "<override_limit_data_per_request_value>",
          "filters": "<filter_list>"
        },
        "data_enrichment": {
           "historic_date_utc": "<historic_date_utc_value>",
          "request_period_in_seconds": "<request_period_in_seconds>",
          "override_limit_data_per_request": "<override_limit_data_per_request_value>",
          "filters": "<filter_list>"
        },
        "files": {
           "historic_date_utc": "<historic_date_utc_value>",
          "request_period_in_seconds": "<request_period_in_seconds>",
          "override_limit_data_per_request": "<override_limit_data_per_request_value>",
          "filters": "<filter_list>"
        }
      }
    }
  }
}
```

### Details

|  |  |  |  |
| --- | --- | --- | --- |
| **Parameter** | **Data Type** | **Necessity** | **Details** |
| `enable_debug_logs` | `boolean` | `Mandatory` | This will make the collector generate  (or not) log messages with the DEBUG level. Format: `true`/`false` |
| `id` | `integer` | `Mandatory` | Use this param to give a **unique** ID to this input service. |
| `api_base_url` | `string` | `Mandatory` | This parameter is the URL of the CloudApps instance. It is usually <u>[https://portal.cloudappsecurity.com/.](https://portal.cloudappsecurity.com/)</u> |
| `token_url` | `string` | `Mandatory` | Set up here your access token created in the CloudApps console. It is usually <u>[https://login.microsoftonline.com/.](https://login.microsoftonline.com/)</u> |
| `tenant_id` | `string` | `Mandatory` | Set up here your tenant id created in the CloudApps console. |
| `client_id` | `string` | `Mandatory` | Set up here your client id created in the CloudApps console. |
| `client_secret` | `string` | `Mandatory` | Set up here your client secret created in the CloudApps console. |
| `access_token` | `string` | `Mandatory only for files service` | Only for **Files** service. |
| `historic_date_utc` | `string` | `Optional` | This configuration allows you to set a custom date as the beginning of the period to download. This allows downloading historical data (1 month back for example) before downloading new events. Format: `%Y-%m-%d %H:%M:%S` |
| `limit_data_per_request` | `integer` | `Optional` | The limit of data to be retrieved for each request. The default value is 100. |
| `devo_tag` | `string` | `Optional` | This parameter allows to define a custom devo tag. |
| `filter_list` | `list` | `Optional` | The list with the custom filters to retrieve the data which have the following structure:<br>```

"filters": [
  {
    "filter_by": "<entity_name>",
    "operator": "<operator_name>",
    "values": [
      "<value_1>",
      "<value_2>"
    ]
  },
  {
    "filter_by": "<entity_name_2>",
    "operator": "<operator_name>",
    "value": "<single_value>"
  }
]
```<br>Example:<br>```

"filters": [
  {
    "filter_by": "entity.service",
    "operator": "neq",
    "value": "example1234"
  },
  {
    "filter_by": "severity",
    "operator": "eq",
    "values": [
      2,
      0
    ]
  }
]
```<br>Do not apply the `data` filter because it is already applied automatically. |
| `flatten_entities` | `boolean` | `Mandatory` | This parameter applies only to the Alerts service. Set to True to flatten alerts.<br>Format: `true`/`false` |
| `requests_per_second` | `integer` | `Optional` | Customize the maximum number of API requests per second. If not used, the default setting will be used: `100000` requests/sec. |
| `request_period_in_seconds` | `integer` | `Optional` | Period in seconds used between each data pulling, this value will overwrite the default value (60 seconds). |

## Troubleshooting

This collector has different security layers that detect both an invalid configuration and abnormal operation. This table will help you detect and resolve the most common errors.

| **Error type** | **Error ID** | **Error message** | **Cause** | **Solution** |
| --- | --- | --- | --- | --- |
| SetupError | `100` | `The remote data is not pullable with the given credentials. Check the error traces for details.` | This error is raised when remote data cannot be accessed with current credentials. | Check that the credentials are correct and that they have the necessary permissions. |
| `101` | `The token/header/authentication was refreshed but is still expired. Check the error traces for details.` | This error is raised when the token cannot be refreshed. | Check that the credentials are correct and contact the internal team if the problem persists. |
| `101` | `access token has expired or invalid. status code: 401. Error message: response.text` | This error is raised when the credentials does not have sufficient permissions to access the data. | Give the credentials the correct permissions to access the data. |
| `102` | `The provided credentials are valid but they do not have the permission to generate access token. status code: 403. Error message: response.text` | This error is raised when the access token does not have sufficient permissions to access the data. | Give the token the correct permissions to access the data. |
| `103` | `Unexpected error occurred at the Microsoft Defender for Cloud Apps server. status code: response.status_code. Error message: response.text` | This error is raised when an unexpected and unknown error occurs in Microsoft Defender Cloud Apps | Contact with Devo Support team. |
| InitVariablesError | `0` | `The internal config did not pass the format validation. Contact Devo Support.` | This error is raised when the `collector_definitions.yaml `does not comply with the json schema validation. | This is an internal issue. Contact with Devo Support team. |
| `1` | `The user config did not pass the format validation. Check error traces for details and visit our documentation.` | This error is raised when the user configuration information does not comply with the json schema validation. | Check in the collector documentation what are the allowed parameters and their formats. |
| `2` | `rate_limiter setting has been defined with wrong type.'Expected dict but received {type(rate_limiter_config)` | This error is raised when the required `rate_limiter `property in the `collector_definitions.yaml` is not a dictionary. | This is an internal issue. Contact with Devo Support team. |
| `3` | `The user config did not pass the format validation. Check error traces for details and visit our documentation.` | This error is raised when the user configuration information does not comply with the json schema validation. | Check in the collector documentation what are the allowed parameters and their formats. |
| PullError | `300` | `Error occurred while retrieving data from Microsoft Defender for Cloud Apps server. Error details: str(e)` | This error is raised when when an unknown error occurs in the Microsoft Defender Cloud Apps request. | This is an internal issue. Contact with Devo Support team. |
| `301` | `Error in the filters : response.json()` | This error is raised when the filters are not in the correct format. | The error description indicates if there are disallowed elements in the filter. Review the Microsoft Defender CloudApps API documentation for the correct format of filters. |
| `302` | `access token has expired or invalid. status code: 401. Error message: response.json()` | This error is raised when the credentials does not have sufficient permissions to access the data. | Give the credentials the correct permissions to access the data. |
| `303` | `The access token does not have valid permissions to perform this request. Add the required permissions in the Microsoft Defender for Cloud Apps azure portal (Azure Active Directory - App registration - select the register app - API Permission) status code: 403. Error message: response.json()` | This error is raised when the access token does not have sufficient permissions to access the data. | Give the token the correct permissions to access the data. |
| `304` | `The resource requested is not found. Resource Url: base_url + endpoint_url `  
`fstatus code: 404. Error message: response.json()` | This error is raised when the requested resource is not found. | This is an internal issue. Contact with Devo Support team. |
| `305` | `Unexpected error occurred at the Microsoft Defender for Cloud Apps server. status code: response.status_code. Error message: response.json()` | This error is raised when when an unknown error occurs in the Microsoft Defender Cloud Apps request. | This is an internal issue. Contact with Devo Support team. |

## API Endpoints

| **API endpoint** | **Collector service name** | **Devo table** |
| --- | --- | --- |
| `/api/v1/activities/` | `activities` | `casb.microsoft_defender.cloud_apps.activities` |
| `/api/v1/alerts/` | `alerts` | `casb.microsoft_defender.cloud_apps.alerts` |
| `/api/v1/entities/` | `entities` | `casb.microsoft_defender.cloud_apps.entities` |
| `/api/v1/subnet/` | `data_enrichment` | `casb.microsoft_defender.cloud_apps.data_enrichment` |
| `/api/v1/files/` | `files` | `casb.microsoft_defender.cloud_apps.files` |

## Devo collector features

| **Feature** | **Details** |
| --- | --- |
| Allow parallel downloading (`multipod`) | `Not allowed` |
| Running environments | `Collector server` |
| Populated Devo events | `Table` |
| Flattening preprocessing | `Yes` |

## Release Notes

- **Version 1.5.0 **(2025-06-03)
  - The DCSDK Docker base image has been updated from "1.3.1" to "1.5.1"
  - The DevoCollectorSDK Python package (devo-collector-sdk) has been updated from "1.13.1" to "1.16.2"
  - Updated default request_period_in_seconds value to 21600 for entities and data_enrichment services
  - Fixed duplicate files fetching issue by saving modifiedDate in persistence
- **Version 1.4.0** (2024-10-29)
  - Upgraded SDK image base and DCSDK, improved queue management and controlled stop processes.
  - Fixed issue with files service not working.
- **Version 1.3.0 **(2023-02-05)
  - Upgraded SDK image base.
  - Fixed issues with persistence reset and duplicated events, modified pull logic to use request_period_in_seconds parameter.
- **Version 1.2.0 **(2023-01-12)
  - Updated API limits, upgraded DCSDK with input metrics and output metrics, standardized exception messages.
  - Removed old rate_limiter parameter, fixed prepull reset steps.
- **Version 1.1.1 **(2023-09-20)
  - Set request limits using schemas.
- **Version 1.1.0** (2023-09-04)
  - Major DCSDK upgrade with numerous enhancements including persistence management, queue handling, and telemetry.
- **Version 1.0.0 **(2022-10-28)
  - Initial release with Activities, Alerts, Entities, Data Enrichment, and Files services.