Create a scan definition

post /public_api/netscan/v1/scan/definition

Create a new scan definition with detailed settings and validation options. A scan definition specifies the targets, schedule, credentials, and scan parameters used when launching scan runs.

Request headers

User-Agent String required

Example: userAgent_example

CLIENT REQUEST

          curl -X 'POST'

        -H
        'Accept: application/json'
      

        -H
        'Content-Type: application/json; charset=UTF-8'
      

          -H
          'User-Agent: userAgent_example'
      

      'https://api-cortex.paloaltonetworks.com/public_api/netscan/v1/scan/definition'
    

      -d
      '{
  "plugins_timeout" : 5,
  "excluded_targets" : [ "" ],
  "schedule_days" : 127,
  "schedule_quiet_hours" : [ ],
  "network_scanner_ids" : [ "scanner-1", "scanner-2" ],
  "schedule_cadence" : "DAILY",
  "description" : "Weekly security scan for production servers",
  "disable_wmi_search" : "1",
  "exclude_printers" : "1",
  "target_ids" : [ ],
  "scanner_plugins_timeout" : 3600,
  "targets" : [ "192.168.1.0/24", "10.0.0.1-10.0.0.100" ],
  "enable_report" : true,
  "network" : 1,
  "definition_id" : 123,
  "schedule_dates" : [ ],
  "credential_ids" : [ 1 ],
  "schedule_start_date" : 1765083183326,
  "timeout_retry" : 5,
  "max_hosts" : 30,
  "strict_unauthenticated" : "0",
  "override_target_exclusions" : false,
  "port_list_id" : 5,
  "auth_port_ssh" : 22,
  "checks_read_timeout" : 5,
  "non_simult_ports" : "139,445,3389,Services/irc",
  "exclude_fragile_devices" : "1",
  "vt_config_id" : 4,
  "disable_cgi_cache" : "1",
  "open_sock_max_attempts" : 5,
  "max_checks" : 4,
  "safe_checks" : "1",
  "schedule_timezone" : "America/Los_Angeles",
  "alive_test_methods" : [ "arp", "icmp", "tcp_ack" ],
  "alive_test_ports" : "21-23,25,53,80,110-111,135,139,143,443,445,993,995,1723,3306,3389,5900,8080",
  "schedule_time" : {
    "hour" : 2,
    "minute" : 0,
    "second" : 0
  },
  "expand_vhosts" : "1",
  "disable_win_cmd_exec" : "1",
  "name" : "Weekly Production Scan",
  "asset_groups" : [ {
    "name" : "name",
    "count" : 6,
    "id" : 0
  }, {
    "name" : "name",
    "count" : 6,
    "id" : 0
  } ],
  "optimize_test" : "1",
  "scan_ports" : [ ]
}'
    


      

import http.client

conn = http.client.HTTPSConnection("api-")

headers = { 'User-Agent': "SOME_STRING_VALUE" }

