Detection Authoring

Custom Detection Authoring — Instructions

Purpose

This skill deploys custom detection rules to Microsoft Defender XDR via the Microsoft Graph API (/beta/security/rules/detectionRules). It handles:

• Query adaptation — Converting Sentinel KQL queries into custom detection format
• Single-rule deployment — Creating one rule via Graph API
• Batch deployment — Deploying multiple rules from a JSON manifest
• Lifecycle management — Listing, updating, enabling/disabling, and deleting rules
• Validation — Dry-run queries in Advanced Hunting before deployment

Entity Type: Custom detection rules (Defender XDR)

Writing new detection queries from scratch? This skill focuses on deploying and managing detection rules — not query creation. If you need to write detection KQL from scratch (schema validation, community examples, performance optimization), use the kql-query-authoring skill first with CD intent markers (say "create custom detection queries for [scenario]"). It will produce Sentinel-format queries with cd-metadata blocks ready for this skill to adapt and deploy.

📑 TABLE OF CONTENTS

1. Prerequisites — Auth, scopes, PowerShell modules
2. Critical Rules — Mandatory constraints (includes query adaptation checklist)
3. Naming Convention — Standardized displayName format (no prefixes, no MITRE IDs, colon separators)
4. API Reference — Graph API schema and field values
5. Frequency & Lookback — Schedule periods, lookback windows, NRT constraints
6. Deployment Workflow — Step-by-step process
7. Batch Deployment — Manifest-driven multi-rule deployment
8. Lifecycle Management — CRUD operations
9. Existing Rule Discovery — Search Analytic Rules & Custom Detections by table, EventID, or keyword
10. Known Pitfalls — Lessons learned (19 pitfalls documented)
11. CD Metadata Contract — Schema for query file ↔ detection skill coordination

Prerequisites

Required PowerShell Module

# Microsoft.Graph.Authentication — provides Invoke-MgGraphRequest
Install-Module Microsoft.Graph.Authentication -Scope CurrentUser

Required Graph API Scopes

Authentication

# Read-only
Connect-MgGraph -Scopes "CustomDetection.Read.All" -NoWelcome

# Full CRUD
Connect-MgGraph -Scopes "CustomDetection.ReadWrite.All" -NoWelcome

Why Invoke-MgGraphRequest? The Graph MCP server and az rest both return 403 for custom detection endpoints — they lack the CustomDetection.* scopes. Invoke-MgGraphRequest uses interactive delegated auth with consent, which works.

Companion Script

Deploy-CustomDetections.ps1 — PowerShell script for manifest-driven batch deployment. See Batch Deployment.

⚠️ CRITICAL RULES — READ FIRST ⚠️

Mandatory Query Requirements

Custom detection queries have strict requirements that differ from Sentinel analytic rules:

Required event-unique columns by table type (MS Learn source):

Query Adaptation Checklist

When converting a Sentinel query to custom detection format:

1. ✅ Remove bare summarize — project raw rows instead. Exception: summarize with arg_max is allowed for threshold-based detections (see Pitfall 3)
2. ✅ Project the timestamp column as-is: TimeGenerated = TimeGenerated for Sentinel/LA tables, Timestamp for XDR tables. Never alias one to the other.
3. ✅ Project the impacted asset identifier column — the column name must match a valid identifier from Impacted Asset Types. Examples: DeviceName = Computer for device-focused detections, AccountUpn = UserId for user-focused. See Pitfall 9. Also populate entityMappings binding that column to the entity (see Entity Mappings and Pitfall 19) — impactedAssets alone is silently dropped on some connector tables.
4. ✅ Project event-unique columns per table type — DeviceId + ReportId for MDE tables; ReportId for other XDR tables; recommended proxy ReportId for Sentinel tables (e.g., ReportId = CorrelationId). Caveat: proxy columns may contain empty strings for some events — acceptable but means those rows won't be individually identifiable in alert details.
5. ✅ Add a time filter as the first where clause — prefer ingestion_time() > ago(1h) over Timestamp > ago(1h) (see tip below). NRT exception: For NRT rules (schedule: "0"), omit all time filters — ingestion_time() causes 400 Bad Request in NRT mode (see Pitfall 17). Timestamp > ago(...) is accepted but unnecessary.
6. ✅ Remove let variables for NRT rules — NRT rejects let entirely (generic 400 error, undocumented). Inline all dynamic arrays directly in where clauses. Non-NRT rules tolerate let.
7. ✅ Validate via Advanced Hunting dry-run before deployment
8. ✅ For NRT rules: avoid tostring() on dynamic columns — use native string columns instead (e.g., Properties instead of tostring(Properties_d)). See Pitfall 11.
9. ✅ For NRT rules: verify the table's ingestion lag justifies NRT. See Pitfall 12.
10. ✅ Count unique {{Column}} references across title AND description combined — max 3 unique columns total (shared across both fields, not per-field). Exceeding this returns 400 Bad Request: "Dynamic properties in alertTitle and alertDescription must not exceed 3 fields". See Pitfall 14.

