HomeGuidesAPI ReferenceChangelog
Log In
Guides

Microsoft Defender

Microsoft Defender 365 & Microsoft Defender for Cloud CLI

This CLI integrates Microsoft 365 Defender recommendations and/or Microsoft Defender for Cloud alerts into RegScale as issues. (NOTE: 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

  1. Update your Azure keys in the init.yaml file with your actual keys.
  2. 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
  3. Adjust your desired number of maxThreads.
  4. 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 RegScale using a set number of days; if no days were used, the command defaults to 30 days.

  • 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.