CreateQuickScan · Customer Self-Service

Creates a new preliminary investigation by specifying criteria with a search operator (AND, OR) and a match condition (IS, CONTAINS).

The investigation targets all endpoints and is performed on server metadata.

HTTP Request

POST /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
criteria	Object	Container for `criteria` objects
criteria[i].operator	String	Operator for this criteria set AND: Endpoints that match all of the specified criteria OR: Endpoints that match any of the specified criteria
criteria[i].item	Object array	Container for criteria `item` objects
criteria[i].item[i].value	String array	Criteria to use for this investigation
criteria[i].item[i].typeId	Integer	Type of criteria to use in the investigation For possible values, see Threat Investigation API Assessment Criteria Types.
criteria[i].item[i].condition	String	Condition to use for this investigation IS: Exact match CONTAIN: Partial match
Optional Parameters
criteriaKvp	String	Criteria string to show in the auditing log
searchPeriod	Integer	Scope of search results. For example, if value is 3, perform assessment on data within the last 90 days only. -1: DEFAULT 0: ALL 1: ONE_MONTH 3: THREE_MONTH 6: SIX_MONTH 12: TWELVE_MONTH

HTTP Request Example

POST /WebApp/OSCE_iES/OsceIes/ApiEntry

HTTP Request Body

Specify a JSON object containing the following HTTP request body:

Request body:

{
  "Url": "V1/Task/CreateQuickScan",
  "TaskType": 4,
  "Payload": {
    "criteria": {
      "operator": "AND",
      "item": [
        {
          "value": [
            "notepad.exe"
          ],
          "typeId": 3,
          "condition": "IS"
        }
      ]
    },
    "criteriaKvp": "File name: notepad.exe",
    "criteriaSource": 1,
    "searchPeriod": 3
  }
}

Response

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

Note:

The API response may return empty results if the task specified is still ongoing. To monitor the progress of the task and verify if results are ready, use the taskId from the response to call the ShowContent API.

For details, see ShowContent.

{
  "Data": {
    "Code": 0,
    "CodeType": 1,
    "Message": "OK",
    "Data": {
      "taskId": "71B0FFF0-C65B-4502-B405-2404970B1D8B",
      "lastContentId": "[{
      \"serverGuid\": \"2EBEC86D-3FEB-4666-9CA6-B80AB1E193E6\",
      \"lastContentId\": 30144,
      \"hasMore\": true,
      \"totalProgress\": 2,
      \"currentProgress\": 1}]",
      "hasMore": true,
      "serverName": "SAMPLE_SERVER",
      "serverGuid": "2EBEC86D-3FEB-4666-9CA6-B80AB1E193E6",
      "content": [
        {
          "statusCode": 0,
          "message": "TMSL_S_SUCCESS",
          "content": {
            "agentServerMeta": [
              {
                "agentGuid": "654B1B52-C3C9-4405-B133
                              -48E2353DA13B",
                "minFirstSeen": 1539568580,
                "serverMeta": [
                  {
                    "criteriaNo": 0,
                    "metaCategory": 8,
                    "metaValue": "chrome.exe",
                    "metaHashId": "6402513676012825508",
                    "firstSeen": 1539568580,
                    "lastSeen": 0,
                    "repeatCount": 0,
                    "isSpecialCmdLine": false
                  }
                ],
                "isCriteriaExceedMaxMetaCount": [
                  false
                ],
                "serverGuid": 
                "2EBEC86D-3FEB-4666-9CA6-B80AB1E193E6",
                "serverName": "SAMPLE_SERVER",
                "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"
              }
            ]
          }
        }
      ]
    },
    "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
agentServerMeta	Object array	Container for `agentServerMeta` objects
agentServerMeta[i].agentGuid	String	GUID of agent
agentServerMeta[i].minFirstSeen	Integer	Date and time when object was first seen, in unix timestamp format
agentServerMeta[i].serverMeta	Object array	Container for `serverMeta` objects
agentServerMeta[i].serverMeta[i].criteriaNo	Integer	Indicates the index number used to determine the location of the criteria in the array
agentServerMeta[i].serverMeta[i].metaCategory	Integer	Number which indicates the category of the criteria For possible values, see Threat Investigation API Meta Category IDs.
agentServerMeta[i].serverMeta[i].metaValue	String	Value of the specified metaHashId
agentServerMeta[i].serverMeta[i].metaHashId	String	Unique hash ID assigned to the object
agentServerMeta[i].serverMeta[i].firstSeen	Integer	Date and time when the object was first logged, in unix timestamp format
agentServerMeta[i].serverMeta[i].lastSeen	Integer	Date and time when the object was last logged, in unix timestamp format
agentServerMeta[i].serverMeta[i].repeatCount	Integer	Cumulative count of the logged event, if repeated multiple times
agentServerMeta[i].serverMeta[i].isSpecialCmdLine	Boolean	Tags the object as `SpecialCmdLine`
agentServerMeta[i].isCriteriaExceedMaxMetaCount	Boolean array	Indicates that the criteria returned more than 50 command line and registry entries
agentServerMeta[i].serverGuid	String	GUID of the server
agentServerMeta[i].serverName	String	Name of the server
agentServerMeta[i].isOnline	Boolean	Indicates if the server is online
agentServerMeta[i].isImportant	Boolean	Indicates if the agent is tagged as important
agentServerMeta[i].ip	String	IP address of the agent
agentServerMeta[i].machineGuid	String	GUID of the endpoint
agentServerMeta[i].machineName	String	Name of the endpoint
agentServerMeta[i].userName	String	User name of agent
agentServerMeta[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
agentServerMeta[i].machineOS	String	Operating system of the endpoint

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