Performance tip (from MS Learn): "Avoid filtering custom detections by using the Timestamp column. The data used for custom detections is prefiltered based on the detection frequency." Use ingestion_time() instead — it aligns with the platform's pre-filtering for better performance. For scheduled rules, match the time filter to the run frequency (ingestion_time() > ago(1h) for 1H rules). For NRT rules, no time filter is needed. ⚠️ PowerShell note: When building queryText containing backslashes (file paths, regex), always use single-quoted here-strings (@'...'@) to avoid escape sequence mangling — see Pitfall 15.

Example Adaptation

Before (Sentinel KQL — uses summarize):

let _Lookback = 7d;
SecurityEvent
| where TimeGenerated > ago(_Lookback)
| where EventID == 4799
| where TargetSid == "S-1-5-32-544"
| where SubjectUserSid != "S-1-5-18"
| where AccountType != "Machine"
| where not(SubjectUserSid endswith "-500")
| project TimeGenerated, Computer, Actor = SubjectUserName, ...
| summarize EnumerationCount = count(), Processes = make_set(CallerProcess)
    by Actor, ActorDomain, ActorSID

After (Custom Detection — row-level, mandatory columns):

SecurityEvent
| where TimeGenerated > ago(1h)
| where EventID == 4799
| where TargetSid == "S-1-5-32-544"
| where SubjectUserSid != "S-1-5-18"
| where AccountType != "Machine"
| where not(SubjectUserSid endswith "-500")
| project
    TimeGenerated = TimeGenerated,
    DeviceName = Computer,
    AccountName = SubjectUserName,
    AccountDomain = SubjectDomainName,
    AccountSid = SubjectUserSid,
    CallerProcess = CallerProcessName,
    ReportId = CallerProcessId

Key changes:

• Removed let _Lookback → hardcoded ago(1h)
• Removed summarize → raw project
• Added TimeGenerated = TimeGenerated (identity projection — mandatory)
• Added DeviceName = Computer (impacted asset identifier — device-focused detection)
• Added ReportId = CallerProcessId (proxy ReportId — event-unique identifier)

Naming Convention

The displayName should be a clean, title-case description of what the detection finds. The portal columns already show Scheduling Type, Tactics, and Techniques — don't repeat them in the name.

API Reference

Endpoint

POST   /beta/security/rules/detectionRules          — Create
GET    /beta/security/rules/detectionRules           — List all
GET    /beta/security/rules/detectionRules/{id}      — Get by ID
PATCH  /beta/security/rules/detectionRules/{id}      — Update
DELETE /beta/security/rules/detectionRules/{id}      — Delete

Schedule Periods

Alert Severity Values

Alert Category Values

category is a case-sensitive, single-value, server-validated enum accepting two groups:

• MITRE tactics (title case): InitialAccess, Execution, Persistence, PrivilegeEscalation, DefenseEvasion, CredentialAccess, Discovery, LateralMovement, Collection, Exfiltration, CommandAndControl, Impact, Reconnaissance, ResourceDevelopment
• Non-tactic threat categories: Malware, Ransomware, SuspiciousActivity, UnwantedSoftware — these hide the MITRE techniques field in the portal (MS Learn); prefer a tactic when you want techniques to display.

Portal label note: The portal labels this control "Tactic" (UX rename, 2026), but the API field stays category — single-value, automation unaffected. Validation details in Pitfall 18.

Impacted Asset Types

Device asset:

{
    "@odata.type": "#microsoft.graph.security.impactedDeviceAsset",
    "identifier": "<identifier>"
}

Valid device identifiers: deviceId, deviceName, remoteDeviceName, targetDeviceName, destinationDeviceName

User asset:

{
    "@odata.type": "#microsoft.graph.security.impactedUserAsset",
    "identifier": "<identifier>"
}

Valid user identifiers: accountObjectId, accountSid, accountUpn, accountName, accountDomain, accountId, requestAccountSid, requestAccountName, requestAccountDomain, recipientObjectId, processAccountObjectId, initiatingAccountSid, initiatingProcessAccountUpn, initiatingAccountName, initiatingAccountDomain, servicePrincipalId, servicePrincipalName, targetAccountUpn

Mailbox asset:

{
    "@odata.type": "#microsoft.graph.security.impactedMailboxAsset",
    "identifier": "<identifier>"
}

Valid mailbox identifiers: accountUpn, fileOwnerUpn, initiatingProcessAccountUpn, lastModifyingAccountUpn, targetAccountUpn, senderFromAddress, senderDisplayName, recipientEmailAddress, senderMailFromAddress

Entity Mappings — Required Column Binding

impactedAssets declares the asset type; entityMappings binds the query column to the entity (both under detectionAction.alertTemplate). The API usually auto-derives entityMappings from impactedAssets, but that silently fails on some connector tables (e.g. GSA NetworkAccess*) — dropping impactedAssets to [] with no error. See Pitfall 19.

You rarely write this by hand — Deploy-CustomDetections.ps1 auto-generates entityMappings from each manifest impactedAssets entry (identifier→column lookup lives in the script) and merges any explicit entityMappings you add for related evidence. Only for manual Invoke-MgGraphRequest POSTs do you send it yourself:

"entityMappings": {
    "accounts": [ { "upnColumn": "AccountUpn" } ],
    "hosts":    [ { "deviceIdColumn": "DeviceId" } ],
    "ips":      [ { "addressColumn": "IPAddress" } ]
}

The column value is the query output column name (PascalCase per the Pitfall 9 convention: accountUpn → AccountUpn). Send only populated entity types — the API fills the rest. Related-evidence types include ips, urls, cloudApplications, dns, oAuthApplications.

Minimal Valid POST Body

{
    "displayName": "Rule Name",
    "isEnabled": true,
    "queryCondition": {
        "queryText": "SecurityEvent\r\n| where TimeGenerated > ago(1h)\r\n| ..."
    },
    "schedule": {
        "period": "1H"
    },
    "detectionAction": {
        "alertTemplate": {
            "title": "Alert Title",
            "description": "Alert description text.",
            "severity": "medium",
            "category": "Discovery",
            "recommendedActions": null,
            "mitreTechniques": ["T1069.001"],
            "impactedAssets": [
                {
                    "@odata.type": "#microsoft.graph.security.impactedDeviceAsset",
                    "identifier": "deviceName"
                }
            ],
            "entityMappings": {
                "hosts": [ { "nameColumn": "DeviceName" } ]
            }
        },
        "responseActions": []
    }
}

impactedAssets: Must contain at least 1 element — an empty array causes 400 BadRequest. Every detection must map to at least one impacted entity (device, user, or mailbox). See Pitfall 13.

recommendedActions: Can be null or a string. The portal sets it to null by default.

responseActions: Must always be [] — response actions are prohibited in LLM-authored detections (see Critical Rules). Must be [], not null — sending null causes 400 Bad Request. See Pitfall 10.

organizationalScope: Omit this field entirely for tenant-wide rules (the API default). Including "organizationalScope": null explicitly may cause 400 Bad Request in some API versions.

Custom details (not shown above): The API also supports a customDetails array of key-value pairs surfaced in the alert side panel. Each rule supports up to 20 KVPs with a combined 4KB size limit. Keys are display labels; values are query column names. See MS Learn.

Related evidence (not shown above): Beyond impactedAssets, the entity mapping also supports linking related evidence entities (Process, File, Registry value, IP, OAuth application, DNS, Security group, URL, Mail cluster, Mail message). These provide correlation context but are not impacted assets. See MS Learn.

Dynamic Alert Titles and Descriptions

Alert titles and descriptions can reference query result columns using {{ColumnName}} syntax, making alerts self-descriptive:

