Skip to main content

createScanTask

This method creates a new scan task.

Note

Please note that the managed endpoints from virtualmachines service are also displayed in computers service under Custom Group. To avoid launching duplicate scan tasks we recommend you to use the endpoints from the computers service.

Services

This method requires you to place the{service} name in the API URL. The allowed services are:

  • computers, for "Computers and Virtual Machines"

  • virtualmachines, for "Virtual Machines"

For example, the request URL for the virtual machines service is:

https://YOUR-HOSTNAME/api/v1.0/jsonrpc/network/virtualmachines

Parameters

Parameter

Type

Optional

Description

targetIds

Array

No

A list with the IDs of the targets to scan. The target ID can designate an endpoint or a container.

type

Number

No

The type of scan. Available options are: 1 - quick scan; 2 - full scan; 3 - memory scan; 4 - custom scan

name

String

Yes

The name of the task. If the parameter is not passed, the name will be automatically generated.

customScanSettings

Array

No

Object containing information such as scan depth and scan path(s). This object should be set only when type parameter has the value 4 - Custom scan. When set for other types, the values will be ignored. Parameter $customScanSettings must contain the following properties:int $scanDepth The scan profile. Available options: 1 - aggressive; 2 - normal; 3 - permissivearray $scanPath The list of target paths to be scanned

returnTaskId (deprecated)

Boolean

Yes

Warning

We recommend using the returnAllTaskIds parameter instead, to make sure all task IDs generated by the request are made available to you in the response.

Indicates if the request will return the ID of the latest task created as a result of the request. Possible values:

  • true, will return the ID of the latest task , if the request is successful.

  • false, will not return the ID of the latest task. Instead, it will return a Boolean value.

Default value: false.

Note

If both returnTaskId and returnAllTaskIds are set to true, only the information requested by the returnAllTaskIds parameter will be returned.

returnAllTaskIds

Boolean

Yes

Indicates if the response will contain the IDs for all the tasks created as a result of the request. Possible values:

  • true - will return an array of strings with the IDs of all the tasks created as a result of the request.

  • false - will not return any task IDs.

Default value: false.

Return value

This method returns the ID of the newly created task or a boolean value which is true if the creation of the task was successful.

Example

Request:

{
    "params": {
        "targetIds": [
            "63f491e5aeb92d393da4ee27", "642ed114edc94a4d0ea7be98"
        ],
        "type": 4,
        "name": "my scan",
        "customScanSettings": {
            "scanDepth": 1,
            "scanPath": [
                "LocalDrives"
            ]
        },
        "returnAllTaskIds":true
    },
    "jsonrpc": "2.0",
    "method": "createScanTask",
    "id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f"
}

Response:

{
    "id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f",
    "jsonrpc": "2.0",
    "result": [
        "64356e4590cbea5a7600ca1e",
        "64356e4590cbea5a7600ca21"
    ]
}
In this section: