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 alertssync_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 alertssync_cloud_recommendations
- pulls recommendations from Microsoft Defender for Cloud and will compare against existing RegScale issues and create issues for any new recommendationssync_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
- 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
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 Name | Required |
---|---|
ASSESSMENTKEY | |
SUBASSESSMENTID | Yes |
SUBASSESSMENTNAME | Yes |
SUBASSESSMENTCATEGORY | |
SEVERITY | Yes |
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.
Updated 6 days ago