{
    "title": "Admin Group Enumeration by {{AccountName}} on {{DeviceName}}",
    "description": "User {{AccountName}} enumerated group {{TargetGroupName}} on the device."
}

Frequency & Lookback

Lookback Windows by Frequency

Each frequency has a built-in lookback window. Results outside this window are ignored even if the query requests them:

Tip: Match the query time filter to the run frequency (ago(1h) for 1H rules), not the full lookback window. The lookback ensures late-arriving data is caught, but your filter should target the detection window.

NRT Constraints

NRT (Continuous, period: "0") rules have stricter requirements than scheduled rules:

NRT-Supported Tables

Not all tables support NRT frequency. Use NRT only with these tables:

Defender XDR tables: AlertEvidence, CloudAppEvents, DeviceEvents, DeviceFileCertificateInfo, DeviceFileEvents, DeviceImageLoadEvents, DeviceLogonEvents, DeviceNetworkEvents, DeviceNetworkInfo, DeviceInfo, DeviceProcessEvents, DeviceRegistryEvents, EmailAttachmentInfo, EmailEvents*, EmailPostDeliveryEvents, EmailUrlInfo, IdentityDirectoryEvents, IdentityLogonEvents, IdentityQueryEvents, UrlClickEvents

* EmailEvents: LatestDeliveryLocation and LatestDeliveryAction columns are excluded from NRT.

Sentinel tables (Preview): ABAPAuditLog_CL, ABAPChangeDocsLog_CL, AuditLogs, AWSCloudTrail, AWSGuardDuty, AzureActivity, CommonSecurityLog, GCPAuditLogs, MicrosoftGraphActivityLogs, OfficeActivity, Okta_CL, OktaV2_CL, ProofpointPOD, ProofPointTAPClicksPermitted_CL, ProofPointTAPMessagesDelivered_CL, SecurityAlert, SecurityEvent, SigninLogs

Important: SecurityEvent and SigninLogs support NRT — our Event ID 4799/4702 queries can run as NRT if they meet the single-table/no-joins constraint.

Ingestion Lag Consideration — NRT Suitability

A table being NRT-supported means the API accepts NRT rules — not that NRT is the right choice. If a table's ingestion lag exceeds the detection frequency benefit, NRT adds overhead with no detection speed improvement. See Pitfall 12 for a per-table ingestion lag assessment and recommendation matrix. Rule of thumb: if ingestion lag > 30 min, use 1H scheduled instead.

Custom Frequency (Sentinel Data Only)

For rules based entirely on Sentinel-ingested data, a custom frequency is available (Preview):

• Range: 5 minutes to 14 days
• Lookback: Automatically calculated — 4× frequency for sub-daily, 30 days for daily or longer
• Requirement: Data must be available in Microsoft Sentinel (not XDR-only tables)

Deployment Workflow

🔴 DEPLOYMENT GATE: Only proceed to Steps 2-3 (API calls) when the user has explicitly requested deployment. Trigger phrases: "deploy", "create the rule", "push", "POST it", "make it live". If the user asked to "author", "write", "create a manifest", "prepare", or "draft" a detection — stop after validation (Step 1) and manifest generation. Present the manifest JSON for review and wait for explicit deployment confirmation.

Single Rule Deployment

Step 1: Validate the query in Advanced Hunting

Run the adapted query with a 1h lookback to validate schema:

Use RunAdvancedHuntingQuery with the adapted KQL query.
Confirm: 0 or more results, correct column schema (TimeGenerated, DeviceName, AccountName, etc.)

Then run with 30d lookback to confirm it returns real data:

Change ago(1h) to ago(30d) for the validation run.
Verify results contain expected columns and realistic data.

Step 2: Check for duplicates, then build and POST the rule

Connect-MgGraph -Scopes "CustomDetection.ReadWrite.All" -NoWelcome

# Pre-flight: check if rule name already exists
$ruleName = "Rule Name"
$existing = (Invoke-MgGraphRequest -Method GET `
    -Uri "/beta/security/rules/detectionRules" -OutputType PSObject).value `
    | Where-Object { $_.displayName -eq $ruleName }
if ($existing) {
    Write-Host "Rule '$ruleName' already exists (ID: $($existing.id)). Skipping POST."
    return
}

$body = @{
    displayName = $ruleName
    isEnabled = $true
    queryCondition = @{
        queryText = "SecurityEvent`r`n| where TimeGenerated > ago(1h)`r`n| ..."
    }
    schedule = @{ period = "1H" }
    detectionAction = @{
        alertTemplate = @{
            title = "Alert Title"
            description = "Description"
            severity = "medium"
            category = "Discovery"
            recommendedActions = $null
            mitreTechniques = @("T1069.001")
            impactedAssets = @(
                @{
                    "@odata.type" = "#microsoft.graph.security.impactedDeviceAsset"
                    identifier = "deviceName"
                }
            )
        }
        responseActions = @()
    }
} | ConvertTo-Json -Depth 10

$result = Invoke-MgGraphRequest -Method POST `
    -Uri "/beta/security/rules/detectionRules" `
    -Body $body -ContentType "application/json" -OutputType PSObject

Step 3: Verify creation

$rules = Invoke-MgGraphRequest -Method GET `
    -Uri "/beta/security/rules/detectionRules" -OutputType PSObject
$rules.value | Select-Object id, displayName, isEnabled,
    @{N='Schedule';E={$_.schedule.period}},
    @{N='Status';E={$_.lastRunDetails.status}} | Format-Table -AutoSize

Batch Deployment

Use the companion script Deploy-CustomDetections.ps1 for manifest-driven batch deployment.

Manifest storage: Save manifest JSON files in the temp/ folder (gitignored). Manifests are deployment artifacts, not versioned query definitions.

Manifest Format

See example-manifest.json for a complete 2-rule reference covering NRT and scheduled (with summarize/arg_max) patterns.

The script reads a JSON file containing an array of rule definitions:

[
    {
        "displayName": "Admin Group Enumeration by Non-Admin User",
        "title": "Admin Group Enumeration by {{AccountName}} on {{DeviceName}}",
        "queryText": "SecurityEvent\r\n| where TimeGenerated > ago(1h)\r\n| ...",
        "schedule": "0",
        "severity": "medium",
        "category": "Discovery",
        "mitreTechniques": ["T1069.001", "T1087.001"],
        "description": "User {{AccountName}} enumerated the local Administrators group.",
        "recommendedActions": "Verify whether the user has a legitimate reason to enumerate admin group membership.",
        "impactedAssets": [
            { "type": "device", "identifier": "deviceName" },
            { "type": "user", "identifier": "accountSid" }
        ],
        "responseActions": []
    }
]

Usage

# Dry-run — validate all queries in Advanced Hunting without creating rules
.\Deploy-CustomDetections.ps1 -ManifestPath .\temp\4799_4702.json -DryRun

# Deploy all rules from manifest (skips existing rules by default)
.\Deploy-CustomDetections.ps1 -ManifestPath .\temp\4799_4702.json

# Deploy and overwrite — attempt POST even if rule name exists (may cause 409)
.\Deploy-CustomDetections.ps1 -ManifestPath .\temp\4799_4702.json -Force

Lifecycle Management

List All Rules

$rules = Invoke-MgGraphRequest -Method GET `
    -Uri "/beta/security/rules/detectionRules" -OutputType PSObject
$rules.value | Select-Object id, displayName, isEnabled,
    @{N='Schedule';E={$_.schedule.period}},
    @{N='LastRun';E={$_.lastRunDetails.status}},
    @{N='Created';E={$_.createdDateTime}} | Format-Table -AutoSize

Get Rule by ID

$rule = Invoke-MgGraphRequest -Method GET `
    -Uri "/beta/security/rules/detectionRules/5632" -OutputType PSObject
$rule | ConvertTo-Json -Depth 10

Update Rule (PATCH)

PATCH /beta/security/rules/detectionRules/{id} — send only the fields you want to change. All fields are optional.

Updatable fields:

Examples:

# Rename a rule
$body = @{ displayName = 'Cloud Password Spray: Multi-Account Failed Auth from Single IP' } | ConvertTo-Json
Invoke-MgGraphRequest -Method PATCH `
    -Uri "/beta/security/rules/detectionRules/6044" `
    -Body $body -ContentType "application/json"

# Change schedule and severity
$body = @{
    schedule = @{ period = "24H" }
    detectionAction = @{
        alertTemplate = @{ severity = "high" }
    }
} | ConvertTo-Json -Depth 10
Invoke-MgGraphRequest -Method PATCH `
    -Uri "/beta/security/rules/detectionRules/5632" `
    -Body $body -ContentType "application/json"

# Batch rename (loop pattern)
$renames = @{
    'Old Rule Name' = 'New Rule Name'
    'Another Old Name' = 'Another New Name'
}
$rules = (Invoke-MgGraphRequest -Method GET `
    -Uri "/beta/security/rules/detectionRules" -OutputType PSObject).value
