riposte-marketplace/integrations/microsoft-defender-endpoint/manifest.yaml

id: microsoft_defender_endpoint
name: Microsoft Defender for Endpoint
version: 1.1.0
description: "Microsoft Defender for Endpoint (Security Center API) — machine isolation, app-execution restriction, antivirus scan, file quarantine, investigation package collection, offboarding, tagging, alert triage, advanced hunting (KQL), custom indicators, and alert ingestion (get_incidents) with an OCSF mapper. Azure AD OAuth 2.0 client-credentials authentication. Stdlib-only, no extra Python dependencies."
changelog: "1.1.0 — Declare the risk tier on the 12 commands that carried none: 4 safe_write, 8 destructive. An unset risk is read as destructive by the agent approval gate, so the 4 that only annotate sat behind the same prompt as the ones that change the estate. | 1.0.0 — Initial release: alert ingestion + triage, machine actions (isolate/unisolate, restrict/unrestrict app execution, AV scan, quarantine file, collect package, offboard, tag), advanced hunting, custom indicators, and machine/action listing."
category: endpoint

# Per-instance configuration. Register an Azure AD application, grant it the
# WindowsDefenderATP application permissions (Machine.Isolate, Machine.Scan,
# Alert.Read.All, Ti.ReadWrite, AdvancedQuery.Read.All, …) and admin-consent
# them. The scripts request a token from Azure AD (client-credentials) for the
# Security Center resource, then call https://api.securitycenter.microsoft.com.
config_schema:
  properties:
    tenant_id:
      type: string
      description: "Azure AD tenant (directory) ID"
    client_id:
      type: string
      description: "Application (client) ID"
    client_secret:
      type: string
      description: "Client secret"
      x-soar-sensitive: true
  required:
    - tenant_id
    - client_id
    - client_secret

