Ctrlk
BlogSupport
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Vulnerability Network Scan Management

Public API for network scan configuration and management.

Get scan run status

get

Retrieve the current status of a scan run by its ID. Use the fields parameter to specify which fields to return in the response.

Query parameters
idinteger · int64Required

Scan run ID to check status for

fieldsstring[]Required

Fields to include in the response (for example, status).

Header parameters
User-AgentstringRequired
Responses
200

Scan status retrieved successfully

application/json

Response containing the current status of a scan run

DATAstringRequired

Scan status message

Example: Scan is in Running state
get/public_api/netscan/v1/scan/run
GET /public_api/netscan/v1/scan/run?id=1&fields=text HTTP/1.1
Host: api-cortex.paloaltonetworks.com
User-Agent: text
Accept: */*

{
  "DATA": "Scan is in Running state"
}

Launch a scan run

post

Launch a scan execution using a previously configured scan definition. Optionally override the target IP addresses for this specific run.

Header parameters
User-AgentstringRequired
Body
Responses
200

Scan launched successfully

application/json

Response returned after a scan action (launch, pause, resume, or abort)

DATAstringRequired

Action result message

Example: Scan launched successfully with run ID: 789
post/public_api/netscan/v1/scan/run
POST /public_api/netscan/v1/scan/run HTTP/1.1
Host: api-cortex.paloaltonetworks.com
User-Agent: text
Content-Type: application/json
Accept: */*
Content-Length: 62

{
  "request_data": {
    "definition_id": 123,
    "target": "1.2.3.4.0/12"
  }
}
{
  "DATA": "Scan launched successfully with run ID: 789"
}

Get scan run status by ID

get

Retrieve the current status of a specific scan run identified by the path parameter. Use the fields parameter to specify which fields to return in the response.

Path parameters
idinteger · int64Required

Scan run ID

Query parameters
fieldsstring[]Required

Fields to include in the response (for example, status).

Header parameters
User-AgentstringRequired
Responses
200

Scan status retrieved successfully

application/json

Response containing the current status of a scan run

DATAstringRequired

Scan status message

Example: Scan is in Running state
get/public_api/netscan/v1/scan/run/{id}
GET /public_api/netscan/v1/scan/run/{id}?fields=text HTTP/1.1
Host: api-cortex.paloaltonetworks.com
User-Agent: text
Accept: */*

{
  "DATA": "Scan is in Running state"
}

Launch a scan run by definition ID

post

Launch a scan execution using a scan definition specified by the path parameter. Optionally override the target IP addresses for this run.

Path parameters
idinteger · int64Required

Scan definition ID

Header parameters
User-AgentstringRequired
Body
Responses
200

Scan launched successfully

application/json

Response returned after a scan action (launch, pause, resume, or abort)

DATAstringRequired

Action result message

Example: Scan launched successfully with run ID: 789
post/public_api/netscan/v1/scan/run/{id}
POST /public_api/netscan/v1/scan/run/{id} HTTP/1.1
Host: api-cortex.paloaltonetworks.com
User-Agent: text
Content-Type: application/json
Accept: */*
Content-Length: 62

{
  "request_data": {
    "definition_id": 123,
    "target": "1.2.3.4.0/12"
  }
}
{
  "DATA": "Scan launched successfully with run ID: 789"
}

Create a scan definition

post

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.

Header parameters
User-AgentstringRequired
Body

Scan engine settings controlling port scanning, timeouts, and host discovery behavior

port_list_idinteger · min: 1Required

Port list ID to use

Example: 5
scan_portsobject[]Required

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

auth_port_sshinteger · min: 1 · max: 65535Optional

SSH authentication port

Example: 22
disable_cgi_cachestring · enumOptional

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

Example: 1Possible values:
plugins_timeoutinteger · min: 1Optional

Plugin timeout in minutes

Example: 5
checks_read_timeoutinteger · min: 1Optional

Checks read timeout in minutes

Example: 5
max_hostsinteger · min: 1Optional

Maximum number of hosts to scan simultaneously

Example: 30
max_checksinteger · min: 1Optional

Maximum number of checks per host

Example: 4
scanner_plugins_timeoutinteger · min: 1Optional

Scanner plugins timeout in seconds

Example: 3600
timeout_retryintegerOptional

Number of timeout retries

Example: 5
open_sock_max_attemptsinteger · min: 1Optional

Maximum attempts to open socket

Example: 5
non_simult_portsstringOptional

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

Example: 139,445,3389,Services/irc
strict_unauthenticatedstring · enumOptional

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

Example: 0Possible values:
optimize_teststring · enumOptional

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

Example: 1Possible values:
expand_vhostsstring · enumOptional

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

Example: 1Possible values:
exclude_fragile_devicesstring · enumOptional

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

Example: 1Possible values:
exclude_printersstring · enumOptional

Exclude printers (0 = disabled, 1 = enabled)

Example: 1Possible values:
safe_checksstring · enumOptional

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

