openapi: 3.0.0 info: title: Detections API description: This is the OAS 3.0 specification for the Detections API in Sophos Central. version: 1.2.0 contact: name: Sophos Central APIs email: apis@sophos.com url: 'https://developer.sophos.com' tags: - name: DetectionGroup description: APIs related to detections grouped by detection rule ID. - name: Detections description: APIs related to the detections. servers: - url: 'https://api-{dataRegion}.central.sophos.com/detections/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: /queries/detections: post: x-soph-permissions: 'detections.queries.detections:create' summary: Run detections query description: Run a query on the detections. The default time range is one day. operationId: startDetectionsRun tags: - Detections parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: description: Request to run a detections query. type: object properties: detectionRule: description: The Detection rule ID. type: string minLength: 0 maxLength: 300 pattern: '^[\p{L}0-9\s_-]*$' example: WIN-PROT-SAV-PUA-PSEXEC-1 deviceName: description: The device name. type: string minLength: 0 maxLength: 200 pattern: '^[\p{L}0-9\s_-]*$' example: EC2AMAZ-HKOG4LG severity: description: Filter detections by the severity level. type: array uniqueItems: true items: type: integer minimum: 0 maximum: 10 example: - 0 - 4 - 8 type: description: Filter detections by the type. type: array uniqueItems: true items: type: string description: Detection type. enum: - process - threat - vulnerability example: - threat - vulnerability category: description: Filter detections by the category. type: array uniqueItems: true items: type: string description: Sensor type where detection occurred. enum: - cloud - endpoint - email - firewall - iam - network - compound - backupAndRecovery example: - endpoint - firewall - identity source: description: The detection source. type: string minLength: 0 maxLength: 200 pattern: '^[\p{L}0-9\s]*$' example: Sophos mitreAttackTactics: description: Filter detections by the MITRE ATT&CK tactic name. type: array uniqueItems: true items: type: string description: MITRE ATT&CK Tactic names. enum: - collection - commandControl - credentialAccess - defenseEvasion - discovery - execution - exfiltration - impact - initialAccess - lateralMovement - persistence - privilegeEscalation - reconnaissance - resourceDevelopment - undefined mitreAttack: description: >- Case-insensitive text field that allows partial matching to filter by the MITRE ATT&CK technique ID, technique name, or tactic. type: string example: T1591.001 userName: description: Filter detections by the username (exact match). type: array maxItems: 10 uniqueItems: true items: description: The user name. type: string minLength: 0 maxLength: 300 pattern: '^[\p{L}\s_-]*$' example: Administrator example: - Administrator - sophosUser entityType: description: The entity type. type: string minLength: 0 maxLength: 200 pattern: '^[\p{L}\s]*$' example: computer location: description: The location. type: string minLength: 0 maxLength: 200 pattern: '^[\p{L}\s.-]*$' example: Canada observable: description: >- Case-insensitive text field that allows partial matching to filter by the raw data. type: string example: Suspicious operatingSystem: description: Filter detections by the operating system (exact match). type: array maxItems: 10 uniqueItems: true items: description: The operating system. type: string minLength: 0 maxLength: 100 pattern: '^[\p{L}\s]*$' example: windows example: - windows - linux operatingSystemName: description: The operating system name. type: string minLength: 0 maxLength: 200 pattern: '^[\p{L}0-9\s._-]*$' example: Red Hat ids: description: Filter detections by the ID. type: array uniqueItems: true maxItems: 10 items: description: The Detection ID. type: string pattern: '^[A-Fa-f0-9_-]+$' maxLength: 150 example: - >- 2e0c6ee620ae864bb0cfbb116ca25a0743582d294bf0061909a5fd739dd5ffec_3bad8fd2b4a035b515be0511bd466146e26d6b8f showSuppressed: description: 'Show suppressed detections, if true. False by default.' type: boolean default: false sort: description: Defines how to sort the data. type: array items: type: object properties: field: type: string description: Detection field that supports sorting. enum: - category - detectionRule - entity - severity - source - time - type - mitreAttack - id - sensorGeneratedAt direction: type: string description: Order of the results. enum: - asc - desc from: type: string format: date-time description: >- Start of time range that is applied when retrieving detections. The default value is one day before the current date and time. example: '2021-11-10T12:23:54.780Z' to: type: string format: date-time description: >- End of time range that is applied when retrieving detections. The default value is the current date and time. example: '2021-11-17T12:23:54.780Z' example: detectionRule: MS-SEC-GRAPH-open severity: - 7 - 8 - 9 - 10 sort: - field: severity direction: asc from: '2021-11-10T12:23:54.780Z' to: '2021-11-17T12:23:54.780Z' responses: '201': description: Successful creation of detections query. content: application/json: schema: description: Information about the run of a query. type: object properties: id: description: ID of the run. type: string format: uuid example: 4a9bb69a-c7f1-4a59-b912-7fe4ba70b751 createdAt: description: Timestamp when the run started. type: string format: date-time example: '2023-11-22T18:55:33.811Z' expiresAt: description: Timestamp when the run expired. type: string format: date-time example: '2023-11-23T18:55:33.811Z' finishedAt: description: Timestamp when the run finished. type: string format: date-time example: '2023-11-22T18:55:35.716Z' resultCount: description: The total number of items across all pages. type: integer example: 100 result: type: string description: Result of a query run on groups or detections. enum: - succeeded - canceled - failed - notAvailable - timedOut status: type: string description: Status of a query run on groups or detections. enum: - finished - pending - started '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 '429': description: Too Many Requests. 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 '/queries/detections/{runId}': get: x-soph-permissions: 'detections.queries.detections:read' summary: Get detections run description: Return the detections query run with the given ID. operationId: getDetectionsRun tags: - Detections parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: runId in: path description: Run ID of a query. required: true schema: type: string format: uuid responses: '200': description: Successful retrieval of the detections query run. content: application/json: schema: description: Information about the run of a query. type: object properties: id: description: ID of the run. type: string format: uuid example: 4a9bb69a-c7f1-4a59-b912-7fe4ba70b751 createdAt: description: Timestamp when the run started. type: string format: date-time example: '2023-11-22T18:55:33.811Z' expiresAt: description: Timestamp when the run expired. type: string format: date-time example: '2023-11-23T18:55:33.811Z' finishedAt: description: Timestamp when the run finished. type: string format: date-time example: '2023-11-22T18:55:35.716Z' resultCount: description: The total number of items across all pages. type: integer example: 100 result: type: string description: Result of a query run on groups or detections. enum: - succeeded - canceled - failed - notAvailable - timedOut status: type: string description: Status of a query run on groups or detections. enum: - finished - pending - started '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 '/queries/detections/{runId}/results': get: x-soph-permissions: 'detections.queries.detections:read' summary: Get detection result description: Return the results of the detections query run with the given ID. operationId: getDetectionsResults tags: - Detections parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: runId in: path description: Run ID of a query. required: true schema: type: string format: uuid - 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. responses: '200': description: Successful retrieval of a detections results page. content: application/json: schema: type: object description: Page of detections. properties: items: description: Page of detection results. type: array items: type: object description: The detection item. required: - id - sensor - detectionRule - detectionAttack - device - mitreAttacks - rawData - severity - time - type properties: id: description: The Detection ID. type: string pattern: '^[A-Fa-f0-9_-]+$' maxLength: 150 attackType: description: The attack type of the detection. type: string example: Security Event Service Detections caseDescription: type: object description: Description of case handler verdict. properties: correlatedReasonId: description: >- ID of the correlation reason used for associating the case with the detection. type: string example: >- XDR-fortinet-fortianalyzer-Application-Layer-Protocol createdReasonId: description: >- ID of the reason for creating this case handler verdict. type: string example: >- XDR-fortinet-fortianalyzer-Application-Layer-Protocol detectionDescription: type: object description: Description of detection handler verdict. properties: createdReasonId: description: >- ID of the reason for creating this detection handler verdict. type: string example: >- XDR-fortinet-fortianalyzer-Application-Layer-Protocol significanceId: description: >- ID of the significance of associated handler verdict. type: string example: >- XDR-fortinet-fortianalyzer-Application-Layer-Protocol 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 entities: description: >- List of impacted and observed entities associated with the detection. type: array items: description: Detection entity. type: object required: - id - type - category properties: id: type: string description: Entity ID. type: type: string description: >- Entity type. Possible values are user, device, ipAddress, networkFlow, file, process. name: type: string description: Entity name. category: type: string description: Entity Category. enum: - impacted - observed attributes: description: Entity attributes. type: object 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 processedData: description: Processed data for the detection. type: string example: >- The process 'C:\Windows\System32\svchost.exe' was created by 'C:\Windows\System32\services.exe'. 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 suppressed: description: >- Indicates whether a detection is marked as suppressed. 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 /queries/detections/counts: get: x-soph-permissions: 'detections.queries.detections:read' summary: Get detection counts description: >- Get detection counts grouped by severity and type. If `resolution`, `to`, and `from` parameters aren't provided, `resolution` is set to day, `to` is set to current date, and `from` is set to 30 days from the current date and time. If `from` and `to` aren't provided, `to` is set to the current date and time. If `resolution` is day, hour, or minute, `from` is set to 30 days ago, 1 day ago, or 1 hour ago respectively. If `from` and `to` are provided, but `resolution` isn't, `resolution` is set based on internal calculation. operationId: getDetectionsCount tags: - Detections parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: from required: false description: Start of time range for query. schema: type: string format: date-time example: '2021-10-01T00:00:00.000Z' - in: query name: to required: false description: End of time range for query. schema: type: string format: date-time example: '2021-10-01T00:00:00.000Z' - in: query name: resolution required: false description: Time interval used for breakdown of detection counts. schema: type: string description: Time interval used for breakdown of detection counts. enum: - day - hour - minute - name: ids in: query description: Filter detection count by the ID. required: false style: form explode: false schema: type: array minItems: 0 maxItems: 10 uniqueItems: true items: description: The Detection ID. type: string pattern: '^[A-Fa-f0-9_-]+$' maxLength: 150 example: - >- 2e0c6ee620ae864bb0cfbb116ca25a0743582d294bf0061909a5fd739dd5ffec_3bad8fd2b4a035b515be0511bd466146e26d6b8f - in: query name: detectionRule required: false description: Filter detection count by the detection rule ID. schema: description: The Detection rule ID. type: string minLength: 0 maxLength: 300 pattern: '^[\p{L}0-9\s_-]*$' example: WIN-PROT-SAV-PUA-PSEXEC-1 - name: severity in: query description: Filter detection count by the severity level. required: false style: form explode: false schema: type: array items: type: integer minimum: 0 maximum: 10 uniqueItems: true - name: type in: query description: Filter detection count by the type. required: false style: form explode: false schema: type: array uniqueItems: true items: type: string description: Detection type. enum: - process - threat - vulnerability - name: category in: query description: Filter detection count by the category. required: false style: form explode: false schema: type: array uniqueItems: true items: type: string description: Sensor type where detection occurred. enum: - cloud - endpoint - email - firewall - iam - network - compound - backupAndRecovery - name: source in: query description: Filter detection count by the source. required: false schema: description: The detection source. type: string minLength: 0 maxLength: 200 pattern: '^[\p{L}0-9\s]*$' example: Sophos - name: deviceNameContains in: query description: Filter detection count by the device name. required: false schema: description: The device name. type: string minLength: 0 maxLength: 200 pattern: '^[\p{L}0-9\s_-]*$' example: EC2AMAZ-HKOG4LG - name: entityType in: query description: Filter detection count by the entity type. required: false style: form explode: false schema: description: The entity type. type: string minLength: 0 maxLength: 200 pattern: '^[\p{L}\s]*$' example: computer - name: location in: query description: >- Case-insensitive text field that allows partial matching to filter detection count by location, City, State, and Country. required: false schema: description: The location. type: string minLength: 0 maxLength: 200 pattern: '^[\p{L}\s.-]*$' example: Canada - name: mitreAttackTactics in: query description: Filter detection count by the MITRE ATT&CK tactic name. required: false style: form explode: false schema: type: array uniqueItems: true items: type: string description: MITRE ATT&CK Tactic names. enum: - collection - commandControl - credentialAccess - defenseEvasion - discovery - execution - exfiltration - impact - initialAccess - lateralMovement - persistence - privilegeEscalation - reconnaissance - resourceDevelopment - undefined - name: mitreAttack in: query description: >- Case-insensitive text field that allows partial matching to filter detection count by the MITRE ATT&CK technique ID, technique name, or tactic. required: false schema: type: string examples: techniqueId: value: T1591.001 techniqueName: value: Boot%20or%20Logon%20Autostart%20Execution tactic: value: Recon - name: operatingSystemName in: query description: >- Case-insensitive text field that allows partial matching to filter detection count by operating system name. required: false schema: description: The operating system name. type: string minLength: 0 maxLength: 200 pattern: '^[\p{L}0-9\s._-]*$' example: Red Hat - name: operatingSystem in: query description: Filter detection count by the operating system (exact match). required: false style: form explode: false schema: type: array minItems: 0 maxItems: 10 uniqueItems: true items: description: The operating system. type: string minLength: 0 maxLength: 100 pattern: '^[\p{L}\s]*$' example: windows - name: username in: query description: Filter detections by the username (exact match). required: false style: form explode: false schema: type: array minItems: 0 maxItems: 10 uniqueItems: true items: description: The user name. type: string minLength: 0 maxLength: 300 pattern: '^[\p{L}\s_-]*$' example: Administrator - name: showSuppressed in: query description: Filter to count detections marked as suppressed. required: false schema: type: boolean example: 'true' responses: '200': description: Successful retrieval of detection counts. content: application/json: schema: type: object description: List of detection counts for a resolution interval. required: - from - resolution - tenant - to properties: from: description: Start time of interval. type: string format: date-time to: description: End time of interval. type: string format: date-time tenant: description: Tenant information. type: object properties: id: description: ID of the Tenant. type: string format: uuid example: 4a9bb69a-c7f1-4a59-b912-7fe4ba70b751 resolution: type: string description: Time interval used for breakdown of detection counts. enum: - day - hour - minute resolutionDetectionCounts: type: array items: type: object description: >- The total count of detections and counts categorized by severity and type within the specified interval. required: - startsAt - totalCount properties: startsAt: description: Start time of the resolution interval. type: string format: date-time endsAt: description: End time of the resolution interval. type: string format: date-time totalCount: description: >- Total number of detections in the resolution interval. type: integer example: 50 countBySeverity: type: object description: 'Counts of detections, grouped by severity.' required: - info - low - medium - high - critical properties: info: description: Count of info severity detections. type: integer example: 10 low: description: Count of low severity detections. type: integer example: 7 medium: description: Count of medium severity detections. type: integer example: 13 high: description: Count of high severity detections. type: integer example: 15 critical: description: Count of critical severity detections. type: integer example: 5 countByType: type: object description: 'Counts of detections, grouped by type.' required: - process - threat - vulnerability properties: process: description: Count of process type detections. type: integer example: 24 threat: description: Count of threat type detections. type: integer example: 20 vulnerability: description: Count of vulnerability type detections. type: integer example: 6 '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 /queries/detection-groups: post: x-soph-permissions: 'detections.queries.detections:create' summary: Run a groups query description: Run a detection groups query. operationId: startGroupRun tags: - DetectionGroup parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: description: >- Request to start a detection group query. It groups the results by severity, detectionId, mitreAttackTactics and time. type: object properties: detectionRule: description: The Detection rule ID. type: string minLength: 0 maxLength: 300 pattern: '^[\p{L}0-9\s_-]*$' example: WIN-PROT-SAV-PUA-PSEXEC-1 deviceName: description: The device name. type: string minLength: 0 maxLength: 200 pattern: '^[\p{L}0-9\s_-]*$' example: EC2AMAZ-HKOG4LG severity: description: Filter detection group by the severity level. type: array uniqueItems: true items: type: integer minimum: 0 maximum: 10 example: - 0 - 4 - 8 type: description: Filter detection group by the type. type: array uniqueItems: true items: type: string description: Detection type. enum: - process - threat - vulnerability example: - threat - vulnerability category: description: Filter detection group by the category. type: array uniqueItems: true items: type: string description: Sensor type where detection occurred. enum: - cloud - endpoint - email - firewall - iam - network - compound - backupAndRecovery example: - endpoint - firewall - identity source: description: The detection source. type: string minLength: 0 maxLength: 200 pattern: '^[\p{L}0-9\s]*$' example: Sophos mitreAttackTactics: description: Filter detection group by the MITRE ATT&CK tactic. type: array uniqueItems: true items: type: string description: MITRE ATT&CK Tactic names. enum: - collection - commandControl - credentialAccess - defenseEvasion - discovery - execution - exfiltration - impact - initialAccess - lateralMovement - persistence - privilegeEscalation - reconnaissance - resourceDevelopment - undefined mitreAttack: description: >- Case-insensitive text field that allows partial matching to filter detection group by MITRE ATT&CK technique ID, technique name, or tactic. type: string example: T1591.001 userName: description: Filter detection group by the username (exact match). type: array items: description: The user name. type: string minLength: 0 maxLength: 300 pattern: '^[\p{L}\s_-]*$' example: Administrator example: - Administrator - sophosUser entityType: description: The entity type. type: string minLength: 0 maxLength: 200 pattern: '^[\p{L}\s]*$' example: computer location: description: The location. type: string minLength: 0 maxLength: 200 pattern: '^[\p{L}\s.-]*$' example: Canada ids: description: Filter detection group by the ID. type: array uniqueItems: true maxItems: 10 items: description: The Detection ID. type: string pattern: '^[A-Fa-f0-9_-]+$' maxLength: 150 example: - >- 2e0c6ee620ae864bb0cfbb116ca25a0743582d294bf0061909a5fd739dd5ffec_3bad8fd2b4a035b515be0511bd466146e26d6b8f operatingSystem: description: >- Filter by detection group by the operating system (exact match). type: array items: description: The operating system. type: string minLength: 0 maxLength: 100 pattern: '^[\p{L}\s]*$' example: windows example: - windows - linux operatingSystemName: description: The operating system name. type: string minLength: 0 maxLength: 200 pattern: '^[\p{L}0-9\s._-]*$' example: Red Hat showSuppressed: description: 'Show suppressed detections, if true. False by default.' type: boolean default: false sort: description: Defines how to sort the data. type: array items: type: object properties: field: type: string description: Field that supports sorting. enum: - category - detectionRule - sensorCount - count - device - firstSeenAt - lastSeenAt - mitreAttack - severity - ruleDescription - sensorGeneratedAt direction: type: string description: Order of the results. enum: - asc - desc from: type: string format: date-time description: >- Start of time range that is applied when retrieving the detection groups. The default value is one day before the current date and time. example: '2021-11-10T12:23:54.780Z' to: type: string format: date-time description: >- End of time range that is applied when retrieving the detection groups. The default value is the current date and time. example: '2021-11-17T12:23:54.780Z' example: detectionRule: MS-SEC-GRAPH-open severity: - 7 - 8 - 9 - 10 sort: - field: severity direction: asc from: '2021-11-10T12:23:54.780Z' to: '2021-11-17T12:23:54.780Z' responses: '201': description: Successful creation of a group query. content: application/json: schema: description: Information about the run of a query. type: object properties: id: description: ID of the run. type: string format: uuid example: 4a9bb69a-c7f1-4a59-b912-7fe4ba70b751 createdAt: description: Timestamp when the run started. type: string format: date-time example: '2023-11-22T18:55:33.811Z' expiresAt: description: Timestamp when the run expired. type: string format: date-time example: '2023-11-23T18:55:33.811Z' finishedAt: description: Timestamp when the run finished. type: string format: date-time example: '2023-11-22T18:55:35.716Z' resultCount: description: The total number of items across all pages. type: integer example: 100 result: type: string description: Result of a query run on groups or detections. enum: - succeeded - canceled - failed - notAvailable - timedOut status: type: string description: Status of a query run on groups or detections. enum: - finished - pending - started '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 '429': description: Too Many Requests. 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 '/queries/detection-groups/{runId}': get: x-soph-permissions: 'detections.queries.detections:read' summary: Get group run description: Return the group query run with the given ID. operationId: getGroupRun tags: - DetectionGroup parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: runId in: path description: Run ID of a query. required: true schema: type: string format: uuid responses: '200': description: Successful retrieval of the group query run. content: application/json: schema: description: Information about the run of a query. type: object properties: id: description: ID of the run. type: string format: uuid example: 4a9bb69a-c7f1-4a59-b912-7fe4ba70b751 createdAt: description: Timestamp when the run started. type: string format: date-time example: '2023-11-22T18:55:33.811Z' expiresAt: description: Timestamp when the run expired. type: string format: date-time example: '2023-11-23T18:55:33.811Z' finishedAt: description: Timestamp when the run finished. type: string format: date-time example: '2023-11-22T18:55:35.716Z' resultCount: description: The total number of items across all pages. type: integer example: 100 result: type: string description: Result of a query run on groups or detections. enum: - succeeded - canceled - failed - notAvailable - timedOut status: type: string description: Status of a query run on groups or detections. enum: - finished - pending - started '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 '/queries/detection-groups/{runId}/results': get: x-soph-permissions: 'detections.queries.detections:read' summary: Get group results description: Return the results of the group query run with the given ID. operationId: getGroupResults tags: - DetectionGroup parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: runId in: path description: Run ID of a query. required: true schema: type: string format: uuid - 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. responses: '200': description: Successful retrieval of a group results page. content: application/json: schema: description: Page of detection groups. type: object properties: items: description: Page of group results. type: array items: type: object description: Group of detections. required: - severity - type - count - sensor - detectionRule - mitreAttacks - time properties: id: description: The group ID. type: string format: uuid severity: description: Suspicion score of the detections in the group. type: integer count: description: Number of events in the group. type: integer detectionRule: description: Detection rule ID. type: string 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 time: description: Creation time of the detections in the group. type: string format: date-time example: '2023-11-18T12:02:15.604Z' detectionRuleDescription: description: Detection rule ID description. type: string mitreAttacks: description: >- List of MITRE ATT&CK objects associated with this detection group. 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 type: description: Type of the detections in the group. 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. '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