id: microsoft_defender_o365
name: Microsoft Defender for Office 365
version: 1.0.0
description: "Microsoft Defender for Office 365 email remediation (Microsoft Graph mail APIs) — anti-phishing containment: search a mailbox for messages, read a message and its attachments, move a message to a folder, and hard-delete (purge) a phishing message. Azure AD OAuth2 client-credentials authentication; stdlib-only, no extra Python dependencies."
changelog: "1.0.0 — Initial release: search mailbox messages, get message, list attachments, list folders, move message, delete (purge) message."
category: email

# Per-instance configuration. Uses application (client-credentials) OAuth2.
# The app registration needs Graph application permission Mail.ReadWrite.
config_schema:
  properties:
    tenant_id:
      type: string
      description: "Azure AD tenant ID"
    client_id:
      type: string
      description: "App registration (client) ID"
    client_secret:
      type: string
      description: "App registration client secret"
      x-soar-sensitive: true
  required:
    - tenant_id
    - client_id
    - client_secret

commands:
  - id: search_messages
    name: mdo-search-messages
    description: "Search a mailbox for messages by sender, subject, or free-text search."
    risk: read
    inputs_schema:
      properties:
        mailbox: { type: string, description: "Target mailbox (user principal name or ID)" }
        subject: { type: string, description: "Filter by exact subject" }
        from_address: { type: string, description: "Filter by sender address" }
        search: { type: string, description: "Free-text $search query (KQL) over the mailbox" }
        limit: { type: number, description: "Max messages (default 25)" }
      required: [mailbox]
    outputs_schema: { properties: {} }
  - id: get_message
    name: mdo-get-message
    description: "Get a single message by ID."
    risk: read
    inputs_schema:
      properties:
        mailbox: { type: string, description: "Target mailbox (UPN or ID)" }
        message_id: { type: string, description: "Message ID" }
      required: [mailbox, message_id]
    outputs_schema: { properties: {} }
  - id: list_attachments
    name: mdo-list-attachments
    description: "List a message's attachments."
    risk: read
    inputs_schema:
      properties:
        mailbox: { type: string, description: "Target mailbox (UPN or ID)" }
        message_id: { type: string, description: "Message ID" }
      required: [mailbox, message_id]
    outputs_schema: { properties: {} }
  - id: list_folders
    name: mdo-list-folders
    description: "List the mail folders of a mailbox (to obtain destination IDs for move)."
    risk: read
    inputs_schema:
      properties:
        mailbox: { type: string, description: "Target mailbox (UPN or ID)" }
      required: [mailbox]
    outputs_schema: { properties: {} }
  - id: move_message
    name: mdo-move-message
    description: "Move a message to another folder (e.g. to Junk Email or a quarantine folder)."
    inputs_schema:
      properties:
        mailbox: { type: string, description: "Target mailbox (UPN or ID)" }
        message_id: { type: string, description: "Message ID" }
        destination_id: { type: string, description: "Destination folder ID or well-known name (e.g. junkemail, deleteditems)" }
      required: [mailbox, message_id, destination_id]
    outputs_schema: { properties: {} }
  - id: delete_message
    name: mdo-delete-message
    description: "Hard-delete (purge) a message from the mailbox."
    inputs_schema:
      properties:
        mailbox: { type: string, description: "Target mailbox (UPN or ID)" }
        message_id: { type: string, description: "Message ID" }
      required: [mailbox, message_id]
    outputs_schema: { properties: {} }

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