Example: 1Possible values:
disable_win_cmd_execstring · enumOptional

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

Example: 1Possible values:
disable_wmi_searchstring · enumOptional

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

Example: 1Possible values:
alive_test_portsstringOptional

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_idintegerOptional

ID of existing definition (for updates)

Example: 123
vt_config_idinteger · min: 1Required

Vulnerability test configuration template ID

Example: 4
namestring · min: 1 · max: 100Required

Name of the scan definition

Example: Weekly Production Scan
descriptionstring · max: 500Required

Description of the scan definition

Example: Weekly security scan for production servers
network_scanner_idsstring · uuid[] · min: 1Required

Array of network scanner UUIDs to use for this scan

Example: ["scanner-1","scanner-2"]
networkinteger · min: 1Required

Network ID

Example: 1
credential_idsinteger[]Required

Array of credential IDs for authenticated scanning

Example: [1]
schedule_cadencestring · enumRequired

Schedule cadence frequency

Example: DAILYPossible values:
schedule_daysinteger · max: 127Required

Scheduled days as bitmask (127 = all days)

Example: 127
schedule_datesinteger[]Required

Array of scheduled dates (for monthly cadence)

schedule_start_dateinteger · int64Required

Schedule start date as Unix timestamp in milliseconds

Example: 1765083183326
schedule_timezonestringRequired

Timezone for scheduling (IANA timezone format)

Example: America/Los_Angeles
override_target_exclusionsbooleanRequired

Whether to override global target exclusions

Example: false
target_idsinteger[]Required

Array of target group IDs

targetsstring[]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_targetsstring[]Required

Array of excluded targets

Example: [""]
enable_reportbooleanRequired

Whether to enable scan reporting

Example: true
Responses
201

New scan definition created successfully.

application/json
definition_idintegerOptional

ID of the created definition

Example: 123
messagestringOptional

Success message

Example: Scan created successfully
post/public_api/netscan/v1/scan/definition
POST /public_api/netscan/v1/scan/definition HTTP/1.1
Host: api-cortex.paloaltonetworks.com
User-Agent: text
Content-Type: application/json; charset=UTF-8
Accept: */*
Content-Length: 1236

{
  "port_list_id": 5,
  "scan_ports": [],
  "auth_port_ssh": 22,
  "disable_cgi_cache": "1",
  "plugins_timeout": 5,
  "checks_read_timeout": 5,
  "max_hosts": 30,
  "max_checks": 4,
  "scanner_plugins_timeout": 3600,
  "timeout_retry": 5,
  "open_sock_max_attempts": 5,
  "non_simult_ports": "139,445,3389,Services/irc",
  "strict_unauthenticated": "0",
  "optimize_test": "1",
  "expand_vhosts": "1",
  "exclude_fragile_devices": "1",
  "exclude_printers": "1",
  "safe_checks": "1",
  "disable_win_cmd_exec": "1",
  "disable_wmi_search": "1",
  "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",
  "definition_id": 123,
  "vt_config_id": 4,
  "name": "Weekly Production Scan",
  "description": "Weekly security scan for production servers",
  "network_scanner_ids": [
    "scanner-1",
    "scanner-2"
  ],
  "network": 1,
  "credential_ids": [
    1
  ],
  "schedule_cadence": "DAILY",
  "schedule_days": 127,
  "schedule_dates": [],
  "schedule_start_date": 1765083183326,
  "schedule_time": {
    "hour": 2,
    "minute": 0,
    "second": 0
  },
  "schedule_quiet_hours": [],
  "schedule_timezone": "America/Los_Angeles",
  "override_target_exclusions": false,
  "target_ids": [],
  "targets": [
    "192.168.1.0/24",
    "10.0.0.1-10.0.0.100"
  ],
  "excluded_targets": [
    ""
  ],
  "enable_report": true,
  "asset_groups": [
    {
      "id": 1,
      "name": "text",
      "count": 1
    }
  ]
}
{
  "definition_id": 123,
  "message": "Scan created successfully"
}

Send a command to a running scan

post

Send a control command to a running scan execution. Supported commands are ABORT (cancel the scan), PAUSE (pause the scan), and RESUME (resume a paused scan).

Path parameters
idinteger · int64Required

Unique identifier of the scan run

Header parameters
User-AgentstringRequired
Body
Responses
200

Command executed successfully

application/json

Response returned after a scan action (launch, pause, resume, or abort)

DATAstringRequired

Action result message

Example: Scan launched successfully with run ID: 789
post/public_api/netscan/v1/scan/run/{id}/command
POST /public_api/netscan/v1/scan/run/{id}/command HTTP/1.1
Host: api-cortex.paloaltonetworks.com
User-Agent: text
Content-Type: application/json
Accept: */*
Content-Length: 33

{
  "request_data": {
    "type": "ABORT"
  }
}
{
  "DATA": "Scan launched successfully with run ID: 789"
}
PreviousNetscan overview
NextModels

Last updated

Was this helpful?