HomeGuidesAPI ReferenceChangelog
Guides

Microsoft Defender

Microsoft Defender 365, Microsoft Defender for Cloud & Azure Entra CLI

This CLI integrates Microsoft 365 Defender recommendations, Microsoft 365 Defender alerts, Microsoft Defender for Cloud alerts/recommendations, and Azure Entra evidence into RegScale.

📘

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.

Commands

Authentication

  • authenticate - Obtains an access token using the credentials provided in init.yaml for the specified system (cloud, 365, or entra)

Microsoft Defender 365 Commands

  • 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

Microsoft Defender for Cloud Commands

  • sync_cloud_alerts - pulls alerts from Microsoft Defender for Cloud and will compare against existing RegScale issues and create issues for any new alerts
  • sync_cloud_recommendations - pulls recommendations from Microsoft Defender for Cloud and will compare against existing RegScale issues and create issues for any new recommendations
  • sync_cloud_resources - pulls resources from Microsoft Defender for Cloud and creates RegScale assets with the information from Microsoft Defender for Cloud. Requires either --regscale_ssp_id or --component_id
  • export_resources - exports data from Microsoft Defender for Cloud resource graph queries and saves them to CSV files. Can export specific queries by name or all saved queries

Azure Entra Commands

  • collect_entra_evidence - collects Azure Entra evidence for FedRAMP compliance controls and uploads to RegScale. Supports collection of:
    • Users & Groups Management
    • Role-Based Access Control & Privileged Identity Management
    • Conditional Access Policies
    • Authentication Methods & Multi-Factor Authentication
    • Audit & Sign-in Logs
    • Access Reviews & Governance
  • show_entra_mappings - displays which FedRAMP controls are mapped to each Azure Entra evidence type

Data Import Commands

  • import_alerts - imports Microsoft Defender alerts from CSV files

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

Authentication

Authenticate with the desired system to obtain access tokens:

regscale defender authenticate --system cloud
regscale defender authenticate --system 365
regscale defender authenticate --system entra

RegScale Login

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

Microsoft Defender 365 Sync

Query defender to pull in recommendations and/or alerts from Microsoft Defender 365:

regscale defender sync_365_recommendations
regscale defender sync_365_alerts

Microsoft Defender for Cloud Sync

Query defender to pull in alerts and recommendations from Microsoft Defender for Cloud:

regscale defender sync_cloud_alerts
regscale defender sync_cloud_recommendations

Cloud Resources Management

Sync Azure cloud resources to RegScale assets:

# Sync to a Security System Plan
regscale defender sync_cloud_resources --regscale_ssp_id 123

# Sync to a Component
regscale defender sync_cloud_resources --component_id 456

Export Resource Graph Queries

Export data from saved Azure Resource Graph queries:

# Export a specific query by name
regscale defender export_resources --regscale_id 5 --regscale_module securityplans --query_name "MyQuery"

# Export all saved queries
regscale defender export_resources --regscale_id 5 --regscale_module securityplans --all_queries

# Export without uploading to RegScale
regscale defender export_resources --regscale_id 5 --regscale_module securityplans --query_name "MyQuery" --no_upload

Azure Entra Evidence Collection

Collect Azure Entra evidence for FedRAMP compliance:

# Collect all evidence types (default 30 days back)
regscale defender collect_entra_evidence --regscale_ssp_id 123

# Collect specific evidence type with custom date range
regscale defender collect_entra_evidence --regscale_ssp_id 123 --evidence_type users_groups --days_back 90

# Evidence type options: all, users_groups, rbac_pim, conditional_access, authentication, audit_logs, access_reviews

View Azure Entra FedRAMP Control Mappings

Display which FedRAMP controls are mapped to Azure Entra evidence:

# Show all mappings
regscale defender show_entra_mappings

# Show mappings for specific evidence type
regscale defender show_entra_mappings --evidence_type authentication

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

# Microsoft Defender 365 Configuration
azure365AccessToken: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJodHRwczovL2FwaS5zZWN1cml0eWNlbnRlci53aW5kb3dzLmNvbSIsImlzcyI6Imh0dHBzOi8vc3RzLndpbmRvd3MubmV0L2lkLyIsInZlciI6IjEuMCJ9
azure365ClientId: 013bf411-edf8-43b5-bbdd-62d433f1523a
azure365Secret: 1EC8~Azc-AU_86D72b4c01f..ab58_29cd752e~054e
azure365TenantId: 8ffee212-c550-42bd-abf5-4484c883f87a

# Microsoft Defender for Cloud Configuration
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

# Azure Entra Configuration (for FedRAMP evidence collection)
azureEntraAccessToken: ""
azureEntraClientId: your-entra-client-id
azureEntraSecret: your-entra-client-secret
azureEntraTenantId: your-entra-tenant-id

# Issue Configuration
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 CSV file

We also support importing defender alerts from a CSV-based, Defender generated report. To import the alerts from a CSV-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>

Additional options for import_alerts:

  • --scan_date - Date of the scan (format: YYYY-MM-DD)
  • --mappings_path - Path to custom mappings file
  • --disable_mapping - Disable custom mappings
  • --s3_bucket - S3 bucket to download files from
  • --s3_prefix - S3 prefix for file downloads
  • --aws_profile - AWS profile for S3 access
  • --upload_file - Whether to upload the file to RegScale (default: True)

File Format

Below are the expected columns of a Defender file:

Header NameRequired
ASSESSMENTKEY
SUBASSESSMENTIDYes
SUBASSESSMENTNAMEYes
SUBASSESSMENTCATEGORY
SEVERITYYes
STATUS
CAUSE
STATUSDESCRIPTION
SUBASSESSMENTDESCRIPTION
SUBASSESSMENTREMEDIATION
SUBASSESSMENTIMPACT
DIGEST
NUMOFRESOURCES
TIMEGENERATED
ADDITIONALDATA
HIGH
MEDIUM
LOW
ALL

Azure Entra Evidence Details

Azure Entra evidence collection supports FedRAMP compliance by automatically gathering and mapping evidence to appropriate controls. The evidence types include:

Evidence Categories

  • users_groups: Users & Groups Management
    • User accounts, guest users, security groups, and group memberships
  • rbac_pim: Role-Based Access Control & Privileged Identity Management
    • Role assignments, role definitions, PIM assignments and eligibility
  • conditional_access: Conditional Access Policies
    • Access control policies and configurations
  • authentication: Authentication Methods & Multi-Factor Authentication
    • Authentication policies, MFA registration, and methods configuration
  • audit_logs: Audit & Sign-in Logs
    • Sign-in logs, directory audits, and provisioning logs
  • access_reviews: Access Reviews & Governance
    • Access review definitions, instances, and decisions

FedRAMP Control Mapping

The integration automatically maps evidence to relevant FedRAMP controls.

Use regscale defender show_entra_mappings to view the complete mapping between evidence types and FedRAMP controls.

📘

NOTE: See All Scanner Integrations for information about how this updates Issues/POAMs, it should follow the same approach as documented in the Jira CLI integration.