Contraforce Cross-workspace incidents API

openapi: 3.2.0
info:
  title: ContraForce Cross-workspace incidents API
  description: ContraForce platform API for security operations management.
  version: '2.0'
tags:
- name: Cross-workspace incidents
paths:
  /api/v2/incidents/across-workspaces:
    post:
      tags:
      - Cross-workspace incidents
      summary: List incidents across workspaces
      operationId: v2-list-incidents-across-workspaces
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListIncidentsAcrossWorkspacesRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseOfListIncidentsForWorkspacesResultDto'
        '400':
          description: Bad request — validation or parameter binding failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '401':
          description: Unauthorized — missing or invalid Bearer token.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '403':
          description: Forbidden — insufficient scope or workspace access.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '404':
          description: Not found — workspace or resource is missing.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
  /api/v2/incidents/across-workspaces/bulk-update:
    post:
      tags:
      - Cross-workspace incidents
      summary: Bulk update incidents across workspaces
      operationId: v2-bulk-update-incidents-across-workspaces
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkUpdateIncidentsRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseOfBulkUpdateIncidentResultDto'
        '400':
          description: Bad request — validation or parameter binding failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '401':
          description: Unauthorized — missing or invalid Bearer token.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '403':
          description: Forbidden — insufficient scope or workspace access.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '404':
          description: Not found — workspace or resource is missing.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
components:
  schemas:
    Status:
      enum:
      - Active
      - New
      - Closed
      - OnHold
      - WaitingOnCustomer
    ResponseMeta:
      type: object
      properties:
        requestId:
          type:
          - 'null'
          - string
        timestamp:
          type:
          - 'null'
          - string
    ClassificationReason:
      enum:
      - InaccurateData
      - IncorrectAlertLogic
      - SuspiciousActivity
      - SuspiciousButExpected
      - Unknown
      - Apt
      - Malware
      - SecurityPersonnel
      - SecurityTesting
      - UnwantedSoftware
      - Other
      - MultistagedAttack
      - CompromisedUser
      - Phishing
      - MaliciousUserActivity
      - NotMalicious
      - NoEnoughDataToValidate
      - ConfirmedUserActivity
      - LineOfBusinessApplication
      - null
    BulkUpdateIncidentResultDto:
      type: object
      properties:
        accepted:
          type:
          - 'null'
          - array
          items:
            type: string
          description: Incident IDs the caller is authorized to update. These are scheduled for async processing.
        forbidden:
          type:
          - 'null'
          - array
          items:
            description: Per-incident rejection detail for a bulk update.
            $ref: '#/components/schemas/ForbiddenBulkUpdateIncidentDto'
          description: Incidents the caller is not authorized to update, grouped with the reason.
      description: Outcome of a bulk incident update request after per-incident authorization.
    ForbiddenBulkUpdateIncidentDto:
      type: object
      properties:
        incidentId:
          type:
          - 'null'
          - string
        workspaceId:
          type:
          - 'null'
          - string
        reason:
          type:
          - 'null'
          - string
      description: Per-incident rejection detail for a bulk update.
    ListIncidentsForWorkspacesResultDto:
      type: object
      properties:
        incidents:
          type:
          - 'null'
          - array
          items:
            description: This incident object built on top of the Microsoft Azure Sentinel Incident and it's open to extend to any new provider
            $ref: '#/components/schemas/Incident'
          description: 'Incidents returned for this page across all workspaces and sources the caller

            has access to. Aggregated and merged in time-descending order by the server.'
        sourcePageTokens:
          type:
          - 'null'
          - array
          items:
            description: Opaque continuation tokens for a single workspace, partitioned by incident source.
            $ref: '#/components/schemas/WorkspaceSourcePageTokens'
          description: 'Opaque per-workspace, per-source continuation tokens for fetching the next

            page. Pass this value verbatim as `WorkspacePageTokens` on the next

            request along with `IsFirstCall = false`.'
        moreIncidentsAvailable:
          type: boolean
          description: "`true` when at least one workspace/source still has additional pages.\n        When `false`, the caller has consumed the full result set and may stop\n        paging."
      description: Wraps the result of listing incidents for multiple workspaces in the multi-tenancy mode.
    SentinelIncidentIdentifiers:
      type: object
      properties:
        armId:
          type:
          - 'null'
          - string
          description: 'The full ARM resource id, e.g.

            `/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.OperationalInsights/workspaces/{ws}/providers/Microsoft.SecurityInsights/incidents/{guid}`.'
        incidentId:
          type:
          - 'null'
          - string
          description: The incident GUID, the last segment of string SentinelIncidentIdentifiers.ArmId.
        subscriptionId:
          type:
          - 'null'
          - string
          description: The Azure subscription holding the Log Analytics workspace.
        resourceGroupName:
          type:
          - 'null'
          - string
          description: The resource group holding the Log Analytics workspace.
        workspaceName:
          type:
          - 'null'
          - string
          description: The Log Analytics workspace name.
        incidentNumber:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - 'null'
          - integer
          - string
          description: The incident's number within the Sentinel workspace, when known.
          format: int32
        portalUrl:
          type:
          - 'null'
          - string
          description: Direct link to the incident in the Microsoft Sentinel portal.
      description: Microsoft Sentinel's identifiers for an incident.
    WorkspaceSourcePageTokens:
      type: object
      properties:
        workspaceId:
          type:
          - 'null'
          - string
          description: Identifier of the workspace these tokens belong to.
        sourceTokens:
          type:
          - 'null'
          - object
          additionalProperties:
            type: string
          description: 'Per-source continuation tokens. Each entry represents one more page of incidents

            available from that source within this workspace; absent sources have no further

            pages.'
      description: Opaque continuation tokens for a single workspace, partitioned by incident source.
    ApiProblemDetails:
      type: object
      properties:
        type:
          type:
          - 'null'
          - string
        title:
          type:
          - 'null'
          - string
        status:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - 'null'
          - integer
          - string
          format: int32
        detail:
          type:
          - 'null'
          - string
        instance:
          type:
          - 'null'
          - string
        code:
          type:
          - 'null'
          - string
        requestId:
          type:
          - 'null'
          - string
        timestamp:
          type:
          - 'null'
          - string
        target:
          type:
          - 'null'
          - string
        errors:
          type:
          - 'null'
          - object
          additionalProperties:
            type: array
            items:
              type: string
      description: 'API extension of ProblemDetails that surfaces the stable error code,

        trace identifier, timestamp, optional target, and optional field-keyed validation

        error map alongside the RFC 7807 members.'
    UpdateIncidentRequest:
      required:
      - id
      type: object
      properties:
        id:
          type:
          - 'null'
          - string
        status:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/Status'
        user:
          description: Represents a light version of the user object, that is used to add reference to a specific user in a foreign entities
          $ref: '#/components/schemas/UserSummary'
        workspace:
          type:
          - 'null'
          - string
          description: Indicates the workspace that the incident is related to in case of multi-workspace environments
        removeAssignee:
          type: boolean
          description: 'If UserId is set to null but this is set to true,

            the incident will be unassigned,

            otherwise it will stay assigned to the current user'
        comment:
          type:
          - 'null'
          - string
        classification:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/Classification'
        classificationReason:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/ClassificationReason'
        incidentSource:
          description: The source system that contains the incident like Sentinel, Defender ..etc
          $ref: '#/components/schemas/IncidentSource'
    ApiResponseOfBulkUpdateIncidentResultDto:
      type: object
      properties:
        data:
          description: Outcome of a bulk incident update request after per-incident authorization.
          $ref: '#/components/schemas/BulkUpdateIncidentResultDto'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      description: Standard v2 API response envelope for single-item responses.
    TimeFilteringType:
      enum:
      - ThreeHours
      - SixHours
      - TwelveHours
      - TwentyFourHours
      - FortyEightHours
      - Custom
      - SevenDays
      - ThirtyDays
      - NinetyDays
      - OneHundredEightyDays
      - SixtyDays
      - null
    TimeFilterSelection:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/TimeFilteringType'
        customStartUtc:
          type:
          - 'null'
          - string
          format: date-time
        customEndUtc:
          type:
          - 'null'
          - string
          format: date-time
      description: 'Canonical representation of a global time filter.

        When Type == Custom, CustomStartUtc and CustomEndUtc must be provided (UTC).'
    IncidentSource:
      enum:
      - Sentinel
      - DefenderXDR
      - QRadar
      - Splunk
      - CrowdStrike
      - SentinelOne
      - SumoLogic
    ApiResponseOfListIncidentsForWorkspacesResultDto:
      type: object
      properties:
        data:
          description: Wraps the result of listing incidents for multiple workspaces in the multi-tenancy mode.
          $ref: '#/components/schemas/ListIncidentsForWorkspacesResultDto'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      description: Standard v2 API response envelope for single-item responses.
    Incident:
      type: object
      properties:
        id:
          type:
          - 'null'
          - string
        name:
          type:
          - 'null'
          - string
        displayId:
          type:
          - 'null'
          - string
          description: 'Optional human-readable identifier shown in the table and

            page heading instead of the long opaque string Incident.Id.

            Populated for sources whose IDs are unwieldy (e.g. CrowdStrike

            cases use a 165-char base64 ID but expose a friendly

            "`6F1-24`"-style `reference_id`). When null, callers

            fall back to the existing short-form derivation of

            string Incident.Id.'
        title:
          type:
          - 'null'
          - string
        description:
          type:
          - 'null'
          - string
        number:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - integer
          - string
          format: int32
        type:
          type:
          - 'null'
          - string
        source:
          $ref: '#/components/schemas/IncidentSource'
        sourceDisplayName:
          type:
          - 'null'
          - string
        lastModificationTime:
          type:
          - 'null'
          - string
          description: Date/Time represents the user's local time
          format: date-time
        creationTime:
          type: string
          description: Date/Time represents the user's local time
          format: date-time
        lastActivityTime:
          type:
          - 'null'
          - string
          description: Date/Time represents the user's local time
          format: date-time
        severity:
          $ref: '#/components/schemas/Severity'
        classification:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/Classification'
        comment:
          type:
          - 'null'
          - string
        classificationReason:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/ClassificationReason'
        classificationComment:
          type:
          - 'null'
          - string
        tactics:
          type:
          - 'null'
          - array
          items:
            type: string
        ruleIds:
          type:
          - 'null'
          - array
          items:
            type: string
          description: Represents the Ids of the related rules of this incidents
        providerName:
          type:
          - 'null'
          - string
          description: 'The vendor that generated this incident, as the vendor reports it. Sentinel returns

            "Azure Sentinel", "Microsoft 365 Defender" or "Microsoft XDR"; other sources leave it null.'
        isForwardedMirror:
          type: boolean
          description: 'True when this incident is the mirror of one that originated in the other Microsoft system, so

            showing it would put the same real-world incident in the inbox twice.'
        vendorIdentifiers:
          description: 'The identifiers of every vendor system that holds a record of this incident, for consumers that

            need to resolve it back to the source vendor.'
          $ref: '#/components/schemas/IncidentVendorIdentifiers'
        alertProductNames:
          type:
          - 'null'
          - array
          items:
            type: string
        user:
          description: Represents the user assigned to work on this incident
          $ref: '#/components/schemas/UserSummary'
        isAssigned:
          type: boolean
        productId:
          type:
          - 'null'
          - string
        status:
          $ref: '#/components/schemas/Status'
        closedUpstreamDuringPause:
          type: boolean
          description: 'Set by `IncidentsManager.GetByIdAsync` reconciliation when the CF incident is in a

            CF-native pause status (Status.OnHold / Status.WaitingOnCustomer)

            but the upstream source has reached terminal Closed. The UI uses this to render the

            "Closed upstream while paused" badge on the detail header. Not persisted.'
        sourceRecordExpired:
          type: boolean
          description: 'True when the source no longer holds this incident''s record, so only what ContraForce recorded

            (status, classification, owner, comments) can be shown.'
        sourceLinks:
          type:
          - 'null'
          - array
          items:
            description: A labeled link to an incident's record in its source console.
            $ref: '#/components/schemas/IncidentSourceLink'
          description: 'Links to this incident in the source''s own console, when the source provides them (for

            example the Sumo Logic monitor and the search behind the alert). Always absolute HTTPS URLs.'
        alertsCount:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - integer
          - string
          format: int32
        entities:
          type:
          - 'null'
          - array
          items:
            description: This class is used to unify the Entities from different sources into a ContraForce Entity
            $ref: '#/components/schemas/IncidentEntity'
        workspaceName:
          type:
          - 'null'
          - string
          description: 'Name of the workspace in the customer tenant

            This property is beneficial when the customer has multiple workspaces or when the partner is working under the multi-tenancy mode'
        workspaceId:
          type:
          - 'null'
          - string
          description: 'Name of the workspace in the customer tenant

            This property is beneficial when the customer has multiple workspaces or when the partner is working under the multi-tenancy mode'
        isDefenderXDRSourced:
          type: boolean
          description: Determines whether the incident is originally sourced from Microsoft Defender XDR
      description: This incident object built on top of the Microsoft Azure Sentinel Incident and it's open to extend to any new provider
    IncidentEntity:
      type: object
      properties:
        id:
          type:
          - 'null'
          - string
        type:
          $ref: '#/components/schemas/EntityType'
        kind:
          type:
          - 'null'
          - string
        displayName:
          type:
          - 'null'
          - string
        friendlyName:
          type:
          - 'null'
          - string
        fileName:
          type:
          - 'null'
          - string
        hostName:
          type:
          - 'null'
          - string
        accountEntityId:
          type:
          - 'null'
          - string
        deviceId:
          type:
          - 'null'
          - string
        deviceAzureId:
          type:
          - 'null'
          - string
        defenderAtpDeviceId:
          type:
          - 'null'
          - string
        defenderEndpointDeviceId:
          type:
          - 'null'
          - string
        networkMessageId:
          type:
          - 'null'
          - string
        hashAlgorithm:
          type:
          - 'null'
          - string
        aadUserId:
          type:
          - 'null'
          - string
        emailAddress:
          type:
          - 'null'
          - string
        userPrincipalName:
          type:
          - 'null'
          - string
        ipAddress:
          type:
          - 'null'
          - string
        fileHash:
          type:
          - 'null'
          - string
        emailId:
          type:
          - 'null'
          - string
        emailSubject:
          type:
          - 'null'
          - string
      description: This class is used to unify the Entities from different sources into a ContraForce Entity
    EntityType:
      enum:
      - User
      - IP
      - File
      - Process
      - Device
      - Malware
      - CloudApplication
      - DomainName
      - AzureResource
      - FileHash
      - RegistryKey
      - RegistryValue
      - SecurityGroup
      - URL
      - IoTDevice
      - Mailbox
      - MailCluster
      - MailMessage
      - Submission
      - SentinelEntities
      - DnsResolution
      - Registry
      - OAuthApplication
      - AmazonResource
      - BlobContainer
      - Blob
      - Container
      - ContainerRegistry
      - ContainerImage
      - GoogleCloudResource
      - KubernetesCluster
      - KubernetesController
      - KubernetesNamespace
      - KubernetesPod
      - KubernetesService
      - KubernetesSecret
      - KubernetesServiceAccount
      - AnalyzedMessage
      - DNS
      - Unknown
    ListIncidentsAcrossWorkspacesRequest:
      type: object
      properties:
        severities:
          type:
          - 'null'
          - array
          items:
            $ref: '#/components/schemas/Severity'
          description: Filter incidents to only the listed severities. Empty list returns all severities.
        statuses:
          type:
          - 'null'
          - array
          items:
            $ref: '#/components/schemas/Status'
          description: Filter incidents to only the listed statuses. Empty list returns all statuses.
        timeFilterSelection:
          description: Time window applied to the incident's creation time, or to its last-modified time when `filterByLastModified` is `true`. Defaults to the last 24 hours.
          $ref: '#/components/schemas/TimeFilterSelection'
        filterByLastModified:
          type: boolean
          description: 'When `true`, `timeFilterSelection` bounds the incident''s last-modified time instead of its creation time, and each page is ordered by last-modified time descending. Use this to synchronise updates into an external system: poll a short window that ends at the time of the call and receive every incident whose Microsoft Sentinel or Microsoft Defender XDR record changed in that window (alert grouped in, severity, status, owner, label, comment), including incidents created long before the window. An incident created inside the window but modified after its end is not in this window; it appears in the next one. In this mode each workspace''s window is returned in full in one call unless it exceeds the server''s page cap; if `moreIncidentsAvailable` is `true`, narrow the window rather than paging, because vendor continuations are positional and a concurrent edit can shift them. The timestamp is the vendor''s (`lastModifiedTimeUtc` / `lastUpdateDateTime`), not `lastActivityTime`. Supported for `Sentinel` and `DefenderXDR` only: an empty `sources` list selects those two, and listing any other source together with this flag returns 400.'
        workspacePageTokens:
          type:
          - 'null'
          - array
          items:
            description: Opaque continuation tokens for a single workspace, partitioned by incident source.
            $ref: '#/components/schemas/WorkspaceSourcePageTokens'
          description: 'Opaque pagination tokens echoed from the previous response''s `SourcePageTokens`.

            Leave empty on the first call. See type-level remarks for the pagination protocol.'
        query:
          type:
          - 'null'
          - string
          description: Free-text search applied across incident title/description fields. Empty matches all.
        isFirstCall:
          type: boolean
          description: "`true` for the initial request; `false` when echoing\n        List<WorkspaceSourcePageTokens> ListIncidentsAcrossWorkspacesRequest.WorkspacePageTokens back for subsequent pages. See type-level\n        remarks for the pagination protocol."
        sources:
          type:
          - 'null'
          - array
          items:
            $ref: '#/components/schemas/IncidentSource'
          description: 'Filter incidents to only the listed sources (e.g. Sentinel, DefenderXDR,

            CrowdStrike). Empty list returns all sources the caller has access to.'
        assigneeIds:
          type:
          - 'null'
          - array
          items:
            type: string
          description: Filter incidents assigned to any of the listed ContraForce user IDs.
        assigneeEmails:
          type:
          - 'null'
          - array
          items:
            type: string
          description: Filter incidents assigned to any of the listed user email addresses.
        includeUnassigned:
          type: boolean
          description: 'When `true`, include incidents that have no assignee alongside any

            matches from List<string> ListIncidentsAcrossWorkspacesRequest.AssigneeIds / List<string> ListIncidentsAcrossWorkspacesRequest.AssigneeEmails.'
      description: v2 request for listing incidents across multiple workspaces.
    Severity:
      enum:
      - Informational
      - Low
      - Medium
      - High
    IncidentVendorIdentifiers:
      type: object
      properties:
        sentinel:
          description: Sentinel's identifiers for this incident, when it exists in Sentinel.
          $ref: '#/components/schemas/SentinelIncidentIdentifiers'
        defender:
          description: Defender XDR's identifiers for this incident, when it exists in Defender XDR.
          $ref: '#/components/schemas/DefenderIncidentIdentifiers'
      description: 'The identifiers of every vendor system that holds a record of one incident, carried together so an

        external consumer can resolve the incident back to whichever system it standardizes on.'
    Classification:
      enum:
      - BenignPositive
      - FalsePositive
      - TruePositive
      - Undetermined
      - null
    UserSummary:
      type: object
      properties:
        id:
          type:
          - 'null'
          - string
        displayName:
          type:
          - 'null'
          - string
        email:
          type:
          - 'null'
          - string
      description: Represents a light version of the user object, that is used to add reference to a specific user in a foreign entities
    BulkUpdateIncidentsRequest:
      type: object
      properties:
        items:
          type:
          - 'null'
          - array
          items:
            $ref: '#/components/schemas/UpdateIncidentRequest'
      description: v2 request body for the cross-workspace bulk incident update endpoint.
    DefenderIncidentIdentifiers:
      type: object
      properties:
        incidentId:
          type:
          - 'null'
          - string
          description: The Defender XDR incident id.
        tenantId:
          type:
          - 'null'
          - string
          description: The Entra tenant the Defender incident belongs to, when the vendor reported it.
        portalUrl:
          type:
          - 'null'
          - string
          description: Direct link to the incident in the Microsoft Defender portal.
      description: Microsoft Defender XDR's identifiers for an incident.
    IncidentSourceLink:
      type: object
      properties:
        label:
          type:
          - 'null'
          - string
          description: What the link opens, for example "Monitor" or "Search".
        url:
          type:
          - 'null'
          - string
          description: Absolute HTTPS URL; producers validate it before setting it.
      description: A labeled link to an incident's record in its source console.