Microsoft Defender

Microsoft Defender 365 & Microsoft Defender for Cloud CLI

This CLI integrates Microsoft 365 Defender recommendations, Microsoft 365 Defender alerts and/or Microsoft Defender for Cloud alerts into RegScale as issues.

📘
Each command has optional --regscale_id and --regscale_module to create issues as child items to the provided id and module in RegScale.
Requires release 4.16.0 or greater.

sync_365_alerts - pulls Alerts from Microsoft Defender 365 and will compare against existing RegScale issues and create issues for any new Microsoft Defender 365 alerts
sync_365_recommendations - pulls recommendations from Microsoft Defender 365 and will compare against existing RegScale issues and create issues for any new recommendations
sync_cloud_alerts - pulls recommendations from Microsoft Defender for Cloud and will compare against existing RegScale issues and create issues for any new alerts

Setup

See Azure integration for initial application configuration.

There are multiple pieces of information needed to configure the Defender integration via the CLI:

maxThreads - number of threads to use during the Defender recommendations and RegScale issue evaluation; default is 1000. (NOTE: Changing this number may have a positive or negative impact on performance.)
issues: {defender365: {high: 30, moderate: 90, low: 365, status: Open}}, {defenderCloud: {high: 30, moderate: 90, low: 365, status: Open}} - number of days to add to today's date when setting due dates to RegScale issues based on recommendation/alert severity and the status to use for a new RegScale issues

Defender Processing Workflow

Update your Azure keys in the init.yaml file with your actual keys.
Adjust the number of days for each severity for the RegScale due date along with the default status for the new RegScale issues.
- Status options: Draft, Open, Pending Decommission, Supply Chain/Procurement Dependency, Vendor Dependency for Fix, Delayed, or Exception/Waiver
Adjust your desired number of maxThreads.
Execute the command to retrieve and analyze the Defender recommendations.

Example Commands

Log into RegScale to set the token, which is good for 24 hours, and will secure all future RegScale API calls. (NOTE: You can skip this step if you are using a RegScale Service Account.)

regscale login

Query defender to pull in recommendations and/or alerts from Microsoft Defender 365 and alerts from Microsoft Defender for Cloud.

regscale defender sync_365_recommendations
regscale defender sync_365_alerts
regscale defender sync_cloud_alerts

init.yaml Example

The following init.yaml structure is necessary (example/notional key structure shown below, replace with actual customer keys):

domain: https://mycompany.regscale.com
token: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6IkpXVCJ9.eyJzdWIiOiJhYmVsYXJkbyJ9.b-ao0bpoc6CiJ3ygG8-XOk_gwn8BehAcuLGaPB6rlu8
maxThreads: 1000
azure365AccessToken: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJodHRwczovL2FwaS5zZWN1cml0eWNlbnRlci53aW5kb3dzLmNvbSIsImlzcyI6Imh0dHBzOi8vc3RzLndpbmRvd3MubmV0L2lkLyIsInZlciI6IjEuMCJ9
azure365ClientId: 013bf411-edf8-43b5-bbdd-62d433f1523a
azure365Secret: 1EC8~Azc-AU_86D72b4c01f..ab58_29cd752e~054e
azure365TenantId: 8ffee212-c550-42bd-abf5-4484c883f87a
azureCloudAccessToken: BearereyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ii1LSTNROW5OUjdiUm9meG1lWm9YcWJIWkdldyIsImtpZCI6Ii1LSTNROW5OUjdiUm9meG1lWm9YcWJIWkdldyJ9.eyJhdWQiOiJodHRwczovL21hbmFnZW1lbnQuYXp1cmUuY29tIiwiaXNzIj
azureCloudClientId: ewtNOaYO-j9Wu-CSNmX-xHhp-5KDUTc7LpSZ
azureCloudSecret: oNJ~6HCaD-YB_n3INNbt..BIhMd7mmZtj~3Irs
azureCloudTenantId: 6d12adab-a16e-48cf-94f5-bed0647d385f
azureCloudSubscriptionId: 9789544c-1e33-4de2-ac72-7f7727d56925
issues: 
  defender365:
    high: 30
    moderate: 90
    low: 365
    status: Open
  defenderCloud:
    high: 30
    moderate: 90
    low: 365
    status: Open

Building a Bash Script to Execute the CLI

You can execute RegScale CLI commands using scripts. These scripts could be in Bash, Python, PowerShell, etc. Below is an example Bash file (named regscaleDefenderRecommendations.sh) in Ubuntu for executing the CLI to pull Microsoft 365 Defender recommendations into RegScale as issues:

#!/bin/sh

# Retrieve any recommendations from Microsoft 365 Defender API and compare them to any existing RegScale
# issues. New recommendations will create new tickets and fixed recommendations will have their respective 
# RegScale issue closed.
regscale defender sync_365_recommendations

To execute the Bash file, run this command: /path/to/folder/regscaleDefenderRecommendations.sh. You can chain together any arbitrary set of CLI commands to have them execute sequentially.

Import Defender Data from a CVS file

We also support importing defender alerts from a cvs-based, Defender generated report. To import the alerts from a CVS-file, set up the issues setting as above and run:

regscale defender import_alerts --regscale_ssp_id <id of security plan> --folder_path <path to folder with defender csv files>

File Format

Below are the expected columns of a Defender file:

Header Name	Required
ASSESSMENTKEY
SUBASSESSMENTID	Yes
SUBASSESSMENTNAME	Yes
SUBASSESSMENTCATEGORY
SEVERITY	Yes
STATUS
CAUSE
STATUSDESCRIPTION
SUBASSESSMENTDESCRIPTION
SUBASSESSMENTREMEDIATION
SUBASSESSMENTIMPACT
DIGEST
NUMOFRESOURCES
TIMEGENERATED
ADDITIONALDATA
HIGH
MEDIUM
LOW
ALL

📘
NOTE: See All Scanner Integrations for information about how this updates Issues/POAMs

Microsoft Defender