CreateScan (Custom Criteria)

Creates a new investigation using custom criteria.

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
agentGuid	Object	GUID of the agent The value of agentGuid is a object of key-value pairs. The key is the serverGuid, and the value is a list of agentGuid strings of the endpoints managed by the target server. It uses the following format: `{ serverGuid : [ agentGuid ] }` If both agentGuid and serverGuid contain an empty array, the request targets all agents.
serverGuid	String array	GUID of servers which manage the endpoints specified in agentGuid If both agentGuid and serverGuid contain an empty array, the request targets all agents.
name	String	Name of the investigation
scanType	Integer	Method used for the investigation 0: Custom criteria 1: Windows registry 2: YARA rule file 3: IOC rule file 6: Disk IOC rule file
timeRange	Object	Container for `timeRange` objects
timeRange.rangeType	String	Period to be investigated ANY: perform investigation on all logged dates SPECIFIC: perform investigation only on logs that fall within the specified dates For investigations using the `SPECIFIC` type, values for `timeRange.endUnixTime` and `timeRange.startUnixTime` are required.
selectAll	Object array	Specify a blank value to return all results To include only results that match certain filters, specify values for `selectAll[i].type` and `selectAll[i].value`
retroCriteria	Object	Container for `retroCriteria` objects
retroCriteria.operator	String	Operator used in the investigation AND: return endpoints that match all the criteria specified OR: return endpoints that match one of the criteria specified
retroCriteria.item	Object	Container for `retroCriteria.item` objects
retroCriteria.item[i].typeId	Integer	Specifies the type of criteria used in the investigation For possible values, see Threat Investigation API Assessment Criteria Types.
retroCriteria.item[i].value	String array	Value of the criteria used in the investigation Multiple values are supported only if `retroCriteria.item[i].typeId` is "Command line" or "Registry Data".
retroCriteria.item[i].condition	String	Condition used in the investigation IS: return results that exactly match the specified criteria CONTAIN: return results that partially match the specified criteria
Optional Parameters
scanScheduleId	Integer	ID of the scheduled investigation, if the investigation is triggered by a schedule
scanScheduleGuid	String	GUID of the scheduled investigation, if the investigation is triggered by a schedule
timeRange.startUnixTime	Integer	Date and time when the investigation starts Specify the time using the unix timestamp format
timeRange.endUnixTime	Integer	Date and time when the investigation ends Specify the time using the unix timestamp format
selectAll[i].type	Integer	Return only the results that match the specified filter For more information, see Threat Investigation API Filter Values.
selectAll[i].value	Integer	Value of the filter type For more information, see Threat Investigation API "selectAll" Types and Values.

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/CreateScan",
  "TaskType": 4,
  "Payload": {
    "name": "test",
    "timeRange": {
      "rangeType": "ANY"
    },
    "agentGuid": {
      "2EBEC86D-3FEB-4666-9CA6-B80AB1E193E6": [
        "6EB14029-2C0D-4EFA-A1D9-A1CECCB0DADE"
      ]
    },
    "retroCriteria": {
      "operator": "AND",
      "item": [
        {
          "value": [
            "chrome.exe"
          ],
          "typeId": 3,
          "condition": "IS"
        }
      ]
    },
    "serverGuid": [
      "2EBEC86D-3FEB-4666-9CA6-B80AB1E193E6"
    ],
    "scanType": 0
  }
}

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": "075978af-4b13-40de-8cc4-2489053955e3",
      "lastContentId": "",
      "hasMore": false,
      "serverName": "SAMPLE_SERVER",
      "serverGuid": "2EBEC86D-3FEB-4666-9CA6-B80AB1E193E6",
      "content": [
        {
          "statusCode": 0,
          "message": "TMSL_S_SUCCESS",
          "content": {
            "scanSummaryGuid": 
            "c484b2a6-7fb2-498e-b074-474e2301e13c"
          }
        }
      ]
    },
    "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
scanSummaryGuid	String	The GUID of the scan summary

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