commands:
  # ── Ingestion / alerts ────────────────────────────────────────────────────
  - id: get_incidents
    name: microsoft-defender-endpoint-get-incidents
    description: "Fetch Defender alerts for ingestion. Returns {result:[...]}; use result as the alert rule results path."
    risk: read
    inputs_schema:
      properties:
        status: { type: string, description: "Filter by status (New, InProgress, Resolved)" }
        severity: { type: string, description: "Filter by severity (Informational, Low, Medium, High)" }
        created_after: { type: string, description: "Lower bound on alertCreationTime, ISO8601 (incremental fetch watermark)" }
        limit: { type: number, description: "Maximum alerts to fetch (default 50)" }
      required: []
    outputs_schema: { properties: {} }
    ingest:
      results_path: result
      dedup_key: id
      incremental_field: created_after
  - id: list_alerts
    name: microsoft-defender-endpoint-list-alerts
    description: "List alerts with an optional OData filter."
    risk: read
    inputs_schema:
      properties:
        filter: { type: string, description: "OData $filter expression" }
        limit: { type: number, description: "Maximum alerts (default 50)" }
      required: []
    outputs_schema: { properties: {} }
  - id: get_alert
    name: microsoft-defender-endpoint-get-alert
    description: "Get a single alert by ID."
    risk: read
    inputs_schema:
      properties:
        alert_id: { type: string, description: "Alert ID" }
      required: [alert_id]
    outputs_schema: { properties: {} }
  - id: update_alert
    name: microsoft-defender-endpoint-update-alert
    description: "Update an alert's status, classification, determination or assignment."
    risk: safe_write
    inputs_schema:
      properties:
        alert_id: { type: string, description: "Alert ID" }
        status: { type: string, description: "New, InProgress or Resolved" }
        classification: { type: string, description: "TruePositive, FalsePositive or InformationalExpectedActivity" }
        determination: { type: string, description: "Determination, e.g. Malware, SecurityTesting" }
        assigned_to: { type: string, description: "Assignee" }
        comment: { type: string, description: "Comment" }
      required: [alert_id]
    outputs_schema: { properties: {} }

  # ── Machines ──────────────────────────────────────────────────────────────
  - id: list_machines
    name: microsoft-defender-endpoint-list-machines
    description: "List machines with an optional OData filter."
    risk: read
    inputs_schema:
      properties:
        filter: { type: string, description: "OData $filter expression" }
        limit: { type: number, description: "Maximum machines (default 50)" }
      required: []
    outputs_schema: { properties: {} }
  - id: get_machine
    name: microsoft-defender-endpoint-get-machine
    description: "Get a machine's details by machine ID."
    risk: read
    inputs_schema:
      properties:
        machine_id: { type: string, description: "Machine (device) ID" }
      required: [machine_id]
    outputs_schema: { properties: {} }
  - id: get_machine_by_ip
    name: microsoft-defender-endpoint-get-machine-by-ip
    description: "Find machines that last reported the given IP at a point in time."
    risk: read
    inputs_schema:
      properties:
        ip: { type: string, description: "IP address" }
        timestamp: { type: string, description: "Point in time, ISO8601 (default now)" }
      required: [ip]
    outputs_schema: { properties: {} }
  - id: isolate_machine
    name: microsoft-defender-endpoint-isolate-machine
    description: "Network-isolate a machine."
    risk: destructive
    inputs_schema:
      properties:
        machine_id: { type: string, description: "Machine ID" }
        comment: { type: string, description: "Reason for the action" }
        isolation_type: { type: string, description: "Full or Selective (default Full)" }
      required: [machine_id]
    outputs_schema: { properties: {} }
  - id: unisolate_machine
    name: microsoft-defender-endpoint-unisolate-machine
    description: "Release a machine from network isolation."
    risk: destructive
    inputs_schema:
      properties:
        machine_id: { type: string, description: "Machine ID" }
        comment: { type: string, description: "Reason for the action" }
      required: [machine_id]
    outputs_schema: { properties: {} }
  - id: restrict_app_execution
    name: microsoft-defender-endpoint-restrict-app-execution
    description: "Restrict application execution on a machine (allow only Microsoft-signed binaries)."
    risk: destructive
    inputs_schema:
      properties:
        machine_id: { type: string, description: "Machine ID" }
        comment: { type: string, description: "Reason for the action" }
      required: [machine_id]
    outputs_schema: { properties: {} }
  - id: remove_app_restriction
    name: microsoft-defender-endpoint-remove-app-restriction
    description: "Remove the application-execution restriction from a machine."
    risk: destructive
    inputs_schema:
      properties:
        machine_id: { type: string, description: "Machine ID" }
        comment: { type: string, description: "Reason for the action" }
      required: [machine_id]
    outputs_schema: { properties: {} }
  - id: run_antivirus_scan
    name: microsoft-defender-endpoint-run-antivirus-scan
    description: "Trigger a Defender antivirus scan on a machine."
    risk: safe_write
    inputs_schema:
      properties:
        machine_id: { type: string, description: "Machine ID" }
        scan_type: { type: string, description: "Quick or Full (default Quick)" }
        comment: { type: string, description: "Reason for the action" }
      required: [machine_id]
    outputs_schema: { properties: {} }
  - id: stop_and_quarantine_file
    name: microsoft-defender-endpoint-stop-and-quarantine-file
    description: "Stop execution of a file (by SHA1) and quarantine it on a machine."
    risk: destructive
    inputs_schema:
      properties:
        machine_id: { type: string, description: "Machine ID" }
        sha1: { type: string, description: "SHA1 of the file" }
        comment: { type: string, description: "Reason for the action" }
      required: [machine_id, sha1]
    outputs_schema: { properties: {} }
  - id: collect_investigation_package
    name: microsoft-defender-endpoint-collect-investigation-package
    description: "Collect a forensic investigation package from a machine (returns a machine action; poll it for the download URI)."
    risk: safe_write
    inputs_schema:
      properties:
        machine_id: { type: string, description: "Machine ID" }
        comment: { type: string, description: "Reason for the action" }
      required: [machine_id]
    outputs_schema: { properties: {} }
  - id: offboard_machine
    name: microsoft-defender-endpoint-offboard-machine
    description: "Offboard a machine from Defender for Endpoint."
    risk: destructive
    inputs_schema:
      properties:
        machine_id: { type: string, description: "Machine ID" }
        comment: { type: string, description: "Reason for the action" }
      required: [machine_id]
    outputs_schema: { properties: {} }
  - id: tag_machine
    name: microsoft-defender-endpoint-tag-machine
    description: "Add or remove a tag on a machine."
    risk: safe_write
    inputs_schema:
      properties:
        machine_id: { type: string, description: "Machine ID" }
        tag: { type: string, description: "Tag value" }
        action: { type: string, description: "Add or Remove (default Add)" }
      required: [machine_id, tag]
    outputs_schema: { properties: {} }
  - id: list_machine_actions
    name: microsoft-defender-endpoint-list-machine-actions
    description: "List machine actions (their status), optionally filtered."
    risk: read
    inputs_schema:
      properties:
        filter: { type: string, description: "OData $filter expression (e.g. machineId eq '...')" }
        limit: { type: number, description: "Maximum actions (default 50)" }
      required: []
    outputs_schema: { properties: {} }

  # ── Hunting / indicators ──────────────────────────────────────────────────
  - id: advanced_hunting
    name: microsoft-defender-endpoint-advanced-hunting
    description: "Run an advanced hunting KQL query."
    risk: read
    inputs_schema:
      properties:
        query: { type: string, description: "KQL query" }
      required: [query]
    outputs_schema: { properties: {} }
  - id: list_indicators
    name: microsoft-defender-endpoint-list-indicators
    description: "List custom threat indicators."
    risk: read
    inputs_schema:
      properties:
        filter: { type: string, description: "OData $filter expression" }
        limit: { type: number, description: "Maximum indicators (default 50)" }
      required: []
    outputs_schema: { properties: {} }
  - id: create_indicator
    name: microsoft-defender-endpoint-create-indicator
    description: "Create a custom indicator (file hash, IP, URL or domain) with an action."
    risk: destructive
    inputs_schema:
      properties:
        indicator_value: { type: string, description: "Indicator value (hash, IP, URL or domain)" }
        indicator_type: { type: string, description: "FileSha256, FileSha1, FileMd5, IpAddress, DomainName or Url" }
        action: { type: string, description: "Alert, AlertAndBlock, Block, Allowed or Warn (default Alert)" }
        title: { type: string, description: "Indicator title" }
        description: { type: string, description: "Indicator description" }
        severity: { type: string, description: "Informational, Low, Medium or High" }
        expiration_time: { type: string, description: "Expiration, ISO8601" }
      required: [indicator_value, indicator_type]
    outputs_schema: { properties: {} }
  - id: delete_indicator
    name: microsoft-defender-endpoint-delete-indicator
    description: "Delete a custom indicator by ID."
    risk: destructive
    inputs_schema:
      properties:
        indicator_id: { type: string, description: "Indicator ID" }
      required: [indicator_id]
    outputs_schema: { properties: {} }

  - id: test_connection
    name: microsoft-defender-endpoint-test-connection
    description: "Verify connectivity and credentials (used by the Test button)."
    risk: read
    inputs_schema:
      properties: {}
      required: []
    outputs_schema: { properties: {} }

ingestion:
  command: get_incidents
  mapper: get_incidents
  default_incident_type: "Microsoft Defender Alert"