Skip to main content

Microsoft Defender Create

Security

Synopsis​

Creates custom alerts in Microsoft Defender for Endpoint using the CreateAlertByReference API, enabling external threat detection systems to integrate with Microsoft's endpoint security platform for centralized incident management and automated response capabilities.

Schema​

- msdefender_create:
    machine_id: <string>
    severity: <string>
    title: <string>
    alert_description: <string>
    recommended_action: <string>
    category: <string>
    report_id: <string>
    tenant_id: <string>
    client_id: <string>
    client_secret: <string>
    event_time: <string>
    description: <text>
    if: <script>
    disabled: <boolean>
    ignore_failure: <boolean>
    ignore_missing: <boolean>
    on_failure: <processor[]>
    on_success: <processor[]>
    tag: <string>

Configuration​

FieldRequiredDefaultDescription
machine_idYTarget device/machine identifier in Defender for Endpoint
severityYAlert severity: Low, Medium, or High (case insensitive)
titleYBrief alert title describing the security event
alert_descriptionYDetailed alert description with context and findings
recommended_actionYSuggested remediation steps for security teams
categoryYAlert category (see valid categories in Details section)
report_idYUnique identifier for tracking and correlating related alerts
tenant_idN${GRAPH_TENANT_ID}Azure AD tenant ID
client_idN${GRAPH_CLIENT_ID}Application (client) ID from Azure AD app registration
client_secretN${GRAPH_CLIENT_SECRET}Client secret for authentication
event_timeNCurrent timeEvent timestamp in ISO 8601 format (e.g., 2024-01-15T10:30:00Z)
descriptionNExplanatory note
ifNConditional expression for processor execution
disabledNfalseDisable this processor
ignore_failureNfalseContinue pipeline on processor failure
ignore_missingNfalseContinue if source field missing
on_failureNProcessors to execute on failure
on_successNProcessors to execute on success
tagNIdentifier for this processor instance

Details​

The msdefender_create processor creates custom alerts in Microsoft Defender for Endpoint using the CreateAlertByReference API, enabling external security detection systems to integrate with Microsoft's unified endpoint security platform.

Authentication: Uses OAuth 2.0 client credentials flow with Azure AD. The processor automatically obtains and manages access tokens with caching for performance. Ensure your Azure AD application has the necessary API permissions (Alert.ReadWrite.All or similar) for Defender for Endpoint.

Machine ID: The target device identifier must exist in your Defender for Endpoint environment. You can obtain machine IDs through the Defender portal or via the Machines API. The machine_id field supports template syntax for dynamic values.

Severity Levels: Determines alert priority and visual indicators in Defender portal. Severity values are case insensitive and normalized to the API's required format (Low, Medium, High). Invalid severity values result in processor failure.

Alert Categories: The processor validates category values against Microsoft Defender's supported categories:

  • General - General security events
  • CommandAndControl - C2 communication attempts
  • Collection - Data collection activities
  • CredentialAccess - Credential theft attempts (MITRE ATT&CK T1003, T1110, etc.)
  • DefenseEvasion - Defense evasion techniques
  • Discovery - Network/system discovery activities
  • Exfiltration - Data exfiltration attempts
  • Exploit - Exploitation activities
  • Execution - Malicious code execution
  • InitialAccess - Initial access techniques
  • LateralMovement - Lateral movement activities
  • Malware - Malicious software detection
  • Persistence - Persistence mechanisms
  • PrivilegeEscalation - Privilege escalation attempts
  • Ransomware - Ransomware-related activities
  • SuspiciousActivity - Unusual behavior patterns

Report ID: Use this field to correlate related alerts across different events. Multiple alerts with the same report_id help security analysts understand the full attack chain and event relationships.

Automated Investigation: Alerts created through this processor trigger Defender's Automated Investigation and Response (AIR) capabilities, enabling automatic containment and remediation based on configured policies.

Template Support: All string fields support Go template syntax with triple curly braces {{{field_name}}} for event field interpolation, enabling dynamic alert content based on telemetry data.

Token Caching: OAuth access tokens are automatically cached to minimize authentication overhead and improve performance when creating multiple alerts in succession.

Examples​

Basic Alert Creation​

Creating a high-severity security alert from detected suspicious activity...

{
  "device_id": "1234567890abcdef",
  "alert_name": "Suspicious Process Detected",
  "alert_description": "A suspicious process was detected on the endpoint"
}
- msdefender_create:
    tenant_id: "${GRAPH_TENANT_ID}"
    client_id: "${GRAPH_CLIENT_ID}"
    client_secret: "${GRAPH_CLIENT_SECRET}"
    machine_id: "{{{device_id}}}"
    severity: "High"
    title: "{{{alert_name}}}"
    alert_description: "{{{alert_description}}}"
    recommended_action: "Investigate and terminate if malicious"
    category: "SuspiciousActivity"
    report_id: "suspicious-process-001"

Alert created in Defender portal with AIR triggered for automatic investigation...

Malware Detection Alert​

Reporting malware detection from external scanner...

{
  "device_id": "abcdef1234567890",
  "malware_name": "Trojan.Generic.12345",
  "file_path": "C:\\Users\\Admin\\Downloads\\malicious.exe"
}
- msdefender_create:
    tenant_id: "${GRAPH_TENANT_ID}"
    client_id: "${GRAPH_CLIENT_ID}"
    client_secret: "${GRAPH_CLIENT_SECRET}"
    machine_id: "{{{device_id}}}"
    severity: "High"
    title: "Malware Detected: {{{malware_name}}}"
    alert_description: "Malware detected at {{{file_path}}}"
    recommended_action: "Quarantine file and run full system scan"
    category: "Malware"
    report_id: "malware-{{{device_id}}}-001"

