id: microsoft_sentinel
name: Microsoft Sentinel
version: 1.0.0
description: "Microsoft Sentinel (Azure Resource Manager API) — incident management (list/get/create/update/delete, comments, related alerts/entities), watchlists, threat indicators, and incident ingestion (get_incidents) with an OCSF mapper. Azure AD OAuth 2.0 client-credentials authentication. Stdlib-only, no extra Python dependencies."
changelog: "1.0.0 — Initial release: incident CRUD + comments + related data, watchlist listing/upsert, threat indicator CRUD, and incident ingestion with an OCSF mapper."
category: siem

# Per-instance configuration. Register an Azure AD application, grant it the
# 'Microsoft Sentinel Contributor' (or Responder) role on the workspace's
# resource group, and admin-consent it. The scripts request an Azure Resource
# Manager token (client-credentials) and call https://management.azure.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
    subscription_id:
      type: string
      description: "Azure subscription ID that holds the Sentinel workspace"
    resource_group:
      type: string
      description: "Resource group of the Sentinel workspace"
    workspace_name:
      type: string
      description: "Log Analytics workspace name backing Sentinel"
  required:
    - tenant_id
    - client_id
    - client_secret
    - subscription_id
    - resource_group
    - workspace_name

commands:
  # ── Ingestion / incidents ─────────────────────────────────────────────────
  - id: get_incidents
    name: microsoft-sentinel-get-incidents
    description: "Fetch Sentinel incidents for ingestion. Returns {result:[...]}; use result as the alert rule results path."
    risk: read
    inputs_schema:
      properties:
        filter: { type: string, description: "OData $filter (e.g. properties/status eq 'New')" }
        created_after: { type: string, description: "Lower bound on createdTimeUtc, ISO8601 (incremental fetch watermark, applied via $filter)" }
        limit: { type: number, description: "Maximum incidents (default 50)" }
      required: []
    outputs_schema: { properties: {} }
    ingest:
      results_path: result
      dedup_key: name
      incremental_field: created_after
  - id: list_incidents
    name: microsoft-sentinel-list-incidents
    description: "List incidents with optional OData filter and ordering."
    risk: read
    inputs_schema:
      properties:
        filter: { type: string, description: "OData $filter expression" }
        orderby: { type: string, description: "OData $orderby (e.g. properties/createdTimeUtc desc)" }
        limit: { type: number, description: "Maximum incidents (default 50)" }
      required: []
    outputs_schema: { properties: {} }
  - id: get_incident
    name: microsoft-sentinel-get-incident
    description: "Get a single incident by its name (GUID)."
    risk: read
    inputs_schema:
      properties:
        incident_id: { type: string, description: "Incident name/ID (GUID)" }
      required: [incident_id]
    outputs_schema: { properties: {} }
  - id: create_incident
    name: microsoft-sentinel-create-incident
    description: "Create an incident."
    inputs_schema:
      properties:
        title: { type: string, description: "Incident title" }
        severity: { type: string, description: "Informational, Low, Medium or High" }
        status: { type: string, description: "New, Active or Closed (default New)" }
        description: { type: string, description: "Description" }
        assigned_to: { type: string, description: "Owner UPN/email" }
      required: [title, severity]
    outputs_schema: { properties: {} }
  - id: update_incident
    name: microsoft-sentinel-update-incident
    description: "Update an incident's title, status, severity, classification or owner."
    inputs_schema:
      properties:
        incident_id: { type: string, description: "Incident name/ID (GUID)" }
        title: { type: string, description: "New title" }
        status: { type: string, description: "New, Active or Closed" }
        severity: { type: string, description: "Informational, Low, Medium or High" }
        classification: { type: string, description: "Closing classification (BenignPositive, FalsePositive, TruePositive, Undetermined)" }
        classification_reason: { type: string, description: "Closing reason" }
        assigned_to: { type: string, description: "Owner UPN/email" }
        description: { type: string, description: "Description" }
      required: [incident_id]
    outputs_schema: { properties: {} }
  - id: delete_incident
    name: microsoft-sentinel-delete-incident
    description: "Delete an incident."
    inputs_schema:
      properties:
        incident_id: { type: string, description: "Incident name/ID (GUID)" }
      required: [incident_id]
    outputs_schema: { properties: {} }
  - id: add_comment
    name: microsoft-sentinel-add-comment
    description: "Add a comment to an incident."
    inputs_schema:
      properties:
        incident_id: { type: string, description: "Incident name/ID (GUID)" }
        comment: { type: string, description: "Comment message" }
      required: [incident_id, comment]
    outputs_schema: { properties: {} }
  - id: list_comments
    name: microsoft-sentinel-list-comments
    description: "List an incident's comments."
    risk: read
    inputs_schema:
      properties:
        incident_id: { type: string, description: "Incident name/ID (GUID)" }
        limit: { type: number, description: "Maximum comments (default 50)" }
      required: [incident_id]
    outputs_schema: { properties: {} }
  - id: list_incident_alerts
    name: microsoft-sentinel-list-incident-alerts
    description: "List the alerts associated with an incident."
    risk: read
    inputs_schema:
      properties:
        incident_id: { type: string, description: "Incident name/ID (GUID)" }
      required: [incident_id]
    outputs_schema: { properties: {} }
  - id: list_incident_entities
    name: microsoft-sentinel-list-incident-entities
    description: "List the entities (accounts, hosts, IPs, …) of an incident."
    risk: read
    inputs_schema:
      properties:
        incident_id: { type: string, description: "Incident name/ID (GUID)" }
      required: [incident_id]
    outputs_schema: { properties: {} }
  - id: list_incident_relations
    name: microsoft-sentinel-list-incident-relations
    description: "List an incident's relations (linked bookmarks and alerts)."
    risk: read
    inputs_schema:
      properties:
        incident_id: { type: string, description: "Incident name/ID (GUID)" }
      required: [incident_id]
    outputs_schema: { properties: {} }

  # ── Watchlists ────────────────────────────────────────────────────────────
  - id: list_watchlists
    name: microsoft-sentinel-list-watchlists
    description: "List watchlists in the workspace."
    risk: read
    inputs_schema:
      properties:
        limit: { type: number, description: "Maximum watchlists (default 50)" }
      required: []
    outputs_schema: { properties: {} }
  - id: list_watchlist_items
    name: microsoft-sentinel-list-watchlist-items
    description: "List the items of a watchlist."
    risk: read
    inputs_schema:
      properties:
        watchlist_alias: { type: string, description: "Watchlist alias" }
        limit: { type: number, description: "Maximum items (default 50)" }
      required: [watchlist_alias]
    outputs_schema: { properties: {} }
  - id: upsert_watchlist_item
    name: microsoft-sentinel-upsert-watchlist-item
    description: "Create or update a watchlist item (properties as a JSON object)."
    inputs_schema:
      properties:
        watchlist_alias: { type: string, description: "Watchlist alias" }
        item_id: { type: string, description: "Watchlist item ID (GUID; generated when omitted)" }
        item_json: { type: string, description: "Item key/value properties as a JSON object" }
      required: [watchlist_alias, item_json]
    outputs_schema: { properties: {} }

  # ── Threat indicators ─────────────────────────────────────────────────────
  - id: list_threat_indicators
    name: microsoft-sentinel-list-threat-indicators
    description: "List threat intelligence 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_threat_indicator
    name: microsoft-sentinel-create-threat-indicator
    description: "Create a threat intelligence indicator."
    inputs_schema:
      properties:
        value: { type: string, description: "Indicator value" }
        pattern_type: { type: string, description: "Type: ipv4-addr, domain-name, url, file:hashes.'SHA-256', …" }
        display_name: { type: string, description: "Display name" }
        threat_types: { type: string, description: "Comma-separated threat types (e.g. malicious-activity)" }
        confidence: { type: number, description: "Confidence 0-100" }
        valid_until: { type: string, description: "Expiration, ISO8601" }
      required: [value, pattern_type]
    outputs_schema: { properties: {} }
  - id: update_threat_indicator
    name: microsoft-sentinel-update-threat-indicator
    description: "Update a threat intelligence indicator (display name, confidence, expiry, threat types)."
    inputs_schema:
      properties:
        indicator_name: { type: string, description: "Indicator name (from list_threat_indicators)" }
        display_name: { type: string, description: "Display name" }
        confidence: { type: number, description: "Confidence 0-100" }
        valid_until: { type: string, description: "Expiration, ISO8601" }
        threat_types: { type: string, description: "Comma-separated threat types" }
      required: [indicator_name]
    outputs_schema: { properties: {} }
  - id: delete_threat_indicator
    name: microsoft-sentinel-delete-threat-indicator
    description: "Delete a threat intelligence indicator by name."
    inputs_schema:
      properties:
        indicator_name: { type: string, description: "Indicator name (from list_threat_indicators)" }
      required: [indicator_name]
    outputs_schema: { properties: {} }

  - id: test_connection
    name: microsoft-sentinel-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 Sentinel Incident"