ShowScanListByScanSummaryGuid

Retrieves investigation details, filtered by investigation status (All, Matched, No match, Pending or Unsuccessful), and contains detailed investigation results for each endpoint.

HTTP Request

PUT /WebApp/OSCE_iES/OsceIes/ApiEntry

Parameters

Important:

The HTTP request body must contain all required parameters.

Name	Type	Description
Required Parameters
Url	String	Specifies the Endpoint Sensor API request to query
TaskType	Integer	Type of API request For Endpoint Sensor, the value is always `4`. For available values, see Threat Investigation API Task Types.
Payload	Object	Payload of the request
scanStatus	Integer	Status of investigation to query 1: All 2: Matched 3: No match 4: Pending 5: Unsuccessful
scanType	Integer array	Method used for the investigation Only the following values are supported: 0: Custom criteria 1: Windows registry 2: YARA rule file 3: IOC rule file 6: Disk IOC rule file
scanSummaryGuid	String array	GUID of the scan summary
Payload.pagination.offset	Integer	Page where to start retrieving records
Payload.pagination.limit	Integer	Number of records to retrieve
Optional Parameters
filter	Object array	Filters used to retrieve scans
filter[i].type	Integer	Filter type Only the following values are supported: 1: Endpoint name (partial string match) 4: Endpoint IP address (partial string match) 5: Endpoint operating system (partial string match) 6: Endpoint user name (partial string match)
filter[i].value	String	Filter value

HTTP Request Example

Example 1: From a registry, YARA, and disk IOC investigation, retrieve agents which have the "No match" status.

{
  "Url": "V1/Task/ShowScanListByScanSummaryGuid",
  "TaskType": 4,
  "Payload": {
    "pagination": {
      "offset": 0,
      "limit": 10
    },
    "scanType": [
      6,
      2,
      1
    ],
    "scanStatus": 3,
    "scanSummaryGuid": [
      "46b01ed9-8f78-447e-91a1-d499d893ab20"
    ]
  }
}

Example 2: From a registry, YARA, and disk IOC investigation, retrieve agents which have the "No match" status and match the "XXX_MACHINE" keyword .

{
  "Url": "V1/Task/ShowScanListByScanSummaryGuid",
  "TaskType": 4,
  "Payload": {
    "pagination": {
      "offset": 0,
      "limit": 50
    },
    "filter": [{
      "type": 1,
      "value": "XXX_MACHINE"
    }],
    "scanStatus": 3,
    "scanType": [1, 2, 6],
    "scanSummaryGuid": [
      "d936ba5d-1697-47fe-8b3a-e25b5cb6048f"]
  }
}

HTTP Request Body

Specify a JSON object containing the following HTTP request body:

Request body:

PUT /WebApp/OSCE_iES/OsceIes/ApiEntry

Response

If successful, this method returns an HTTP status code of "200", result code of "0", and a response body with the following structure:

{
  "Data": {
    "Code": 0,
    "CodeType": 1,
    "Message": "OK",
    "Data": {
      "taskId": "dc665c13-dced-43b7-80d5-9c1aa91a6d7a",
      "lastContentId": "",
      "hasMore": false,
      "serverName": "SAMPLE_SERVER",
      "serverGuid": "654B1B52-C3C9-4405-B133-48E2353DA13B",
      "content": [
        {
          "statusCode": 0,
          "message": "TMSL_S_SUCCESS",
          "content": {
            "scanEntity": [
              {
                "rowId": 20,
                "agentGuid":
                   "654B1B52-C3C9-4405-B133-48E2353DA13B",
                "scanSummaryGuid":
                   "64e8cf77-fdb9-4efb-b8b8-3963c24b33c4",
                "status": 4,
                "name": "test",
                "riskCount": 0,
                "triggerTime": 1540427755,
                "finishTime": 1540427776,
                "submitTime": 1540427699,
                "exceedLeafModuleCountLimit": false,
                "scanType": 6,
                "serverGuid": 
                 "654B1B52-C3C9-4405-B133-48E2353DA13B",
                "serverName": "SAMPLE_SERVER_OSCE",
                "isOnline": true,
                "isImportant": true,
                "ip": "10.1.172.94",
                "machineGuid":
                   "6528BA85-67E0-44E0-9C20-0D311CF986D1",
                "machineName": "SAMPLE_AGENT",
                "machineType": "Server",
                "userName": "SAMPLE_AGENT\\Administrator",
                "userGuid":
                   "5EAA9A7B4-6CE1-FB7E-1D13-C192D233721",
                "isolateStatus": 0,
                "machineOS": "Windows 2016",
                "taskType": 4,
                "creator": "jerry",
                "scanCriteriaEntity": {
                  "criteriaId": 1,
                  "criteriaName": "DD IOC.ioc",
                  "criteriaContent": ""
                }
              }
            ],
            "pagination": {
              "offset": 0,
              "limit": 10,
              "total": 1
            }
          }
        }
      ]
    },
    "TimeZone": 8
  },
  "Meta": {
    "result": 1,
    "errorCode": 0,
    "errorMessgae": "Success"
  },
  "PermissionCtrl": {
    "permission": "255",
    "elements": null
  },
  "FeatureCtrl": {
    "mode": "0"
  },
  "SystemCtrl": {
    "TmcmSoDist_Role": "none"
  }
}

The following table describes the response objects specific to this API.

Name	Type	Description
scanEntity	Object array	Container for `scanEntity` objects
scanEntity[i].rowId	Integer	Unique id assigned to the investigation row
scanEntity[i].agentGuid	String	GUID of the agent
scanEntity[i].scanSummaryGuid	String	GUID of the investigation
scanEntity[i].status	Integer	Status of the investigation 0: None 1: Pending 2: Processing 3: Error 4: Complete 5: Timeout 6: Abort
scanEntity[i].name	String	Name of the investigation
scanEntity[i].riskCount	Integer	Number of matched objects in the investigation
scanEntity[i].triggerTime	Integer	Date and time when the investigation was triggered
scanEntity[i].finishTime	Integer	Date and time when the investigation was completed for each agent
scanEntity[i].submitTime	Integer	Date and time when the investigation was submitted
scanEntity[i].exceedLeafModuleCountLimit	Boolean	Indicates that the investigation returned more than 1000 matched objects
scanEntity[i].scanType	Integer	Method used for the investigation 1: Windows registry 2: YARA rule file 3: IOC rule file 6: Disk IOC rule file
scanEntity[i].serverGuid	String	GUID of the server
scanEntity[i].serverName	String	Name of the server
scanEntity[i].isOnline	Boolean	Indicates if the server is online
scanEntity[i].isImportant	Boolean	Indicates if the agent is tagged as important
scanEntity[i].ip	String	IP address of agent
scanEntity[i].machineGuid	String	GUID of the endpoint
scanEntity[i].machineName	String	Name of the endpoint
scanEntity[i].machineType	String	Type of agent Desktop Server
scanEntity[i].userName	String	User name of agent
scanEntity[i].userGuid	String	GUID of the user
scanEntity[i].isolateStatus	Integer	Isolation status of the agent 0: N/A 1: Normal 2: Isolated 3: Isolate command sent - pending 4: Restore agent from isolation - pending
scanEntity[i].machineOS	String	Operating system of the endpoint
scanEntity[i].taskType	Integer	Type of API request For Endpoint Sensor, the value is always `4`. For available values, see Threat Investigation API Task Types.
scanEntity[i].creator	String	Name of the user who created the investigation
scanEntity[i].scanCriteriaEntity	Object	Container for `scanCriteria` objects
scanEntity[i].scanCriteriaEntity.criteriaId	Integer	Unique identifier used by the server to store the criteria
scanEntity[i].scanCriteriaEntity.criteriaName	String	Name of the criteria The criteriaName is "registry" if scanType value is 1 (Windows registry). The criteriaName is the file name for other scanType values.
scanEntity[i].scanCriteriaEntity.criteriaContent	String	Content of the criteria The criteriaContent is the criteria used to perform registry investigation. The criteriaContent is empty for other scanType values.

For more information about standard responses and response codes for this API, see the following topics: