;)
While investigating ways to automate adding, modifying, or removing Microsoft Defender for Cloud Apps (MDCA) policies, I could not locate any good Microsoft references. While researching the topic, I discovered a blog post discussing how to automate some MDCA rules within some policy types. This served as a starting point to investigate further automation of the MDCA policies. In addition, I discovered some of the REST API calls used to add, view, or modify MDCA policies through trial and error, which I used to create automated PowerShell functions to implement a consistent set of MDCA policies across our clients. This blog post will serve as a starting point for using the MDCA REST API.
Activate the API
First, make sure to activate the API in MDCA’s security extensions setting. Then, in the MDCA portal, click on the Gear icon, and select Security Extensions.
Under API tokens, select the Add token button. Type in a name for the token and select the Generate button. Copy the URL and API token now, as you will not have access to the token again. Select the Close button when you are finished. This token will appear in the API tokens list and can be revoked at any time. If using the Invoke-RestMethod command in PowerShell, include the token in your header as follows:
$headers = @{
"Authorization" = "Token abcdefghijklmnopqrstuvwxyz1234567890="
"Content-Type" = "application/json"
}Microsoft does include other methods of authentication which can be used in your automation, so I will link the article here.
Depending on the region, the URL copied might have the letters “us2” or “eu2” added to the address. Remove these letters when using the URL in your Invoke-RestMethod PowerShell command, or you will receive errors when executing the script, i.e., for the URL https://example.us2.portal.cloudappsecurity.com, use https://example.portal.cloudappsecurity.com instead.
Basic REST API Calls
Let us review the REST API calls:
GET https://<URL>/cas/api/v1/policies/ – This API lists all active policies on the tenant, and their ID, which will be required to get the policy information later. The JSON output will also show the number of active policies.
GET https://<URL>/cas/api/v1/policy/activity/ – This API is the activity log of the tenant’s MDCA. You can test this by adding a policy from a template, then review the API output. At the bottom of the JSON output should be your new policy. You can also review the settings of an edited policy or see if a policy has been deleted by checking the “deleted” attribute.
JSON Policy Breakdown
Here is an example of one of the policies in the output:
{
"_id": "627b9de8a0039f63881ce801",
"ref_policy_id": 308,
"actions": {
"0": [],
"11161": [],
"11114": [],
"11770": [],
"10489": []
},
"alertEmailRecipients": [],
"alertSeverity": "MEDIUM",
"alertSmsRecipients": [],
"anomalyDetection": {
"riskFactors": []
},
"bip_created": 1545748144000,
"consoleFilters": "{}",
"created": 1652268519991.5312,
"createdBy": "Builtin Policy",
"deletable": true,
"deleted": false,
"description": "This policy profiles your environment and triggers alerts when users perform multiple file sharing activities in a single session with respect to the baseline learned, which could indicate an attempted breach.",
"descriptionTemplate": "CONSOLE_POLICIES_BUILT_IN_POLICY_ANUBIS_UNUSUAL_ACTIVITY_SHARE_DESCRIPTION",
"detectionEngine": 1,
"editable": true,
"enableAlerts": true,
"enabled": true,
"isHidden": false,
"lastModified": 1652814616971.3586,
"lastModifiedBy": "Builtin Policy",
"name": "Unusual file share activity (by user)",
"nameTemplate": "CONSOLE_POLICIES_BUILT_IN_POLICY_ANUBIS_UNUSUAL_ACTIVITY_SHARE_NAME",
"policyId": 3,
"policyType": "ANOMALY_DETECTION",
"stories": [
0
],
"version": {
"full": "0.227.1",
"major": "0.227",
"minor": "1"
},
"ref_policy_created": 1545748144000,
"lastUserModified": 1652814616971.3586,
"matchesCount": 0,
"msFlowCheckboxChecked": false,
"msFlowId": null,
"perApp": true,
"readOnly": false,
"selectedRate": "all",
"templateId": "default",
"threshold": 5,
"windowSizeInMinutes": 30,
"editMode": true,
"story": 0
}This will be the template for adding, editing, or removing the policy “Unusual file share activity (by user).”
All policies are grouped into different Policy Types in the portal and are identified in the JSON output as the policyType attribute:
- ANOMALY_DETECTION – Anomaly detection policy
- ANOMALY_DISCOVERY – Cloud discovery anomaly detection policy
- APP_PERMISSION – OAuth app policy, OAuth app anomaly detection policy
- AUDIT – Activity policy
- FILE – File policy, Malware detection policy
- INLINE – Session Policy
- NEW_SERVICE – App discovery policy
API Call Samples (get policy data)
If we need to retrieve a single Activity policy, use the API call:
GET https://<URL>/cas/api/v1/policy/activity/<ID>/To retrieve an Anomaly detection policy:
GET https://<URL>/cas/api/v1/policy/anomaly/<ID>/To retrieve an App discovery policy:
GET https://<URL>/cas/api/v1/policy/discovery/<ID>/To retrieve a Cloud discovery anomaly detection policy:
GET https://<URL>/cas/api/v1/policy/discovery_anomaly/<ID>/To retrieve a File or Malware detection policy:
GET https://<URL>/cas/api/v1/policy/file/<ID>/To retrieve an OAuth app or OAuth app anomaly detection policy:
GET https://<URL>/cas/api/v1/policy/app_permissions/<ID>/And to retrieve a Session policy:
GET https://<URL>/cas/api/v1/policy/session/<ID>/Edit/Delete Policies
To edit individual policies, use the output from the activity log for the body of the API call and modify the required attributes. Then, use PUT instead of GET in your API call. I recommend configuring a test policy, gathering the output, and applying it to your automation. This is a more straightforward method than modifying the attributes manually.
Using our previous JSON output example, we would change the enabled attribute to false to disable the policy, copy the JSON with the changed attribute into the API body, and submit using PUT https://<URL>/cas/api/v1/policy/anomaly/627b9de8a0039f63881ce801/.
"editable": true,
"enableAlerts": true,
"enabled": false,
"isHidden": false,
"lastModified": 1652814616971.3586,When we inspect the web portal, the policy is disabled after refreshing the browser.
To delete a policy, edit, or verify, the attributes deletable and deleted are set to true. Not all policies may be deleted. The Malicious OAuth app consent policy is one policy during my testing that may only be set to disabled, even if the deletable attribute is set to true.
Construct the JSON Body to Add a Policy
We will use the JSON output as a template again to add a policy. This time, we will remove the _id attribute and modify the templateId attribute with “default” vice the numeric value. Change the name attribute to the new name of the policy. This will be the body of the API call.
WARNING! If you do not remove the _id attribute when creating the policy, it will create a second policy and show both policies in the portal. If you try to delete one of the two, it will delete, but the duplicate policy will remain in the portal. While the policy is not active, you will not be able to delete the duplicate since the _id is already marked as deleted. You will need to contact Microsoft to delete the duplicate.
{
"ref_policy_id": 308,
"actions": {
"0": [],
"11161": [],
"11114": [],
"11770": [],
"10489": []
},
"alertEmailRecipients": [],
"alertSeverity": "MEDIUM",
"alertSmsRecipients": [],
"anomalyDetection": {
"riskFactors": []
},
"bip_created": 1545748144000,
"consoleFilters": "{}",
"created": 1652268519991.5312,
"createdBy": "Builtin Policy",
"deletable": true,
"deleted": false,
"description": "This policy profiles your environment and triggers alerts when users perform multiple file sharing activities in a single session with respect to the baseline learned, which could indicate an attempted breach.",
"descriptionTemplate": "CONSOLE_POLICIES_BUILT_IN_POLICY_ANUBIS_UNUSUAL_ACTIVITY_SHARE_DESCRIPTION",
"detectionEngine": 1,
"editable": true,
"enableAlerts": true,
"enabled": true,
"isHidden": false,
"lastModified": 1652814616971.3586,
"lastModifiedBy": "Builtin Policy",
"name": "Test - Unusual file share activity (by user)",
"nameTemplate": "CONSOLE_POLICIES_BUILT_IN_POLICY_ANUBIS_UNUSUAL_ACTIVITY_SHARE_NAME",
"policyId": 3,
"policyType": "ANOMALY_DETECTION",
"stories": [
0
],
"version": {
"full": "0.227.1",
"major": "0.227",
"minor": "1"
},
"ref_policy_created": 1545748144000,
"lastUserModified": 1652814616971.3586,
"matchesCount": 0,
"msFlowCheckboxChecked": false,
"msFlowId": null,
"perApp": true,
"readOnly": false,
"selectedRate": "all",
"templateId": "default",
"threshold": 5,
"windowSizeInMinutes": 30,
"editMode": true,
"story": 0
}API Call Samples (Add a policy)
To add an Activity policy, use the API call:
POST https://<URL>/cas/api/v1/policy/activity/To add an Anomaly detection policy:
POST https://<URL>/cas/api/v1/policy/anomaly/To add an App discovery policy:
POST https://<URL>/cas/api/v1/policy/discovery/To add a Cloud discovery anomaly detection policy:
POST https://<URL>/cas/api/v1/policy/discovery_anomaly/To add a File or Malware detection policy:
POST https://<URL>/cas/api/v1/policy/file/To add an OAuth app or OAuth app anomaly detection policy:
POST https://<URL>/cas/api/v1/policy/app_permissions/And to add a Session policy:
POST https://<URL>/cas/api/v1/policy/session/To add the policy in our example, we would copy the modified JSON output into the API body and submit it using POST https://<URL>/cas/api/v1/policy/anomaly/.
Summary:
Microsoft should create official documentation to help automate MDCA policy tasks. However, these notes should help the community “fill in the blanks” by creating awesome automations!