conn.request("POST", "%7Bfqdn%7D/public_api/netscan/v1/scan/definition", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api-/%7Bfqdn%7D/public_api/netscan/v1/scan/definition")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["User-Agent"] = 'SOME_STRING_VALUE'

response = http.request(request)
puts response.read_body

const data = null;

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api-/%7Bfqdn%7D/public_api/netscan/v1/scan/definition");
xhr.setRequestHeader("User-Agent", "SOME_STRING_VALUE");

xhr.send(data);

HttpResponse<String> response = Unirest.post("https://api-/%7Bfqdn%7D/public_api/netscan/v1/scan/definition")
  .header("User-Agent", "SOME_STRING_VALUE")
  .asString();

import Foundation

let headers = ["User-Agent": "SOME_STRING_VALUE"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api-/%7Bfqdn%7D/public_api/netscan/v1/scan/definition")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-/%7Bfqdn%7D/public_api/netscan/v1/scan/definition",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "User-Agent: SOME_STRING_VALUE"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api-/%7Bfqdn%7D/public_api/netscan/v1/scan/definition");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "User-Agent: SOME_STRING_VALUE");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

var client = new RestClient("https://api-/%7Bfqdn%7D/public_api/netscan/v1/scan/definition");
var request = new RestRequest(Method.POST);
request.AddHeader("User-Agent", "SOME_STRING_VALUE");
IRestResponse response = client.Execute(request);

Body parameters

required

application/json; charset=UTF-8

Complete scan definition including scan settings, targets, schedule, and credentials

port_list_idinteger

Port list ID to use

Example:5

scan_portsarray

Custom list of ports to scan (overrides port_list_id if provided)

[

]

auth_port_sshinteger

SSH authentication port

Example:22

disable_cgi_cachestring (Enum)

Disable CGI cache (0 = enabled, 1 = disabled)

Example:"1"

Allowed values:"0""1"

plugins_timeoutinteger

Plugin timeout in minutes

Example:5

checks_read_timeoutinteger

Checks read timeout in minutes

Example:5

max_hostsinteger

Maximum number of hosts to scan simultaneously

Example:30

max_checksinteger

Maximum number of checks per host

Example:4

scanner_plugins_timeoutinteger

Scanner plugins timeout in seconds

Example:3600

timeout_retryinteger

Number of timeout retries

Example:5

open_sock_max_attemptsinteger

Maximum attempts to open socket

Example:5

non_simult_portsstring

Ports that should not be scanned simultaneously (comma-separated)

Example:"139,445,3389,Services/irc"

strict_unauthenticatedstring (Enum)

Strict unauthenticated mode (0 = disabled, 1 = enabled)

Example:"0"

Allowed values:"0""1"

optimize_teststring (Enum)

Optimize test execution (0 = disabled, 1 = enabled)

Example:"1"

Allowed values:"0""1"

expand_vhostsstring (Enum)

Expand virtual hosts (0 = disabled, 1 = enabled)

Example:"1"

Allowed values:"0""1"

exclude_fragile_devicesstring (Enum)

Exclude fragile devices (0 = disabled, 1 = enabled)

Example:"1"

Allowed values:"0""1"

exclude_printersstring (Enum)

Exclude printers (0 = disabled, 1 = enabled)

Example:"1"

Allowed values:"0""1"

safe_checksstring (Enum)

Enable safe checks (0 = disabled, 1 = enabled)

Example:"1"

Allowed values:"0""1"

disable_win_cmd_execstring (Enum)

Disable Windows command execution (0 = disabled, 1 = enabled)

Example:"1"

Allowed values:"0""1"

disable_wmi_searchstring (Enum)

Disable WMI search (0 = disabled, 1 = enabled)

Example:"1"

Allowed values:"0""1"

alive_test_methodsarray[string]

Methods to test if hosts are alive

Example:["arp","icmp","tcp_ack"]

alive_test_portsstring

Ports to use for alive testing (comma-separated or ranges)

Example:"21-23,25,53,80,110-111,135,139,143,443,445,993,995,1723,3306,3389,5900,8080"

definition_idinteger

ID of existing definition (for updates)

Example:123

vt_config_idintegerrequired

Vulnerability test configuration template ID

Example:4

namestringrequired

Name of the scan definition

Example:"Weekly Production Scan"

descriptionstringrequired

Description of the scan definition

Example:"Weekly security scan for production servers"

network_scanner_idsarray[string]required

Array of network scanner UUIDs to use for this scan

Example:["scanner-1","scanner-2"]

networkintegerrequired

Network ID

Example:1

credential_idsarray[integer]required

Array of credential IDs for authenticated scanning

Example:[1]

schedule_cadencestring (Enum)required

Schedule cadence frequency

Example:"DAILY"

Allowed values:"DAILY""WEEKLY""MONTHLY""ONCE"

schedule_daysintegerrequired

Scheduled days as bitmask (127 = all days)

Example:127

schedule_datesarray[integer]required

Array of scheduled dates (for monthly cadence)

schedule_start_dateintegerrequiredint64

Schedule start date as Unix timestamp in milliseconds

Example:1765083183326

schedule_timeobject

Time of day specification for scan scheduling

hourintegerrequired

Hour of the day (0-23)

Example:2

minuteintegerrequired

Minute of the hour (0-59)

secondintegerrequired

Second of the minute (0-59)

schedule_quiet_hoursarrayrequired

Array of quiet hours periods when scanning should not run

[

startobject

Time of day specification for scan scheduling

hourintegerrequired

Hour of the day (0-23)

Example:2

minuteintegerrequired

Minute of the hour (0-59)

secondintegerrequired

Second of the minute (0-59)

endobject

Time of day specification for scan scheduling

hourintegerrequired

Hour of the day (0-23)

Example:2

minuteintegerrequired

Minute of the hour (0-59)

secondintegerrequired

Second of the minute (0-59)

]

schedule_timezonestringrequired

Timezone for scheduling (IANA timezone format)

Example:"America/Los_Angeles"

override_target_exclusionsbooleanrequired

Whether to override global target exclusions

target_idsarray[integer]required

Array of target group IDs

targetsarray[string]required

Array of target hosts or IP ranges (CIDR notation)

Example:["192.168.1.0/24","10.0.0.1-10.0.0.100"]

excluded_targetsarray[string]required

Array of excluded targets

Example:[""]

enable_reportbooleanrequired

Whether to enable scan reporting

Example:true

asset_groupsarray

[

idintegerrequired

namestring

countinteger

]

REQUEST
[application/json; charset=UTF-8 content]

Responses

New scan definition created successfully.

Body

application/json

definition_idinteger

ID of the created definition

Example:123

messagestring

Success message

Example:"Scan created successfully"

RESPONSE
{
  "definition_id": 123,
  "message": "Scan created successfully"
}

Bad Request

Body

application/json

Standard error response returned for all error status codes

err_msgstringrequired

Human-readable error message

metadataobject

Additional error context with field-level details

err_extraarray

List of field-level error details

[

fieldstring

Name of the field that caused the error

messagestring

Error message for the field

]

RESPONSE
{
  "err_msg": "The request contains invalid or missing parameters",
  "metadata": {
    "err_extra": [
      {
        "field": "name",
        "message": "Field required"
      },
      {
        "field": "extra_info",
        "message": "Extra inputs are not permitted"
      }
    ]
  }
}

User not Authorized

Body

application/json

Standard error response returned for all error status codes

err_msgstringrequired

Human-readable error message

metadataobject

Additional error context with field-level details

err_extraarray

List of field-level error details

[

fieldstring

Name of the field that caused the error

messagestring

Error message for the field

]

RESPONSE
{
  "err_msg": "The request contains invalid or missing parameters",
  "metadata": {
    "err_extra": [
      {
        "field": "name",
        "message": "Field required"
      },
      {
        "field": "extra_info",
        "message": "Extra inputs are not permitted"
      }
    ]
  }
}

VT template not found or cannot create a new scan definition

Body

application/json

Standard error response returned for all error status codes

err_msgstringrequired

Human-readable error message

metadataobject

Additional error context with field-level details

err_extraarray

List of field-level error details

[

fieldstring

Name of the field that caused the error

messagestring

Error message for the field

]

RESPONSE
{
  "err_msg": "The request contains invalid or missing parameters",
  "metadata": {
    "err_extra": [
      {
        "field": "name",
        "message": "Field required"
      },
      {
        "field": "extra_info",
        "message": "Extra inputs are not permitted"
      }
    ]
  }
}

Failed definition validation during scan definition creation.

Body

application/json

Standard error response returned for all error status codes

err_msgstringrequired

Human-readable error message

metadataobject

Additional error context with field-level details

err_extraarray

List of field-level error details

[

fieldstring

Name of the field that caused the error

messagestring

Error message for the field

]

RESPONSE
{
  "err_msg": "The request contains invalid or missing parameters",
  "metadata": {
    "err_extra": [
      {
        "field": "name",
        "message": "Field required"
      },
      {
        "field": "extra_info",
        "message": "Extra inputs are not permitted"
      }
    ]
  }
}

Internal Server Error

Body

application/json

Standard error response returned for all error status codes

err_msgstringrequired

Human-readable error message

metadataobject

Additional error context with field-level details

err_extraarray

List of field-level error details

[

fieldstring

Name of the field that caused the error

messagestring

Error message for the field

]

RESPONSE
{
  "err_msg": "The request contains invalid or missing parameters",
  "metadata": {
    "err_extra": [
      {
        "field": "name",
        "message": "Field required"
      },
      {
        "field": "extra_info",
        "message": "Extra inputs are not permitted"
      }
    ]
  }
}