foreach ($old in $renames.Keys) {
    $rule = $rules | Where-Object { $_.displayName -eq $old }
    if (-not $rule) { continue }
    $body = @{ displayName = $renames[$old] } | ConvertTo-Json
    Invoke-MgGraphRequest -Method PATCH `
        -Uri "/beta/security/rules/detectionRules/$($rule.id)" `
        -Body $body -ContentType "application/json"
}

Delete Rule

Invoke-MgGraphRequest -Method DELETE `
    -Uri "/beta/security/rules/detectionRules/5632"

⚠️ Deletion propagation delay: After deleting a rule, the name remains reserved for ~30-60 seconds. Creating a rule with the same displayName during this window returns 409 Conflict — but the rule may still be created despite the error. Always verify with a GET after creation.

Enable/Disable Without Deleting

# Disable
Invoke-MgGraphRequest -Method PATCH `
    -Uri "/beta/security/rules/detectionRules/5632" `
    -Body '{"isEnabled": false}' -ContentType "application/json"

# Enable
Invoke-MgGraphRequest -Method PATCH `
    -Uri "/beta/security/rules/detectionRules/5632" `
    -Body '{"isEnabled": true}' -ContentType "application/json"

Existing Rule Discovery

Before authoring new custom detections, check what Analytic Rules (Sentinel) and Custom Detection rules (Defender XDR) already exist for the same table, EventID, or keyword. This avoids duplicating coverage and helps identify gaps.

Step 0: Construct the Analytic Rules URL (once per session)

$cfg = Get-Content config.json | ConvertFrom-Json
$sub = $cfg.subscription_id
$rg  = $cfg.azure_mcp.resource_group
$ws  = $cfg.azure_mcp.workspace_name
$arUrl = "https://management.azure.com/subscriptions/$sub/resourceGroups/$rg/providers/Microsoft.OperationalInsights/workspaces/$ws/providers/Microsoft.SecurityInsights/alertRules?api-version=2024-09-01"

# Verify (should return rule count)
az rest --method get --url $arUrl --query "length(value)" -o tsv 2>$null

All patterns below reuse $arUrl. The Sentinel REST API returns the full KQL query text for every rule — there is no server-side content filtering, so we pull all rules in one call and filter client-side with JMESPath contains().

Search Analytic Rules by Table Name or Keyword

# Which rules reference a specific table? (e.g., SecurityEvent)
az rest --method get --url $arUrl `
  --query "value[?properties.query && contains(properties.query, 'SecurityEvent')].{name: properties.displayName, severity: properties.severity, enabled: properties.enabled}" `
  -o table 2>$null

Search Analytic Rules by EventID

# Which rules reference a specific EventID?
az rest --method get --url $arUrl `
  --query "value[?properties.query && contains(properties.query, '<EventID>')].{name: properties.displayName, severity: properties.severity, enabled: properties.enabled}" `
  -o table 2>$null

To see the surrounding KQL context of a match:

az rest --method get --url $arUrl `
  --query "value[?properties.query && contains(properties.query, '<EventID>')].properties.query" `
  -o tsv 2>$null | Select-String -Pattern '<EventID>' -Context 1,1

Search Analytic Rules for ASIM Parser Dependencies

$rules = az rest --method get --url $arUrl `
  --query "value[?properties.enabled==``true`` && properties.query].{displayName: properties.displayName, query: properties.query}" `
  -o json 2>$null | ConvertFrom-Json

$asimRules = $rules | Where-Object { $_.query -match '_Im_|_ASim_' }
$asimRules | ForEach-Object {
    $schemas = [regex]::Matches($_.query, '_Im_(\w+)') | ForEach-Object { $_.Groups[1].Value } | Sort-Object -Unique
    Write-Host "$($_.displayName): $($schemas -join ', ')"
}

Dump All Enabled Rule Queries for Local Search

az rest --method get --url $arUrl `
  --query "value[?properties.enabled==``true`` && properties.query].{name: properties.displayName, query: properties.query}" `
  -o json > temp/analytic_rule_queries.json

# Then search locally for any pattern
Get-Content temp/analytic_rule_queries.json | Select-String -Pattern 'EventID\s*(==|in\s*\(|has|contains)' -AllMatches

Search Custom Detection Rules (Graph API)

⚠️ Important: The Graph MCP server returns 403 for the Custom Detection endpoint. Always use Invoke-MgGraphRequest via the terminal.

Import-Module Microsoft.Graph.Authentication -ErrorAction Stop

$ctx = Get-MgContext
if (-not $ctx -or $ctx.Scopes -notcontains 'CustomDetection.Read.All') {
    Connect-MgGraph -Scopes 'CustomDetection.Read.All' -NoWelcome
}

$response = Invoke-MgGraphRequest -Method GET `
    -Uri '/beta/security/rules/detectionRules?$select=id,displayName,isEnabled,queryCondition,schedule,lastRunDetails,createdDateTime,lastModifiedDateTime' `
    -OutputType PSObject

Then filter by table name or keyword:

# Which CD rules reference SecurityEvent?
$response.value | Where-Object { $_.queryCondition.queryText -match 'SecurityEvent' } |
    Select-Object displayName, isEnabled, @{N='Query';E={$_.queryCondition.queryText}}

# Which CD rules reference a specific EventID?
$response.value | Where-Object { $_.queryCondition.queryText -match '4688|ProcessCreate' } |
    Select-Object displayName, isEnabled, @{N='Query';E={$_.queryCondition.queryText}}

Identify stale rules (no run in 90 days):

$cutoff = (Get-Date).AddDays(-90).ToString('yyyy-MM-ddTHH:mm:ssZ')
$response.value | Where-Object {
    $_.lastRunDetails.lastRunDateTime -and $_.lastRunDetails.lastRunDateTime -lt $cutoff
} | Select-Object displayName, isEnabled,
    @{N='LastRun';E={$_.lastRunDetails.lastRunDateTime}},
    @{N='Status';E={$_.lastRunDetails.status}}

Key API Fields for Rule Discovery

Tip: JMESPath contains() (used in az rest --query) is case-sensitive. For case-insensitive search, dump to JSON and use PowerShell -match instead.

Known Pitfalls

Pitfall 1: Timestamp vs TimeGenerated — Project As-Is

The query must project the timestamp column exactly as it appears in the source table. Do NOT alias one to the other.

The MS Learn docs confirm: "Timestamp or TimeGenerated — This column sets the timestamp for generated alerts. The query shouldn't manipulate this column and should return it exactly as it appears in the raw event." Aliasing across types causes 400 Bad Request.

Pitfall 2: Silent Rule Creation on Error Responses (400 AND 409)

The API can silently create a rule even when it returns an error. This applies to both 400 Bad Request and 409 Conflict responses.

Cause A — 400 with partial validation: A POST may pass structural validation (creating the rule) but fail a secondary check (e.g., let variable in NRT query, >3 dynamic fields). The API returns 400 Bad Request — but the rule was already created. A subsequent retry with a fixed query then hits 409 Conflict because the rule exists.

Cause B — Deletion propagation delay: Deleting a rule leaves a name reservation for ~30-60 seconds. POSTing a rule with the same displayName in this window returns 409 Conflict — but the API may still create the rule.

Cause C — Silent success + accidental retry: When running Invoke-MgGraphRequest in a terminal, the POST may succeed but the output buffer splits across calls, making it look like nothing happened. Re-running the same POST produces a 409 because the rule was already created seconds earlier.

Prevention:

1. Always run a GET before POST to check if the rule name already exists (see Step 2)
2. Always verify with GET after ANY error response (400 or 409) — the rule may have been created despite the error
3. Never re-run a POST without first checking via GET whether the previous attempt succeeded
4. If a rule was silently created with a bad query, use PATCH to update the queryCondition.queryText rather than deleting and re-creating