Malware alert with automatic quarantine investigation initiated...

Credential Access Detection​

Alerting on credential dumping attempts with MITRE ATT&CK mapping...

{
  "device_id": "device-prod-001",
  "attack_type": "Credential Dumping",
  "technique_id": "T1003",
  "user_account": "admin@contoso.com"
}
- msdefender_create:
    tenant_id: "${GRAPH_TENANT_ID}"
    client_id: "${GRAPH_CLIENT_ID}"
    client_secret: "${GRAPH_CLIENT_SECRET}"
    machine_id: "{{{device_id}}}"
    severity: "High"
    title: "Credential Access Detected: {{{attack_type}}}"
    alert_description: "MITRE ATT&CK Technique {{{technique_id}}} detected on user {{{user_account}}}"
    recommended_action: "Reset credentials and investigate attack"
    category: "CredentialAccess"
    report_id: "credential-{{{device_id}}}-{{{technique_id}}}"

MITRE ATT&CK mapped alert for credential theft investigation...

Ransomware Detection​

Critical ransomware detection requiring immediate action...

{
  "device_id": "endpoint-finance-05",
  "ransomware_family": "WannaCry",
  "encrypted_files": "150"
}
- msdefender_create:
    tenant_id: "${GRAPH_TENANT_ID}"
    client_id: "${GRAPH_CLIENT_ID}"
    client_secret: "${GRAPH_CLIENT_SECRET}"
    machine_id: "{{{device_id}}}"
    severity: "High"
    title: "Ransomware Detected: {{{ransomware_family}}}"
    alert_description: "Ransomware detected. {{{encrypted_files}}} files encrypted"
    recommended_action: "Isolate device immediately and restore from backup"
    category: "Ransomware"
    report_id: "ransomware-{{{device_id}}}"

High-priority alert triggering automatic device isolation...

Custom Event Time​

Reporting historical events with specific timestamps for forensic analysis...

{
  "device_id": "test-device-001",
  "event_time": "2024-01-15T10:30:00Z",
  "alert_name": "Backdoor Detected"
}
- msdefender_create:
    tenant_id: "${GRAPH_TENANT_ID}"
    client_id: "${GRAPH_CLIENT_ID}"
    client_secret: "${GRAPH_CLIENT_SECRET}"
    machine_id: "{{{device_id}}}"
    severity: "High"
    title: "{{{alert_name}}}"
    alert_description: "Persistent backdoor mechanism identified"
    recommended_action: "Remove backdoor and audit system access"
    category: "SuspiciousActivity"
    event_time: "{{{event_time}}}"
    report_id: "backdoor-{{{device_id}}}"

Alert with historical timestamp for forensic timeline analysis...

Template Processing​

Using templates to construct dynamic alert content from event fields...

{
  "device_id": "prod-server-01",
  "alert_name": "High CPU Usage",
  "cpu_usage": "95%",
  "process_name": "malicious.exe"
}
- msdefender_create:
    tenant_id: "${GRAPH_TENANT_ID}"
    client_id: "${GRAPH_CLIENT_ID}"
    client_secret: "${GRAPH_CLIENT_SECRET}"
    machine_id: "{{{device_id}}}"
    severity: "Medium"
    title: "[{{{alert_name}}}] on {{{device_id}}}"
    alert_description: "CPU usage is at {{{cpu_usage}}} caused by {{{process_name}}}"
    recommended_action: "Investigate process {{{process_name}}} and terminate if malicious"
    category: "SuspiciousActivity"
    report_id: "cpu-{{{device_id}}}-001"

Alert with interpolated values from event data for context-rich reporting...

Error Handling​

Continuing pipeline execution even if alert creation fails...

- msdefender_create:
    tenant_id: "${GRAPH_TENANT_ID}"
    client_id: "${GRAPH_CLIENT_ID}"
    client_secret: "${GRAPH_CLIENT_SECRET}"
    machine_id: "{{{device_id}}}"
    severity: "Medium"
    title: "Security Event"
    alert_description: "Security event detected"
    recommended_action: "Investigate"
    category: "SuspiciousActivity"
    report_id: "{{{event_id}}}"
    ignore_failure: true

Pipeline continues even if Defender API is unavailable...

Azure AD App Registration​

To use the msdefender_create processor, you must register an application in Azure AD with appropriate permissions:

  1. Register Application:

    • Navigate to Azure Portal > Microsoft Entra ID > App registrations > New registration
    • Choose a name and select supported account types
    • Register the application

  2. Create Client Secret:

    • Go to Certificates & secrets > New client secret
    • Add description and expiration
    • Copy the secret value (shown only once)

  3. Assign API Permissions:

    • Go to API Permissions > Add permission
    • Select "APIs my organization uses" > Search for "WindowsDefenderATP"
    • Choose Application permissions > Alert.ReadWrite.All
    • Grant admin consent

  4. Configure Environment Variables:

    export GRAPH_TENANT_ID="your-tenant-id"
    export GRAPH_CLIENT_ID="your-client-id"
    export GRAPH_CLIENT_SECRET="your-client-secret"

  5. Obtain Machine IDs:

    • Machine IDs can be found in the Defender portal under Devices
    • Or retrieved via the Machines API endpoint

For detailed setup instructions, see Microsoft Defender for Endpoint API Documentation.