CreateScan (OpenIOC and YARA Files)

Creates a new investigation using OpenIOC and YARA files.

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`
fileContentCriteria	Object	Container for `fileContentCriteria` objects
fileContentCriteria.criteriaHashId	String	Unique hash ID of the OpenIOC or YARA file to be used in the investigation
fileContentCriteria.base64EncodedContent	String	Contents of the OpenIOC or YARA file encoded in base64 format
fileContentCriteria.fileName	String	File name of the OpenIOC or YARA file
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 possible values, 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",
    "scanType": 6,
    "timeRange": {
      "rangeType": "ANY"
    },
    "agentGuid": {
      "2EBEC86D-3FEB-4666-9CA6-B80AB1E193E6": [
        "654b1b52-c3c9-4405-b133-48e2353da13b"
      ]
    },
    "serverGuid": [
      "2EBEC86D-3FEB-4666-9CA6-B80AB1E193E6"
    ],
    "fileContentCriteria": {
      "criteriaHashId": "24c268bee95b7fb4097dcc4c0aee10df431ad46e",
      "base64EncodedContent": "PD94bWwgdmVyc2lvbj0nMS4wJyBlbm...",
      "fileName": "DD IOC.ioc"
    },
    "selectAll": []
  }
}

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: