openapi: 3.0.0 info: description: >- This is the OAS 3.0 specification for the Live Discover API in Sophos Central. version: 1.2.0 contact: name: Sophos Central APIs email: apis@sophos.com url: 'https://developer.sophos.com' title: Live Discover API tags: - name: Category description: Manage EDR query categories. - name: Execution Result description: Manage EDR execution results. - name: Live Discover description: Run EDR queries on remote endpoints. - name: Query description: Manage EDR queries. - name: Query Run description: Manage EDR query runs. - name: Query Run Results description: Manage EDR query run results. - name: Sessions description: Manage EDR query sessions. servers: - url: 'https://api-{dataRegion}.central.sophos.com/live-discover/v1' description: Regional service in the production environment. variables: dataRegion: description: Data region where tenant data is stored. default: eu01 enum: - eu01 - eu02 - us01 - us03 - ca01 - au01 - jp01 - in01 - br01 - ae01 security: - bearerAuth: [] paths: /queries/categories: get: x-soph-permissions: 'live-discover.query-catalog:read' summary: List categories description: 'Get all categories, canned as well as custom.' operationId: listCategories tags: - Category parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string responses: '200': description: List of categories. content: application/json: schema: type: object description: List of categories. required: - items properties: items: type: array description: List of categories. items: type: object description: Category for a query. required: - id - name - type - queryCount properties: id: description: Category ID. type: string format: uuid name: description: Category name. type: string code: description: >- Identifier for category name. This is available only for pre-defined categories. type: string description: description: Category description. type: string icon: description: Category icon name. type: string tenant: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. type: type: string description: Query category type. enum: - canned - custom queryCount: description: Number of queries in this category. type: integer createdAt: description: When the category was created. type: string format: datetime createdBy: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. updatedAt: description: When the category was last updated. type: string format: datetime updatedBy: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. '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/categories/{categoryId}': get: x-soph-permissions: 'live-discover.query-catalog:read' summary: Get category description: Get the details of a category by ID. operationId: getCategory tags: - Category parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: categoryId description: Category ID. required: true schema: type: string format: uuid - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string responses: '200': description: Found category. content: application/json: schema: type: object description: Category for a query. required: - id - name - type - queryCount properties: id: description: Category ID. type: string format: uuid name: description: Category name. type: string code: description: >- Identifier for category name. This is available only for pre-defined categories. type: string description: description: Category description. type: string icon: description: Category icon name. type: string tenant: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. type: type: string description: Query category type. enum: - canned - custom queryCount: description: Number of queries in this category. type: integer createdAt: description: When the category was created. type: string format: datetime createdBy: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. updatedAt: description: When the category was last updated. type: string format: datetime updatedBy: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. '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: Can't find category. 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: get: x-soph-permissions: 'live-discover.query-catalog:read' summary: Get queries description: Get queries matching the given filters. operationId: listQueries tags: - Query parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: categoryId description: Category ID. schema: type: string format: uuid - in: query name: search description: Search for items that match the given terms. schema: type: string - in: query name: searchFields description: Search only within the specified fields. style: form explode: false schema: type: array items: type: string - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string responses: '200': description: List of queries. content: application/json: schema: type: object description: List of queries. required: - items - pages properties: items: type: array description: List of queries. items: type: object description: Saved Live Discover query. required: - id - name - type - template - variables - categories - supportedOSes properties: id: description: Query ID. type: string format: uuid name: description: Query name. type: string code: description: >- Identifier for query name. This is available only for pre-defined queries. type: string description: description: Query description. type: string template: description: >- SQL statement for a query. This can contain replacement variables wrapped in `$$` (double dollar sign) delimiters. type: string variables: description: Variables embedded in the value of `template`. type: array items: type: object description: Query variable. required: - name - dataType properties: name: description: Variable name. type: string minLength: 1 maxLength: 100 dataType: type: string description: >- Data types supported for Live Discover queries. enum: - double - integer - text - dateTime - boolean value: description: String value of the variable. type: string minLength: 1 maxLength: 5000 pivotType: type: string description: Meaning of an input parameter of a query. enum: - deviceId - deviceName - sophosPid - ipAddress - username - sha256 - filePath - registryKey - url supportedOSes: description: Supported endpoint operating systems. type: array items: type: string description: Platform and operating systems combinations. enum: - linuxServer - macOSComputer - windowsComputer - windowsServer categories: description: Categories the query belongs to. type: array items: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. performance: type: object description: >- Query performance metrics based on historical data from query runs. properties: score: type: string description: Live Discover query performance score. enum: - excellent - good - fair - poor - notEvaluated averageExecutionTimeInMillis: description: >- Average of all the execution times of historical executions in milliseconds. type: integer averageDataTransferredInBytes: description: >- Average of all the data transfer sizes of historical executions in bytes. type: integer type: type: string description: Query type. enum: - canned - custom tenant: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. createdAt: description: When the query was created. type: string format: datetime createdBy: type: object description: Principal reference. required: - id - type properties: id: description: >- Principal ID. This is the client ID for service principals. type: string format: uuid 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 updatedAt: description: When the query was last updated. type: string format: datetime updatedBy: type: object description: Principal reference. required: - id - type properties: id: description: >- Principal ID. This is the client ID for service principals. type: string format: uuid 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 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. '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/{queryId}': get: x-soph-permissions: 'live-discover.query-catalog:read' summary: Get query description: Get a query by ID. operationId: getQuery tags: - Query parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: queryId description: Query ID. required: true schema: type: string format: uuid - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string responses: '200': description: Query found. content: application/json: schema: type: object description: Saved Live Discover query. required: - id - name - type - template - variables - categories - supportedOSes properties: id: description: Query ID. type: string format: uuid name: description: Query name. type: string code: description: >- Identifier for query name. This is available only for pre-defined queries. type: string description: description: Query description. type: string template: description: >- SQL statement for a query. This can contain replacement variables wrapped in `$$` (double dollar sign) delimiters. type: string variables: description: Variables embedded in the value of `template`. type: array items: type: object description: Query variable. required: - name - dataType properties: name: description: Variable name. type: string minLength: 1 maxLength: 100 dataType: type: string description: Data types supported for Live Discover queries. enum: - double - integer - text - dateTime - boolean value: description: String value of the variable. type: string minLength: 1 maxLength: 5000 pivotType: type: string description: Meaning of an input parameter of a query. enum: - deviceId - deviceName - sophosPid - ipAddress - username - sha256 - filePath - registryKey - url supportedOSes: description: Supported endpoint operating systems. type: array items: type: string description: Platform and operating systems combinations. enum: - linuxServer - macOSComputer - windowsComputer - windowsServer categories: description: Categories the query belongs to. type: array items: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. performance: type: object description: >- Query performance metrics based on historical data from query runs. properties: score: type: string description: Live Discover query performance score. enum: - excellent - good - fair - poor - notEvaluated averageExecutionTimeInMillis: description: >- Average of all the execution times of historical executions in milliseconds. type: integer averageDataTransferredInBytes: description: >- Average of all the data transfer sizes of historical executions in bytes. type: integer type: type: string description: Query type. enum: - canned - custom tenant: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. createdAt: description: When the query was created. type: string format: datetime createdBy: type: object description: Principal reference. required: - id - type properties: id: description: >- Principal ID. This is the client ID for service principals. type: string format: uuid 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 updatedAt: description: When the query was last updated. type: string format: datetime updatedBy: type: object description: Principal reference. required: - id - type properties: id: description: >- Principal ID. This is the client ID for service principals. type: string format: uuid 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 '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: Can't find query. 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/runs: get: x-soph-permissions: 'live-discover.query:execute' summary: List query runs description: Get the list of query runs matching the given filters. operationId: getQueryRunPage tags: - Query Run parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. - in: query name: sort description: Defines how to sort the data. style: form explode: false schema: type: array items: type: string pattern: '(^[^:]+$)|(^[^:]+:(asc|desc)$)' examples: OneFieldDefaultSort: value: - lastSeenAt OneFieldSort: value: - 'lastSeenAt:asc' MoreThanOneTermSort: value: - 'lastSeenAt:asc' - 'hostname:desc' - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string - in: query name: queryId description: Query ID. schema: type: string format: uuid - in: query name: categoryId description: Category ID. schema: type: string format: uuid - in: query name: status description: One or more values indicating the status of a query run. style: form explode: false schema: type: array items: type: string enum: - pending - started - finished - in: query name: result description: One or more values indicating the overall result of a query run. style: form explode: false schema: type: array items: type: string enum: - notAvailable - succeeded - failed - timedOut - in: query name: createdByPrincipalType description: Type of principal that ran the query. style: form explode: false schema: type: array items: type: string enum: - service - user responses: '200': description: Page of query runs. content: application/json: schema: type: object description: Page of query runs. required: - items - pages properties: items: description: List of query runs. type: array items: type: object description: Query run. required: - id - name - matchEndpoints - template - status - result - endpointCounts - maxDurationInSeconds - timeRemainingInSeconds properties: id: description: Query run ID. type: string format: uuid category: description: Reference to a query category. type: object required: - id properties: id: description: Category ID. type: string format: uuid name: description: Category name. type: string code: description: >- Identifier for category name. This is available only for pre-defined categories. type: string query: type: object required: - id properties: id: description: Query ID. type: string format: uuid name: description: Query name. type: string code: description: Localization code of the query. type: string name: description: Query name. type: string template: description: Query SQL template. type: string variables: description: Query template replacement variables. type: array items: type: object description: Query variable. required: - name - dataType properties: name: description: Variable name. type: string minLength: 1 maxLength: 100 dataType: type: string description: >- Data types supported for Live Discover queries. enum: - double - integer - text - dateTime - boolean value: description: String value of the variable. type: string minLength: 1 maxLength: 5000 pivotType: type: string description: Meaning of an input parameter of a query. enum: - deviceId - deviceName - sophosPid - ipAddress - username - sha256 - filePath - registryKey - url status: type: string description: Status of a query run. enum: - pending - started - finished result: type: string description: Overall result of a query run. enum: - notAvailable - succeeded - failed - timedOut createdAt: description: When the query run was started. type: string format: datetime createdBy: type: object description: Principal reference. required: - id - type properties: id: description: >- Principal ID. This is the client ID for service principals. type: string format: uuid 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 finishedAt: description: When the query run completed. type: string format: datetime maxDurationInSeconds: description: >- Maximum query duration allowed (in seconds) after which the query is terminated. type: integer timeRemainingInSeconds: description: Remaining time in seconds. type: integer performance: type: object description: Overall query performance metrics. properties: score: type: string description: Live Discover query performance score. enum: - excellent - good - fair - poor - notEvaluated dataTransferredInBytes: type: object description: Statistics. properties: total: description: Total value. type: integer format: int64 min: description: Min value. type: integer format: int64 max: description: Max value. type: integer format: int64 median: description: Median value. type: integer format: int64 average: description: Average value. type: integer format: int64 executionTimeInMillis: type: object description: Statistics. properties: total: description: Total value. type: integer format: int64 min: description: Min value. type: integer format: int64 max: description: Max value. type: integer format: int64 median: description: Median value. type: integer format: int64 average: description: Average value. type: integer format: int64 resultCount: description: Count of query run results collected. type: integer format: int64 matchEndpoints: type: object description: Criteria to select endpoints. properties: all: description: Whether to include all endpoints. type: boolean default: false filters: description: >- Filters to select specific endpoints. If present, must contain between one and five filter objects. type: array items: type: object description: Find endpoints matching criteria. properties: healthStatus: description: Find endpoints by health status. type: array items: type: string description: >- Health status of the endpoint or a service running on the endpoint. enum: - good - suspicious - bad - unknown type: description: Find endpoints by type. type: array items: type: string description: >- Endpoint type. Please note `securityVm` is deprecated and will be removed soon. enum: - computer - server - securityVm tamperProtectionEnabled: description: >- Find endpoints by whether Tamper Protection is turned on. type: boolean lockdownStatus: description: Find endpoints by lockdown status. type: array items: type: string description: Endpoint lockdown status. enum: - creatingWhitelist - installing - locked - notInstalled - registering - starting - stopping - unavailable - uninstalled - unlocked - locking ids: description: Find endpoints with the specified IDs. type: array minItems: 1 maxItems: 1000 items: type: string format: uuid lastSeenBefore: description: >- Find endpoints that were last seen before the given date and time (UTC) or a duration relative to the current date and time (exclusive). type: string lastSeenAfter: description: >- Find endpoints that were last seen after the given date and time (UTC) or a duration relative to the current date and time (inclusive). type: string hostnameContains: description: >- Find endpoints where the hostname contains the given string. type: string associatedPersonContains: description: >- Find endpoints where the name of the person associated with the endpoint contains the specified string. type: string groupNameContains: description: >- Find endpoints where the name of the group the endpoint is in contains the given string. We are temporarily stopping support for `groupNameContains` until further notice. type: string os: description: >- Matches endpoints with any of the supplied operating system versions. type: array items: type: object description: >- Matches where operating system platform, type, and version match. properties: platform: type: string description: OS platform type. enum: - windows - linux - macOS type: type: string description: >- Endpoint type. Please note `securityVm` is deprecated and will be removed soon. enum: - computer - server - securityVm version: type: object description: >- Specifies the criteria for a version match. properties: match: description: >- Exact version match. Takes precedence over 'from' and 'to' range options. type: string from: description: >- Match versions greater than or equal to this value. type: string to: description: >- Match versions less or equal to this value. type: string ipAddresses: description: Find endpoints by IP addresses. type: array items: type: string search: description: >- Term to search for in the specified search fields. type: string searchFields: description: >- List of search fields for finding the given search term. Defaults to all applicable fields. type: array items: type: string description: Field that supports searching. enum: - hostname - groupName - associatedPersonName - ipAddresses - osName minItems: 1 maxItems: 5 endpointCounts: type: object description: Count of endpoints grouped by various attributes. properties: total: description: Total number of endpoints. type: integer types: description: Number of endpoints of each type. type: object additionalProperties: type: integer platforms: description: Number of endpoints by platform. type: object additionalProperties: type: integer statuses: type: object description: >- Count of endpoints grouped by the status of the query running on each endpoint. properties: pending: type: object description: >- Count of endpoints grouped by whether they are online or not. properties: total: description: Total number of endpoints. type: integer format: int32 offline: description: Number of endpoints that are offline. type: integer format: int32 online: description: Number of endpoints that are online. type: integer format: int32 started: type: object description: >- Count of endpoints by whether they have returned any data. properties: total: description: Total number of endpoints. type: integer format: int32 withData: description: >- Number of endpoints that have returned some data. type: integer format: int32 withoutData: description: >- Number of endpoints that have returned no data. type: integer format: int32 finished: type: object description: >- Count of endpoints grouped by the result of the query run on each endpoint. properties: succeeded: type: object description: >- Count of endpoints by whether they have returned any data. properties: total: description: Total number of endpoints. type: integer format: int32 withData: description: >- Number of endpoints that have returned some data. type: integer format: int32 withoutData: description: >- Number of endpoints that have returned no data. type: integer format: int32 failed: type: object description: >- Count of endpoints by whether they have returned any data. properties: total: description: Total number of endpoints. type: integer format: int32 withData: description: >- Number of endpoints that have returned some data. type: integer format: int32 withoutData: description: >- Number of endpoints that have returned no data. type: integer format: int32 timedOut: type: object description: >- Count of endpoints by whether they have returned any data. properties: total: description: Total number of endpoints. type: integer format: int32 withData: description: >- Number of endpoints that have returned some data. type: integer format: int32 withoutData: description: >- Number of endpoints that have returned no data. type: integer format: int32 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. '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: x-soph-permissions: 'live-discover.query:execute' summary: Run query description: Run a saved EDR query or an ad hoc query on remote endpoints. operationId: runQuery tags: - Query Run parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: required: true description: Query run request. content: application/json: schema: type: object description: Request to start a query run. required: - matchEndpoints properties: savedQuery: type: object description: >- Saved query to run. Required if an ad hoc query isn't supplied. required: - queryId properties: categoryId: description: (Optional) Query category ID. type: string format: uuid queryId: description: Saved query ID. type: string format: uuid adHocQuery: type: object description: >- Ad hoc query to run. Required if a saved query isn't supplied. required: - template properties: name: description: (Optional) Name for the ad hoc query. type: string minLength: 1 maxLength: 300 template: description: >- SQL statement for the query. This can contain replacement variables wrapped in `$$` (double dollar sign) delimiters. example: >- select * from processes where parent_name = '$$proc_name$$' type: string minLength: 15 maxLength: 50000 variables: description: Values of variables to be replaced in the template SQL. type: array items: type: object description: Query variable. required: - name - dataType properties: name: description: Variable name. type: string minLength: 1 maxLength: 100 dataType: type: string description: Data types supported for Live Discover queries. enum: - double - integer - text - dateTime - boolean value: description: String value of the variable. type: string minLength: 1 maxLength: 5000 pivotType: type: string description: Meaning of an input parameter of a query. enum: - deviceId - deviceName - sophosPid - ipAddress - username - sha256 - filePath - registryKey - url matchEndpoints: type: object description: Criteria to select endpoints. properties: all: description: Whether to include all endpoints. type: boolean default: false filters: description: >- Filters to select specific endpoints. If present, must contain between one and five filter objects. type: array items: type: object description: Find endpoints matching criteria. properties: healthStatus: description: Find endpoints by health status. type: array items: type: string description: >- Health status of the endpoint or a service running on the endpoint. enum: - good - suspicious - bad - unknown type: description: Find endpoints by type. type: array items: type: string description: >- Endpoint type. Please note `securityVm` is deprecated and will be removed soon. enum: - computer - server - securityVm tamperProtectionEnabled: description: >- Find endpoints by whether Tamper Protection is turned on. type: boolean lockdownStatus: description: Find endpoints by lockdown status. type: array items: type: string description: Endpoint lockdown status. enum: - creatingWhitelist - installing - locked - notInstalled - registering - starting - stopping - unavailable - uninstalled - unlocked - locking ids: description: Find endpoints with the specified IDs. type: array minItems: 1 maxItems: 1000 items: type: string format: uuid lastSeenBefore: description: >- Find endpoints that were last seen before the given date and time (UTC) or a duration relative to the current date and time (exclusive). type: string lastSeenAfter: description: >- Find endpoints that were last seen after the given date and time (UTC) or a duration relative to the current date and time (inclusive). type: string hostnameContains: description: >- Find endpoints where the hostname contains the given string. type: string associatedPersonContains: description: >- Find endpoints where the name of the person associated with the endpoint contains the specified string. type: string groupNameContains: description: >- Find endpoints where the name of the group the endpoint is in contains the given string. We are temporarily stopping support for `groupNameContains` until further notice. type: string os: description: >- Matches endpoints with any of the supplied operating system versions. type: array items: type: object description: >- Matches where operating system platform, type, and version match. properties: platform: type: string description: OS platform type. enum: - windows - linux - macOS type: type: string description: >- Endpoint type. Please note `securityVm` is deprecated and will be removed soon. enum: - computer - server - securityVm version: type: object description: Specifies the criteria for a version match. properties: match: description: >- Exact version match. Takes precedence over 'from' and 'to' range options. type: string from: description: >- Match versions greater than or equal to this value. type: string to: description: >- Match versions less or equal to this value. type: string ipAddresses: description: Find endpoints by IP addresses. type: array items: type: string search: description: Term to search for in the specified search fields. type: string searchFields: description: >- List of search fields for finding the given search term. Defaults to all applicable fields. type: array items: type: string description: Field that supports searching. enum: - hostname - groupName - associatedPersonName - ipAddresses - osName minItems: 1 maxItems: 5 example: savedQuery: categoryId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 queryId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 variables: - name: ExecutionName dataType: integer value: '123' pivotType: deviceId matchEndpoints: all: false filters: - healthStatus: - good type: - computer tamperProtectionEnabled: true lockdownStatus: - creatingWhitelist ids: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 lastSeenBefore: '2020-05-13T21:00:01.000' hostnameContains: example associatedPersonContains: person groupNameContains: group os: - platform: windows type: computer version: match: '10' ipAddresses: - 10.50.100.100 search: example searchFields: - hostname responses: '201': description: Query run created. content: application/json: schema: type: object description: Query run. required: - id - name - matchEndpoints - template - status - result - endpointCounts - maxDurationInSeconds - timeRemainingInSeconds properties: id: description: Query run ID. type: string format: uuid category: description: Reference to a query category. type: object required: - id properties: id: description: Category ID. type: string format: uuid name: description: Category name. type: string code: description: >- Identifier for category name. This is available only for pre-defined categories. type: string query: type: object required: - id properties: id: description: Query ID. type: string format: uuid name: description: Query name. type: string code: description: Localization code of the query. type: string name: description: Query name. type: string template: description: Query SQL template. type: string variables: description: Query template replacement variables. type: array items: type: object description: Query variable. required: - name - dataType properties: name: description: Variable name. type: string minLength: 1 maxLength: 100 dataType: type: string description: Data types supported for Live Discover queries. enum: - double - integer - text - dateTime - boolean value: description: String value of the variable. type: string minLength: 1 maxLength: 5000 pivotType: type: string description: Meaning of an input parameter of a query. enum: - deviceId - deviceName - sophosPid - ipAddress - username - sha256 - filePath - registryKey - url status: type: string description: Status of a query run. enum: - pending - started - finished result: type: string description: Overall result of a query run. enum: - notAvailable - succeeded - failed - timedOut createdAt: description: When the query run was started. type: string format: datetime createdBy: type: object description: Principal reference. required: - id - type properties: id: description: >- Principal ID. This is the client ID for service principals. type: string format: uuid 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 finishedAt: description: When the query run completed. type: string format: datetime maxDurationInSeconds: description: >- Maximum query duration allowed (in seconds) after which the query is terminated. type: integer timeRemainingInSeconds: description: Remaining time in seconds. type: integer performance: type: object description: Overall query performance metrics. properties: score: type: string description: Live Discover query performance score. enum: - excellent - good - fair - poor - notEvaluated dataTransferredInBytes: type: object description: Statistics. properties: total: description: Total value. type: integer format: int64 min: description: Min value. type: integer format: int64 max: description: Max value. type: integer format: int64 median: description: Median value. type: integer format: int64 average: description: Average value. type: integer format: int64 executionTimeInMillis: type: object description: Statistics. properties: total: description: Total value. type: integer format: int64 min: description: Min value. type: integer format: int64 max: description: Max value. type: integer format: int64 median: description: Median value. type: integer format: int64 average: description: Average value. type: integer format: int64 resultCount: description: Count of query run results collected. type: integer format: int64 matchEndpoints: type: object description: Criteria to select endpoints. properties: all: description: Whether to include all endpoints. type: boolean default: false filters: description: >- Filters to select specific endpoints. If present, must contain between one and five filter objects. type: array items: type: object description: Find endpoints matching criteria. properties: healthStatus: description: Find endpoints by health status. type: array items: type: string description: >- Health status of the endpoint or a service running on the endpoint. enum: - good - suspicious - bad - unknown type: description: Find endpoints by type. type: array items: type: string description: >- Endpoint type. Please note `securityVm` is deprecated and will be removed soon. enum: - computer - server - securityVm tamperProtectionEnabled: description: >- Find endpoints by whether Tamper Protection is turned on. type: boolean lockdownStatus: description: Find endpoints by lockdown status. type: array items: type: string description: Endpoint lockdown status. enum: - creatingWhitelist - installing - locked - notInstalled - registering - starting - stopping - unavailable - uninstalled - unlocked - locking ids: description: Find endpoints with the specified IDs. type: array minItems: 1 maxItems: 1000 items: type: string format: uuid lastSeenBefore: description: >- Find endpoints that were last seen before the given date and time (UTC) or a duration relative to the current date and time (exclusive). type: string lastSeenAfter: description: >- Find endpoints that were last seen after the given date and time (UTC) or a duration relative to the current date and time (inclusive). type: string hostnameContains: description: >- Find endpoints where the hostname contains the given string. type: string associatedPersonContains: description: >- Find endpoints where the name of the person associated with the endpoint contains the specified string. type: string groupNameContains: description: >- Find endpoints where the name of the group the endpoint is in contains the given string. We are temporarily stopping support for `groupNameContains` until further notice. type: string os: description: >- Matches endpoints with any of the supplied operating system versions. type: array items: type: object description: >- Matches where operating system platform, type, and version match. properties: platform: type: string description: OS platform type. enum: - windows - linux - macOS type: type: string description: >- Endpoint type. Please note `securityVm` is deprecated and will be removed soon. enum: - computer - server - securityVm version: type: object description: >- Specifies the criteria for a version match. properties: match: description: >- Exact version match. Takes precedence over 'from' and 'to' range options. type: string from: description: >- Match versions greater than or equal to this value. type: string to: description: >- Match versions less or equal to this value. type: string ipAddresses: description: Find endpoints by IP addresses. type: array items: type: string search: description: >- Term to search for in the specified search fields. type: string searchFields: description: >- List of search fields for finding the given search term. Defaults to all applicable fields. type: array items: type: string description: Field that supports searching. enum: - hostname - groupName - associatedPersonName - ipAddresses - osName minItems: 1 maxItems: 5 endpointCounts: type: object description: Count of endpoints grouped by various attributes. properties: total: description: Total number of endpoints. type: integer types: description: Number of endpoints of each type. type: object additionalProperties: type: integer platforms: description: Number of endpoints by platform. type: object additionalProperties: type: integer statuses: type: object description: >- Count of endpoints grouped by the status of the query running on each endpoint. properties: pending: type: object description: >- Count of endpoints grouped by whether they are online or not. properties: total: description: Total number of endpoints. type: integer format: int32 offline: description: Number of endpoints that are offline. type: integer format: int32 online: description: Number of endpoints that are online. type: integer format: int32 started: type: object description: >- Count of endpoints by whether they have returned any data. properties: total: description: Total number of endpoints. type: integer format: int32 withData: description: >- Number of endpoints that have returned some data. type: integer format: int32 withoutData: description: >- Number of endpoints that have returned no data. type: integer format: int32 finished: type: object description: >- Count of endpoints grouped by the result of the query run on each endpoint. properties: succeeded: type: object description: >- Count of endpoints by whether they have returned any data. properties: total: description: Total number of endpoints. type: integer format: int32 withData: description: >- Number of endpoints that have returned some data. type: integer format: int32 withoutData: description: >- Number of endpoints that have returned no data. type: integer format: int32 failed: type: object description: >- Count of endpoints by whether they have returned any data. properties: total: description: Total number of endpoints. type: integer format: int32 withData: description: >- Number of endpoints that have returned some data. type: integer format: int32 withoutData: description: >- Number of endpoints that have returned no data. type: integer format: int32 timedOut: type: object description: >- Count of endpoints by whether they have returned any data. properties: total: description: Total number of endpoints. type: integer format: int32 withData: description: >- Number of endpoints that have returned some data. type: integer format: int32 withoutData: description: >- Number of endpoints that have returned no data. type: integer format: int32 '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: No resolved endpoints 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/runs/{runId}': get: x-soph-permissions: 'live-discover.query:execute' summary: Get query run description: Get a query run by ID. operationId: getExecutionSummary tags: - Query Run parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: runId description: Query run ID. required: true schema: type: string format: uuid - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string responses: '200': description: Query run found. content: application/json: schema: type: object description: Query run. required: - id - name - matchEndpoints - template - status - result - endpointCounts - maxDurationInSeconds - timeRemainingInSeconds properties: id: description: Query run ID. type: string format: uuid category: description: Reference to a query category. type: object required: - id properties: id: description: Category ID. type: string format: uuid name: description: Category name. type: string code: description: >- Identifier for category name. This is available only for pre-defined categories. type: string query: type: object required: - id properties: id: description: Query ID. type: string format: uuid name: description: Query name. type: string code: description: Localization code of the query. type: string name: description: Query name. type: string template: description: Query SQL template. type: string variables: description: Query template replacement variables. type: array items: type: object description: Query variable. required: - name - dataType properties: name: description: Variable name. type: string minLength: 1 maxLength: 100 dataType: type: string description: Data types supported for Live Discover queries. enum: - double - integer - text - dateTime - boolean value: description: String value of the variable. type: string minLength: 1 maxLength: 5000 pivotType: type: string description: Meaning of an input parameter of a query. enum: - deviceId - deviceName - sophosPid - ipAddress - username - sha256 - filePath - registryKey - url status: type: string description: Status of a query run. enum: - pending - started - finished result: type: string description: Overall result of a query run. enum: - notAvailable - succeeded - failed - timedOut createdAt: description: When the query run was started. type: string format: datetime createdBy: type: object description: Principal reference. required: - id - type properties: id: description: >- Principal ID. This is the client ID for service principals. type: string format: uuid 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 finishedAt: description: When the query run completed. type: string format: datetime maxDurationInSeconds: description: >- Maximum query duration allowed (in seconds) after which the query is terminated. type: integer timeRemainingInSeconds: description: Remaining time in seconds. type: integer performance: type: object description: Overall query performance metrics. properties: score: type: string description: Live Discover query performance score. enum: - excellent - good - fair - poor - notEvaluated dataTransferredInBytes: type: object description: Statistics. properties: total: description: Total value. type: integer format: int64 min: description: Min value. type: integer format: int64 max: description: Max value. type: integer format: int64 median: description: Median value. type: integer format: int64 average: description: Average value. type: integer format: int64 executionTimeInMillis: type: object description: Statistics. properties: total: description: Total value. type: integer format: int64 min: description: Min value. type: integer format: int64 max: description: Max value. type: integer format: int64 median: description: Median value. type: integer format: int64 average: description: Average value. type: integer format: int64 resultCount: description: Count of query run results collected. type: integer format: int64 matchEndpoints: type: object description: Criteria to select endpoints. properties: all: description: Whether to include all endpoints. type: boolean default: false filters: description: >- Filters to select specific endpoints. If present, must contain between one and five filter objects. type: array items: type: object description: Find endpoints matching criteria. properties: healthStatus: description: Find endpoints by health status. type: array items: type: string description: >- Health status of the endpoint or a service running on the endpoint. enum: - good - suspicious - bad - unknown type: description: Find endpoints by type. type: array items: type: string description: >- Endpoint type. Please note `securityVm` is deprecated and will be removed soon. enum: - computer - server - securityVm tamperProtectionEnabled: description: >- Find endpoints by whether Tamper Protection is turned on. type: boolean lockdownStatus: description: Find endpoints by lockdown status. type: array items: type: string description: Endpoint lockdown status. enum: - creatingWhitelist - installing - locked - notInstalled - registering - starting - stopping - unavailable - uninstalled - unlocked - locking ids: description: Find endpoints with the specified IDs. type: array minItems: 1 maxItems: 1000 items: type: string format: uuid lastSeenBefore: description: >- Find endpoints that were last seen before the given date and time (UTC) or a duration relative to the current date and time (exclusive). type: string lastSeenAfter: description: >- Find endpoints that were last seen after the given date and time (UTC) or a duration relative to the current date and time (inclusive). type: string hostnameContains: description: >- Find endpoints where the hostname contains the given string. type: string associatedPersonContains: description: >- Find endpoints where the name of the person associated with the endpoint contains the specified string. type: string groupNameContains: description: >- Find endpoints where the name of the group the endpoint is in contains the given string. We are temporarily stopping support for `groupNameContains` until further notice. type: string os: description: >- Matches endpoints with any of the supplied operating system versions. type: array items: type: object description: >- Matches where operating system platform, type, and version match. properties: platform: type: string description: OS platform type. enum: - windows - linux - macOS type: type: string description: >- Endpoint type. Please note `securityVm` is deprecated and will be removed soon. enum: - computer - server - securityVm version: type: object description: >- Specifies the criteria for a version match. properties: match: description: >- Exact version match. Takes precedence over 'from' and 'to' range options. type: string from: description: >- Match versions greater than or equal to this value. type: string to: description: >- Match versions less or equal to this value. type: string ipAddresses: description: Find endpoints by IP addresses. type: array items: type: string search: description: >- Term to search for in the specified search fields. type: string searchFields: description: >- List of search fields for finding the given search term. Defaults to all applicable fields. type: array items: type: string description: Field that supports searching. enum: - hostname - groupName - associatedPersonName - ipAddresses - osName minItems: 1 maxItems: 5 endpointCounts: type: object description: Count of endpoints grouped by various attributes. properties: total: description: Total number of endpoints. type: integer types: description: Number of endpoints of each type. type: object additionalProperties: type: integer platforms: description: Number of endpoints by platform. type: object additionalProperties: type: integer statuses: type: object description: >- Count of endpoints grouped by the status of the query running on each endpoint. properties: pending: type: object description: >- Count of endpoints grouped by whether they are online or not. properties: total: description: Total number of endpoints. type: integer format: int32 offline: description: Number of endpoints that are offline. type: integer format: int32 online: description: Number of endpoints that are online. type: integer format: int32 started: type: object description: >- Count of endpoints by whether they have returned any data. properties: total: description: Total number of endpoints. type: integer format: int32 withData: description: >- Number of endpoints that have returned some data. type: integer format: int32 withoutData: description: >- Number of endpoints that have returned no data. type: integer format: int32 finished: type: object description: >- Count of endpoints grouped by the result of the query run on each endpoint. properties: succeeded: type: object description: >- Count of endpoints by whether they have returned any data. properties: total: description: Total number of endpoints. type: integer format: int32 withData: description: >- Number of endpoints that have returned some data. type: integer format: int32 withoutData: description: >- Number of endpoints that have returned no data. type: integer format: int32 failed: type: object description: >- Count of endpoints by whether they have returned any data. properties: total: description: Total number of endpoints. type: integer format: int32 withData: description: >- Number of endpoints that have returned some data. type: integer format: int32 withoutData: description: >- Number of endpoints that have returned no data. type: integer format: int32 timedOut: type: object description: >- Count of endpoints by whether they have returned any data. properties: total: description: Total number of endpoints. type: integer format: int32 withData: description: >- Number of endpoints that have returned some data. type: integer format: int32 withoutData: description: >- Number of endpoints that have returned no data. type: integer format: int32 '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: Can't find query run. 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/runs/{runId}/endpoints': get: x-soph-permissions: 'live-discover.query:execute' summary: Get endpoints description: Get statuses of endpoints in the query run. operationId: getEndpointExecutionStatus tags: - Query Run parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: runId description: Query run ID. required: true schema: type: string format: uuid - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. - in: query name: sort description: Defines how to sort the data. style: form explode: false schema: type: array items: type: string pattern: '(^[^:]+$)|(^[^:]+:(asc|desc)$)' examples: OneFieldDefaultSort: value: - lastSeenAt OneFieldSort: value: - 'lastSeenAt:asc' MoreThanOneTermSort: value: - 'lastSeenAt:asc' - 'hostname:desc' - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string - in: query name: match description: >- Combination of query run status, result, and "with data" filter, delimited with a `:` (colon) symbol. For example, `finished:succeeded:withData`, `finished:succeeded:withoutData`. schema: type: array items: type: string responses: '200': description: Endpoint statuses. content: application/json: schema: type: object description: Page of endpoint status objects for endpoints in a query run. required: - items - pages properties: items: type: array description: List of endpoint status objects. items: type: object description: Status of an endpoint in a query run. required: - id - hostname - type - status properties: id: description: Endpoint ID. type: string format: uuid type: type: string description: >- Endpoint type. Please note `securityVm` is deprecated and will be removed soon. enum: - computer - server - securityVm hostname: description: Endpoint hostname. type: string os: type: object description: OS information. required: - platform - name properties: isServer: description: Whether the OS is a server OS. type: boolean platform: type: string description: OS platform type. enum: - windows - linux - macOS name: description: OS name as reported by the endpoint. type: string majorVersion: description: OS major version. type: integer minorVersion: description: OS minor version. type: integer build: description: OS build. type: integer ipv4Addresses: description: List of IPv4 addresses. type: array items: type: string ipv6Addresses: description: List of IPv6 addresses. type: array items: type: string status: type: string description: Status of a query run. enum: - pending - started - finished result: type: string description: Overall result of a query run. enum: - notAvailable - succeeded - failed - timedOut statusCode: description: >- Status code returned by the query running on the endpoint. type: string statusMessage: description: >- Message returned by the query running on the endpoint. type: string performance: type: object description: Query run metrics for an endpoint. properties: score: type: string description: Live Discover query performance score. enum: - excellent - good - fair - poor - notEvaluated dataTransferredInBytes: description: >- Total size of the query results returned by the endpoints. type: integer format: int64 executionTimeInMillis: description: Time the query took to execute on the endpoint. type: integer format: int64 resultCount: description: Number of rows of results returned by the endpoint. type: integer format: int64 createdAt: description: When the endpoint sent the first status. type: string format: datetime finishedAt: description: When the endpoint finished running the query. type: string format: datetime 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. '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: Can't find query run. 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/runs/{runId}/results': get: x-soph-permissions: 'live-discover.query:execute' summary: Get results description: Get the results of a query run. operationId: getExecutionResultsById tags: - Query Run Results parameters: - name: X-Correlation-ID in: header description: Response header to correlate requests. required: false schema: type: string format: uuid - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: runId description: Query run ID. required: true schema: type: string format: uuid - in: query name: pageSize description: >- Page size for Live Discover query run results. Default is 1000; max is 1000. required: false schema: type: integer default: 1000 - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. - in: query name: pageFromKey required: false schema: type: string description: The key of the item from where to fetch a page. - in: query name: sort description: Defines how to sort the data. style: form explode: false schema: type: array items: type: string pattern: '(^[^:]+$)|(^[^:]+:(asc|desc)$)' examples: OneFieldDefaultSort: value: - lastSeenAt OneFieldSort: value: - 'lastSeenAt:asc' MoreThanOneTermSort: value: - 'lastSeenAt:asc' - 'hostname:desc' responses: '200': description: Query run results. content: application/json: schema: type: object description: Tabular results for a query run. required: - pages - metadata - items properties: pages: type: object required: - maxSize - size properties: fromKey: type: string description: The key of the first item in the returned page. nextKey: type: string description: The key to use when fetching the next page. 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 on all the pages, if pageTotal=true was passed into the request. maxSize: type: integer description: The maximum page size that can be requested. metadata: description: Metadata for tabular data in `items`. type: object required: - columns properties: columns: type: array description: List of columns. items: type: object description: Column metadata. required: - name - type properties: name: type: string description: Column name. type: type: string description: Data types of values returned in query results. enum: - boolean - dateTime - double - integer - text items: type: array description: >- Ordered list of JSON objects, one for each row in the results for the SQL query. A row JSON object has one field for each column in the SQL query. The value of the field is the value of the column. items: type: object description: Single row in the query run results. required: - endpointId - hostname additionalProperties: oneOf: - type: string - type: integer format: int64 - type: boolean - type: number format: double - type: string format: date-time properties: endpointId: type: string description: Endpoint ID. format: uuid hostname: type: string description: Endpoint name. '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: Can't find query run. 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 /enrichment-pivots: get: x-soph-permissions: 'live-discover.query-catalog:read' summary: Get enrichments description: Get enrichments. operationId: getEnrichmentPivots tags: - Live Discover parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid responses: '200': description: Enrichments. content: application/json: schema: type: object description: 'All enrichments, canned as well as custom.' required: - items properties: items: type: array description: Array of enrichments. items: type: object description: Enrichment. required: - sourceType - name - description - type - url properties: id: description: Enrichment ID. type: string format: uuid tenant: description: Tenant these resources belong to. type: object required: - id properties: id: type: string format: uuid name: type: string sourceType: type: string format: enum description: Enrichment source type. enum: - canned - custom name: description: Enrichment name. type: string description: description: Enrichment description. type: string type: type: string format: enum description: Enrichment type. enum: - ipAddress - md5 - sha256 - dns - port - geolocation url: description: Enrichment URL. type: string createdAt: description: When the enrichment was created. type: string format: datetime createdBy: type: object description: Principal reference. required: - id - type properties: id: description: >- Principal ID. This is the client ID for service principals. type: string format: uuid 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 updatedAt: description: When the enrichment was last updated. type: string format: datetime updatedBy: type: object description: Principal reference. required: - id - type properties: id: description: >- Principal ID. This is the client ID for service principals. type: string format: uuid 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 '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: x-soph-permissions: 'live-discover.query-catalog:write' summary: Create enrichment description: Create a new enrichment. operationId: createEnrichmentPivot tags: - Live Discover parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object description: Request to create a new enrichment. required: - name - description - url - type properties: name: description: Enrichment name. type: string pattern: '^[\p{L}\p{N}][-\p{L}\p{N}. ]*[\p{L}\p{N}]$' minLength: 1 maxLength: 255 description: description: Enrichment description. type: string pattern: '^[-\p{L}\p{N}\d ,.]+$' minLength: 1 maxLength: 1024 url: description: >- Enrichment URL. This must start with `http://` or `https://` and contain at least one of the supported variables (`ipAddress`, `dns`, `port`, `sha256`, `md5`) delimited by `$$`. Variables may be used only after the first `/` following the domain name. type: string pattern: >- ^https?://[^/$]+[/][^$]*(?:[$]{2}(?:ipAddress|dns|port|sha256|md5)[$]{2}[^$]*)+$ example: >- https://enrichment.example.com/lookup?ip=$$ipAddress$$&portNumber=$$port$$ minLength: 17 maxLength: 1024 type: type: string format: enum description: Enrichment type. enum: - ipAddress - md5 - sha256 - dns - port - geolocation examples: NewEnrichmentPivot: value: name: VirusTotal description: Lookup the IP Address on Virus Total url: 'https://enrichment.example.com/lookup?ip=$$ipAddress$$' type: ipAddress responses: '201': description: New enrichment. content: application/json: schema: type: object description: Enrichment. required: - sourceType - name - description - type - url properties: id: description: Enrichment ID. type: string format: uuid tenant: description: Tenant these resources belong to. type: object required: - id properties: id: type: string format: uuid name: type: string sourceType: type: string format: enum description: Enrichment source type. enum: - canned - custom name: description: Enrichment name. type: string description: description: Enrichment description. type: string type: type: string format: enum description: Enrichment type. enum: - ipAddress - md5 - sha256 - dns - port - geolocation url: description: Enrichment URL. type: string createdAt: description: When the enrichment was created. type: string format: datetime createdBy: type: object description: Principal reference. required: - id - type properties: id: description: >- Principal ID. This is the client ID for service principals. type: string format: uuid 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 updatedAt: description: When the enrichment was last updated. type: string format: datetime updatedBy: type: object description: Principal reference. required: - id - type properties: id: description: >- Principal ID. This is the client ID for service principals. type: string format: uuid 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 '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 '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 '/enrichment-pivots/{enrichmentPivotId}': patch: x-soph-permissions: 'live-discover.query-catalog:write' summary: Update enrichment description: Update an existing enrichment. operationId: updateEnrichmentPivot tags: - Live Discover parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: enrichmentPivotId description: Enrichment ID. required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object description: Patch object to update an existing enrichment. properties: name: description: Enrichment name. type: string pattern: '^[\p{L}\p{N}][-\p{L}\p{N}. ]*[\p{L}\p{N}]$' minLength: 1 maxLength: 255 description: description: Enrichment description. type: string pattern: '^[-\p{L}\p{N}\d ,.]+$' minLength: 1 maxLength: 1024 url: description: >- Enrichment URL. This must start with `http://` or `https://` and contain at least one of the supported variables (`ipAddress`, `dns`, `port`, `sha256`, `md5`) delimited by `$$`. Variables may be used only after the first `/` following the domain name. type: string pattern: >- ^https?://[^/$]+[/][^$]*(?:[$]{2}(?:ipAddress|dns|port|sha256|md5)[$]{2}[^$]*)+$ example: >- https://enrichment.example.com/lookup?ip=$$ipAddress$$&portNumber=$$port$$ minLength: 17 maxLength: 1024 type: type: string format: enum description: Enrichment type. enum: - ipAddress - md5 - sha256 - dns - port - geolocation examples: EnrichmentPivotPatchRequest: value: name: VirusTotal description: Lookup the IP Address on Virus Total url: 'https://enrichment.example.com/lookup?ip=$$ipAddress$$' type: ipAddress responses: '200': description: Updated enrichment. content: application/json: schema: type: object description: Enrichment. required: - sourceType - name - description - type - url properties: id: description: Enrichment ID. type: string format: uuid tenant: description: Tenant these resources belong to. type: object required: - id properties: id: type: string format: uuid name: type: string sourceType: type: string format: enum description: Enrichment source type. enum: - canned - custom name: description: Enrichment name. type: string description: description: Enrichment description. type: string type: type: string format: enum description: Enrichment type. enum: - ipAddress - md5 - sha256 - dns - port - geolocation url: description: Enrichment URL. type: string createdAt: description: When the enrichment was created. type: string format: datetime createdBy: type: object description: Principal reference. required: - id - type properties: id: description: >- Principal ID. This is the client ID for service principals. type: string format: uuid 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 updatedAt: description: When the enrichment was last updated. type: string format: datetime updatedBy: type: object description: Principal reference. required: - id - type properties: id: description: >- Principal ID. This is the client ID for service principals. type: string format: uuid 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 '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: Can't find enrichment. 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: x-soph-permissions: 'live-discover.query-catalog:delete' summary: Delete enrichment description: Delete enrichment. operationId: deleteEnrichmentPivot tags: - Live Discover parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: enrichmentPivotId description: Enrichment ID. required: true schema: type: string format: uuid responses: '200': description: Enrichment is deleted. content: application/json: schema: type: object description: Result of deleting an object. properties: deleted: description: Whether the object was successfully deleted. type: boolean '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 components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT