Palo Alto Cortex Xpanse

The Palo Alto Cortex Xpanse connector facilitates the integration of Swimlane Turbine with Cortex Xpanse's attack surface management capabilities, enabling automated monitoring and management of internet-facing assets.

Palo Alto Cortex Xpanse offers a comprehensive view of your organization's internet-facing assets and potential security gaps. This connector enables Swimlane Turbine users to automate asset management, incident response, and threat intelligence tasks by integrating with Cortex Xpanse's extensive telemetry data. Enhance your security posture by proactively managing alerts, assets, and vulnerabilities with streamlined workflows and real-time data analysis.

Limitations

None to date.

Prerequisites

To effectively utilize the Palo Alto Cortex Xpanse connector within Swimlane Turbine, ensure you have the following:

Cortex Custom Authentication with the following parameters:

FQDN: The fully qualified domain name for the API endpoint

API Key: Your unique authentication key for accessing the Cortex Xpanse API

API Key ID: The identifier associated with your API Key

Capabilities

This Connector provides the following capabilities:

Create User-Defined IP Range

Get Alerts

Get Asset Details

Get Business Units

Get Extra Incident Data

Get Incidents

Remove Assets

Update Alerts

Upload Assets

Update Asset Annotation

Update an Incident

Create User-Defined IP Range

Define an IP address range and assign a business unit (BU) or IP address tag (IPR) to that range.

Cortex Xpanse documentation for this action can be found here.

Get Alerts

Get a single alert or list of alerts with multiple events.

Cortex Xpanse documentation for this action can be found here.

Get Asset Details

Get asset details according to the asset ID.

Cortex Xpanse documentation for this action can be found here.

Get Business Units

Fetches business unit information for all or a subset of the business units in your Cortex Xpanse tenant.

Cortex Xpanse documentation for this action can be found here.

Get Extra Incident Data

Get extra data fields for a specific incident including alerts and key artifacts.

Cortex Xpanse documentation for this action can be found here.

Get Incidents

Get details for a single incident or a list of incidents filtered by a list of severity or creation time.

Cortex Xpanse documentation for this action can be found here.

Remove Assets

Remove certificates, domains and IPv4 address ranges from your inventory.

Cortex Xpanse documentation for this action can be found here.

Update Alerts

Update one or more alerts.

Cortex Xpanse documentation for this action can be found here.

Upload Assets

Upload domains and IPv4 address ranges to your inventory.

Cortex Xpanse documentation for this action can be found here.

Update Asset Annotation

Adds an annotation to an asset or IP range.

Cortex Xpanse documentation for this action can be found here.

Update an Incident

Update one or more fields of a specific incident.

Cortex Xpanse documentation for this action can be found here.

Notes

Get your Cortex Xpanse API Key.

In Cortex Xpanse, navigate to Settings & Info > Settings > Integrations > API Keys.

Select + New Key.

Choose the type of API Key you want to generate based on your desired security level: Advanced or Standard. The Advanced API key hashes the key using a nonce, a random string, and a timestamp to prevent replay attacks. cURL does not support this but is suitable with scripts. Use the example script to create the advanced API authentication token.

If you want to define a time limit on the API key authentication, mark Enable Expiration Date and select the expiration date and time. Navigate to Settings & Info > Settings > Integrations > API Keys to track the Expiration Time field for each API key. In addition, Cortex XSOAR displays an API Key Expiration notification in the Notification Center one week and one day prior to the defined expiration date.

Provide a comment that describes the purpose for the API key, if desired.

Select the desired level of access for this key. You can select existing Roles, or you can select Custom to set the permissions on a more granular level. Be sure to select a role with View/Edit access for the Public API. Use the predefined Instance Administrator role or a create a custom role with Public API permission. Roles are described in the Manage Roles section of the Cortex Xpanse User Guide.

Generate the API Key.

Copy the API key, and then click Done. This value represents your unique Authorization:.

Additional Documentation

Palo Alto Cortex Xpanse Connector Documentation

Palo Alto Cortex Xpanse API Documentation

Palo Alto Cortex Xpanse Authentication Guide

Configurations

Palo Alto Cortex Xpanse Authentication

Palo Alto Cortex Xpanse authenticates using API Key and API Key ID.

Configuration Parameters

Parameter	Description	Type	Required
fqdn	The FQDN is a unique host and domain name associated with each tenant.	string	Required
api_key	The API Key is your unique identifier.	string	Required
api_key_id	The API Key ID is your unique token used to authenticate the API Key.	string	Required
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

Actions

Create User-Defined IP Range

Create a user-defined IP range in Palo Alto Cortex Xpanse and assign it to a specific business unit or tag.

Endpoint

URL: /v1/assets/create_user_defined_ip_range

Method: POST

Input

Argument Name	Type	Required	Description
request_data	object	Optional	Request body for creating a user-defined IP range.
request_data.startIp	string	Optional	First IP address of the range.
request_data.endIp	string	Optional	Ending IP address of the range.
request_data.cidrIp	string	Optional	IP range in CIDR notation.
request_data.buTagIds	array	Optional	List of business unit tag IDs that will be applied to the IP range.
request_data.iprTagIds	array	Optional	List of IP range tag IDs (IPR) that will be applied to the IP range.
request_data.shouldReplace	boolean	Optional	Boolean denoting whether to replace all previously applied business units on overlapping ranges.

Input Example

{"json_body":{"request_data":{"startIp":"x.x.x.24","endIp":"x.x.x.25","cidrIp":"null","buTagIds":["BU:af500527-9f45-4bd8-8eb5-e161d18a47b3"],"iprTagIds":["IPR:cc1d6312306d48c79fb3023b93d69923"],"shouldReplace":false}}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
reply	object	Output field: reply
reply.user_defined_ip_range	string	Output field: reply.user_defined_ip_range

Output Example

{"status_code":200,"reason":"OK","json_body":{"reply":{"user_defined_ip_range":"succeeded"}}}

Get Alerts

Obtain a specific alert or a collection of alerts from Palo Alto Cortex Xpanse, utilizing the provided request data.

Endpoint

URL: /v2/alerts/get_alerts_multi_events

Method: POST

Input

Argument Name	Type	Required	Description
request_data	object	Optional	Request body for getting alerts.
request_data.search_from	number	Required	An integer representing the starting offset within the query result set from which you want alerts returned.
request_data.next_page_token	string	Required	Use string to page token into the next request to paginate the next set of data.
request_data.filters	array	Required	An array of filter fields.
request_data.filters.field	string	Required	Identifies the alert fields the filter is matching.
request_data.filters.value	object	Required	Value that this filter must match. The contents of this field will differ based on the field.
request_data.filters.operator	string	Required	String that identifies the comparison operator you want to use for this filter.
request_data.sort	object	Required	Identifies the sort order for the result set.
request_data.sort.field	string	Required	Can either be severity or creation_time.
request_data.sort.keyword	string	Required	The sort order for the field. Can either be asc or desc.
request_data.search_to	number	Optional	An integer representing the end offset within the result set after which you do not want alerts returned.
request_data.use_page_token	boolean	Required	A boolean value to paginate the response data.

Input Example

{"json_body":{"request_data":{"search_from":0,"next_page_token":"next_page_token","filters":[{"field":"business_units_list","value":"AlertFilter_value","operator":"gte"},{"field":"business_units_list","value":"AlertFilter_value","operator":"gte"}],"sort":{"field":"creation_time","keyword":"desc"},"search_to":0,"use_page_token":true}}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
reply	object	Output field: reply
reply.total_count	number	Count value
reply.result_count	number	Result of the operation
reply.alerts	array	Output field: reply.alerts
reply.alerts.category	string	Output field: reply.alerts.category
reply.alerts.project	string	Output field: reply.alerts.project
reply.alerts.cloud_provider	string	Unique identifier
reply.alerts.resource_sub_type	string	Type of the resource
reply.alerts.resource_type	string	Type of the resource
reply.alerts.action_country	array	Output field: reply.alerts.action_country
reply.alerts.description	string	Output field: reply.alerts.description
reply.alerts.events	string	Output field: reply.alerts.events
reply.alerts.event_type	string	Type of the resource
reply.alerts.is_whitelisted	boolean	Output field: reply.alerts.is_whitelisted
reply.alerts.image_name	string	Name of the resource
reply.alerts.action_local_ip	string	Output field: reply.alerts.action_local_ip
reply.alerts.action_local_port	string	Output field: reply.alerts.action_local_port
reply.alerts.mitre_tactic_id_and_name	array	Unique identifier
reply.alerts.mitre_technique_id_and_name	array	Unique identifier
reply.alerts.action_external_hostname	string	Name of the resource
reply.alerts.action_remote_ip	array	Output field: reply.alerts.action_remote_ip
reply.alerts.action_remote_port	array	Output field: reply.alerts.action_remote_port
reply.alerts.matching_service_rule_id	string	Unique identifier

Output Example

{"status_code":200,"reason":"OK","json_body":{"reply":{"total_count":0,"result_count":0,"alerts":[],"next_page_token":"next_page_token_example"}}}

Get All Assets

Retrieve a comprehensive or filtered list of assets from Palo Alto Cortex Xpanse using specified request data.

Endpoint

URL: /v1/assets/get_assets_internet_exposure

Method: POST

Input

Argument Name	Type	Required	Description
request_data	object	Optional	A dictionary containing the API request fields. An empty dictionary returns all results.
request_data.search_from	number	Optional	Response data
request_data.next_page_token	string	Optional	A token used to retrieve the next page of results.
request_data.filters	array	Optional	An array of filter fields.
request_data.filters.field	string	Required	Identifies the assetss field the filter is matching. Case-sensitive.
request_data.filters.value	object	Required	Value depends on the filter field used.
request_data.filters.operator	string	Required	Identifies the comparison operator you want to use for this filter.
request_data.sort	object	Optional	Identifies the sort order for the result set.
request_data.sort.field	string	Required	The asset field by which to sort results.
request_data.sort.keyword	string	Required	The sort order.
request_data.search_to	number	Optional	An integer representing the start offset index of results.
request_data.use_page_token	boolean	Optional	Boolean indicating whether to use pagination for the results.

Input Example

{"json_body":{"request_data":{"search_from":0,"next_page_token":"next_page_token","filters":[{"field":"name","value":"AsmAssetsFilter_value","operator":"in"},{"field":"name","value":"AsmAssetsFilter_value","operator":"in"}],"sort":{"field":"name","keyword":"asc"},"search_to":0,"use_page_token":true}}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
reply	object	Output field: reply
reply.total_count	number	Count value
reply.result_count	number	Result of the operation
reply.assets_internet_exposure	array	Output field: reply.assets_internet_exposure
reply.assets_internet_exposure.agent_id	string	Unique identifier
reply.assets_internet_exposure.annotation	string	Output field: reply.assets_internet_exposure.annotation
reply.assets_internet_exposure.asm_ids	array	Unique identifier
reply.assets_internet_exposure.asm_va_score	number	Score value
reply.assets_internet_exposure.asset_explainers	array	Output field: reply.assets_internet_exposure.asset_explainers
reply.assets_internet_exposure.asset_type	string	Type of the resource
reply.assets_internet_exposure.aws_cloud_tags	array	Output field: reply.assets_internet_exposure.aws_cloud_tags
reply.assets_internet_exposure.azure_cloud_tags	array	Output field: reply.assets_internet_exposure.azure_cloud_tags
reply.assets_internet_exposure.business_units	array	Output field: reply.assets_internet_exposure.business_units
reply.assets_internet_exposure.business_units.0	object	Output field: reply.assets_internet_exposure.business_units.0
reply.assets_internet_exposure.business_units.0.creation_time	number	Time value
reply.assets_internet_exposure.business_units.0.family	string	Output field: reply.assets_internet_exposure.business_units.0.family
reply.assets_internet_exposure.business_units.0.family_alias	string	Output field: reply.assets_internet_exposure.business_units.0.family_alias
reply.assets_internet_exposure.business_units.0.id	string	Unique identifier
reply.assets_internet_exposure.business_units.0.is_active	number	Output field: reply.assets_internet_exposure.business_units.0.is_active
reply.assets_internet_exposure.business_units.0.name	string	Name of the resource
reply.assets_internet_exposure.business_units.0.parent_id	string	Unique identifier
reply.assets_internet_exposure.business_units.0.update_time	number	Time value
reply.assets_internet_exposure.certificate_algorithm	string	Output field: reply.assets_internet_exposure.certificate_algorithm

Output Example

{"status_code":200,"reason":"OK","json_body":{"reply":{"total_count":0,"result_count":0,"assets_internet_exposure":[],"next_page_token":"next_page_token_example"}}}

Get All Owned IP Ranges

Retrieve a list of owned IP address ranges associated with specific business units and organization handles in Palo Alto Cortex Xpanse.

Endpoint

URL: /v1/assets/get_external_ip_address_ranges

Method: POST

Input

Argument Name	Type	Required	Description
request_data	object	Optional	A dictionary containing the API request fields. An empty dictionary returns all results.
request_data.search_from	number	Optional	The starting index from which to return results.
request_data.next_page_token	string	Optional	A token to retrieve the next page of results.
request_data.filters	array	Optional	An array of filter fields.
request_data.filters.field	string	Required	Identifies the external IP ranges field the filter is matching.
request_data.filters.value	string	Required	Value depends on the filter field used.
request_data.filters.operator	string	Required	Identifies the comparison operator you want to use for this filter.
request_data.sort	object	Optional	A dictionary containing the sort field and keyword.
request_data.sort.field	string	Required	The field by which to sort the results.
request_data.sort.keyword	string	Required	The sort order, either ascending (asc) or descending (desc).
request_data.search_to	number	Optional	Response data
request_data.use_page_token	boolean	Optional	Boolean indicating whether to use pagination for the results.

Input Example

{"json_body":{"request_data":{"search_from":0,"next_page_token":"next_page_token","filters":[{"field":"organization_handles","value":"ExternalIpAddressRangesFilter_value","operator":"in"},{"field":"organization_handles","value":"ExternalIpAddressRangesFilter_value","operator":"in"}],"sort":{"field":"first_ip","keyword":"desc"},"search_to":0,"use_page_token":true}}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
reply	object	Output field: reply
reply.total_count	number	Count value
reply.result_count	number	Result of the operation
reply.external_ip_address_ranges	array	Output field: reply.external_ip_address_ranges
reply.external_ip_address_ranges.range_id	string	Unique identifier
reply.external_ip_address_ranges.first_ip	string	Output field: reply.external_ip_address_ranges.first_ip
reply.external_ip_address_ranges.last_ip	string	Output field: reply.external_ip_address_ranges.last_ip
reply.external_ip_address_ranges.ips_count	number	Count value
reply.external_ip_address_ranges.active_responsive_ips_count	number	Count value
reply.external_ip_address_ranges.date_added	number	Output field: reply.external_ip_address_ranges.date_added
reply.external_ip_address_ranges.organization_handles	array	Output field: reply.external_ip_address_ranges.organization_handles
reply.external_ip_address_ranges.ipaddress_version	number	Output field: reply.external_ip_address_ranges.ipaddress_version
reply.external_ip_address_ranges.tags	array	Output field: reply.external_ip_address_ranges.tags
reply.external_ip_address_ranges.first_ipv6	string	Output field: reply.external_ip_address_ranges.first_ipv6
reply.external_ip_address_ranges.last_ipv6	string	Output field: reply.external_ip_address_ranges.last_ipv6
reply.external_ip_address_ranges.annotation	string	Output field: reply.external_ip_address_ranges.annotation
reply.external_ip_address_ranges.has_bu_overrides	boolean	Unique identifier
reply.next_page_token	string	Output field: reply.next_page_token

Output Example

{"status_code":200,"reason":"OK","json_body":{"reply":{"total_count":0,"result_count":0,"external_ip_address_ranges":[],"next_page_token":"next_page_token_example"}}}

Get All Services

Retrieves a comprehensive or filtered list of all external services from Palo Alto Cortex Xpanse using specified request data.

Endpoint

URL: /v1/assets/get_external_services

Method: POST

Input

Argument Name	Type	Required	Description
request_data	object	Optional	A dictionary containing the API request fields.
request_data.search_from	number	Optional	An integer representing the start offset index of results.
request_data.next_page_token	string	Optional	A token to retrieve the next page of results.
request_data.vulnerability_test_results	boolean	Optional	Includes vulnerability test results from the last 14 days for each service in the response.
request_data.filters	array	Optional	An array of filter fields.
request_data.filters.field	string	Required	Identifies the external service field the filter is matching.
request_data.filters.value	object	Required	Value depends on the filter field used.
request_data.filters.operator	string	Required	Identifies the comparison operator you want to use for this filter.
request_data.sort	object	Optional	Sorts the results by the specified field and order.
request_data.sort.field	string	Required	The field to sort by.
request_data.sort.keyword	string	Required	The sort order, either 'asc' for ascending or 'desc' for descending.
request_data.search_to	number	Optional	An integer representing the start offset index of results.
request_data.use_page_token	boolean	Optional	Boolean indicating whether to use pagination for the results.

Input Example

{"json_body":{"request_data":{"search_from":0,"next_page_token":"next_page_token","vulnerability_test_results":true,"filters":[{"field":"service_name","value":"ExternalServicesFilter_value","operator":"in"},{"field":"service_name","value":"ExternalServicesFilter_value","operator":"in"}],"sort":{"field":"service_name","keyword":"asc"},"search_to":0,"use_page_token":true}}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
reply	object	Output field: reply
reply.total_count	number	Count value
reply.result_count	number	Result of the operation
reply.external_services	array	Output field: reply.external_services
reply.external_services.service_id	string	Unique identifier
reply.external_services.service_name	string	Name of the resource
reply.external_services.service_type	string	Type of the resource
reply.external_services.ip_address	array	Output field: reply.external_services.ip_address
reply.external_services.domain	array	Output field: reply.external_services.domain
reply.external_services.domain.file_name	string	Name of the resource
reply.external_services.domain.file	string	Output field: reply.external_services.domain.file
reply.external_services.externally_detected_providers	array	Unique identifier
reply.external_services.is_active	string	Output field: reply.external_services.is_active
reply.external_services.first_observed	number	Output field: reply.external_services.first_observed
reply.external_services.last_observed	number	Output field: reply.external_services.last_observed
reply.external_services.port	number	Output field: reply.external_services.port
reply.external_services.protocol	string	Output field: reply.external_services.protocol
reply.external_services.active_classifications	array	Output field: reply.external_services.active_classifications
reply.external_services.inactive_classifications	array	Output field: reply.external_services.inactive_classifications
reply.external_services.inactive_classifications.file_name	string	Name of the resource
reply.external_services.inactive_classifications.file	string	Output field: reply.external_services.inactive_classifications.file
reply.external_services.discovery_type	string	Type of the resource
reply.external_services.externally_inferred_vulnerability_score	string	Score value

Output Example

{"status_code":200,"reason":"OK","json_body":{"reply":{"total_count":1,"result_count":1,"external_services":[]}}}

Get All Websites

Retrieve a comprehensive or filtered list of public-facing websites from Palo Alto Cortex Xpanse, requiring request data.

Endpoint

URL: /v1/assets/get_external_websites

Method: POST

Input

Argument Name	Type	Required	Description
request_data	object	Optional	A dictionary containing the API request fields. An empty dictionary returns all results.
request_data.search_from	number	Optional	An integer representing the start offset index of results.
request_data.next_page_token	string	Optional	A string representing the page token from a previous response to retrieve the next page of results.
request_data.filters	array	Optional	Response data
request_data.filters.field	string	Required	String that identifies the external service field the filter is matching.
request_data.filters.value	object	Required	Value depends on the filter field used. For fields that support multiple values, provide an array of strings.
request_data.filters.operator	string	Required	String that identifies the comparison operator you want to use for this filter.
request_data.sort	object	Optional	Response data
request_data.sort.field	string	Required	The field by which to sort results.
request_data.sort.keyword	string	Required	The direction in which to sort results.
request_data.search_to	number	Optional	An integer representing the start offset index of results.
request_data.use_page_token	boolean	Optional	Boolean indicating whether to use pagination for the results.

Input Example

{"json_body":{"request_data":{"search_from":0,"next_page_token":"next_page_token","filters":[{"field":"ips","value":"ExternalWebsitesFilter_value","operator":"in"},{"field":"ips","value":"ExternalWebsitesFilter_value","operator":"in"}],"sort":{"field":"host","keyword":"asc"},"search_to":0,"use_page_token":true}}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
reply	object	Output field: reply
reply.total_count	number	Count value
reply.result_count	number	Result of the operation
reply.websites	array	Output field: reply.websites
reply.websites.website_id	string	Unique identifier
reply.websites.host	string	Output field: reply.websites.host
reply.websites.protocol	string	Output field: reply.websites.protocol
reply.websites.is_active	string	Output field: reply.websites.is_active
reply.websites.site_categories	array	Output field: reply.websites.site_categories
reply.websites.technology_ids	array	Unique identifier
reply.websites.first_observed	number	Output field: reply.websites.first_observed
reply.websites.last_observed	number	Output field: reply.websites.last_observed
reply.websites.provider_names	array	Unique identifier
reply.websites.ips	array	Output field: reply.websites.ips
reply.websites.port	number	Output field: reply.websites.port
reply.websites.active_service_ids	array	Unique identifier
reply.websites.http_type	string	Type of the resource
reply.websites.third_party_script_domains	array	Output field: reply.websites.third_party_script_domains
reply.websites.security_assessments	array	Output field: reply.websites.security_assessments
reply.websites.security_assessments.name	string	Name of the resource
reply.websites.security_assessments.priority	number	Output field: reply.websites.security_assessments.priority
reply.websites.security_assessments.score	number	Score value
reply.websites.security_assessments.securityAssessmentDetails	object	Output field: reply.websites.security_assessments.securityAssessmentDetails

Output Example

{"status_code":200,"reason":"OK","json_body":{"reply":{"total_count":0,"result_count":0,"websites":[],"next_page_token":"next_page_token_example"}}}

Get Asset Details

Retrieve detailed information for a specified asset in Palo Alto Cortex Xpanse using the asset ID provided in the request data.

Endpoint

URL: /v1/assets/get_asset_internet_exposure

Method: POST

Input

Argument Name	Type	Required	Description
request_data	object	Optional	A dictionary containing the API request fields.
request_data.asm_id_list	array	Required	A list of string(s) representing the asset IDs.

Input Example

{"json_body":{"request_data":{"asm_id_list":["asm_id_1","asm_id_2"]}}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
reply	object	Output field: reply
reply.details	array	Output field: reply.details
reply.details.asm_ids	string	Unique identifier
reply.details.name	string	Name of the resource
reply.details.type	string	Type of the resource
reply.details.last_observed	number	Output field: reply.details.last_observed
reply.details.first_observed	number	Output field: reply.details.first_observed
reply.details.externally_detected_providers	array	Unique identifier
reply.details.created	number	Output field: reply.details.created
reply.details.ips	array	Output field: reply.details.ips
reply.details.ips.ip	number	Output field: reply.details.ips.ip
reply.details.ips.ipv6	string	Output field: reply.details.ips.ipv6
reply.details.ips.protocol	string	Output field: reply.details.ips.protocol
reply.details.ips.provider	string	Unique identifier
reply.details.ips.geolocation	object	Output field: reply.details.ips.geolocation
reply.details.ips.geolocation.latitude	number	Output field: reply.details.ips.geolocation.latitude
reply.details.ips.geolocation.longitude	number	Output field: reply.details.ips.geolocation.longitude
reply.details.ips.geolocation.countryCode	string	Output field: reply.details.ips.geolocation.countryCode
reply.details.ips.geolocation.city	string	Output field: reply.details.ips.geolocation.city
reply.details.ips.geolocation.regionCode	string	Output field: reply.details.ips.geolocation.regionCode
reply.details.ips.geolocation.timeZone	string	Output field: reply.details.ips.geolocation.timeZone
reply.details.ips.activityStatus	string	Status value
reply.details.ips.lastObserved	number	Output field: reply.details.ips.lastObserved

Output Example

{"status_code":200,"reason":"OK","json_body":{"reply":{"details":[]}}}

Get Assets Last Assessment

Retrieve the last assessment time and status for assets in Palo Alto Cortex Xpanse, requiring request_data.

Endpoint

URL: /v1/assets/get_assets_internet_exposure/last_external_assessment

Method: POST

Input

Argument Name	Type	Required	Description
request_data	string	Optional	An empty dictionary returns the time and status of the last websites assessment.

Input Example

{"json_body":{"request_data":"{}"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
last_external_assessment	object	Output field: last_external_assessment
last_external_assessment.status	boolean	Status value
last_external_assessment.time	string	Time value

Output Example

{"status_code":200,"reason":"OK","json_body":{"last_external_assessment":{"status":false,"time":"time_example"}}}

Get Business Units

Retrieves information for all or specific business units within your Palo Alto Cortex Xpanse tenant.

Endpoint

URL: /v1/assets/get_business_units

Method: POST

Input

Argument Name	Type	Required	Description
request_data	object	Optional	A dictionary containing the API request fields. An empty dictionary returns all results.
request_data.filters	array	Required	An array of filter fields.
request_data.filters.field	string	Required	Identifies the business unit field the filter is matching.
request_data.filters.operator	string	Required	Identifies the comparison operator you want to use for this filter.
request_data.filters.value	string	Required	Value depends on the filter field used.
request_data.use_page_token	boolean	Optional	Boolean indicating whether to use pagination for the results.
request_data.next_page_token	string	Optional	Token to retrieve the next page of results if pagination is enabled.

Input Example

{"json_body":{"request_data":{"filters":[{"field":"business_unit_id","operator":"contains","value":"string"}],"use_page_token":true,"next_page_token":"string"}}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
reply	object	Output field: reply
reply.total_count	number	Count value
reply.result_count	number	Result of the operation
reply.business_units	array	Output field: reply.business_units
reply.business_units.business_unit_id	string	Unique identifier
reply.business_units.business_unit_name	string	Name of the resource
reply.business_units.parent_id	string	Unique identifier

Output Example

{"status_code":200,"reason":"OK","json_body":{"reply":{"total_count":0,"result_count":0,"business_units":[]}}}

Get Extra Incident Data

Retrieve additional data fields for a specified incident, encompassing alerts and key artifacts in Palo Alto Cortex Xpanse.

Endpoint

URL: /v1/incidents/get_incident_extra_data

Method: POST

Input

Argument Name	Type	Required	Description
request_data	object	Optional	A dictionary containing the API request fields.
request_data.alerts_limit	number	Optional	The maximum number of related alerts in the incident that you want to retrieve.
request_data.incident_id	string	Required	The ID of the incident for which you want to retrieve extra data.

Input Example

{"json_body":{"request_data":{"alerts_limit":0,"incident_id":"x0000001abc789"}}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
reply	object	Output field: reply
reply.incident	object	Unique identifier
reply.incident.incident_id	string	Unique identifier
reply.incident.is_blocked	boolean	Unique identifier
reply.incident.incident_name	string	Unique identifier
reply.incident.creation_time	number	Unique identifier
reply.incident.modification_time	number	Unique identifier
reply.incident.detection_time	number	Unique identifier
reply.incident.status	string	Unique identifier
reply.incident.severity	string	Unique identifier
reply.incident.description	string	Unique identifier
reply.incident.assigned_user_mail	string	Unique identifier
reply.incident.assigned_user_pretty_name	string	Unique identifier
reply.incident.alert_count	number	Unique identifier
reply.incident.low_severity_alert_count	number	Unique identifier
reply.incident.med_severity_alert_count	number	Unique identifier
reply.incident.high_severity_alert_count	number	Unique identifier
reply.incident.critical_severity_alert_count	number	Unique identifier
reply.incident.user_count	number	Unique identifier
reply.incident.host_count	number	Unique identifier
reply.incident.notes	string	Unique identifier
reply.incident.resolve_comment	string	Unique identifier
reply.incident.resolved_timestamp	number	Unique identifier

Output Example

{"status_code":200,"reason":"OK","json_body":{"reply":{"incident":{},"alerts":{},"network_artifacts":{},"file_artifacts":{}}}}

Get Incidents

Retrieve detailed information for a single incident or multiple incidents filtered by severity or creation time in Palo Alto Cortex Xpanse.

Endpoint

URL: /v1/incidents/get_incidents

Method: POST

Input

Argument Name	Type	Required	Description
request_data	object	Optional	A dictionary containing the API request fields.
request_data.search_from	number	Optional	Integer representing the starting offset within the query result set from which you want incidents returned.
request_data.filters	array	Required	Array of filter fields.
request_data.filters.field	string	Required	Identifies the incident field the filter is matching.
request_data.filters.value	object	Required	Value that this filter must match. The content of this field will differ depending on the field.
request_data.filters.operator	string	Required	Identifies the comparison operator you want to use for this filter.
request_data.sort	object	Optional	Identifies the sort order for the results.
request_data.sort.field	string	Optional	Field to sort by.
request_data.sort.keyword	string	Optional	Sort order, either ASC or DESC.
request_data.search_to	number	Optional	Integer representing the end offset within the result set after which you do not want incidents returned.

Input Example

{"json_body":{"request_data":{"search_from":0,"filters":[{"field":"modification_time","value":"IncidentFilter_value","operator":"in"},{"field":"modification_time","value":"IncidentFilter_value","operator":"in"}],"sort":{"field":"modification_time","keyword":"desc"},"search_to":0}}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
reply	object	Output field: reply
reply.total_count	number	Count value
reply.result_count	number	Result of the operation
reply.incidents	array	Unique identifier
reply.incidents.incident_id	string	Unique identifier
reply.incidents.is_blocked	boolean	Unique identifier
reply.incidents.incident_name	string	Unique identifier
reply.incidents.creation_time	number	Unique identifier
reply.incidents.modification_time	number	Unique identifier
reply.incidents.detection_time	number	Unique identifier
reply.incidents.status	string	Unique identifier
reply.incidents.severity	string	Unique identifier
reply.incidents.description	string	Unique identifier
reply.incidents.assigned_user_mail	string	Unique identifier
reply.incidents.assigned_user_pretty_name	string	Unique identifier
reply.incidents.alert_count	number	Unique identifier
reply.incidents.low_severity_alert_count	number	Unique identifier
reply.incidents.med_severity_alert_count	number	Unique identifier
reply.incidents.high_severity_alert_count	number	Unique identifier
reply.incidents.critical_severity_alert_count	number	Unique identifier
reply.incidents.user_count	number	Unique identifier
reply.incidents.host_count	number	Unique identifier
reply.incidents.notes	string	Unique identifier

Output Example

{"status_code":200,"reason":"OK","json_body":{"reply":{"total_count":0,"result_count":0,"incidents":[],"restricted_incident_ids":[]}}}

Get IP Address Ranges Last Assessment

Retrieve the last assessment time and status for IP address ranges in Palo Alto Cortex Xpanse, requiring request_data.

Endpoint

URL: /v1/assets/get_external_ip_address_ranges/last_external_assessment

Method: POST

Input

Argument Name	Type	Required	Description
request_data	string	Optional	An empty dictionary returns the time and status of the last websites assessment.

Input Example

{"json_body":{"request_data":"{}"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
last_external_assessment	object	Output field: last_external_assessment
last_external_assessment.status	boolean	Status value
last_external_assessment.time	string	Time value

Output Example

{"status_code":200,"reason":"OK","json_body":{"last_external_assessment":{"status":false,"time":"time_example"}}}

Get Owned IP Range Details

Retrieve details for owned external IP address ranges using specified range IDs in Palo Alto Cortex Xpanse.

Endpoint

URL: /v1/assets/get_external_ip_address_range

Method: POST

Input

Argument Name	Type	Required	Description
request_data	object	Optional	A dictionary containing the API request fields.
request_data.range_id_list	array	Required	A string representing the range ID for which you want to get the details.

Input Example

{"json_body":{"request_data":{"range_id_list":["range_id_list","range_id_list","range_id_list","range_id_list","range_id_list"]}}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
reply	object	Output field: reply
reply.details	array	Output field: reply.details
reply.details.range_id	string	Unique identifier
reply.details.first_ip	string	Output field: reply.details.first_ip
reply.details.last_ip	string	Output field: reply.details.last_ip
reply.details.ips_count	number	Count value
reply.details.active_responsive_ips_count	number	Count value
reply.details.date_added	number	Output field: reply.details.date_added
reply.details.organization_handles	array	Output field: reply.details.organization_handles
reply.details.details	object	Output field: reply.details.details
reply.details.details.networkRecords	array	Output field: reply.details.details.networkRecords
reply.details.details.networkRecords.firstIp	string	Output field: reply.details.details.networkRecords.firstIp
reply.details.details.networkRecords.firstIpv6	string	Output field: reply.details.details.networkRecords.firstIpv6
reply.details.details.networkRecords.handle	string	Output field: reply.details.details.networkRecords.handle
reply.details.details.networkRecords.lastChanged	number	Output field: reply.details.details.networkRecords.lastChanged
reply.details.details.networkRecords.lastIp	string	Output field: reply.details.details.networkRecords.lastIp
reply.details.details.networkRecords.lastIpv6	string	Output field: reply.details.details.networkRecords.lastIpv6
reply.details.details.networkRecords.name	string	Name of the resource
reply.details.details.networkRecords.organizationRecords	array	Output field: reply.details.details.networkRecords.organizationRecords
reply.details.details.networkRecords.remarks	string	Output field: reply.details.details.networkRecords.remarks
reply.details.details.networkRecords.whoIsServer	string	Output field: reply.details.details.networkRecords.whoIsServer
reply.details.explainers	array	Output field: reply.details.explainers
reply.details.ipaddress_version	number	Output field: reply.details.ipaddress_version

Output Example

{"status_code":200,"reason":"OK","json_body":{"reply":{"details":[]}}}

Get Service Details

Retrieve detailed information for a specific service in Palo Alto Cortex Xpanse using the service ID provided in the request data.

Endpoint

URL: /v1/assets/get_external_service

Method: POST

Input

Argument Name	Type	Required	Description
request_data	object	Optional	A dictionary containing the API request fields.
request_data.service_id_list	array	Required	A list of one or more service IDs to retrieve details for.

Input Example

{"json_body":{"request_data":{"service_id_list":["service_id_1","service_id_2","service_id_3"]}}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
reply	object	Output field: reply
reply.details	array	Output field: reply.details
reply.details.service_id	string	Unique identifier
reply.details.service_name	string	Name of the resource
reply.details.service_type	string	Type of the resource
reply.details.ip_address	array	Output field: reply.details.ip_address
reply.details.domain	array	Output field: reply.details.domain
reply.details.externally_detected_providers	array	Unique identifier
reply.details.is_active	string	Output field: reply.details.is_active
reply.details.first_observed	number	Output field: reply.details.first_observed
reply.details.last_observed	number	Output field: reply.details.last_observed
reply.details.port	number	Output field: reply.details.port
reply.details.protocol	string	Output field: reply.details.protocol
reply.details.active_classifications	array	Output field: reply.details.active_classifications
reply.details.inactive_classifications	array	Output field: reply.details.inactive_classifications
reply.details.discovery_type	string	Type of the resource
reply.details.externally_inferred_vulnerability_score	number	Score value
reply.details.externally_inferred_cves	array	Output field: reply.details.externally_inferred_cves
reply.details.details	object	Output field: reply.details.details
reply.details.details.serviceKey	string	Output field: reply.details.details.serviceKey
reply.details.details.serviceKeyType	string	Type of the resource
reply.details.details.providerDetails	array	Unique identifier
reply.details.details.providerDetails.name	string	Unique identifier

Output Example

{"status_code":200,"reason":"OK","json_body":{"reply":{"details":[],"pretty_name":"pretty_name_example","groups":[],"users":[]}}}

Get Services Last Assessment

Retrieves the last assessment time and status for services data in Palo Alto Cortex Xpanse, requiring request_data in JSON body.

Endpoint

URL: /v1/assets/get_external_services/last_external_assessment

Method: POST

Input

Argument Name	Type	Required	Description
request_data	string	Optional	An empty dictionary returns the time and status of the last websites assessment.

Input Example

{"json_body":{"request_data":"{}"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
last_external_assessment	object	Output field: last_external_assessment
last_external_assessment.status	boolean	Status value
last_external_assessment.time	string	Time value

Output Example

{"status_code":200,"reason":"OK","json_body":{"last_external_assessment":{"status":false,"time":"time_example"}}}

Get Website Details

Retrieve detailed information about specific websites using their IDs in Palo Alto Cortex Xpanse.

Endpoint

URL: /v1/assets/get_external_website

Method: POST

Input

Argument Name	Type	Required	Description
request_data	object	Optional	A dictionary containing the API request fields.
request_data.website_id_list	array	Required	A string representing the website ID you want to get details for. Limit is 20 website ids.

Input Example

{"json_body":{"request_data":{"website_id_list":["website_id_1","website_id_2","website_id_3"]}}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
reply	object	Output field: reply
reply.details	array	Output field: reply.details
reply.details.website_id	string	Unique identifier
reply.details.host	string	Output field: reply.details.host
reply.details.protocol	string	Output field: reply.details.protocol
reply.details.is_active	string	Output field: reply.details.is_active
reply.details.site_categories	array	Output field: reply.details.site_categories
reply.details.technology_ids	array	Unique identifier
reply.details.first_observed	number	Output field: reply.details.first_observed
reply.details.last_observed	number	Output field: reply.details.last_observed
reply.details.provider_names	array	Unique identifier
reply.details.ips	array	Output field: reply.details.ips
reply.details.port	number	Output field: reply.details.port
reply.details.active_service_ids	array	Unique identifier
reply.details.http_type	string	Type of the resource
reply.details.security_assessments	array	Output field: reply.details.security_assessments
reply.details.security_assessments.name	string	Name of the resource
reply.details.security_assessments.priority	number	Output field: reply.details.security_assessments.priority
reply.details.security_assessments.score	number	Score value
reply.details.security_assessments.securityAssessmentDetails	object	Output field: reply.details.security_assessments.securityAssessmentDetails
reply.details.security_assessments.securityAssessmentDetails.pages	array	Output field: reply.details.security_assessments.securityAssessmentDetails.pages
reply.details.security_assessments.securityAssessmentDetails.description	string	Output field: reply.details.security_assessments.securityAssessmentDetails.description
reply.details.rootPageHttpStatusCode	string	Status value

Output Example

{"status_code":200,"reason":"OK","json_body":{"reply":{"details":[]}}}

Get Websites Last Assessment

Retrieve the latest assessment time and status for websites in Palo Alto Cortex Xpanse, requiring request_data.

Endpoint

URL: /v1/assets/get_external_websites/last_external_assessment

Method: POST

Input

Argument Name	Type	Required	Description
request_data	string	Optional	An empty dictionary returns the time and status of the last websites assessment.

Input Example

{"json_body":{"request_data":"{}"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
last_external_assessment	object	Output field: last_external_assessment
last_external_assessment.status	boolean	Status value
last_external_assessment.time	string	Time value

Output Example

{"status_code":200,"reason":"OK","json_body":{"last_external_assessment":{"status":false,"time":"time_example"}}}

Remove Alerts

Remove certificates, domains, and IPv4 address ranges from your Palo Alto Cortex Xpanse inventory.

Endpoint

URL: /public_api/v1/asm_management/remove_asm_data

Method: POST

Input

Argument Name	Type	Required	Description
data_body	object	Optional	Data Body
headers	object	Optional	Request Headers

Input Example

{"path_parameters":{},"parameters":{},"data_body":{},"headers":{}}

Remove Assets

Removes specified certificates, domains, and IPv4 address ranges from the Palo Alto Cortex Xpanse inventory.

Endpoint

URL: /v1/asm_management/remove_asm_data

Method: POST

Input

Argument Name	Type	Required	Description
request_data	object	Optional	A dictionary containing the API request fields.
request_data.asset_type	string	Required	The type of asset being removed.
request_data.asset_identifiers	array	Required	A list of one or more assets you want to add to the inventory.

Input Example

{"json_body":{"request_data":{"asset_type":"certificate","asset_identifiers":["10.92.16.32"]}}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
reply	string	Output field: reply

Output Example

{"status_code":200,"reason":"OK","json_body":{"reply":"Successfully removed assets."}}

Update Alerts

Update one or more alerts in Palo Alto Cortex Xpanse using specified request data.

Endpoint

URL: /v1/alerts/update_alerts

Method: POST

Input

Argument Name	Type	Required	Description
request_data	object	Optional	A dictionary containing the API request fields. An empty dictionary returns all results.
request_data.alert_id_list	array	Optional	A list of alert IDs to update.
request_data.update_data	object	Optional	A dictionary containing the fields to update for the specified alerts.
request_data.update_data.severity	string	Optional	The severity level to set for the alerts.
request_data.update_data.status	string	Optional	The status to set for the alerts.
request_data.update_data.comment	string	Optional	A comment to add to the alerts.

Input Example

{"json_body":{"request_data":{"alert_id_list":["string"],"update_data":{"severity":"string","status":"string","comment":"string"}}}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
reply	object	Output field: reply
reply.alerts_ids	array	Unique identifier

Output Example

{"status_code":200,"reason":"OK","json_body":{"reply":{"alerts_ids":[]}}}

Update an Incident

Updates specific fields of an incident in Palo Alto Cortex Xpanse using the provided request data.

Endpoint

URL: /v1/incidents/update_incident

Method: POST

Input

Argument Name	Type	Required	Description
request_data	object	Optional	Response data
request_data.incident_id	string	Optional	Response data
request_data.update_data	object	Required	Response data
request_data.update_data.assigned_user_mail	string	Required	Updated email address of the incident assignee.
request_data.update_data.comment	object	Required	Add a comment to the incident.
request_data.update_data.comment.comment_action	string	Required	Action to perform on the comment.
request_data.update_data.comment.value	string	Required	The content of the comment to be added.
request_data.update_data.assigned_user_pretty_name	string	Required	Updated full name of the incident assignee.
request_data.update_data.manual_severity	string	Required	Administrator-defined severity.
request_data.update_data.status	string	Required	Updated incident status.
request_data.update_data.resolve_comment	string	Required	Descriptive comment explaining the incident change.

Input Example

{"json_body":{"request_data":{"incident_id":"incident_id","update_data":{"assigned_user_mail":"assigned_user_mail","comment":{"comment_action":"add","value":"value"},"assigned_user_pretty_name":"assigned_user_pretty_name","manual_severity":"low","status":"resolved","resolve_comment":"resolve_comment"}}}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
reply	boolean	Output field: reply
warnings	array	Output field: warnings

Output Example

{"status_code":200,"reason":"OK","json_body":{"reply":false,"warnings":["warnings_example"]}}

Update Asset Annotation

Adds an annotation to a specified asset or IP range in Palo Alto Cortex Xpanse using the provided request data.

Endpoint

URL: /v1/assets/assets_internet_exposure/annotation

Method: POST

Input

Argument Name	Type	Required	Description
request_data	object	Optional	Response data
request_data.assets	array	Required	Response data
request_data.assets.annotation	string	Required	Annotation text.
request_data.assets.entity_type	string	Required	Type of the entity being annotated.
request_data.assets.entity_id	string	Required	Unique identifier for the entity being annotated.
request_data.should_append	boolean	Optional	Boolean indicating whether to append the annotation to existing annotations or replace them.

Input Example

{"json_body":{"request_data":{"assets":[{"annotation":"annotation","entity_type":"asset","entity_id":"entity_id"},{"annotation":"annotation","entity_type":"asset","entity_id":"entity_id"}],"should_append":true}}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
reply	string	Output field: reply

Output Example

{"status_code":200,"reason":"OK","json_body":{"reply":"reply_example"}}

Upload Assets

Upload domains and IPv4 address ranges to your Palo Alto Cortex Xpanse inventory using the provided request data.

Endpoint

URL: /v1/asm_management/upload_asm_data

Method: POST

Input

Argument Name	Type	Required	Description
request_data	object	Optional	A dictionary containing the API request fields.
request_data.request_type	string	Required	Indicates that you want to add new assets to your inventory.
request_data.asset_type	string	Required	The type of asset being added.
request_data.asset_identifiers	array	Required	List of assets to be uploaded.
request_data.business_units	array	Required	One or more business unit IDs or business unit names to which the uploaded assets will be assigned.

Input Example

{"json_body":{"request_data":{"request_type":"addition","asset_type":"ip_range","asset_identifiers":["string"],"business_units":["BU:1","BU:2"]}}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
reply	object	Output field: reply
reply.asset_names	array	Name of the resource
reply.errors	array	Error message if any

Output Example

{"status_code":200,"reason":"OK","json_body":{"reply":{"asset_names":[],"errors":[]}}}

Response Headers

Header	Description	Example
Content-Type	The media type of the resource	application/json
Date	The date and time at which the message was originated	Thu, 01 Jan 2024 00:00:00 GMT

Docs powered by Archbee