id: sekoia_xdr
name: Sekoia XDR
version: 1.0.0
description: "Sekoia Defend (XDR) REST API — alert ingestion and lifecycle (list/get/search, status workflow, comments), event search jobs (create/status/results + one-shot search), cases, asset management (get/list, attributes/keys add/remove), users, kill chains and a generic authenticated HTTP passthrough."
changelog: "1.0.0 — Initial release: alert ingestion (list_alerts) with an exhaustive OCSF mapper, 20 commands across alerts, event search, cases, assets, users and kill chains."
category: siem

# Per-instance configuration. The API host defaults to the EU region; an
# Organization API key is sent as a Bearer token.
config_schema:
  properties:
    url:
      type: string
      description: "Sekoia API base URL, e.g. https://api.sekoia.io"
      default: https://api.sekoia.io
    api_key:
      type: string
      description: "Sekoia API key (Bearer token)"
      x-soar-sensitive: true
  required:
    - url
    - api_key

auth:
  - id: bearer
    type: api_key
    in: header
    name: Authorization
    value_template: "Bearer {{secret}}"
    secret_field: api_key

commands:
  # ── Ingestion ───────────────────────────────────────────────────────────────
  - id: list_alerts
    name: sekoia-xdr-list-alerts
    description: "List alerts, sorted by created_at. Used for ingestion: results path = items. Alerts aggregate the matching events and are tied to rules and a kill chain."
    risk: read
    inputs_schema:
      properties:
        limit: { type: number, description: "Number of alerts to return (1-100, default 20)" }
        status: { type: string, description: "Comma-separated statuses to include (Pending, Acknowledged, Ongoing, Rejected, Closed)" }
        created_at: { type: string, description: "Filter by creation date. A bare date is treated as the lower bound ('<date>,now'); a range '<start>,<end>' is passed through. Incremental fetch watermark." }
        updated_at: { type: string, description: "Filter by update date, same format as created_at" }
        urgency: { type: string, description: "Urgency range 'MIN,MAX' (e.g. 80,100)" }
        alerts_type: { type: string, description: "Comma-separated alert categories (e.g. malware,phishing)" }
        sort_by: { type: string, description: "Field to sort by (created_at, updated_at, target, urgency, status). Default created_at." }
        direction: { type: string, description: "Sort direction (asc, desc). Default asc." }
        offset: { type: number, description: "Result offset for paging" }
      required: []
    outputs_schema: { properties: {} }
    ingest:
      results_path: items
      dedup_key: uuid
      incremental_field: created_at

  - id: get_alert
    name: sekoia-xdr-get-alert
    description: "Retrieve a single alert by UUID or short_id."
    risk: read
    inputs_schema:
      properties:
        id: { type: string, description: "Alert UUID or short_id (e.g. ALUnyZCYZ9Ga)" }
      required: [id]
    outputs_schema: { properties: {} }

  - id: search_events
    name: sekoia-xdr-search-events
    description: "Search events for an alert in one call: creates an event search job, waits for it to finish and returns the events. Falls back to returning the job UUID if it is still running."
    risk: read
    inputs_schema:
      properties:
        earliest_time: { type: string, description: "Lower time bound (e.g. -3d, -2w, or ISO 8601 2023-01-15T00:00:00Z)" }
        latest_time: { type: string, description: "Upper time bound (e.g. now, +1d, or ISO 8601)" }
        query: { type: string, description: "Event query, e.g. alert_short_ids:ALUnyZCYZ9Ga" }
        max_last_events: { type: string, description: "Maximum number of events to return" }
      required: [earliest_time, latest_time]
    outputs_schema: { properties: {} }

  - id: events_execute_query
    name: sekoia-xdr-events-execute-query
    description: "Create an event search job. Use events_status_query then events_results_query to poll and retrieve, or use search_events for a one-shot."
    risk: read
    inputs_schema:
      properties:
        earliest_time: { type: string, description: "Lower time bound (e.g. -3d or ISO 8601)" }
        latest_time: { type: string, description: "Upper time bound (e.g. now or ISO 8601)" }
        query: { type: string, description: "Event query, e.g. alert_short_ids:ALUnyZCYZ9Ga" }
        max_last_events: { type: string, description: "Maximum number of events to return" }
      required: [earliest_time, latest_time]
    outputs_schema: { properties: {} }

  - id: events_status_query
    name: sekoia-xdr-events-status-query
    description: "Get the status of a previously created event search job."
    risk: read
    inputs_schema:
      properties:
        uuid: { type: string, description: "Event search job UUID" }
      required: [uuid]
    outputs_schema: { properties: {} }

  - id: events_results_query
    name: sekoia-xdr-events-results-query
    description: "Retrieve the events of a finished event search job."
    risk: read
    inputs_schema:
      properties:
        uuid: { type: string, description: "Event search job UUID" }
      required: [uuid]
    outputs_schema: { properties: {} }

  - id: update_status_alert
    name: sekoia-xdr-update-status-alert
    description: "Change the status of an alert by applying the matching workflow transition (Acknowledged, Rejected, Ongoing, Closed)."
    risk: safe_write
    inputs_schema:
      properties:
        id: { type: string, description: "Alert UUID or short_id" }
        status: { type: string, description: "New status: Acknowledged, Rejected, Ongoing or Closed" }
        comment: { type: string, description: "Optional comment describing the status change" }
      required: [id, status]
    outputs_schema: { properties: {} }

  - id: post_comment_alert
    name: sekoia-xdr-post-comment-alert
    description: "Post a comment on an alert."
    risk: safe_write
    inputs_schema:
      properties:
        id: { type: string, description: "Alert UUID or short_id" }
        comment: { type: string, description: "Comment content" }
        author: { type: string, description: "Optional comment author" }
      required: [id, comment]
    outputs_schema: { properties: {} }

  - id: get_comments
    name: sekoia-xdr-get-comments
    description: "Get all comments of an alert."
    risk: read
    inputs_schema:
      properties:
        id: { type: string, description: "Alert UUID or short_id" }
      required: [id]
    outputs_schema: { properties: {} }

  - id: get_workflow_alert
    name: sekoia-xdr-get-workflow-alert
    description: "Get the available status transitions for an alert."
    risk: read
    inputs_schema:
      properties:
        id: { type: string, description: "Alert UUID or short_id" }
      required: [id]
    outputs_schema: { properties: {} }

  - id: get_cases_alert
    name: sekoia-xdr-get-cases-alert
    description: "Retrieve the cases related to an alert. If case_id is given, only that case is returned."
    risk: read
    inputs_schema:
      properties:
        alert_id: { type: string, description: "Alert UUID or short_id" }
        case_id: { type: string, description: "Optional case short_id (e.g. CAQNurTJM8q2)" }
      required: [alert_id]
    outputs_schema: { properties: {} }

  - id: get_asset
    name: sekoia-xdr-get-asset
    description: "Get an asset by its UUID."
    risk: read
    inputs_schema:
      properties:
        asset_uuid: { type: string, description: "Asset UUID" }
      required: [asset_uuid]
    outputs_schema: { properties: {} }

  - id: list_assets
    name: sekoia-xdr-list-assets
    description: "List assets, optionally filtered by type."
    risk: read
    inputs_schema:
      properties:
        limit: { type: number, description: "Number of assets to return (default 10)" }
        assets_type: { type: string, description: "Filter by asset type name (e.g. computer, network)" }
      required: []
    outputs_schema: { properties: {} }

  - id: get_user
    name: sekoia-xdr-get-user
    description: "Get information about a user by UUID (e.g. a comment author)."
    risk: read
    inputs_schema:
      properties:
        user_uuid: { type: string, description: "User UUID" }
      required: [user_uuid]
    outputs_schema: { properties: {} }

  - id: add_attributes_asset
    name: sekoia-xdr-add-attributes-asset
    description: "Add an attribute (name/value) to an asset."
    risk: safe_write
    inputs_schema:
      properties:
        asset_uuid: { type: string, description: "Asset UUID" }
        name: { type: string, description: "Attribute name" }
        value: { type: string, description: "Attribute value" }
      required: [asset_uuid, name, value]
    outputs_schema: { properties: {} }

  - id: add_keys_asset
    name: sekoia-xdr-add-keys-asset
    description: "Add a key (name/value) to an asset."
    risk: safe_write
    inputs_schema:
      properties:
        asset_uuid: { type: string, description: "Asset UUID" }
        name: { type: string, description: "Key name" }
        value: { type: string, description: "Key value" }
      required: [asset_uuid, name, value]
    outputs_schema: { properties: {} }

  - id: remove_attribute_asset
    name: sekoia-xdr-remove-attribute-asset
    description: "Remove an attribute from an asset. Use get_asset to find the attribute UUID."
    risk: destructive
    inputs_schema:
      properties:
        asset_uuid: { type: string, description: "Asset UUID" }
        attribute_uuid: { type: string, description: "UUID of the attribute to remove" }
      required: [asset_uuid, attribute_uuid]
    outputs_schema: { properties: {} }

  - id: remove_key_asset
    name: sekoia-xdr-remove-key-asset
    description: "Remove a key from an asset. Use get_asset to find the key UUID."
    risk: destructive
    inputs_schema:
      properties:
        asset_uuid: { type: string, description: "Asset UUID" }
        key_uuid: { type: string, description: "UUID of the key to remove" }
      required: [asset_uuid, key_uuid]
    outputs_schema: { properties: {} }

  - id: get_kill_chain
    name: sekoia-xdr-get-kill-chain
    description: "Retrieve the definition of a Cyber Kill Chain step by UUID or short_id."
    risk: read
    inputs_schema:
      properties:
        kill_chain_uuid: { type: string, description: "Kill chain UUID or short_id" }
      required: [kill_chain_uuid]
    outputs_schema: { properties: {} }

  - id: http_request
    name: sekoia-xdr-http-request
    description: "Perform an authenticated HTTP request to the Sekoia API. Advanced escape hatch for endpoints without a dedicated command."
    inputs_schema:
      properties:
        method: { type: string, description: "HTTP method (GET, POST, PUT, PATCH, DELETE). Default GET." }
        url_suffix: { type: string, description: "Path after the base URL, e.g. /v1/sic/alerts/ or /v1/asset-management/assets/" }
        parameters: { type: string, description: "Query parameters as a JSON object string, e.g. {\"limit\": 10}" }
        data: { type: string, description: "Request body as a JSON object string (for POST/PUT/PATCH)" }
      required: [url_suffix]
    outputs_schema: { properties: {} }

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

ingestion:
  command: list_alerts
  mapper: list_alerts
  default_incident_type: "Sekoia XDR Alert"