openapi: 3.0.0 info: title: Cases API description: This is the OAS 3.0 specification for the Cases API in Sophos Central. version: 1.3.0 contact: name: Sophos Central APIs email: apis@sophos.com url: 'https://developer.sophos.com' tags: - name: Cases description: Case management operations. servers: - url: 'https://api-{dataRegion}.central.sophos.com/cases/v1' description: Regional service in the production environment. variables: dataRegion: description: The data region where the service is. default: eu01 enum: - eu01 - eu02 - us01 - us03 - ca01 - au01 - jp01 - in01 - br01 - ae01 security: - bearerAuth: [] paths: /cases: get: summary: Get cases x-soph-permissions: 'xdr-cases.case:read' description: Search a specific customer's cases. operationId: getCases tags: - Cases parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: managedBy description: Case is managed by. in: query required: false schema: type: string description: Case managed by. enum: - self - sophos - name: type description: Match by case type. in: query required: false style: form explode: false schema: type: array items: type: string description: Case type. enum: - hunt - investigation - incident - healthCheck - duplicate - postureImprovement - customerRequest - activeThreat - exposure - managedRisk - generalRequest - name: severity in: query description: Case severity. style: form explode: false schema: type: array items: type: string description: Case severity. enum: - notSet - critical - high - medium - low - informational - name: status description: >- Match by case status. Self-managed cases support `new`, `investigating`, `onHold`, and `resolved`, while Sophos-managed cases include additional statuses such as `actionRequired`. in: query required: false style: form explode: false schema: type: array items: type: string description: >- Case status. `actionRequired` applies only to Sophos-managed cases. enum: - actionRequired - resolved - investigating - new - onHold - name: assignee in: query description: >- For self-managed cases, match by case assignee email, or 'Unassigned' if no assignee is set. For Sophos-managed cases, the assignee is always 'MDR Ops' or 'Unassigned'. required: false schema: type: string example: user@example.com examples: selfManaged: summary: Self-managed case with a specific assignee value: user@example.com unassigned: summary: No assignee for either self-managed or Sophos-managed cases value: Unassigned sophosManaged: summary: Sophos-managed case with default assignee value: MDR Ops - name: name description: Match by case name. in: query required: false schema: type: string - name: overviewContains description: Partial match by case overview. in: query required: false schema: type: string - in: query name: createdAfter description: Timestamp or duration format. schema: type: string examples: FullUtcTimestamp: value: '2019-09-23T12:02:01.700Z' DateOnly: value: '2019-09-23T00:00:00.000Z' Duration: value: '-P3DT4H5M0S' summary: >- 3 days 4 hours 5 minutes and 0 seconds ago, value is case-sensitive DaysOnly: value: P1D summary: one day from now HoursOnly: value: '-PT2H' summary: 2 hours ago MinutesOnly: value: '-PT20M' summary: 20 minutes ago SecondsOnly: value: PT200S summary: 200 seconds from now - in: query name: createdBefore description: Timestamp or duration format. schema: type: string examples: FullUtcTimestamp: value: '2019-09-23T12:02:01.700Z' DateOnly: value: '2019-09-23T00:00:00.000Z' Duration: value: '-P3DT4H5M0S' summary: >- 3 days 4 hours 5 minutes and 0 seconds ago, value is case-sensitive DaysOnly: value: P1D summary: one day from now HoursOnly: value: '-PT2H' summary: 2 hours ago MinutesOnly: value: '-PT20M' summary: 20 minutes ago SecondsOnly: value: PT200S summary: 200 seconds from now - name: escalated description: Case escalated. in: query required: false schema: type: boolean - name: verdict in: query description: Is the case a false positive or true positive. required: false schema: type: string description: Case verdict. enum: - falsePositive - truePositiveMalicious - truePositiveBenign - truePositive - inconclusive - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - name: sort in: query description: 'Sort column ex. sort=“type:asc” sort=“type:desc" sort=“type”.' required: false schema: type: string responses: '200': description: Cases found. content: application/json: schema: description: Page of cases. type: object properties: items: type: array items: type: object description: A case. required: - id - type - name - tenant - createdAt - status properties: id: description: Case ID. type: string type: type: string description: Case type. enum: - hunt - investigation - incident - healthCheck - duplicate - postureImprovement - customerRequest - activeThreat - exposure - managedRisk - generalRequest name: description: Case name. type: string maxLength: 510 tenant: description: Tenant reference. type: object properties: id: description: Tenant ID. type: string format: uuid managedBy: type: string description: Case managed by. enum: - self - sophos createdAt: description: Case created date-time. type: string format: date-time createdBy: type: object description: Principal reference. properties: id: description: >- Principal ID. This is the client ID for service principals. type: string type: description: Principal type. type: string format: enum enum: - user - service name: description: >- Principal name. This doesn't apply to service principals. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid resolvedAt: description: Case resolved date-time. type: string format: date-time updatedAt: description: Case updated date-time. type: string format: date-time severity: type: string description: Case severity. enum: - notSet - critical - high - medium - low - informational status: type: string description: >- Case status. `actionRequired` applies only to Sophos-managed cases. enum: - actionRequired - resolved - investigating - new - onHold initialDetection: description: Initial Detection in a Case. type: object properties: id: type: string description: Detection ID. severity: description: >- Severity of the detection. A higher score implies a more severe detection. type: integer minimum: 1 maximum: 10 example: 5 type: description: Type of the detection. type: string example: Threat detectionRule: type: string description: Detection rule ID. example: WIN-MITRE-Behavioral-TA0011-T1105 mitreAttacks: description: >- List of MITRE ATT&CK objects associated with this detection. type: array items: type: object description: MITRE ATT&CK name and description. properties: tactic: description: Tactic used in the MITRE ATT&CK. type: object properties: id: description: ID of the tactic. type: string example: TA0002 name: description: MITRE ATT&CK name. type: string example: Execution techniques: description: MITRE ATT&CK techniques. type: array items: description: Technique used in the MITRE ATT&CK. type: object properties: id: description: ID of the technique. type: string example: T1059 name: description: Name of the technique. type: string example: Command and Scripting Interpreter time: description: Detection event time. type: string format: timestamp sensor: type: object description: The sensor which generated the detection. required: - id - type - source - version properties: id: description: ID of the sensor. type: string example: SophosSensorID type: type: string description: Sensor type where detection occurred. enum: - cloud - endpoint - email - firewall - iam - network - compound - backupAndRecovery source: description: The name of the sensor source. type: string example: Sophos version: description: >- The version of the sensor provided by the vendor. type: string example: 1.18.1 name: description: The name of the sensor. type: string assignee: type: object description: Principal reference. properties: id: description: >- Principal ID. This is the client ID for service principals. type: string type: description: Principal type. type: string format: enum enum: - user - service name: description: >- Principal name. This doesn't apply to service principals. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid assignedAt: description: Assignee set date-time. type: string format: date-time overview: description: Case overview. type: string maxLength: 20000 detectionCount: description: Count of detections associated with the case. type: integer verdict: type: string description: Case verdict. enum: - falsePositive - truePositiveMalicious - truePositiveBenign - truePositive - inconclusive escalated: description: Case escalated. type: boolean pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '401': description: Unauthorized. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '403': description: Forbidden. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri post: summary: Create case x-soph-permissions: 'xdr-cases.case:create' description: Create a new case. operationId: createCase tags: - Cases parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: description: Request to create a case. content: application/json: schema: description: >- Request to create a new case in Sophos Central. The `name` and `type` must be supplied. Only self-managed cases can be created at this time (`managedBy = 'self'`). For self-managed cases: The `initialDetectionId` is required. Currently, only detections from the past 30 days can be added when creating a case. The `status` must be either `new` or `investigating`. The `type` cannot be `generalRequest` or `managedRisk`. type: object required: - name - type properties: name: description: >- Case name. Alphanumeric characters, spaces, and the following punctuation are allowed `.`, `,`, `:`, `(`, `)`, `!`, `+`, `_`, `|` `-`, `?`, `\\`, `/`, `'`, `\"`, `$`, `#`. type: string pattern: '^[-\p{L}\p{Nl}\d ,!()\\/."'':?#$+_|]+$' maxLength: 510 type: type: string description: Case type. enum: - hunt - investigation - incident - healthCheck - duplicate - postureImprovement - customerRequest - activeThreat - exposure - managedRisk - generalRequest managedBy: type: string description: Case managed by. enum: - self - sophos severity: type: string description: Case severity. enum: - notSet - critical - high - medium - low - informational status: type: string description: >- Case status. `actionRequired` applies only to Sophos-managed cases. enum: - actionRequired - resolved - investigating - new - onHold assignee: description: >- The email address of the case assignee. This field is required and can be set to `Unassigned` if the case is unassigned. type: string initialDetectionId: description: Detection ID. type: string pattern: '^[a-f0-9_-]+$' maxLength: 150 example: 2e0cdd5ffec_3bad8fb8f otherDetectionIds: description: Additional detection IDs to associate with the case. type: array maxItems: 100 uniqueItems: true items: description: Detection ID. type: string pattern: '^[a-f0-9_-]+$' maxLength: 150 example: 2e0cdd5ffec_3bad8fb8f overview: description: Case overview. type: string maxLength: 20000 responses: '201': description: New case. content: application/json: schema: type: object description: A case. required: - id - type - name - tenant - createdAt - status properties: id: description: Case ID. type: string type: type: string description: Case type. enum: - hunt - investigation - incident - healthCheck - duplicate - postureImprovement - customerRequest - activeThreat - exposure - managedRisk - generalRequest name: description: Case name. type: string maxLength: 510 tenant: description: Tenant reference. type: object properties: id: description: Tenant ID. type: string format: uuid managedBy: type: string description: Case managed by. enum: - self - sophos createdAt: description: Case created date-time. type: string format: date-time createdBy: type: object description: Principal reference. properties: id: description: >- Principal ID. This is the client ID for service principals. type: string type: description: Principal type. type: string format: enum enum: - user - service name: description: >- Principal name. This doesn't apply to service principals. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid resolvedAt: description: Case resolved date-time. type: string format: date-time updatedAt: description: Case updated date-time. type: string format: date-time severity: type: string description: Case severity. enum: - notSet - critical - high - medium - low - informational status: type: string description: >- Case status. `actionRequired` applies only to Sophos-managed cases. enum: - actionRequired - resolved - investigating - new - onHold initialDetection: description: Initial Detection in a Case. type: object properties: id: type: string description: Detection ID. severity: description: >- Severity of the detection. A higher score implies a more severe detection. type: integer minimum: 1 maximum: 10 example: 5 type: description: Type of the detection. type: string example: Threat detectionRule: type: string description: Detection rule ID. example: WIN-MITRE-Behavioral-TA0011-T1105 mitreAttacks: description: >- List of MITRE ATT&CK objects associated with this detection. type: array items: type: object description: MITRE ATT&CK name and description. properties: tactic: description: Tactic used in the MITRE ATT&CK. type: object properties: id: description: ID of the tactic. type: string example: TA0002 name: description: MITRE ATT&CK name. type: string example: Execution techniques: description: MITRE ATT&CK techniques. type: array items: description: Technique used in the MITRE ATT&CK. type: object properties: id: description: ID of the technique. type: string example: T1059 name: description: Name of the technique. type: string example: Command and Scripting Interpreter time: description: Detection event time. type: string format: timestamp sensor: type: object description: The sensor which generated the detection. required: - id - type - source - version properties: id: description: ID of the sensor. type: string example: SophosSensorID type: type: string description: Sensor type where detection occurred. enum: - cloud - endpoint - email - firewall - iam - network - compound - backupAndRecovery source: description: The name of the sensor source. type: string example: Sophos version: description: The version of the sensor provided by the vendor. type: string example: 1.18.1 name: description: The name of the sensor. type: string assignee: type: object description: Principal reference. properties: id: description: >- Principal ID. This is the client ID for service principals. type: string type: description: Principal type. type: string format: enum enum: - user - service name: description: >- Principal name. This doesn't apply to service principals. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid assignedAt: description: Assignee set date-time. type: string format: date-time overview: description: Case overview. type: string maxLength: 20000 detectionCount: description: Count of detections associated with the case. type: integer verdict: type: string description: Case verdict. enum: - falsePositive - truePositiveMalicious - truePositiveBenign - truePositive - inconclusive escalated: description: Case escalated. type: boolean '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '401': description: Unauthorized. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '403': description: Forbidden. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/cases/{caseId}': get: summary: Get case by ID x-soph-permissions: 'xdr-cases.case:read' description: Get a case by ID. operationId: getCaseById tags: - Cases parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: caseId in: path description: 'Case ID. The ID follows the pattern `^[A-Za-z0-9]+-[A-Za-z0-9]+$`.' required: true schema: type: string example: 3-201650 responses: '200': description: Requested case. content: application/json: schema: type: object description: A case. required: - id - type - name - tenant - createdAt - status properties: id: description: Case ID. type: string type: type: string description: Case type. enum: - hunt - investigation - incident - healthCheck - duplicate - postureImprovement - customerRequest - activeThreat - exposure - managedRisk - generalRequest name: description: Case name. type: string maxLength: 510 tenant: description: Tenant reference. type: object properties: id: description: Tenant ID. type: string format: uuid managedBy: type: string description: Case managed by. enum: - self - sophos createdAt: description: Case created date-time. type: string format: date-time createdBy: type: object description: Principal reference. properties: id: description: >- Principal ID. This is the client ID for service principals. type: string type: description: Principal type. type: string format: enum enum: - user - service name: description: >- Principal name. This doesn't apply to service principals. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid resolvedAt: description: Case resolved date-time. type: string format: date-time updatedAt: description: Case updated date-time. type: string format: date-time severity: type: string description: Case severity. enum: - notSet - critical - high - medium - low - informational status: type: string description: >- Case status. `actionRequired` applies only to Sophos-managed cases. enum: - actionRequired - resolved - investigating - new - onHold initialDetection: description: Initial Detection in a Case. type: object properties: id: type: string description: Detection ID. severity: description: >- Severity of the detection. A higher score implies a more severe detection. type: integer minimum: 1 maximum: 10 example: 5 type: description: Type of the detection. type: string example: Threat detectionRule: type: string description: Detection rule ID. example: WIN-MITRE-Behavioral-TA0011-T1105 mitreAttacks: description: >- List of MITRE ATT&CK objects associated with this detection. type: array items: type: object description: MITRE ATT&CK name and description. properties: tactic: description: Tactic used in the MITRE ATT&CK. type: object properties: id: description: ID of the tactic. type: string example: TA0002 name: description: MITRE ATT&CK name. type: string example: Execution techniques: description: MITRE ATT&CK techniques. type: array items: description: Technique used in the MITRE ATT&CK. type: object properties: id: description: ID of the technique. type: string example: T1059 name: description: Name of the technique. type: string example: Command and Scripting Interpreter time: description: Detection event time. type: string format: timestamp sensor: type: object description: The sensor which generated the detection. required: - id - type - source - version properties: id: description: ID of the sensor. type: string example: SophosSensorID type: type: string description: Sensor type where detection occurred. enum: - cloud - endpoint - email - firewall - iam - network - compound - backupAndRecovery source: description: The name of the sensor source. type: string example: Sophos version: description: The version of the sensor provided by the vendor. type: string example: 1.18.1 name: description: The name of the sensor. type: string assignee: type: object description: Principal reference. properties: id: description: >- Principal ID. This is the client ID for service principals. type: string type: description: Principal type. type: string format: enum enum: - user - service name: description: >- Principal name. This doesn't apply to service principals. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid assignedAt: description: Assignee set date-time. type: string format: date-time overview: description: Case overview. type: string maxLength: 20000 detectionCount: description: Count of detections associated with the case. type: integer verdict: type: string description: Case verdict. enum: - falsePositive - truePositiveMalicious - truePositiveBenign - truePositive - inconclusive escalated: description: Case escalated. type: boolean '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '401': description: Unauthorized. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '403': description: Forbidden. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri patch: summary: Update a case x-soph-permissions: 'xdr-cases.case:update' description: Update a case. operationId: updateCase tags: - Cases parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: caseId in: path description: 'Case ID. The ID follows the pattern `^[A-Za-z0-9]+-[A-Za-z0-9]+$`.' required: true schema: type: string example: 3-201650 requestBody: description: Request to update a case. content: application/json: schema: description: >- Request to update a case. Only self-managed cases can be updated. type: object properties: name: description: >- Case name. Must not be empty. Only alphanumeric characters, spaces, and the following punctuation marks are allowed `-,!()\/."':?_|#$+`. type: string pattern: '^[-\p{L}\p{Nl}\d ,!()\\/."'':?#$+_|]+$' maxLength: 510 type: type: string description: Case type. enum: - hunt - investigation - incident - healthCheck - duplicate - postureImprovement - customerRequest - activeThreat - exposure - managedRisk - generalRequest severity: type: string description: Case severity. enum: - notSet - critical - high - medium - low - informational status: type: string description: >- Case status. `actionRequired` applies only to Sophos-managed cases. enum: - actionRequired - resolved - investigating - new - onHold assignee: description: Case owner/assignee's email address. type: string overview: description: Case overview. type: string maxLength: 20000 responses: '200': description: Updated case. content: application/json: schema: type: object description: A case. required: - id - type - name - tenant - createdAt - status properties: id: description: Case ID. type: string type: type: string description: Case type. enum: - hunt - investigation - incident - healthCheck - duplicate - postureImprovement - customerRequest - activeThreat - exposure - managedRisk - generalRequest name: description: Case name. type: string maxLength: 510 tenant: description: Tenant reference. type: object properties: id: description: Tenant ID. type: string format: uuid managedBy: type: string description: Case managed by. enum: - self - sophos createdAt: description: Case created date-time. type: string format: date-time createdBy: type: object description: Principal reference. properties: id: description: >- Principal ID. This is the client ID for service principals. type: string type: description: Principal type. type: string format: enum enum: - user - service name: description: >- Principal name. This doesn't apply to service principals. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid resolvedAt: description: Case resolved date-time. type: string format: date-time updatedAt: description: Case updated date-time. type: string format: date-time severity: type: string description: Case severity. enum: - notSet - critical - high - medium - low - informational status: type: string description: >- Case status. `actionRequired` applies only to Sophos-managed cases. enum: - actionRequired - resolved - investigating - new - onHold initialDetection: description: Initial Detection in a Case. type: object properties: id: type: string description: Detection ID. severity: description: >- Severity of the detection. A higher score implies a more severe detection. type: integer minimum: 1 maximum: 10 example: 5 type: description: Type of the detection. type: string example: Threat detectionRule: type: string description: Detection rule ID. example: WIN-MITRE-Behavioral-TA0011-T1105 mitreAttacks: description: >- List of MITRE ATT&CK objects associated with this detection. type: array items: type: object description: MITRE ATT&CK name and description. properties: tactic: description: Tactic used in the MITRE ATT&CK. type: object properties: id: description: ID of the tactic. type: string example: TA0002 name: description: MITRE ATT&CK name. type: string example: Execution techniques: description: MITRE ATT&CK techniques. type: array items: description: Technique used in the MITRE ATT&CK. type: object properties: id: description: ID of the technique. type: string example: T1059 name: description: Name of the technique. type: string example: Command and Scripting Interpreter time: description: Detection event time. type: string format: timestamp sensor: type: object description: The sensor which generated the detection. required: - id - type - source - version properties: id: description: ID of the sensor. type: string example: SophosSensorID type: type: string description: Sensor type where detection occurred. enum: - cloud - endpoint - email - firewall - iam - network - compound - backupAndRecovery source: description: The name of the sensor source. type: string example: Sophos version: description: The version of the sensor provided by the vendor. type: string example: 1.18.1 name: description: The name of the sensor. type: string assignee: type: object description: Principal reference. properties: id: description: >- Principal ID. This is the client ID for service principals. type: string type: description: Principal type. type: string format: enum enum: - user - service name: description: >- Principal name. This doesn't apply to service principals. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid assignedAt: description: Assignee set date-time. type: string format: date-time overview: description: Case overview. type: string maxLength: 20000 detectionCount: description: Count of detections associated with the case. type: integer verdict: type: string description: Case verdict. enum: - falsePositive - truePositiveMalicious - truePositiveBenign - truePositive - inconclusive escalated: description: Case escalated. type: boolean '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '401': description: Unauthorized. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '403': description: Forbidden. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri delete: summary: Delete a case by ID x-soph-permissions: 'xdr-cases.case:delete' description: Delete a self-managed case. operationId: deleteCase tags: - Cases parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: caseId in: path description: 'Case ID. The ID follows the pattern `^[A-Za-z0-9]+-[A-Za-z0-9]+$`.' required: true schema: type: string example: 3-201650 responses: '200': description: Case deleted. content: application/json: schema: description: Case deleted. type: object properties: deleted: type: boolean description: Case deleted. '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '401': description: Unauthorized. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '403': description: Forbidden. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/cases/{caseId}/impacted-entities': get: summary: Get a impacted entities x-soph-permissions: 'xdr-cases.case.impacted-entities:read' description: Get impacted entities for an XDR case. operationId: getCaseImpactedEntities tags: - Cases parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: caseId in: path description: 'Case ID. The ID follows the pattern `^[A-Za-z0-9]+-[A-Za-z0-9]+$`.' required: true schema: type: string example: 3-201650 - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - name: sort in: query description: 'Sort column ex. sort=“type:asc” sort=“type:desc" sort=“type”.' required: false schema: type: string - name: id in: query description: Exact match search for entity ID. required: false schema: type: string - name: name in: query description: Exact match search for entity name. required: false schema: type: string example: EC2AMAZ-C9BOKG4 - name: type in: query description: Exact match search for entity type. required: false schema: type: string example: ipAddress responses: '200': description: Impacted Entities. content: application/json: schema: description: Page of impacted entities associated with a case. type: object properties: items: type: array items: description: Impacted entity. type: object required: - id - name - type properties: id: type: string description: Entity ID. name: type: string description: Entity name. type: type: string description: Entity type. enum: - user - device - ipAddress - networkFlow - file - process detections: description: Associated detections. type: array items: type: object description: Detection reference. required: - id properties: id: description: Detection ID. type: string pattern: '^[a-f0-9_-]+$' maxLength: 150 example: 2e0cdd5ffec_3bad8fb8f detectionRule: description: Detection rule ID. type: string example: WIN-PER-PSH-ADD-SERVICE-REG-1 entityAttributes: description: Entity attributes. type: object pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '401': description: Unauthorized. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '403': description: Forbidden. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/cases/{caseId}/detections': get: summary: Get case detections x-soph-permissions: 'xdr-cases.case.detection:read' description: Get all case detections. operationId: getCaseDetections tags: - Cases parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: caseId in: path description: 'Case ID. The ID follows the pattern `^[A-Za-z0-9]+-[A-Za-z0-9]+$`.' required: true schema: type: string example: 3-201650 - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - name: sort in: query description: 'Sort column ex. sort=“type:asc” sort=“type:desc" sort=“type”.' required: false schema: type: string responses: '200': description: Case detections. content: application/json: schema: description: Page of detections associated with a case. type: object properties: items: type: array items: type: object description: The detection item. required: - id - sensor - detectionRule - detectionAttack - device - mitreAttacks - rawData - severity - time - type properties: id: description: Detection ID. type: string pattern: '^[a-f0-9_-]+$' maxLength: 150 example: 2e0cdd5ffec_3bad8fb8f attackType: description: The attack type of the detection. type: string example: Security Event Service Detections detectionRule: description: Detection rule ID. type: string example: WIN-PER-PSH-ADD-SERVICE-REG-1 sensorGeneratedAt: description: Time when the event was created by the sensor. type: string format: date-time example: '2023-11-18T12:01:21Z' sensor: type: object description: The sensor which generated the detection. required: - id - type - source - version properties: id: description: ID of the sensor. type: string example: SophosSensorID type: type: string description: Sensor type where detection occurred. enum: - cloud - endpoint - email - firewall - iam - network - compound - backupAndRecovery source: description: The name of the sensor source. type: string example: Sophos version: description: >- The version of the sensor provided by the vendor. type: string example: 1.18.1 name: description: The name of the sensor. type: string device: type: object description: Device associated with a detection. properties: id: description: ID of the device. type: string format: uuid example: 0569f2b7-756c-4d16-8804-798a6d0030cf type: type: string description: Device type where detection occurred. enum: - computer - sensor - server entity: description: Entity of the device. type: string example: EC2AMAZ-HKOG4LG detectionSigma: description: Information about the detection method. type: object detectionEql: description: EQL instructions for performing the classification. type: string detectionAttack: description: MITRE ATT&CK tactic category of the detection. type: string example: Defense Evasion detectionLicenses: description: Licenses required for the rule or process. type: string geolocation: description: >- List of geolocation of sensors associated with the detection. type: array items: type: object description: Geolocation of the sensor. properties: fieldName: description: Name of the IP. type: string example: raw.meta_public_ip fieldValue: description: Value of the IP. type: string example: 52.11.152.156 city: description: City where the device is located. type: string example: Boardman state: description: State where the device is located. type: string example: Oregon country: description: Country where the device is located. type: string example: United States countryCode: description: >- Country code where the device is located, in ISO 3166-1 format. type: string example: US postal: description: Postal code where the device is located. type: string example: '97818' latitude: description: Latitude of device location. type: number format: float example: 45.8234 longitude: description: Longitude of device location. type: number format: float example: -119.7257 intelixFileReputation: description: >- List of Intelix file reputation objects associated with this detection. type: array items: type: object description: Intelix file reputation of detection. properties: fieldName: description: Name of the file. type: string example: raw.sha256 fieldValue: description: Value of the file. type: string example: >- de96a6e69944335375dc1ac238336066889d9ffc7d73628ef4fe1b1b160ab32c reputationScore: description: Reputation score of the file. type: integer maximum: 100 minimum: 0 example: 95 detectionName: description: Name of the detection. type: string example: WIN-EXE-DM-SUS-POWERSHELL-SCRIPT-BLOCK-1 mitreAttacks: description: >- List of MITRE ATT&CK objects associated with this detection. type: array items: type: object description: MITRE ATT&CK name and description. properties: tactic: description: Tactic used in the MITRE ATT&CK. type: object properties: id: description: ID of the tactic. type: string example: TA0002 name: description: MITRE ATT&CK name. type: string example: Execution techniques: description: MITRE ATT&CK techniques. type: array items: description: Technique used in the MITRE ATT&CK. type: object properties: id: description: ID of the technique. type: string example: T1059 name: description: Name of the technique. type: string example: Command and Scripting Interpreter rawData: description: Raw data received from the source. type: object ruleDescription: description: >- A description of the rule that produced the detection. type: string severity: description: >- Severity of the detection. A higher score implies a more severe detection. type: integer minimum: 1 maximum: 10 example: 5 schema: description: Describes the schema for the detection. type: string time: description: Creation time of the detection. type: string format: date-time example: '2023-11-18T12:02:15.604Z' type: description: Type of the detection. type: string example: Threat pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '401': description: Unauthorized. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '403': description: Forbidden. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/cases/{caseId}/mitre-attack-summary': get: summary: Get summary of MITRE x-soph-permissions: 'xdr-cases.case.mitre-attack-summary:read' description: Get summary of MITRE ATT&CK Tactics and Techniques. operationId: getMitreAttackSummary tags: - Cases parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: caseId in: path description: 'Case ID. The ID follows the pattern `^[A-Za-z0-9]+-[A-Za-z0-9]+$`.' required: true schema: type: string example: 3-201650 responses: '200': description: MITRE ATT&CK summary for case. content: application/json: schema: type: object description: MITRE ATT&CK summary object. properties: tactics: type: array description: List of tactics. items: description: Tactic used in the MITRE ATT&CK. type: object properties: id: description: ID of the tactic. type: string example: TA0002 name: description: MITRE ATT&CK name. type: string example: Execution techniques: description: MITRE ATT&CK techniques. type: array items: description: Technique used in the MITRE ATT&CK. type: object properties: id: description: ID of the technique. type: string example: T1059 name: description: Name of the technique. type: string example: Command and Scripting Interpreter '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '401': description: Unauthorized. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '403': description: Forbidden. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/cases/{caseId}/detections/{detectionId}': get: summary: Get a single detection x-soph-permissions: 'xdr-cases.case.detection:read' description: Get a detection associated with case. operationId: getCaseDetectionById tags: - Cases parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: caseId in: path description: 'Case ID. The ID follows the pattern `^[A-Za-z0-9]+-[A-Za-z0-9]+$`.' required: true schema: type: string example: 3-201650 - name: detectionId in: path description: Detection ID. required: true schema: description: Detection ID. type: string pattern: '^[a-f0-9_-]+$' maxLength: 150 example: 2e0cdd5ffec_3bad8fb8f responses: '200': description: Requested case detection. content: application/json: schema: type: object description: The detection item. required: - id - sensor - detectionRule - detectionAttack - device - mitreAttacks - rawData - severity - time - type properties: id: description: Detection ID. type: string pattern: '^[a-f0-9_-]+$' maxLength: 150 example: 2e0cdd5ffec_3bad8fb8f attackType: description: The attack type of the detection. type: string example: Security Event Service Detections detectionRule: description: Detection rule ID. type: string example: WIN-PER-PSH-ADD-SERVICE-REG-1 sensorGeneratedAt: description: Time when the event was created by the sensor. type: string format: date-time example: '2023-11-18T12:01:21Z' sensor: type: object description: The sensor which generated the detection. required: - id - type - source - version properties: id: description: ID of the sensor. type: string example: SophosSensorID type: type: string description: Sensor type where detection occurred. enum: - cloud - endpoint - email - firewall - iam - network - compound - backupAndRecovery source: description: The name of the sensor source. type: string example: Sophos version: description: The version of the sensor provided by the vendor. type: string example: 1.18.1 name: description: The name of the sensor. type: string device: type: object description: Device associated with a detection. properties: id: description: ID of the device. type: string format: uuid example: 0569f2b7-756c-4d16-8804-798a6d0030cf type: type: string description: Device type where detection occurred. enum: - computer - sensor - server entity: description: Entity of the device. type: string example: EC2AMAZ-HKOG4LG detectionSigma: description: Information about the detection method. type: object detectionEql: description: EQL instructions for performing the classification. type: string detectionAttack: description: MITRE ATT&CK tactic category of the detection. type: string example: Defense Evasion detectionLicenses: description: Licenses required for the rule or process. type: string geolocation: description: >- List of geolocation of sensors associated with the detection. type: array items: type: object description: Geolocation of the sensor. properties: fieldName: description: Name of the IP. type: string example: raw.meta_public_ip fieldValue: description: Value of the IP. type: string example: 52.11.152.156 city: description: City where the device is located. type: string example: Boardman state: description: State where the device is located. type: string example: Oregon country: description: Country where the device is located. type: string example: United States countryCode: description: >- Country code where the device is located, in ISO 3166-1 format. type: string example: US postal: description: Postal code where the device is located. type: string example: '97818' latitude: description: Latitude of device location. type: number format: float example: 45.8234 longitude: description: Longitude of device location. type: number format: float example: -119.7257 intelixFileReputation: description: >- List of Intelix file reputation objects associated with this detection. type: array items: type: object description: Intelix file reputation of detection. properties: fieldName: description: Name of the file. type: string example: raw.sha256 fieldValue: description: Value of the file. type: string example: >- de96a6e69944335375dc1ac238336066889d9ffc7d73628ef4fe1b1b160ab32c reputationScore: description: Reputation score of the file. type: integer maximum: 100 minimum: 0 example: 95 detectionName: description: Name of the detection. type: string example: WIN-EXE-DM-SUS-POWERSHELL-SCRIPT-BLOCK-1 mitreAttacks: description: >- List of MITRE ATT&CK objects associated with this detection. type: array items: type: object description: MITRE ATT&CK name and description. properties: tactic: description: Tactic used in the MITRE ATT&CK. type: object properties: id: description: ID of the tactic. type: string example: TA0002 name: description: MITRE ATT&CK name. type: string example: Execution techniques: description: MITRE ATT&CK techniques. type: array items: description: Technique used in the MITRE ATT&CK. type: object properties: id: description: ID of the technique. type: string example: T1059 name: description: Name of the technique. type: string example: Command and Scripting Interpreter rawData: description: Raw data received from the source. type: object ruleDescription: description: A description of the rule that produced the detection. type: string severity: description: >- Severity of the detection. A higher score implies a more severe detection. type: integer minimum: 1 maximum: 10 example: 5 schema: description: Describes the schema for the detection. type: string time: description: Creation time of the detection. type: string format: date-time example: '2023-11-18T12:02:15.604Z' type: description: Type of the detection. type: string example: Threat '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '401': description: Unauthorized. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '403': description: Forbidden. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT